Skip to content

Commit a3636d2

Browse files
kentonvkentonv
committed
WIP: dynamic loader docs
1 parent 03d811a commit a3636d2

File tree

3 files changed

+322
-3
lines changed

3 files changed

+322
-3
lines changed

‎src/content/docs/durable-objects/api/state.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,11 @@ export class MyDurableObject extends DurableObject {
4949

5050
</TabItem> </Tabs>
5151

52-
## Methods
52+
## Methods and Properties
53+
54+
### `exports`
55+
56+
Contains loopback bindings to the Worker's own top-level exports. This has exactly the same meaning as [`ExecutionContext`'s `ctx.exports`](/workers/runtime-apis/context/#exports).
5357

5458
### `waitUntil`
5559

‎src/content/docs/workers/runtime-apis/bindings/worker-loader.mdx‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
pcx_content_type: configuration
3+
title: Dynamic Worker Loaders
4+
head: []
5+
description: The Dynamic Worker Loader API, which allows dynamically spawning isolates that run arbitrary code.
6+
7+
---
8+
9+
import {
10+
Type,
11+
MetaInfo
12+
} from "~/components";
13+
14+
:::note[Dynamic Worker Loading is in closed beta]
15+
16+
The Worker Loader API is available in local development with Wrangler and workerd. But, to use it in production, you must [sign up for the closed beta](TODO: Link to sign-up form).
17+
18+
:::
19+
20+
A Worker Loader binding allows you to load additional Workers containing arbiratry code at runtime.
21+
22+
An isolate is like a lightweight container. [The Workers platform uses isolates instead of containers or VMs](/workers/reference/how-workers-works/), so every Worker runs in an isolate already. But, a Worker Loader binding allows your Worker to create additional isolates that load arbitrary code on-demand.
23+
24+
Isolates are much cheaper than containers. You can start an isolate in milliseconds, and it's fine to start one just to run a snippet of code and immediately throw away. There's no need to worry about pooling isolates or trying to reuse already-warm isolates, as you would need to do with containers.
25+
26+
Worker Loaders also enable **sandboxing** of code, meaning that you can strictly limit what the code is allowed to do. In particular:
27+
* You can arrange to intercept or simply block all network requests made by the Worker within.
28+
* You can supply the sandboxed Worker with custom bindings to represent specific resources which it should be allowed to access.
29+
30+
With proper sandboxing configured, you can safely run code you do not trust in a dynamic isolate.
31+
32+
A Worker Loader is a binding with just one method, `get()`, which loads an isolate. Example usage:
33+
34+
```js
35+
let id = "foo";
36+
37+
// Get the isolate with the given ID, creating it if no such isolate exists yet.
38+
let worker = env.LOADER.get(id, async () => {
39+
// If the isolate does not already exist, this callback is invoked to fetch
40+
// the isolate's Worker code.
41+
42+
return {
43+
compatibilityDate: "2025-06-01",
44+
45+
// Specify the worker's code (module files).
46+
mainModule: "foo.js",
47+
modules: {
48+
"foo.js":
49+
"export default {\n" +
50+
" fetch(req, env, ctx) { return new Response('Hello'); }\n" +
51+
"}\n",
52+
},
53+
54+
// Specify the dynamic Worker's environment (`env`). This is specified
55+
// as a JavaScript object, exactly as you want it to appear to the
56+
// child Worker. It can contain basic serializable types as well as
57+
// Service Bindings (see below).
58+
env: {
59+
SOME_ENV_VAR: 123
60+
},
61+
62+
// To block the worker from talking to the internet using `fetch()` or
63+
// `connect()`, set `globalOutbound` to `null`. You can also set this
64+
// to any service binding, to have calls be intercepted and redirected
65+
// to that binding.
66+
globalOutbound: null,
67+
};
68+
});
69+
70+
// Now you can get the Worker's entrypoint and send requests to it.
71+
let defaultEntrypoint = worker.getEntrypoint();
72+
await defaultEntrypoint.fetch("http://example.com");
73+
74+
// You can get non-default entrypoints as well, and specify the
75+
// `ctx.props` value to be delivered to the entrypoint.
76+
let someEntrypoint = worker.getEntrypoint("SomeEntrypointClass", {
77+
props: {someProp: 123}
78+
});
79+
```
80+
81+
## API Reference
82+
83+
### `get`
84+
85+
<code>get(id <Type text="string" />, getCodeCallback <Type text="() => Promise<WorkerCode>" />): <Type text="WorkerStub" /></code>
86+
87+
Loads a Worker with the given ID.
88+
89+
As a convenience, the loader implements basic caching of isolates: If this loader has alerady been used to load a Worker with the same ID in the past, and that Worker's isolate is still resigent in memory, then the existing Worker will be returned, and the callback will not be called. When an isolate has not been used in a while, the system will discard it automatically, and then the next attempt to get the same ID will have to load it again. If you frequently run the same code, you should use the same ID in order to get automatic caching. On the other hand, if the code you load is different every time, you can provide a random ID. Note that if your code has many versions, each version will need a unique ID, as there is no way to explicitly evict a previous version.
90+
91+
If the system opts not to reuse an existing Worker, then it invokes `codeCallback` to get the Worker's code. This is an async callback, so the application can load the code from remote storage if desired. The callback returns a `WorkerCode` object (described below).
92+
93+
`get()` returns a `WorkerStub`, which can be used to send requests to the loaded Worker. Note that the stub is returned synchronously&mdash;you do not have to await it. If the Worker is not loaded yet, requests made to the stub will wait for the Worker to load before being delivered. If loading fails, the request will throw an exception.
94+
95+
### `WorkerCode`
96+
97+
This is the structure returned by `getCodeCallback` to rerpesent a worker.
98+
99+
#### <code>compatibilityDate <Type text="string" /></code>
100+
101+
The [compatibility date](/workers/configuration/compatibility-dates/) for the Worker. This has the same meaning as the `compatibility_date` setting in a Wrangler config file.
102+
103+
#### <code>compatibilityFlags <Type text="string[]" /> <MetaInfo text='Optional' /></code>
104+
105+
An optional list of [compatibility flags](/workers/configuration/compatibility-flags) augmenting the compatibility date. This has the same meaning as the `compatibility_flags` setting in a Wrangler config file.
106+
107+
#### <code>allowExperimental <Type text="boolean" /> <MetaInfo text='Optional' /></code>
108+
109+
If true, then experimental compatibility flags will be permitted in `compatibilityFlags`. In order to set this, the worker calling the loader must itself have the compatibiltiy flag `"experimental"` set. Experimental flags cannot be enabled in production.
110+
111+
#### <code>mainModule <Type text="string" /></code>
112+
113+
The name of the Worker's main module. This must be one of the modules listed in `modules`.
114+
115+
#### <code>modules <Type text="Record<string, string | Module>"/></code>
116+
117+
A dictionary object mapping module names to their string contents. If the module content is a plain string, then the module name must have a file extension indicating its type: either `.js` or `.py`.
118+
119+
A module's content can also be specified as an object, in order to specify its type indepnedent from the name. The allowed objects are:
120+
121+
* `{js: string}`: A JavaScript module, using ES modules syntax for imports and exports.
122+
* `{cjs: string}`: A CommonJS module, using `require()` syntax for imports.
123+
* `{py: string}`: A [Python module](/workers/languages/python/), but see the warning below.
124+
* `{text: string}`: An importable string value.
125+
* `{data: ArrayBuffer}`: An importable `ArrayBuffer` value.
126+
* `{json: object}`: An importable object. The value must be JSON-serializable. However, note that value is provided as a parsed object, and is delivered as a parsed object; neither side actually sees the JSON serialization.
127+
128+
:::caution[Warning]
129+
130+
While Dynamic Isolates support Python, please note that at this time, Python Workers are much slower to start than JavaScript Workers, which may defeat some of the benefits of dynamic isolate loading. They may also be priced differently, when Worker Loaders become generally available.
131+
132+
:::
133+
134+
#### <code>globalOutbound <Type text="ServiceStub | null" /> Optional</code>
135+
136+
Controls whether the dynamic Worker has access to the network. The global `fetch()` and `connect()` functions (for making HTTP requests and TCP connections, respectively) can be blocked or redirected to isolate the Worker.
137+
138+
If `globalOutbound` is not specified, the default is to inherit the parent's network access, which usually means the dynamic Worker will have full access to the public Internet.
139+
140+
If `globalOutbound` is `null`, then the dynamic Worker will be totally cut off from the network. Both `fetch()` and `connect()` will throw exceptions.
141+
142+
`globalOutbound` can also be set to any serivce binding, including service bindings in the parent worker's `env` as well as [loopback bindings from `ctx.exports`](/workers/runtime-apis/context/#exports).
143+
144+
Using `ctx.exports` is particularly useful as it allows you to customize the binding further for the specific sandbox, by setting the value of `ctx.props` that should be passed back to it. The `props` can contain information to identify the specific dynamic Worker that made the request.
145+
146+
For exmaple:
147+
148+
```js
149+
import { WorkerEntrypoint } from "cloudflare:workers";
150+
151+
export class Greeter extends WorkerEntrypoint {
152+
fetch(request) {
153+
return new Response(`Hello, ${this.ctx.props.name}!`);
154+
}
155+
}
156+
157+
export default {
158+
async fetch(request, env, ctx) {
159+
let worker = env.LOADER.get("alice", () => {
160+
return {
161+
// Redirect the worker's global outbound to send all requests
162+
// to the `Greeter` class, filling in `ctx.props.name` with
163+
// the name "Alice", so that it always responds "Hello, Alice!".
164+
globalOutbound: ctx.exports.Greeter({props: {name: "Alice"}})
165+
166+
// ... code ...
167+
}
168+
});
169+
}
170+
}
171+
```
172+
173+
#### <code>env <Type text="object" /></code>
174+
175+
The environment object to provide to the dynamic Worker.
176+
177+
Using this, you can provide custom bindings to the Worker.
178+
179+
`env` is serialized and transferred into the dynamic Worker, where it is used directly as the value of `env` there. It may contain:
180+
181+
* [Structured clonable types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
182+
* [Service Bindings](/workers/runtime-apis/bindings/service-bindings), including [loopback bindings from `ctx.exports`](/workers/runtime-apis/context/#exports).
183+
184+
The second point is the key to creating custom bindings: you can define a binding with any arbitrary API, by defining a [`WorkerEntrypoint` class](/workers/runtime-apis/bindings/service-bindings/rpc) implementing an RPC API, and then giving it to the dynamic Worker as a Service Binding.
185+
186+
Moreover, by using `ctx.exports` loopback bindings, you can further customize the bindings for the specific dynamic Worker by setting `ctx.props`, just as described for `globalOutbound`, above.
187+
188+
```js
189+
import { WorkerEntrypoint } from "cloudflare:workers";
190+
191+
// Implement a binding which can be called by the dynamic Worker.
192+
export class Greeter extends WorkerEntrypoint {
193+
greet() {
194+
return `Hello, ${this.ctx.props.name}!`;
195+
}
196+
}
197+
198+
export default {
199+
async fetch(request, env, ctx) {
200+
let worker = env.LOADER.get("alice", () => {
201+
return {
202+
env {
203+
// Provide a binding which has a method greet() which can be called
204+
// to receive a greeting. The binding knows the Worker's name.
205+
GREETER: ctx.exports.Greeter({props: {name: "Alice"}})
206+
}
207+
208+
// ... code ...
209+
}
210+
});
211+
}
212+
}
213+
```

‎src/content/docs/workers/runtime-apis/context.mdx‎

Lines changed: 104 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,119 @@
22
pcx_content_type: configuration
33
title: Context (ctx)
44
head: []
5-
description: The Context API in Cloudflare Workers, including waitUntil and
5+
description: The Context API in Cloudflare Workers, including props, exports, waitUntil and
66
passThroughOnException.
77

88
---
99

10+
import { WranglerConfig } from "~/components";
11+
1012
The Context API provides methods to manage the lifecycle of your Worker or Durable Object.
1113

1214
Context is exposed via the following places:
1315

1416
* As the third parameter in all [handlers](/workers/runtime-apis/handlers/), including the [`fetch()` handler](/workers/runtime-apis/handlers/fetch/). (`fetch(request, env, ctx)`)
15-
* As a class property of the [`WorkerEntrypoint` class](/workers/runtime-apis/bindings/service-bindings/rpc)
17+
* As a class property of the [`WorkerEntrypoint` class](/workers/runtime-apis/bindings/service-bindings/rpc) (`this.ctx`)
18+
19+
Note that the Context API is available strictly in stateless contexts, that is, not [Durable Objects](/durable-objects/). However, Durable Objects have a different object, the [Durable Object State](/durable-objects/api/state/), which is available as `this.ctx` inside a Durable Object class, and provides some of the same functionality as the Context API.
20+
21+
## `props`
22+
23+
`ctx.props` provides a way to pass additional configuration to a worker based on the context in which it was invoked. For example, when your Worker is called by another Worker, `ctx.props` can provide information about the calling worker.
24+
25+
For example, imagine that you are configuring a Worker called "frontend-worker", which must talk to another Worker called "doc-worker" in order to manipulate documents. You might configure "frontend-worker" with a [Service Binding](/workers/runtime-apis/bindings/service-bindings) like:
26+
27+
<WranglerConfig>
28+
29+
```toml
30+
[[services]]
31+
binding = "DOC_SERVICE"
32+
service = "doc-worker"
33+
entypoint = "DocServiceApi"
34+
props = { clientId = "frontend-worker", permissions = ["read", "write"] }
35+
```
36+
37+
</WranglerConfig>
38+
39+
Now frontend-worker can make calls to doc-worker with code like `env.DOC_SERVICE.getDoc(id)`. This will make a [Remote Procedure Call](/workers/runtime-apis/rpc/) invoking the method `getDoc()` of the class `DocServiceApi`, a [`WorkerEntrypoint` class](/workers/runtime-apis/bindings/service-bindings/rpc) exported by doc-worker.
40+
41+
The coniguration contains a `props` value. This in an arbitrary JSON value. When the `DOC_SERVICE` binding is used, the `DocServiceApi` instance receiving the call will be able to access this `props` value as `this.ctx.props`. Here, we've configured `props` to specify that the call comes from frontend-worker, and that it should be allowed to read and write documents. However, the contents of `props` can be anything you want.
42+
43+
The Workers platform is designed to ensure that `ctx.props` can only be set by someone who has permission to edit and deploy the worker to which it is being delivered. This means that you can trust that the content of `ctx.props` is authentic. There is no need to use secret keys or cryptographic signatures in a `ctx.props` value.
44+
45+
`ctx.props` can also be used to configure an RPC interface to represent a _specific_ resource, thus creating a "custom binding". For exmaple, we could configure a Service Binding to our "doc-worker" which grants access only to a specific document:
46+
47+
<WranglerConfig>
48+
49+
```toml
50+
[[services]]
51+
binding = "FOO_DOCUMENT"
52+
service = "doc-worker"
53+
entypoint = "DocumentApi"
54+
props = { docId = "e366592caec1d88dff724f74136b58b5", permissions = ["read", "write"] }
55+
```
56+
57+
</WranglerConfig>
58+
59+
Here, we've placed a `docId` property in `ctx.props`. The `DocumentApi` class could be designed to provide an API to the specific document identified by `ctx.props.docId`, and enforcing the given permissions.
60+
61+
## `exports`
62+
63+
`ctx.exports` provides automatically-configured "loopback" bindings for all of your top-level exports.
64+
65+
* For each top-level exports that `extends WorkerEntrypoint` (or simply implements a fetch handler), `ctx.exports` atomatically contains a [Service Binding](/workers/runtime-apis/bindings/service-bindings).
66+
* For each top-level export that `extends DurableObject` (and which has been configured with storage via a [migration](https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/)), `ctx.exports` automatically contains a [Durable Object namespace binding](https://developers.cloudflare.com/durable-objects/api/namespace/).
67+
68+
For example:
69+
70+
```js
71+
import { WorkerEntrypoint } from "cloudflare:workers";
72+
73+
export class Greeter extends WorkerEntrypoint {
74+
greet(name) {
75+
return `Hello, ${name}!`;
76+
}
77+
}
78+
79+
export default {
80+
async fetch(request, env, ctx) {
81+
let greeting = await ctx.exports.Greeter.greet("World")
82+
return new Response(greeting);
83+
}
84+
}
85+
```
86+
87+
In this example, the default fetch handler calls the `Greeter` class over RPC, like how you'd use a Service Binding. However, there is no external configuration required. `ctx.exports` is populated _automatically_ from your top-level imports.
88+
89+
### Specifying `ctx.props` when using `ctx.exports`
90+
91+
Loopback Service Bindings in `ctx.exports` have an extra capability that regular Service Bindings do not: the caller can specify the value of `ctx.props` that should be delivered to the callee.
92+
93+
```js
94+
import { WorkerEntrypoint } from "cloudflare:workers";
95+
96+
export class Greeter extends WorkerEntrypoint {
97+
greet(name) {
98+
return `${this.props.greeting}, ${name}!`;
99+
}
100+
}
101+
102+
export default {
103+
async fetch(request, env, ctx) {
104+
// Make a custom greeter that uses the greeting "Welcome".
105+
let greeter = this.ctx.exports.Greeter({props: {greeting: "Welcome"}})
106+
107+
// Greet the world. Returns "Welcome, World!"
108+
let greeting = await ctx.exports.Greeter.greet("World")
109+
110+
return new Response(greeting);
111+
}
112+
}
113+
```
114+
115+
Specifying props dynamically is permitted in this case because the caller is the same Worker, and thus can be presumed to be trusted to specify any props. The ability to customize props is particularly useful when the resulting binding is to be passed to another Worker over RPC or used in the `env` of a [dynamically-loaded worker](/workers/runtime-apis/bindings/worker-loader/).
116+
117+
Note that `props` values specified in this way are allowed to contain any "persistently" serializable type. This includes all basic [structured clonable data types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). It also includes Service Bindings themselves: you can place a Service Binding into the `props` of another Service Binding.
16118

17119
## `waitUntil`
18120

0 commit comments

Comments
 (0)