[Containers] Correct and extend Durable Object container docs by ghostwriternr · Pull Request #33767 · cloudflare/cloudflare-docs · GitHub
Skip to content

[Containers] Correct and extend Durable Object container docs - #33767

Merged
ghostwriternr merged 9 commits into
productionfrom
sandboxes/platform-reference
Sep 30, 2026
Merged

ghostwriternr merged 9 commits into
productionfrom
sandboxes/platform-reference

Conversation

@ghostwriternr

@ghostwriternr ghostwriternr commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

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 absent exec() stream is undefined although the TypeScript types say null, and interceptAllOutboundHttp() covers only port 80.

This PR corrects those claims and documents the missing API: inspect(), start() labels and errors, the exec() pty, signal, and resize options, how exec() 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 as root, carry an MDX comment with the condition for removing them.

Merge after #33531.

Documentation checklist

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

AI Review

✅ Reviewed 3b1ce3e · 0 findings · incremental

Commands
  • /review Run a review now.
  • /full-review Review the entire PR diff.
  • /disable-auto-review Stop automatic reviews.
  • /rebase Rebase against production.

@thomasgauvin thomasgauvin left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Four inline comments cover local exec() environment behavior, the managed-image scheduling-policy constraint, already-aborted request handling, and inactivity-timeout timing.

Comment thread src/content/docs/containers/api/durable-object-container.mdx Outdated
Comment thread src/content/docs/containers/api/durable-object-container.mdx Outdated
Comment thread src/content/docs/containers/api/durable-object-container.mdx Outdated
Comment thread src/content/docs/containers/api/durable-object-container.mdx Outdated
Comment thread src/content/docs/containers/api/durable-object-container.mdx Outdated
@ghostwriternr
ghostwriternr changed the base branch from sandboxes/containers-base to codex/containers-scheduling-policy September 29, 2026 17:11
@ghostwriternr
ghostwriternr added this pull request to stack #33805 September 29, 2026 17:11
@ghostwriternr
ghostwriternr removed request for a team September 29, 2026 17:15
@ghostwriternr

Copy link
Copy Markdown
Member Author

ugh, for anyone who got pinged for a review here unnecessarily: this was a me-issue, mishandling how gh stacks work when changing the target branch for the PR and doing a rebase. sorry! will keep noise on this PR clean so as to not bother too many people.

@th0m

th0m commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

LGTM

@thomasgauvin

Copy link
Copy Markdown
Contributor

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.
@github-actions

Copy link
Copy Markdown
Contributor

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants