Skip to content

align README outbound examples with egress docs - #248

Open
iMagdy wants to merge 1 commit into
cloudflare:mainfrom
iMagdy:patch-1
Open

align README outbound examples with egress docs#248
iMagdy wants to merge 1 commit into
cloudflare:mainfrom
iMagdy:patch-1

Conversation

@iMagdy

@iMagdy iMagdy commented Aug 21, 2026

Copy link
Copy Markdown

What

Align README.md with docs/egress.md on how the three static outbound accessors are set:
by assignment after the class declaration, not as static class fields.

Fixes the documentation half of #247.

Why

outbound, outboundByHost and outboundHandlers are declared as static accessor pairs
(dist/lib/container.d.ts:50-55), and their setters are the only writers of the handler
registry. Under useDefineForClassFields semantics — the default for target: ES2022 and
above — a static outbound = … class field is installed with [[DefineOwnProperty]]. That
creates an own property which shadows the inherited setter instead of invoking it, so the
handler is never registered and every outbound request fails closed with
520 Origin is disallowed. No error, no warning, and MyContainer.outbound still reads back
the function you assigned — it is just the own property, not a registration.

The repo already documents this correctly elsewhere. docs/egress.md uses the assignment
form in all six of its examples (lines 150, 165, 177, 310, 316, 322):

MyContainer.outboundByHost = { ... };

while README.md uses the class-field form in all six of its own (lines 311, 315, 319, 479,
485, 491). This PR makes the README match the egress docs; it does not introduce a new
convention.

All three accessors are affected identically, not just outbound.

Changes

  • Reference list: show the three as assignments, and add a note explaining why the class-field
    form does not register.
  • TypeScript example: move the three static blocks out of the class body into assignments
    after the declaration.

Instance properties in the same example (allowedHosts, deniedHosts, interceptHttps,
enableInternet, defaultPort) are plain properties rather than accessors, so they are
correct as class fields and are left unchanged.

Docs-only — no changeset, no behaviour change.

The three static outbound accessors — outbound, outboundByHost and
outboundHandlers — must be set by assignment after the class declaration.
Written as `static` class fields they are installed with
[[DefineOwnProperty]] under useDefineForClassFields (the default for
target ES2022 and above), which shadows the inherited setter instead of
invoking it. The handler is never registered and outbound requests fail
closed with 520, with no error or warning.

docs/egress.md already uses the assignment form in all six of its
examples; README.md used the class-field form in all six of its own.
This brings the README in line with the egress docs.

Instance properties in the same example (allowedHosts, deniedHosts,
interceptHttps, enableInternet, defaultPort) are plain properties rather
than accessors, so they are correct as class fields and are unchanged.

Refs cloudflare#247
@iMagdy
iMagdy requested a review from a team as a code owner August 21, 2026 17:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant