1/// <reference types="@cloudflare/workers-types" />
2
3import * as Data from "effect/Data";
4import * as Effect from "effect/Effect";
5import * as Binding from "../../Binding.ts";
6import type { RuntimeContext } from "../../RuntimeContext.ts";
7import type { DispatchNamespace as DispatchNamespaceResource } from "./DispatchNamespace.ts";
8
9/**
10 * Bind a {@link DispatchNamespace} to a Worker and obtain the Effect-native
11 * dynamic-dispatch client (`get`).
12 *
13 * `Get` is a single identifier that is simultaneously the binding's Context
14 * tag, its type, and the callable —
15 * `yield* Cloudflare.WorkersForPlatforms.Get(namespace)`.
16 *
17 * Provide {@link GetBinding} on the Worker's runtime layer to resolve the
18 * underlying `dispatch_namespace` binding at request time.
19 *
20 *
21 * ### Dispatching to user Workers
22 * **Example:** Dispatch a request to a customer Worker
23 * Bind the namespace during the Worker's init phase, then look up and forward
24 * to a user Worker from a request handler.
25 * ```typescript
26 * const dispatch = yield* Cloudflare.WorkersForPlatforms.Get(namespace);
27 *
28 * return {
29 * fetch: Effect.gen(function* () {
30 * const request = yield* HttpServerRequest;
31 * const userWorker = yield* dispatch.get("customer-a");
32 * return yield* Effect.promise(() => userWorker.fetch(request));
33 * }),
34 * };
35 * ```
36 *
37 * @see https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/dynamic-dispatch/
38 *
39 * @binding
40 * @product Workers for Platforms
41 * @category Workers & Compute
42 */
43export interface Get extends Binding.Service<
44 Get,
45 "Cloudflare.WorkersForPlatforms.Get",
46 (
47 namespace: DispatchNamespaceResource,
48 ) => Effect.Effect<DispatchNamespaceClient>
49> {}
50
51export const Get = Binding.Service<Get>("Cloudflare.WorkersForPlatforms.Get");
52
53/** Error raised by dynamic-dispatch runtime operations. */
54export class DispatchNamespaceError extends Data.TaggedError(
55 "DispatchNamespaceError",
56)<{
57 /** Human-readable runtime error message. */
58 message: string;
59 /** Original error thrown by the Cloudflare runtime binding. */
60 cause: unknown;
61}> {}
62
63/**
64 * Effect-native client for a Workers for Platforms dispatch-namespace Worker
65 * binding.
66 *
67 * Wraps the runtime `DispatchNamespace` binding so the lookup returns an
68 * Effect tagged with {@link DispatchNamespaceError}. Use
69 * `Cloudflare.WorkersForPlatforms.Get(namespace)` inside a Worker's init
70 * phase.
71 */
72export interface DispatchNamespaceClient {
73 /** Effect resolving to the raw dispatch-namespace runtime binding. */
74 raw: Effect.Effect<DispatchNamespace, never, RuntimeContext>;
75 /**
76 * Look up a user Worker in the dispatch namespace by script name and obtain
77 * a `Fetcher` to send it requests.
78 *
79 * @param name Name of the user Worker script.
80 * @param args Arguments passed to the user Worker script.
81 * @param options Options for the dynamic-dispatch invocation.
82 */
83 get(
84 name: string,
85 args?: { [key: string]: any },
86 options?: DynamicDispatchOptions,
87 ): Effect.Effect<Fetcher, DispatchNamespaceError, RuntimeContext>;
88}