Document raw Containers API alongside Container class by thomasgauvin · Pull Request #33093 · cloudflare/cloudflare-docs

thomasgauvin · 2026-08-28T19:38:22Z

Summary

Focuses this PR on the Containers documentation information architecture:

Recommends the Durable Object Container API (ctx.container) for direct lifecycle control and compares it with the higher-level Container class.
Moves both API references into the Containers docs and adds a Container class to direct API migration guide.
Adds Wrangler configuration documentation, updates navigation and links, and validates redirects.
Moves direct-API example-page additions to the separately reviewable stacked PR [Containers] Add direct API variants to container examples #33681. This PR does not document the new start() options or snapshots from [Containers] Document scheduling policies and snapshots #33531.

Testing

pnpm run check (0 errors, 0 warnings)
pnpm exec tsm bin/validate-redirects.ts
Scoped Prettier check and git diff --check against the PR base
Local build rendered the changed routes, then failed on an unrelated missing GET /zones/{zone_identifier}/custom_pages/{identifier} APIRequest operation in the local OpenAPI schema. Review CI before merging.

cloudflare-docs-bot · 2026-08-28T19:38:32Z

AI Review

✅ Reviewed ef3f6b2 · 2 findings · incremental

👉 Fix in your agent 👈

Fix the following review findings in PR #33093 (https://github.com/cloudflare/cloudflare-docs/pull/33093).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification.
- If you disagree, explain why.
- If you need clarification before deciding, ask those questions.
- Then share your plan for which issues to tackle and in what order.

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit because the next review reads PR comments.

## Style Guide
- S-1195645a | src/content/docs/containers/concepts/architecture.mdx:123 | Semicolon joins two independent clauses
  The sentence "The Durable Object becomes inactive when it stops receiving requests; the timeout can keep the container available while the Durable Object sleeps." joins two independent clauses with a semicolon. Per the writing-style rules, break it into two sentences.
- S-01025b58 | src/content/docs/containers/guides/migrate-to-durable-object-container-api.mdx:25 | Missing serial comma before final conjunction
  The three replacement options `ctx.container.start()`, `signal()`, and `destroy()` are joined by `and`/`or` without a comma before the final `or`. Per the serial comma rule, the comma must appear before the final top-level conjunction.

Style Guide

src/content/docs/containers/concepts/architecture.mdx:123 · Semicolon joins two independent clauses

The sentence "The Durable Object becomes inactive when it stops receiving requests; the timeout can keep the container available while the Durable Object sleeps." joins two independent clauses with a semicolon. Per the writing-style rules, break it into two sentences.
src/content/docs/containers/guides/migrate-to-durable-object-container-api.mdx:25 · Missing serial comma before final conjunction

The three replacement options ctx.container.start(), signal(), and destroy() are joined by and/or without a comma before the final or. Per the serial comma rule, the comma must appear before the final top-level conjunction.

Not reviewed (1)

src/content/docs/containers/reference/durable-object-methods.mdx — deleted file

Resolved (2) · Dismissed (0)

Resolved: Passive voice in API recommendation · Verified at head (api/index.mdx): line 43 now reads 'Inside a Durable Object, use ctx.container...'; the passive 'is recommended' sentence is gone, and lines 16 and 105 state the recommendation actively ('we recommend', 'use').
Resolved: Description omits new migration guide page · The current description bullet 2 states 'adds a Container class to direct API migration guide', which identifies the new migrate-to-durable-object-container-api.mdx page; the description no longer omits this core change.

Commands

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

cloudflare-docs-bot · 2026-09-17T15:13:22Z

Review coverage

✅ All 5 ownership areas are covered.

✅ 5 areas already covered

Area	Approved by
workers _{1 file changed}	`irvinebroque`
Other _{1 file changed} `/public/__redirects`	`irvinebroque`
containers _{21 files changed}	`irvinebroque`
durable-objects _{1 file changed}	`irvinebroque`
rules _{1 file changed}	`irvinebroque`

CODEOWNERS mappings for displayed areas (5)

