@rivetkit/cloudflare-workers 2.2.1 → 2.3.0-rc.13

package/README.md

@@ -1,11 +1,49 @@
-# RivetKit Cloudflare Workers Adapter
+# @rivetkit/cloudflare-workers
 
-_Library to build and scale stateful workloads_
+Cloudflare Workers integration for [RivetKit](https://rivet.dev) actors.
 
-[Learn More →](https://github.com/rivet-dev/rivetkit)
+Host Rivet Actors on Cloudflare Workers with a single import. The wasm runtime
+and the fetch-based WebSocket shim are wired automatically.
 
-[Discord](https://rivet.dev/discord) — [Documentation](https://rivetkit.org) — [Issues](https://github.com/rivet-dev/rivetkit/issues)
+```ts
+import { actor } from "rivetkit";
+import { createHandler } from "@rivetkit/cloudflare-workers";
 
-## License
+const counter = actor({
+	state: { count: 0 },
+	actions: {
+		increment: (c, amount = 1) => (c.state.count += amount),
+		getCount: (c) => c.state.count,
+	},
+});
 
-Apache 2.0
+export default createHandler({ use: { counter } });
+```
+
+Set `RIVET_ENDPOINT` in `wrangler.toml` `[vars]` (namespace and token may be
+embedded in the URL as `https://namespace:token@host`).
+
+## Mounting your own routes
+
+Pass `fetch` to handle everything outside the Rivet manager API path
+(`/api/rivet`). Use `setup` to get a typed registry so a `createClient` call is
+fully typed:
+
+```ts
+import { createHandler, setup } from "@rivetkit/cloudflare-workers";
+import { createClient } from "rivetkit/client";
+import { Hono } from "hono";
+
+const registry = setup({ use: { counter } });
+
+const app = new Hono<{ Bindings: { RIVET_ENDPOINT: string } }>();
+app.post("/increment/:name", async (c) => {
+	const client = createClient<typeof registry>({ endpoint: c.env.RIVET_ENDPOINT });
+	const count = await client.counter.getOrCreate(c.req.param("name")).increment(1);
+	return c.json({ count });
+});
+
+export default createHandler(registry, { fetch: app.fetch });
+```
+
+Learn more at https://rivet.dev/docs.

package/dist/mod.d.mts

@@ -0,0 +1,44 @@
+import { RegistryActors, RegistryConfigInput, Registry } from 'rivetkit';
+
+/** Config passed to `setup` / `createHandler`. The wasm runtime is wired automatically. */
+type CloudflareSetupConfig<A extends RegistryActors> = Omit<RegistryConfigInput<A>, "runtime" | "wasm">;
+/**
+ * Wraps rivetkit's `setup` with the Cloudflare Workers WebAssembly runtime wired
+ * in. Returns a typed `Registry`, so you can derive a typed client with
+ * `createClient<typeof registry>(...)` and pass the same registry to
+ * `createHandler`.
+ */
+declare function setup<A extends RegistryActors>(config: CloudflareSetupConfig<A>): Registry<A>;
+interface CreateHandlerOptions {
+    /**
+     * Path the Rivet manager API is mounted at. Defaults to `/api/rivet`.
+     *
+     * `rivet dev` and the engine poll `<managerPath>/metadata`, so changing this
+     * also requires configuring the engine-side serverless runner URL to match.
+     */
+    managerPath?: string;
+    /**
+     * Handler for requests that fall outside the Rivet manager API path. Accepts
+     * a plain `(request, env, ctx)` handler or a framework `fetch` such as
+     * Hono's `app.fetch`.
+     */
+    fetch?: (request: Request, ...args: any[]) => Response | Promise<Response>;
+}
+interface CloudflareHandler {
+    fetch(request: Request, env: unknown, ctx: unknown): Promise<Response>;
+}
+/**
+ * Creates a Cloudflare Workers handler that hosts Rivet Actors on the wasm
+ * runtime. Accepts either a registry from this package's `setup` or a setup
+ * config (which is wired through `setup` for you).
+ *
+ * The Rivet manager API is mounted at `managerPath` (default `/api/rivet`).
+ * Requests outside that path are routed to `options.fetch` if provided, letting
+ * you mount your own routes alongside Rivet. The engine endpoint is read from
+ * `RIVET_ENDPOINT` (with `RIVET_NAMESPACE`, `RIVET_TOKEN`, `RIVET_POOL` optional)
+ * unless set in the config.
+ */
+declare function createHandler<A extends RegistryActors>(registry: Registry<A>, options?: CreateHandlerOptions): CloudflareHandler;
+declare function createHandler<A extends RegistryActors>(config: CloudflareSetupConfig<A>, options?: CreateHandlerOptions): CloudflareHandler;
+
+export { type CloudflareHandler, type CloudflareSetupConfig, type CreateHandlerOptions, createHandler, setup };

package/dist/mod.d.ts

@@ -1,88 +1,44 @@
-import { Client, Registry, ActorKey } from 'rivetkit';
-export { Client } from 'rivetkit';
-import { DurableObject } from 'cloudflare:workers';
-import { GetUpgradeWebSocket } from 'rivetkit/utils';
-import { z } from 'zod/v4';
+import { RegistryActors, RegistryConfigInput, Registry } from 'rivetkit';
 
-interface DriverContext {
-    state: DurableObjectState;
-}
-
-declare const ConfigSchema: z.ZodDefault<z.ZodObject<{
-    managerPath: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    runnerKey: z.ZodOptional<z.ZodString>;
-    noWelcome: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    fetch: z.ZodOptional<z.ZodCustom<ExportedHandlerFetchHandler<{
-        RIVET: Client<any>;
-    }, unknown>, ExportedHandlerFetchHandler<{
-        RIVET: Client<any>;
-    }, unknown>>>;
-}, z.core.$strip>>;
-type InputConfig = z.input<typeof ConfigSchema>;
-type Config = z.infer<typeof ConfigSchema>;
-
-/** Cloudflare Workers env */
-interface Bindings {
-    ACTOR_KV: KVNamespace;
-    ACTOR_DO: DurableObjectNamespace<ActorHandlerInterface>;
-}
-interface InlineOutput<A extends Registry<any>> {
-    /** Client to communicate with the actors. */
-    client: Client<A>;
-    /** Fetch handler to manually route requests to the Rivet manager API. */
-    fetch: (request: Request, ...args: any) => Response | Promise<Response>;
-    config: Config;
-    ActorHandler: DurableObjectConstructor;
-}
-interface HandlerOutput {
-    handler: ExportedHandler<Bindings>;
-    ActorHandler: DurableObjectConstructor;
-}
+/** Config passed to `setup` / `createHandler`. The wasm runtime is wired automatically. */
+type CloudflareSetupConfig<A extends RegistryActors> = Omit<RegistryConfigInput<A>, "runtime" | "wasm">;
 /**
- * Creates an inline client for accessing Rivet Actors privately without a public manager API.
- *
- * If you want to expose a public manager API, either:
- *
- * - Use `createHandler` to expose the Rivet API on `/api/rivet`
- * - Forward Rivet API requests to `InlineOutput::fetch`
+ * Wraps rivetkit's `setup` with the Cloudflare Workers WebAssembly runtime wired
+ * in. Returns a typed `Registry`, so you can derive a typed client with
+ * `createClient<typeof registry>(...)` and pass the same registry to
+ * `createHandler`.
  */
-declare function createInlineClient<R extends Registry<any>>(registry: R, inputConfig?: InputConfig): InlineOutput<R>;
+declare function setup<A extends RegistryActors>(config: CloudflareSetupConfig<A>): Registry<A>;
+interface CreateHandlerOptions {
+    /**
+     * Path the Rivet manager API is mounted at. Defaults to `/api/rivet`.
+     *
+     * `rivet dev` and the engine poll `<managerPath>/metadata`, so changing this
+     * also requires configuring the engine-side serverless runner URL to match.
+     */
+    managerPath?: string;
+    /**
+     * Handler for requests that fall outside the Rivet manager API path. Accepts
+     * a plain `(request, env, ctx)` handler or a framework `fetch` such as
+     * Hono's `app.fetch`.
+     */
+    fetch?: (request: Request, ...args: any[]) => Response | Promise<Response>;
+}
+interface CloudflareHandler {
+    fetch(request: Request, env: unknown, ctx: unknown): Promise<Response>;
+}
 /**
- * Creates a handler to be exported from a Cloudflare Worker.
- *
- * This will automatically expose the Rivet manager API on `/api/rivet`.
+ * Creates a Cloudflare Workers handler that hosts Rivet Actors on the wasm
+ * runtime. Accepts either a registry from this package's `setup` or a setup
+ * config (which is wired through `setup` for you).
  *
- * This includes a `fetch` handler and `ActorHandler` Durable Object.
+ * The Rivet manager API is mounted at `managerPath` (default `/api/rivet`).
+ * Requests outside that path are routed to `options.fetch` if provided, letting
+ * you mount your own routes alongside Rivet. The engine endpoint is read from
+ * `RIVET_ENDPOINT` (with `RIVET_NAMESPACE`, `RIVET_TOKEN`, `RIVET_POOL` optional)
+ * unless set in the config.
  */
-declare function createHandler(registry: Registry<any>, inputConfig?: InputConfig): HandlerOutput;
-
-interface ActorHandlerInterface extends DurableObject {
-    create(req: ActorInitRequest): Promise<ActorInitResponse>;
-    getMetadata(): Promise<{
-        actorId: string;
-        name: string;
-        key: ActorKey;
-        destroying: boolean;
-    } | undefined>;
-    managerKvGet(key: Uint8Array): Promise<Uint8Array | null>;
-}
-interface ActorInitRequest {
-    name: string;
-    key: ActorKey;
-    input?: unknown;
-    allowExisting: boolean;
-}
-type ActorInitResponse = {
-    success: {
-        actorId: string;
-        created: boolean;
-    };
-} | {
-    error: {
-        actorAlreadyExists: true;
-    };
-};
-type DurableObjectConstructor = new (...args: ConstructorParameters<typeof DurableObject<Bindings>>) => DurableObject<Bindings>;
-declare function createActorDurableObject(registry: Registry<any>, getUpgradeWebSocket: GetUpgradeWebSocket): DurableObjectConstructor;
+declare function createHandler<A extends RegistryActors>(registry: Registry<A>, options?: CreateHandlerOptions): CloudflareHandler;
+declare function createHandler<A extends RegistryActors>(config: CloudflareSetupConfig<A>, options?: CreateHandlerOptions): CloudflareHandler;
 
-export { type Bindings, type InputConfig as Config, type DriverContext, type HandlerOutput, type InlineOutput, createActorDurableObject, createHandler, createInlineClient };
+export { type CloudflareHandler, type CloudflareSetupConfig, type CreateHandlerOptions, createHandler, setup };