Skip to content

feat: add custom fetch option to newHttpBatchRpcSession - #285

Open
harshbhx wants to merge 1 commit into
cloudflare:mainfrom
harshbhx:feat/66-custom-fetch
Open

harshbhx wants to merge 1 commit into
cloudflare:mainfrom
harshbhx:feat/66-custom-fetch

Conversation

@harshbhx

Copy link
Copy Markdown

Fixes #66

Summary

newHttpBatchRpcSession() now accepts an optional fetch function in its options and uses it instead of the global fetch() to send the batch.

Problem

The batch client always calls the global fetch, so there is no supported way to send a batch through a VPC or service binding (they expose their own fetch). The workaround in the issue is to overwrite globalThis.fetch temporarily, and new Request(url, { fetcher }) relies on an old undocumented runtime API that only works with the built-in Fetcher type. Kenton agreed a custom fetch in options makes sense.

Solution

Add HttpBatchRpcSessionOptions = RpcSessionOptions & { fetch?: typeof fetch } and use it only for newHttpBatchRpcSession. fetch is looked up at send time with options?.fetch ?? fetch, so the default is still the global fetch, exactly as before.

Design choice: I put the option on a dedicated options type rather than on RpcSessionOptions, because the other transports (WebSocket, MessagePort, custom) never call fetch, and the shared type would suggest otherwise. It is a superset of RpcSessionOptions, so existing calls still type-check. Happy to move it onto RpcSessionOptions if you prefer.

The function is called unbound as fetch(urlOrRequest, init), so a method like env.VPC.fetch needs a wrapper ((input, init) => env.VPC.fetch(input, init)); the docs example shows this.

Changes

File Change
src/batch.ts New HttpBatchRpcSessionOptions; use options.fetch when present
src/index.ts Export the type; update the newHttpBatchRpcSession signature and JSDoc
__tests__/index.test.ts Tests: custom fetch is used (global fetch replaced with a throwing stub), and the global fetch is still the default
packages/docs/src/content/docs/transports/http-batch.mdx "Custom fetch" section
.changeset/http-batch-custom-fetch.md Minor changeset for capnweb

Before / After

// Before: only the global fetch
using stub = newHttpBatchRpcSession<Api>(url);

// After
using stub = newHttpBatchRpcSession<Api>(url, {
  fetch: (input, init) => env.VPC.fetch(input, init),
});

How to test

  1. pnpm install && pnpm test and look at the "HTTP requests" tests.
  2. Remove the options?.fetch ?? part in src/batch.ts: "sends the batch using a custom fetch function from options" fails.

Testing done

  • New tests in __tests__/index.test.ts (custom fetch used and called once with POST; global fetch default preserved).
  • CI on my fork (docs build, markdown lint, full vitest, bun tests, type tests): green, 1457/1457 vitest tests, 34 files: https://github.com/harshbhx/capnweb/actions/runs/39424986018
  • Not run locally (2-CPU machine), only fork CI.
  • Not tested against a real Workers VPC or service binding; the test uses a plain wrapper around the global fetch.
  • No type-level test for the new option beyond the compile of the new tests.

Notes for reviewers

Backwards compatible: options without fetch behaves as before. Also happy to add the option to the API reference table if wanted.

@changeset-bot

changeset-bot Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 9a5dd40

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

This PR includes changesets to release 1 package
Name Type
capnweb Minor

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

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

@clanky-the-clanker

clanky-the-clanker Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

✅ Approved — Small, backwards-compatible addition of an optional fetch to newHttpBatchRpcSession, with tests, docs and a changeset. No issues found.

The decision is advisory: this comment never approves, blocks or requests changes on the pull request.


✅ All checks passed

📋 Code Quality: ✅ LGTM

This change is safe to merge as it is.

  • Default unchanged: options?.fetch ?? fetch runs when each batch is sent, so when no fetch option is given, the global fetch is used exactly as before.
  • Existing code still compiles: HttpBatchRpcSessionOptions is RpcSessionOptions with one optional field added. Existing calls still type-check, and RpcSessionOptions is already imported in src/batch.ts (line 6).
  • Tests: the new tests cover two cases: a custom fetch is used, and the global fetch is still the default. Both tests put globalThis.fetch back in a finally block.
  • Changeset: it is marked minor, which fits a new feature.

📝 Documentation: ✅ LGTM

The new "Custom fetch" section in http-batch.mdx is clear. Its example wraps the binding's method, (input, init) => env.VPC.fetch(input, init), which matches how the code calls the function: on its own, without a this binding. The JSDoc on the new option says the same thing.


Reviewed commit: c06f4e66

@harshbhx

Copy link
Copy Markdown
Author

I have read the CLA Document and I hereby sign the CLA

github-actions Bot added a commit that referenced this pull request Oct 20, 2026
@ndisidore

Copy link
Copy Markdown
Member

clanky review

Lets callers pass a fetch function in the options, used instead of the
global fetch to send the batch (e.g. a VPC or service binding).
@harshbhx
harshbhx force-pushed the feat/66-custom-fetch branch from c06f4e6 to 9a5dd40 Compare November 22, 2026 15:12
@pkg-pr-new

pkg-pr-new Bot commented Nov 22, 2026

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/capnweb@285
npm i https://pkg.pr.new/cloudflare/capnweb/capnweb-validate@285

commit: 9a5dd40

@ndisidore ndisidore left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

few notes inline. also reference/api.mdx still says every session helper takes RpcSessionOptions and doesnt mention fetch, worth updating here

Comment thread src/batch.ts
* fetch function, such as a VPC or service binding (pass e.g.
* `(input, init) => env.VPC.fetch(input, init)`), or for instrumenting requests.
*/
fetch?: typeof fetch;

@ndisidore ndisidore Nov 22, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

typeof fetch breaks with Bun types loaded (its fetch requires preconnect), so a plain wrapper fails with TS2741. the test below hits it too, CI just doesnt typecheck it. maybe:

fetch?: (input: string | Request, init?: RequestInit) => Promise<Response>

Comment thread src/batch.ts
let response = await fetch(urlOrRequest, {
// Look up the global `fetch` at send time (not at session creation) so that it behaves as it
// did before this option existed.
let fetchFunc = options?.fetch ?? fetch;

@ndisidore ndisidore Nov 22, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

called unbound, so { fetch: env.VPC.fetch } typechecks but throws Illegal invocation in workerd, which is the #66 use case. could also accept a { fetch } object and call it as a method?

Comment thread __tests__/index.test.ts
.toStrictEqual([36, 5, 9]);
});

it("sends the batch using a custom fetch function from options", async () => {

@ndisidore ndisidore Nov 22, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

these only wrap global fetch, the binding path isnt covered. workerd.test.ts already has env.testServer (~L461) so a test there would be cheap

Comment thread __tests__/index.test.ts
let url = `http://${inject("testServerHost")}`;
let originalFetch = globalThis.fetch;
let calls = 0;
globalThis.fetch = <any>((input: any, init?: RequestInit) => {

@ndisidore ndisidore Nov 22, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

swapping globalThis.fetch seems flaky, any stray fetch fails the toBe(1). a recording custom fetch or vi.spyOn filtered by URL would be sturdier

Comment thread src/index.ts
@@ -142,9 +143,12 @@ export let newWebSocketRpcSession:<T extends RpcCompatible<T> = Empty>
* The parameters to this method have exactly the same signature as `fetch()`, but the return

@ndisidore ndisidore Nov 22, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

nit, pre-existing: this still says "exactly the same signature as fetch()" which the new paragraph contradicts (2nd arg is session options, not RequestInit)

This branch has not been deployed

No deployments
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.

optional custom fetch implementation

2 participants