Fetch function signature and return type
The fetch() function has the signature: fetch(resource, options optional) returns Promise<Response>. The resource parameter can be a Request, string, or URL. The options parameter is optional.
Cloudflare Workers · Runtime APIs · all subjects
bindings
175 notes in this subject, read out of this brain and free to use. This is page 3 of 3.
Fetch cache option values
The cache option in fetch accepts the following values: undefined (default), 'no-store', or 'no-cache'. Only cache: 'no-store' and cache: 'no-cache' are supported. Any other cache header value will result in a TypeError with message 'Unsupported cache mode: <attempted-cache-mode>'.
Fetch cache: 'no-store' behavior
For cache: 'no-store', requests to origins not hosted by Cloudflare bypass the use of Cloudflare's caches. For all requests, this forwards the Pragma: no-cache and Cache-Control: no-cache headers to the origin.
Fetch cache: 'no-cache' behavior
For cache: 'no-cache', requests to origins not hosted by Cloudflare are forced to revalidate with the origin before responding. For all requests, this forwards the Pragma: no-cache and Cache-Control: no-cache headers to the origin.
Accept-Encoding header handling for brotli compression
To support requesting brotli from the origin, you must enable the brotli_content_encoding compatibility flag in your Worker. Soon, this compatibility flag will be enabled by default for all Workers past an upcoming compatibility date. Workers supports both gzip and brotli compression algorithms.
Automatic compression behavior in Workers
In the Workers Runtime production environment, it is usually not necessary to specify Accept-Encoding or Content-Encoding headers. Brotli or gzip compression is automatically requested when fetching from an origin and applied to the response when returning data to the client, depending on the capabilities of the client and origin server.
Compressed response passthrough without recompression
If you do not read the body of a compressed response prior to returning it to the client and keep the Content-Encoding header intact, the compressed data will pass through without being decompressed and then recompressed again. This is useful when using Workers in front of origin servers or when fetching compressed media assets.
Recompression when encoding not supported by client
Recompression is needed when a response uses an encoding not supported by the client. For example, when a Worker requests brotli or gzip as the encoding but the client only supports gzip, recompression will be applied automatically if the server returns brotli-encoded data.
Passthrough fetch with Accept-Encoding and Content-Encoding headers example
This example shows how to pass through compressed data from a server to the client by preserving the original response body and Content-Encoding header: ```typescript export default { async fetch(request) { // Accept brotli or gzip compression const headers = new Headers({ "Accept-Encoding": "br, gzip", }); let response = await fetch("https://developers.cloudflare.com", { method: "GET", headers, }); // As long as the original response body is returned and the Content-Encoding header is // preserved, the same encoded data will be returned without needing to be compressed again. return new Response(response.body, { status: response.status, statusText: response.statusText, headers: response.headers, }); }, }; ```
Module Worker fetch syntax example
This example shows fetch usage in a Module Worker: ```js export default { async scheduled(controller, env, ctx) { return await fetch("https://example.com", { headers: { "X-Source": "Cloudflare-Workers", }, }); }, }; ```
Service Worker fetch syntax example
This example shows fetch usage in a Service Worker (deprecated but still supported): ```js addEventListener("fetch", (event) => { // NOTE: can't use fetch here, as we're not in an async scope yet event.respondWith(eventHandler(event)); }); async function eventHandler(event) { // fetch can be awaited here since `event.respondWith()` waits for the Promise it receives to settle const resp = await fetch(event.request); return resp; } ```
Python Worker fetch syntax example
This example shows fetch usage in a Python Worker: ```python from workers import WorkerEntrypoint, Response, fetch class Default(WorkerEntrypoint): async def scheduled(self, controller, env, ctx): return await fetch("https://example.com", headers={"X-Source": "Cloudflare-Workers"}) ```
node:net module for TCP socket connections
The node:net module can be used in Cloudflare Workers to create direct TCP socket connections to external servers using net.Socket. This module uses the connect functionality from the built-in cloudflare:sockets module.
net.Socket creation and connection example
Create a TCP socket connection using new net.Socket(), then call socket.connect(port, host, callback) to establish the connection, write data with socket.write(), and close with socket.end(). Example: import net from "node:net"; const exampleIP = "127.0.0.1"; export default { async fetch(req): Promise<Response> { const socket = new net.Socket(); socket.connect(4000, exampleIP, function () { console.log("Connected"); }); socket.write("Hello, Server!"); socket.end(); return new Response("Wrote to server", { status: 200 }); }, } satisfies ExportedHandler;
Supported net module APIs in Workers
The net.BlockList and net.SocketAddress APIs are available in Cloudflare Workers alongside net.Socket.
net.Server not supported in Workers
The net.Server class is not supported by Cloudflare Workers.
Error cause property not propagated in RPC
Own properties of error objects, such as the `cause` property, are not propagated back to the caller in RPC.
RPC exception propagation with standard JavaScript Error types
When a standard JavaScript Error type is thrown by an RPC method implementation, it propagates to the caller. The `message` and the prototype's `name` are retained, but the stack trace is not propagated.
AggregateError not propagated in RPC
If an AggregateError is thrown by an RPC method, it is not propagated back to the caller.
SuppressedError not supported in Workers RPC
The SuppressedError type from the Explicit Resource Management proposal is not currently implemented or supported in Workers.
Runtime-set properties on remote exceptions
For some remote exceptions, the runtime may set properties on the propagated exception to provide more information about the error. See Durable Object error handling for more details.
RPC compatibility date requirement
To use RPC, define a compatibility date of 2024-04-03 or higher, or include 'rpc' in your compatibility flags.
RPC allows calling Worker methods via Service Bindings
Workers provide a built-in JavaScript-native RPC system allowing you to define public methods on your Worker that can be called by other Workers on the same Cloudflare account via Service Bindings, and to define public methods on Durable Objects that can be called by other workers on the same Cloudflare account that declare a binding to it.
All RPC calls are asynchronous
Whether or not the method being called was declared asynchronous on the server side, it will behave as asynchronous on the client side. You must await the result. RPC calls do not actually return Promises, but return a type that behaves like a Promise called a 'custom thenable', which implements the then() method.
Structured Cloneable types supported in RPC
Nearly all types that are Structured Cloneable can be used as a parameter or return value of an RPC method, including basic value types in JavaScript such as objects, arrays, strings, and numbers. As an exception to Structured Clone, application-defined classes or objects with custom prototypes cannot be passed over RPC, except when they extend RpcTarget.
Non-Structured Cloneable types supported in RPC
The RPC system supports several types that are not Structured Cloneable: Functions, which are replaced by stubs that call back to the sender; Application-defined classes that extend RpcTarget, which are similarly replaced by stubs; ReadableStream and WriteableStream with automatic streaming flow control; Request and Response for representing HTTP messages; and RPC stubs themselves, even if the stub was received from a third Worker.
Functions can be sent over RPC
You can send a function over RPC. When you do so, the function is replaced by a stub. The recipient can call the stub like a function, but doing so makes a new RPC call back to the place where the function originated. Functions can be returned from RPC methods or sent as parameters, enabling the server to call back to the client.
RpcTarget class for custom class instances
To use an instance of a class as a parameter or return value of an RPC method, the class must extend the built-in RpcTarget class. The object itself is not serialized but is replaced by a stub. Calling any method on the stub actually makes an RPC call back to the original object where it was created.
Accessing properties on RPC stubs
You can access properties of classes that extend RpcTarget. Properties behave like RPC methods that don't take any arguments — you await the property to asynchronously fetch its current value. The act of awaiting the property (which calls .then() on it) is what causes the property to be fetched. If you do not use await when accessing the property, it will not be fetched.
Class instances more efficient than objects with functions
Returning a class instance that extends RpcTarget is more efficient than returning a plain object containing many functions. If you return an object containing five functions, you create five stubs. If you return a class instance with five methods, you only return a single stub. Returning a single stub is often more efficient and easier to reason about.
Promise pipelining reduces round trips
When calling an RPC method that returns an object, you can omit the first await to avoid multiple round trips. By not awaiting the initial call, you can initiate speculative calls on the future result of the promise. These calls are sent to the server immediately without waiting for the initial call to complete, allowing multiple chained calls to be completed in a single round trip. This is called promise pipelining.
RPC promises are custom thenables not real Promises
The promise returned by an RPC call is not a real JavaScript Promise but a custom thenable. It has a .then() method like Promise, allowing it to be used wherever you'd use a normal Promise and can be awaited. In addition to .then(), an RPC promise acts like a stub and allows speculative calls on the promise's eventual result through promise pipelining.
ReadableStream and WriteableStream in RPC
You can send and receive ReadableStream and WriteableStream using RPC methods. When doing so, bytes in the body are automatically streamed with appropriate flow control, allowing you to send messages over RPC larger than the typical 32 MiB limit. Only byte-oriented streams with an underlying byte source of type 'bytes' are supported.
Request and Response in RPC
You can send and receive Request and Response objects using RPC methods. Bytes in the body are automatically streamed with appropriate flow control, allowing you to send messages over RPC larger than the typical 32 MiB limit. Ownership of the stream is transferred to the recipient, and the sender can no longer read/write the stream after sending it.
Stream ownership transfer in RPC
In all cases of sending streams, Request, or Response over RPC, ownership is transferred to the recipient. The sender can no longer read/write the stream after sending it. If the sender wishes to keep its own copy, it can use the tee() method of ReadableStream or the clone() method of Request or Response. However, doing this may force the system to buffer bytes and lose the benefits of flow control.
Forwarding RPC stubs between Workers
A stub received over RPC from one Worker can be forwarded over RPC to another Worker. When ANOTHER_SERVICE calls a method on a stub passed to it, the call will automatically be proxied through the introducer Worker and on to the RpcTarget class implemented by the original service. In this way, the introducer Worker can connect two Workers that did not otherwise have any ability to form direct connections to each other.
RPC proxy connection persistence
When forwarding RPC stubs between Workers, the proxying only lasts until the end of the Workers' execution contexts. A proxy connection cannot be persisted for later use.
RPC Smart Placement limitation
Smart Placement is currently ignored when making RPC calls. If Smart Placement is enabled for Worker A and Worker B declares a Service Binding to it, when Worker B calls Worker A via RPC, Worker A will run locally on the same machine.
RPC 32 MiB serialization limit
The maximum serialized RPC limit is 32 MiB. When returning more data, consider using ReadableStream for streaming the data from its original source, which yields better performance than buffering large amounts of data into memory.
RPC method example with Counter class
Example showing a Counter class extending RpcTarget with increment method and value property, exposed via a CounterService WorkerEntrypoint. The client calls newCounter() to get a Counter instance, then calls increment(amount) multiple times and reads the value property. Methods are awaited as they return promises.
Promise pipelining example
When calling getCounter() and immediately calling increment() on the result, omit the first await to combine calls into a single round trip: `using promiseForCounter = env.COUNTER_SERVICE.getCounter(); await promiseForCounter.increment();` This avoids two separate round trips and sends both calls to the server immediately.
Promise pipelining with nested properties
Promise pipelining works when calling properties of objects returned by RPC methods. Example: `using foo = env.MY_SERVICE.foo(); let baz = await foo.bar.baz();` This initiates speculative calls on the future result, completing multiple chained property accesses and method calls in a single round trip.
RPC exception propagation in pipelined calls
If the initial RPC call ends up throwing an exception, then any pipelined calls will also fail with the same exception.
Using declaration for resource management in RPC
The JavaScript/TypeScript example uses the `using` declaration (e.g., `using counter = await env.COUNTER_SERVICE.newCounter()`) for explicit resource management when working with RPC stubs. This relates to the RPC lifecycle and resource cleanup patterns.
ReadableStream byte stream requirement for RPC
Only byte-oriented streams (streams with an underlying byte source of type 'bytes') are supported for RPC. This restriction applies to both ReadableStream and WriteableStream sent over RPC.
DurableObjectNamespace type parameter in generated env
The DurableObjectNamespace type in the generated env accepts an import statement to the Durable Object implementation type. For example, DurableObjectNamespace<import("../counter/src/index").Counter> creates a typed binding to a Durable Object.
Workers RPC security model based on Object Capabilities
Workers RPC uses a capability-based security model, commonly known as Object Capabilities, to allow safe communications between Workers that do not trust each other. The system is built on Cap'n Proto RPC, which is based on CapTP, the object transport protocol used by the distributed programming language E. Neither side of an RPC session can access arbitrary objects on the other side or invoke arbitrary code. Each side can only invoke objects and functions for which they have explicitly received stubs via previous calls.
Private properties not exposed over RPC
Private properties of classes, denoted with the `#` prefix, are not directly exposed over RPC.
Arrow functions not exposed over RPC
Arrow function expressions are not exposed over RPC because they are defined on class instances, not on the class prototype. Arrow functions should not be used as class methods of WorkerEntrypoint classes.
Function own properties exposure over RPC
When passing a function over RPC, own properties attached to the function object are visible to the caller. For example, in `someRpcMethod() { let func = () => {}; func.prop = 123; return func; }`, the `prop` property with value 123 is visible over RPC.
Class instance properties not accessible over RPC
When you send an instance of an application-defined class over RPC, the recipient can only access methods and properties declared on the class, not properties of the instance. Instance properties should be declared private with the `#` prefix. Since the RPC interface between Workers may be a security boundary, instance properties are always private when communicating between Workers using RPC, whether or not they have the `#` prefix. You can declare an explicit getter at the class level if you wish to expose the property.
Plain objects passed by value over RPC
Visibility rules for private properties and instance properties apply only to objects that extend RpcTarget, WorkerEntrypoint, or DurableObject. Plain objects are passed by value, sending all of their own properties over RPC.
Own properties of functions accessible over RPC
When you pass a function over RPC, the caller can access the own properties of the function object itself. Such properties on a function are accessed asynchronously, like class properties of an RpcTarget. Unlike RpcTarget examples, the function's instance properties are accessible to the caller. In practice, properties are rarely added to functions.
Class property and method accessibility over RPC
For a class extending RpcTarget: instance properties like `this.i = 0` cannot be accessed over RPC, instance function properties like `this.funcProp = () => {}` cannot be called over RPC, getter properties declared on the class like `get value() { return this.i; }` can be accessed over RPC, and class methods like `method() {}` can be called over RPC.
WorkerEntrypoint RPC visibility example
When implementing a WorkerEntrypoint class for RPC, methods defined on the class prototype using regular function syntax are exposed over RPC, while arrow function properties defined on the instance are not exposed. In the example: `add(a, b) { return a + b; }` is exposed over RPC, but `subtract = (a, b) => a - b;` is NOT exposed over RPC.