[wrangler] add `tcp_handlers` wrangler config section by ThomasRubini · Pull Request #14995 · cloudflare/workers-sdk

ThomasRubini · 2026-08-03T15:14:21Z

This PR adds a tcp_handlers config section, for the upcoming inbound TCP feature on Workers. It will configure workerd TCP listeners as implemented in cloudflare/workerd#6059

It would have to be set in the wrangler config like this:

{
	"tcp_handlers": [{
		"port": 5432,
		"address": "127.0.0.1", // default
	}],
}

I'd love feedback on the tcp_handlers name. Please also note that UDP handlers are planned, so if this name is merged, it would probably also mean adding a udp_handlers section in the future.

Tests
- Tests included/updated
- Automated tests not possible - manual testing has been completed as follows:
- Additional testing not necessary because:
Public documentation
- Cloudflare docs PR(s): Document connect() TCP inbound handler cloudflare-docs#32443
- Documentation not necessary because:

A picture of a cute animal (not mandatory, but encouraged)

changeset-bot · 2026-08-03T15:14:31Z

🦋 Changeset detected

Latest commit: 1cf6e86

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
wrangler	Minor
miniflare	Minor
@cloudflare/workers-utils	Minor
@cloudflare/vite-plugin	Patch
@cloudflare/vitest-pool-workers	Patch
@cloudflare/deploy-helpers	Patch
@cloudflare/pages-shared	Patch
@cloudflare/remote-bindings	Patch
@cloudflare/runtime-types	Patch
@cloudflare/autoconfig	Patch
@cloudflare/cli-shared-helpers	Patch
@cloudflare/workers-auth	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

workers-devprod · 2026-08-03T15:14:54Z

Codeowners approval required for this PR:

@cloudflare/wrangler

Show detailed file reviewers

.changeset/tcp-handlers.md: [@cloudflare/wrangler]
packages/miniflare/src/index.ts: [@cloudflare/wrangler]
packages/miniflare/src/plugins/core/index.ts: [@cloudflare/wrangler]
packages/miniflare/src/plugins/core/modules.ts: [@cloudflare/wrangler]
packages/miniflare/src/plugins/shared/constants.ts: [@cloudflare/wrangler]
packages/miniflare/src/runtime/config/generated/workerd.ts: [@cloudflare/wrangler]
packages/miniflare/src/runtime/config/workerd.ts: [@cloudflare/wrangler]
packages/miniflare/test/index.spec.ts: [@cloudflare/wrangler]
packages/vitest-pool-workers/src/pool/module-fallback.ts: [@cloudflare/wrangler]
packages/workers-utils/src/config/config.ts: [@cloudflare/wrangler]
packages/workers-utils/src/config/environment.ts: [@cloudflare/wrangler]
packages/workers-utils/src/config/validation.ts: [@cloudflare/wrangler]
packages/workers-utils/src/types.ts: [@cloudflare/wrangler]
packages/workers-utils/tests/config/validation/normalize-and-validate-config.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/type-generation.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/api/startDevWorker/ConfigController.ts: [@cloudflare/wrangler]
packages/wrangler/src/api/startDevWorker/LocalRuntimeController.ts: [@cloudflare/wrangler]
packages/wrangler/src/dev/miniflare/index.ts: [@cloudflare/wrangler]

pkg-pr-new · 2026-08-03T20:27:10Z

@cloudflare/autoconfig

npm i https://pkg.pr.new/@cloudflare/autoconfig@14995

@cloudflare/build-output-utils

npm i https://pkg.pr.new/@cloudflare/build-output-utils@14995

@cloudflare/config

npm i https://pkg.pr.new/@cloudflare/config@14995

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@14995

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@14995

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@14995

miniflare

npm i https://pkg.pr.new/miniflare@14995

@cloudflare/pages-functions

npm i https://pkg.pr.new/@cloudflare/pages-functions@14995

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@14995

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@14995

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@14995

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@14995

@cloudflare/workers-auth

npm i https://pkg.pr.new/@cloudflare/workers-auth@14995

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@14995

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@14995

wrangler

npm i https://pkg.pr.new/wrangler@14995

commit: 3bdb8ca

