Skip to content

Add WorkerdDebugPort interface for dynamic RPC entrypoint access#5568

Merged
danlapid merged 4 commits intomainfrom
dlapid/debug_port
Dec 4, 2025
Merged

Add WorkerdDebugPort interface for dynamic RPC entrypoint access#5568
danlapid merged 4 commits intomainfrom
dlapid/debug_port

Conversation

@danlapid
Copy link
Copy Markdown
Collaborator

Introduces a new privileged debug port interface that enables dynamic access to worker entrypoints at runtime.

Currently, service bindings between workerd processes must be configured at startup in the config file. Changing binding targets requires a full process restart. This is problematic for local development tools like Miniflare, which need to dynamically re-target RPC connections at runtime.

Today, Miniflare works around this by running a Node.js TCP server that sits between workerd processes and manually re-routes RPC traffic. This adds significant complexity and overhead.

This commit implements the WorkerdDebugPort interface which exposes all service entrypoints in a process through a privileged RPC interface. External tools can now:

  • Get direct access to any entrypoint with custom props at runtime
  • Start events and invoke methods via JS RPC without HTTP overhead
  • Dynamically switch between entrypoints without process restarts

This enables Miniflare to eliminate its TCP proxy layer and handle dynamic RPC routing natively through workerd.

interface WorkerdDebugPort {
  getEntrypoint(service, entrypoint, props) -> (worker)
  getActor(service, entrypoint, actorId) -> (actor);
}

🤖 Generated with Claude Code

@danlapid danlapid requested a review from penalosa November 21, 2025 17:46
@danlapid danlapid force-pushed the dlapid/debug_port branch 2 times, most recently from ffbdd7c to df9b629 Compare November 21, 2025 17:59
@codspeed-hq
Copy link
Copy Markdown

codspeed-hq bot commented Nov 21, 2025

CodSpeed Performance Report

Merging #5568 will degrade performances by 10.73%

Comparing dlapid/debug_port (1ad5b60) with main (c5836a3)

Summary

❌ 1 regression
✅ 56 untouched
⏩ 30 skipped1

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Benchmarks breakdown

Benchmark BASE HEAD Change
Encode_ASCII_256[TextEncoder][0/0/256] 3.2 ms 3.6 ms -10.73%

Footnotes

  1. 30 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

@github-actions
Copy link
Copy Markdown

github-actions bot commented Nov 21, 2025

The generated output of @cloudflare/workers-types matches the snapshot in types/generated-snapshot 🎉

@danlapid danlapid marked this pull request as ready for review November 21, 2025 19:24
@danlapid danlapid requested review from a team as code owners November 21, 2025 19:24
@danlapid danlapid requested a review from kentonv November 21, 2025 19:24
@danlapid danlapid force-pushed the dlapid/debug_port branch 3 times, most recently from 9389f13 to 452a4c4 Compare November 21, 2025 23:45
@danlapid danlapid force-pushed the dlapid/debug_port branch 4 times, most recently from 3be2c9e to c6916af Compare December 3, 2025 13:50
@danlapid
Copy link
Copy Markdown
Collaborator Author

danlapid commented Dec 3, 2025

@kentonv I think this PR should be ready for another round of reviews.
The slight refactor you requested was addressed without any functional changes in 039c4b5 in order to make review of it easier.
The rest of the review comments were addressed in c6916af

Thanks!

danlapid and others added 3 commits December 3, 2025 21:04
Introduces a new privileged debug port interface that enables dynamic
access to worker entrypoints at runtime.

Currently, service bindings between workerd processes must be configured
at startup in the config file. Changing binding targets requires a full
process restart. This is problematic for local development tools like
Miniflare, which need to dynamically re-target RPC connections at runtime.

Today, Miniflare works around this by running a Node.js TCP server that
sits between workerd processes and manually re-routes RPC traffic. This
adds significant complexity and overhead.

This commit implements the WorkerdDebugPort interface which exposes all
service entrypoints in a process through a privileged RPC interface.
External tools can now:

- Get direct access to any entrypoint with custom props at runtime
- Start events and invoke methods via JS RPC without HTTP overhead
- Dynamically switch between entrypoints without process restarts

This enables Miniflare to eliminate its TCP proxy layer and handle
dynamic RPC routing natively through workerd.

```
interface WorkerdDebugPort {
  getEntrypoint(service, entrypoint, props) -> (worker)
  getActor(service, entrypoint, actorId) -> (actor);
}
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@danlapid
Copy link
Copy Markdown
Collaborator Author

danlapid commented Dec 3, 2025

Last change is just a rebase to pick up the wpt test fix.

@danlapid
Copy link
Copy Markdown
Collaborator Author

danlapid commented Dec 3, 2025

@kentonv applied latest round of review comments in 1ad5b60

Nothing controversial and you approved so I'll enable auto-merge.

@danlapid danlapid enabled auto-merge (squash) December 3, 2025 21:31
@danlapid danlapid disabled auto-merge December 4, 2025 00:03
@danlapid danlapid merged commit 5c454bb into main Dec 4, 2025
20 of 22 checks passed
@danlapid danlapid deleted the dlapid/debug_port branch December 4, 2025 00:04
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.

2 participants