Pattern	Owners
`/src/content/docs/workers/wrangler/`	`@irvinebroque`, `@MattieTK`, `@vy-ton`, `@cloudflare/wrangler`, `@cloudflare/product-owners`
`/public/__redirects`	`@cloudflare/product-owners`, `@cloudflare/content-engineering`
`/src/content/docs/containers/`	`@mikenomitch`, `@th0m`, `@cloudflare/cloudchamber`, `@cloudflare/product-owners`
`/src/content/docs/durable-objects/`	`@danlapid`, `@iglesiasbrandon`, `@irvinebroque`, `@joshthoward`, `@lambrospetrou`, `@mikenomitch`, `@rita3ko`, `@vy-ton`, `@cloudflare/product-owners`
`/src/content/docs/rules/`	`@maurizioabba`, `@mbullock1986`, `@smarsh-cf`, `@cloudflare/appsec-reviewers`, `@cloudflare/product-owners`

thomasgauvin · 2026-09-23T21:08:27Z

Review triage for findings on 285ad23:

CR-9183433ea624: Keep both the navigation stub and the 301 redirect. The stub supplies the Durable Objects sidebar link to the new Containers API page; the redirect handles direct requests to the old URL. The stub is not intended as a separate content destination.
SG-f074c72134c1 and SG-0e8254639803: These blocks are method signatures, not executable Worker examples. They now use txt fences instead of raw ts fences. TypeScriptExample generates JavaScript and its parser rejects standalone method signatures without bodies. Executable examples use TypeScriptExample.

The other findings are fixed and validated in the isolated local PR worktree. No commit or push has been made yet.

gabivlj · 2026-09-24T15:15:23Z

+	constructor(ctx: DurableObjectState, env: Env) {
+		super(ctx, env);
+		ctx.blockConcurrencyWhile(() =>
+			ctx.container!.setInactivityTimeout(10 * 60 * 1000),


This example could use a container: Container; property that gets init in the constructor, and then users dont have to use ! operator when accessing ctx.container.

Addressed in #33093: the short API comparison snippet now checks for a configured container instead of using the non-null assertion.

gabivlj · 2026-09-24T15:21:04Z

 ### Container shutdown

-The Container class sets [`sleepAfter`](/containers/reference/container-class/#sleepafter) to 10 minutes by default. Its default [`onActivityExpired()`](/containers/reference/container-class/#onactivityexpired) implementation signals the container to stop after that period without activity. You can change the duration or override the hook.
+With the Durable Object Container API, call [`setInactivityTimeout()`](/containers/api/durable-object-container/#setinactivitytimeout) to let the runtime stop an inactive container. You can also stop a container with [`signal()`](/containers/api/durable-object-container/#signal) or [`destroy()`](/containers/api/durable-object-container/#destroy).


There will be questions around setinactivitytimeout. In general, we should explain that setInactivityTimeout triggers when the Durable Object goes to sleep, use it so the container can be kept around while the DO is inactive (which is when requests do not come in).

Addressed in #33093: the shutdown section now explains inactivity in terms of the Durable Object receiving no requests and the timeout keeping its container available while the Durable Object sleeps.

gabivlj · 2026-09-24T15:21:46Z

+
+	constructor(ctx: DurableObjectState, env: Env) {
+		super(ctx, env);
+		ctx.blockConcurrencyWhile(() =>


In these examples I do not think we shouldbe using blockConcurrencyWhile.

Moved the raw backend example to the stacked examples PR #33681 and removed blockConcurrencyWhile() and constructor setup there. #33093 now has no example-code changes.

gabivlj · 2026-09-24T15:22:53Z

+	private async startAndWaitForPort(): Promise<void> {
+		const container = this.ctx.container!;
+		if (!container.running) {
+			container.start();


Do we have any examples with monitor()? We should add an incentive for LLMs to use monitor() to track when the container exits (and track if there is any errors.

Addressed in the stacked examples PR #33681: the backend direct-API example now uses monitor() to log both container exit and errors. The status-hooks example also demonstrates monitor().

gabivlj · 2026-09-24T15:24:11Z

We should add an example somewhere for LLMs to read that showcase how to keep the container "always running", and add an RPC in the DO that exposes a destroy() + destry alarm.

gabivlj · 2026-09-24T15:33:14Z

+					enableInternet: true,
+					env: {
+						ENV_VAR: env.ENV_VAR,
+						WORKER_SECRET: env.WORKER_SECRET,


No blockConcurrencyWhile, I recommend just exposing a start() method on this DO as it does not seem to do anything.

In general, let's discourage starting in the constructor for LLMs

Agreed about not starting in the constructor. The raw environment-variable variant was removed from #33093 and deferred from #33681 because its options overlap the separate start() work in #33531. The remaining direct-API examples in #33681 start from methods or requests without blockConcurrencyWhile().

gabivlj · 2026-09-24T15:33:22Z

+		ctx.blockConcurrencyWhile(async () => {
+			if (!ctx.container!.running) {
+				ctx.container!.start({
+					image: env.CONTAINER_IMAGE,


ctx.container.images?

The runtime-image selection variant is out of scope for these two PRs and belongs with the separate start() work in #33531; this example was removed from #33093 and is not in #33681.

gabivlj · 2026-09-24T15:33:46Z

+		if (this.ctx.container!.running) {
+			throw new Error("Container is already running");
+		}
+		this.ctx.container!.start({ image, enableInternet: true, env });


This is a great example, let's add monitor() too?

This raw environment-variable variant is deferred from both PRs because passing startup options would overlap the new start() documentation in #33531. The backend and status-hooks examples in #33681 demonstrate monitor() for exit and error tracking.

Document raw Containers API alongside Container class

c4d901b

thomasgauvin requested review from a team, MattieTK, danlapid, iglesiasbrandon, irvinebroque, joshthoward, lambrospetrou, ncrouch-cflare, rita3ko, securitypedant, th0m and vy-ton as code owners August 28, 2026 19:38

github-actions Bot added product:workers Related to Workers product product:reference-architecture product:durable-objects Durable Objects: https://developers.cloudflare.com/workers/learning/using-durable-objects/ product:changelog product:containers product:sandbox size/xl labels Aug 28, 2026

github-actions Bot assigned th0m, danlapid, iglesiasbrandon and irvinebroque Aug 28, 2026

thomasgauvin mentioned this pull request Sep 23, 2026

[Containers] Move outbound traffic into Configuration #33639

Open

2 tasks

[Containers] Separate outbound traffic IA from API docs

272759a

github-actions Bot removed product:reference-architecture product:changelog product:sandbox labels Sep 23, 2026

thomasgauvin added 6 commits September 23, 2026 18:09

[Containers] Validate API examples and preserve redirects

3a6606f

[Containers] Clarify recommended API guidance

95ec926

[Containers] Remove redundant API description heading

6520790

[Containers] Clarify Durable Object proxying

3c236fa

[Containers] Highlight recommended API in note

1822a2b

[Containers] Explain Durable Object benefits for containers

1df7fc4

gabivlj reviewed Sep 24, 2026

View reviewed changes

[Containers] Focus API docs on migration and navigation

e8d18c6

github-actions Bot added the product:sandbox label Sep 25, 2026

[Containers] Separate API examples from navigation changes

e32a64f

github-actions Bot removed the product:sandbox label Sep 25, 2026

thomasgauvin mentioned this pull request Sep 25, 2026

[Containers] Add direct API variants to container examples #33681

Open

[Containers] Recommend direct API for new applications

ef3f6b2

thomasgauvin requested review from mbullock1986 and smarsh-cf as code owners September 25, 2026 02:53

github-actions Bot added the product:rules Related to rules label Sep 25, 2026

Conversation

thomasgauvin commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Uh oh!

cloudflare-docs-bot Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

AI Review

Style Guide

Uh oh!

cloudflare-docs-bot Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review coverage

Uh oh!

thomasgauvin commented Sep 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gabivlj commented Sep 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

13 participants

thomasgauvin commented Aug 28, 2026 •

edited

Loading

cloudflare-docs-bot Bot commented Aug 28, 2026 •

edited

Loading

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

edited

Loading