devin-ai-integration

Devin Review found 1 new potential issue.

View 3 additional findings in Devin Review.

devin-ai-integration · 2026-08-03T21:00:57Z

 	| { json?: string }
 	| { pythonModule?: string }
-	| { pythonRequirement?: string }
+	| { obsoletePythonRequirement?: string }


🟡 Hand-written runtime config types still expose a removed R2 admin option, which would crash config serialization if used

The hand-written runtime config type still advertises the removed R2 admin binding option (r2Admin at packages/miniflare/src/runtime/config/workerd.ts:116) even though the generated encoder for it was renamed away in this change, so any code that sets it would crash while building the runtime configuration instead of being rejected up front.
Impact: A stale, unusable option remains advertised to callers, and using it would abort local development startup rather than fail cleanly.

Rename applied to python requirements but not to the R2 admin field

The regenerated Cap'n Proto bindings renamed r2Admin to obsolete0 (packages/miniflare/src/runtime/config/generated/workerd.ts:2391-2415), removing _initR2Admin/set r2Admin. encodeCapnpStruct() (packages/miniflare/src/runtime/config/index.ts:21-49) dispatches dynamically by key: an object-valued r2Admin entry would call anyStruct["_initR2Admin"](), which is now undefined. The parallel rename for pythonRequirement → obsoletePythonRequirement was propagated to the hand-written types (packages/miniflare/src/runtime/config/workerd.ts:100), but r2Admin was left in both Worker_Binding and Worker_Binding_Type unions. No current call site sets r2Admin, so this is latent rather than actively broken.

Prompt for agents

The regenerated Cap'n Proto bindings in packages/miniflare/src/runtime/config/generated/workerd.ts renamed the `r2Admin` union member to `obsolete0` (and `pythonRequirement` to `obsoletePythonRequirement`). This PR updated the hand-written mirror types in packages/miniflare/src/runtime/config/workerd.ts for the python requirement rename, but left `r2Admin?: ServiceDesignator` in the `Worker_Binding` union and `r2Admin?: Void` in `Worker_Binding_Type`. Since encodeCapnpStruct() dispatches dynamically on object keys, a config containing `r2Admin` would attempt to call a now-nonexistent `_initR2Admin` and throw. Update the hand-written types so they match the generated schema (either rename to `obsolete0` or drop the member entirely), keeping the two files in sync as documented in packages/miniflare/CONTRIBUTING.md.

Was this helpful? React with 👍 or 👎 to provide feedback.

feat: implement tcp_handlers wrangler config section

a3c9dde

ThomasRubini requested a review from workers-devprod as a code owner August 3, 2026 15:14

workers-devprod requested review from a team and petebacondarwin and removed request for a team August 3, 2026 15:14

This comment was marked as resolved.

Sign in to view

ThomasRubini mentioned this pull request Aug 3, 2026

feat: add bindings for inbound connect() TCP handler cloudflare/workers-rs#1041

Draft

ThomasRubini added 2 commits August 3, 2026 17:55

chore: fix linting

01e5019

fix: rename pythonRequirement to obsoletePythonRequirement

3bdb8ca

This comment was marked as resolved.

Sign in to view

workers-devprod added this to workers-sdk Aug 3, 2026

github-project-automation Bot moved this to Untriaged in workers-sdk Aug 3, 2026

chore: fix linting

1cf6e86

devin-ai-integration Bot reviewed Aug 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[wrangler] add `tcp_handlers` wrangler config section - #14995

[wrangler] add `tcp_handlers` wrangler config section#14995
ThomasRubini wants to merge 4 commits into
cloudflare:mainfrom
ThomasRubini:feature/tcp-handlers

ThomasRubini commented Aug 3, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

workers-devprod commented Aug 3, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

pkg-pr-new Bot commented Aug 3, 2026

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

devin-ai-integration Bot Aug 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

workers-devprod commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

pkg-pr-new Bot commented Aug 3, 2026

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ThomasRubini commented Aug 3, 2026 •

edited

Loading

changeset-bot Bot commented Aug 3, 2026 •

edited

Loading

workers-devprod commented Aug 3, 2026 •

edited

Loading