Repository navigation
[Containers] Correct and extend Durable Object container docs - #33767
Conversation
AI Review✅ Reviewed Commands
|
thomasgauvin
left a comment
There was a problem hiding this comment.
Four inline comments cover local exec() environment behavior, the managed-image scheduling-policy constraint, already-aborted request handling, and inactivity-timeout timing.
4130457 to
af0f06f
Compare
|
ugh, for anyone who got pinged for a review here unnecessarily: this was a me-issue, mishandling how |
|
LGTM |
|
Looks good approved! |
Sandboxes build on containers that a Durable Object starts with this.ctx.container. The Durable Object Container API page and the Containers pages around it miss behavior the sandbox pages rely on, and contain several wrong claims. Document what the Durable Object Container API page leaves out: start() errors and labels, inspect(), when monitor() settles, the exec() pty, signal and resize options, the order of outbound intercepts, and how DNS answers when the Internet is off. Correct setInactivityTimeout(): it sets how long a container keeps running after its Durable Object becomes inactive. State that exec() does not inherit the start() environment, that a canceled request keeps exec() running, and that a signal from exec() misses child processes. Add snapshot errors and retention to snapshotContainer(). Give the minimum Wrangler version for local containers with the durable_object policy, and add the local and deployed differences to local development. Run Docker-in-Docker from docker:dind, and name Firecracker on the architecture page.
The Durable Object Container API page filed process, restart, and signal behavior under Return values and Exceptions, and said three times that durable_object containers need an image. It typed the exec() streams as null, while the runtime returns undefined. It also told readers to pass request.signal to exec(), which the page's own caution says can raise an internal error. Move exec() stop and cancel behavior into a Process lifetime section. Point to the Durable Object lifecycle page for client disconnects, and route request.signal through an AbortController. Give the stream types the runtime values, and warn that the TypeScript types say null. List the DNS rules for containers without the Internet, and say that the intercept methods return promises and fail at the target limit. On the other Containers pages, give one DNS explanation per page in terms of the Container class, correct the exit codes and process group of GNU timeout, and give the Wrangler version for the managed image. Keep the Docker-in-Docker FAQ to what readers run. Mark the notes about runtime bugs with the condition for removing them.
The local development page said the deployed hostname is too long for a DNS label and does not resolve, without saying what the hostname is. Readers could take it for a public name, and could expect a shorter name to fix the lookup, but the name is also missing from /etc/hosts. Say that the hostname is the name the container uses for itself, and state the length and the missing /etc/hosts entry as separate facts. The removal comment now waits for both to be fixed.
The reference said a container accepts 64 distinct intercept targets, and blamed the "128 egress interceptors" error on every target using two entries. Only hostname targets use two entries, one for IPv4 and one for IPv6. An IP address or CIDR target uses one, so a container holds 128 of them. The CIDR example also claimed that an IPv4 range covers IPv6, and some examples did not await the call that throws. Describe the limit once, in entries, under an Intercept limit heading that the three intercept methods link to. Explain how to route a changing set of hostnames through one catch-all, and await every intercept call in the examples.
The Streams over RPC link in Execute commands misspelled its anchor as writeablestream, and the wrangler dev link in local development pointed at the general commands page, which does not document dev. Both links landed at the top of the page. Point them at the anchors that exist, and drop "simply" from the wrangler dev sentence.
The Durable Object container reference stated several rules without code: which user a command runs as, how to stop a command when the client disconnects, and when to set the inactivity timeout. It told readers to set the timeout on every request, although the timeout only needs setting again when a Durable Object restarts. Its exec() example extended the deprecated Container class, and the note on output() did not say that the output counts against Durable Object memory. Add examples for the user option, request.signal, and the timeout, and set the timeout after start() and in the constructor. Base the exec() example on DurableObject and drop the sleepAfter pointer. Say that output() buffers in memory, move the list-snapshots fact into a note, and mark runtime workarounds with when to remove them. Give the processes a command starts their own section in Execute commands, and link the scheduling policy where the local development and FAQ pages compare the two policies.
Several added paragraphs on the container API, local development, outbound traffic, and FAQ pages joined two or three facts with "so" or "and", or left "it" without a clear subject. Reviewers had to read them twice, and one said the pty default applied to every command. Give each fact its own sentence, lead with the subject, state that stderr defaults to "combined" only under pty, and split the signal caution into the rule and the workaround.
The Durable Object container reference had five problems. The abort example misses a request signal that is already aborted, because abort listeners do not fire for past events. The exec() env text says PATH comes from the image, but a PATH passed to start() also reaches exec(). The HTTPS intercept text says it covers only port 443, but a target can name another port. The DNS list says CIDR targets add no answers, which is not true for 0.0.0.0/0 and ::/0. The setInactivityTimeout example uses the managed image without saying that it needs the durable_object scheduling policy. Handle an already aborted signal, state where PATH comes from on the reference and the Execute commands guide, document HTTPS targets with a port, add the CIDR exception, and note the scheduling policy next to the managed image.
The Process lifetime section said a process keeps running when its request is canceled and linked to a Durable Object lifecycle section that is no longer part of this change. A process stops when its container stops, and the Durable Object that owns the container can be evicted after a fetch() client disconnects. The section also said to pass the incoming request to the stub, when calling the stub with any request delivers the abort, and did not say which Worker needs enable_request_signal. State only that canceling the request does not stop the process, drop the link, and name the Worker that defines the Durable Object as the one that needs the flag.
|
Preview URL: https://3b1ce3ec.preview.developers.cloudflare.com Files with changes (up to 15) |

Summary
The Durable Object Container API page and the Containers guides around it miss several methods and options, and some of their claims do not match deployed containers. For example,
exec()does not inherit the container's environment, an absentexec()stream isundefinedalthough the TypeScript types saynull, andinterceptAllOutboundHttp()covers only port80.This PR corrects those claims and documents the missing API:
inspect(),start()labels and errors, theexec()pty,signal, andresizeoptions, howexec()processes stop,monitor()results, intercept limits and order, DNS in containers without the Internet, and snapshot expiry. It also adds the Wrangler versions and deploy differences to local development, fixes the Docker-in-Docker FAQ, and names Firecracker on the architecture page.Where the runtime and the TypeScript types disagree, the page documents the runtime value and tells readers how to test for a stream. Notes about runtime bugs, such as
exec()running a user ID without a group ID asroot, carry an MDX comment with the condition for removing them.Merge after #33531.
Documentation checklist