@ohos-ports/rivetkit-effect 2.3.17-beta.0

package/src/Registry.test.ts

@@ -0,0 +1,400 @@
+import { assert, describe, it } from "@effect/vitest";
+import { Action, Actor, Registry, RivetLogger } from "@rivetkit/effect";
+import { Effect, Layer } from "effect";
+import { HttpEffect } from "effect/unstable/http";
+import * as RivetkitLog from "@ohos-ports/rivetkit/log";
+import { vi } from "vitest";
+
+const TestActor = Actor.make("TestActor", {
+	actions: [Action.make("Test")],
+});
+
+const TestActorLive = TestActor.toLayer({
+	Test: () => Effect.void,
+});
+
+const ActorsLayer = Layer.mergeAll(TestActorLive);
+
+const RegistryLive = ActorsLayer.pipe(
+	Layer.provideMerge(
+		Registry.layer({
+			endpoint: "http://127.0.0.1:6420",
+			noWelcome: true,
+		}),
+	),
+);
+
+function makeTestLogger(): RivetkitLog.Logger {
+	const logger: Record<string, unknown> = {
+		level: "debug",
+		child: () => logger,
+	};
+	for (const level of ["trace", "debug", "info", "warn", "error", "fatal"]) {
+		logger[level] = (): void => {};
+	}
+
+	return logger as unknown as RivetkitLog.Logger;
+}
+
+describe("Registry.toWebHandler", () => {
+	it("serves registered actors as a Fetch handler", async () => {
+		const { handler, dispose } = Registry.toWebHandler(RegistryLive);
+
+		try {
+			const response = await handler(
+				new Request("http://runner.test/api/rivet/metadata"),
+			);
+
+			assert.strictEqual(response.status, 200);
+			const body = (await response.json()) as {
+				readonly actorNames: Record<string, unknown>;
+			};
+			assert.ok(body.actorNames.TestActor);
+		} finally {
+			await dispose();
+		}
+	});
+
+	it("uses a custom serverless base path", async () => {
+		const { handler, dispose } = Registry.toWebHandler(RegistryLive, {
+			basePath: "/",
+		});
+
+		try {
+			const response = await handler(
+				new Request("http://runner.test/metadata"),
+			);
+
+			assert.strictEqual(response.status, 200);
+			const body = (await response.json()) as {
+				readonly actorNames: Record<string, unknown>;
+			};
+			assert.ok(body.actorNames.TestActor);
+		} finally {
+			await dispose();
+		}
+	});
+
+	it("uses the custom base path to identify start requests", async () => {
+		const { handler, dispose } = Registry.toWebHandler(RegistryLive, {
+			basePath: "/custom",
+			maxStartPayloadBytes: 1,
+		});
+
+		try {
+			const defaultPrefix = await handler(
+				new Request("http://runner.test/api/rivet/start", {
+					method: "POST",
+					body: new Uint8Array([1, 2]),
+				}),
+			);
+			assert.notStrictEqual(defaultPrefix.status, 413);
+
+			const customPrefix = await handler(
+				new Request("http://runner.test/custom/start", {
+					method: "POST",
+					body: new Uint8Array([1, 2]),
+				}),
+			);
+			assert.strictEqual(customPrefix.status, 413);
+			const body = (await customPrefix.json()) as {
+				readonly group: string;
+				readonly code: string;
+				readonly message: string;
+			};
+			assert.deepStrictEqual(
+				{ group: body.group, code: body.code },
+				{ group: "message", code: "incoming_too_long" },
+			);
+			assert.match(body.message, /limit is 1 bytes/);
+		} finally {
+			await dispose();
+		}
+	});
+
+	it("uses a custom serverless start payload size limit", async () => {
+		const { handler, dispose } = Registry.toWebHandler(RegistryLive, {
+			maxStartPayloadBytes: 1,
+		});
+
+		try {
+			const response = await handler(
+				new Request("http://runner.test/api/rivet/start", {
+					method: "POST",
+					body: new Uint8Array([1, 2]),
+				}),
+			);
+
+			assert.strictEqual(response.status, 413);
+			const body = (await response.json()) as {
+				readonly group: string;
+				readonly code: string;
+				readonly message: string;
+			};
+			assert.deepStrictEqual(
+				{ group: body.group, code: body.code },
+				{ group: "message", code: "incoming_too_long" },
+			);
+			assert.match(body.message, /limit is 1 bytes/);
+		} finally {
+			await dispose();
+		}
+	});
+
+	it("does not print the welcome banner when disabled", async () => {
+		const log = vi.spyOn(console, "log").mockImplementation(() => {});
+		const { handler, dispose } = Registry.toWebHandler(RegistryLive);
+
+		try {
+			const response = await handler(
+				new Request("http://runner.test/api/rivet/metadata"),
+			);
+
+			assert.strictEqual(response.status, 200);
+			assert.strictEqual(log.mock.calls.length, 0);
+		} finally {
+			await dispose();
+			log.mockRestore();
+		}
+	});
+
+	it("builds the registry layer once across requests", async () => {
+		let builds = 0;
+		const CountingRegistryLive = Layer.mergeAll(
+			RegistryLive,
+			Layer.effectDiscard(
+				Effect.sync(() => {
+					builds += 1;
+				}),
+			),
+		);
+		const { handler, dispose } =
+			Registry.toWebHandler(CountingRegistryLive);
+
+		try {
+			const first = await handler(
+				new Request("http://runner.test/api/rivet/metadata"),
+			);
+			const second = await handler(
+				new Request("http://runner.test/api/rivet/metadata"),
+			);
+
+			assert.strictEqual(first.status, 200);
+			assert.strictEqual(second.status, 200);
+			assert.strictEqual(builds, 1);
+		} finally {
+			await dispose();
+		}
+	});
+
+	it("initializes the underlying RivetKit registry once across requests", async () => {
+		const log = vi.spyOn(console, "log").mockImplementation(() => {});
+		const WelcomeRegistryLive = ActorsLayer.pipe(
+			Layer.provideMerge(
+				Registry.layer({
+					endpoint: "http://127.0.0.1:6420",
+				}),
+			),
+		);
+		const { handler, dispose } = Registry.toWebHandler(WelcomeRegistryLive);
+
+		try {
+			const first = await handler(
+				new Request("http://runner.test/api/rivet/metadata"),
+			);
+			const callsAfterFirst = log.mock.calls.length;
+			const second = await handler(
+				new Request("http://runner.test/api/rivet/metadata"),
+			);
+
+			assert.strictEqual(first.status, 200);
+			assert.strictEqual(second.status, 200);
+			assert.ok(callsAfterFirst > 0);
+			assert.strictEqual(log.mock.calls.length, callsAfterFirst);
+		} finally {
+			await dispose();
+			log.mockRestore();
+		}
+	});
+
+	it("uses a custom logger layer for the underlying RivetKit registry", async () => {
+		const baseLogger = makeTestLogger();
+		const CustomLoggerRegistryLive = RegistryLive.pipe(
+			Layer.provide(RivetLogger.layerFromPino(baseLogger)),
+		);
+		const { handler, dispose } = Registry.toWebHandler(
+			CustomLoggerRegistryLive,
+		);
+
+		try {
+			const response = await handler(
+				new Request("http://runner.test/api/rivet/metadata"),
+			);
+
+			assert.strictEqual(response.status, 200);
+			assert.strictEqual(RivetkitLog.getBaseLogger(), baseLogger);
+		} finally {
+			await dispose();
+			RivetkitLog.configureDefaultLogger("silent");
+		}
+	});
+
+	it("closes registry layer finalizers on dispose", async () => {
+		let finalizers = 0;
+		const FinalizedRegistryLive = Layer.mergeAll(
+			RegistryLive,
+			Layer.effectDiscard(
+				Effect.addFinalizer(() =>
+					Effect.sync(() => {
+						finalizers += 1;
+					}),
+				),
+			),
+		);
+		const { handler, dispose } = Registry.toWebHandler(
+			FinalizedRegistryLive,
+		);
+
+		try {
+			const response = await handler(
+				new Request("http://runner.test/api/rivet/metadata"),
+			);
+
+			assert.strictEqual(response.status, 200);
+			assert.strictEqual(finalizers, 0);
+		} finally {
+			await dispose();
+		}
+		assert.strictEqual(finalizers, 1);
+	});
+});
+
+describe("Registry.toHttpEffect", () => {
+	it.effect("serves registered actors as an Effect HTTP handler", () =>
+		Effect.scoped(
+			Effect.gen(function* () {
+				const httpEffect = yield* Registry.toHttpEffect(RegistryLive);
+				const handler = HttpEffect.toWebHandler(httpEffect);
+				const response = yield* Effect.promise(() =>
+					handler(
+						new Request("http://runner.test/api/rivet/metadata"),
+					),
+				);
+
+				yield* Effect.promise(() =>
+					(async (response: Response) => {
+						assert.strictEqual(response.status, 200);
+						const body = (await response.json()) as {
+							readonly actorNames: Record<string, unknown>;
+						};
+						assert.ok(body.actorNames.TestActor);
+					})(response),
+				);
+			}),
+		),
+	);
+
+	it.effect("uses a custom serverless base path", () =>
+		Effect.scoped(
+			Effect.gen(function* () {
+				const httpEffect = yield* Registry.toHttpEffect(RegistryLive, {
+					basePath: "/",
+				});
+				const handler = HttpEffect.toWebHandler(httpEffect);
+				const response = yield* Effect.promise(() =>
+					handler(new Request("http://runner.test/metadata")),
+				);
+
+				yield* Effect.promise(() =>
+					(async (response: Response) => {
+						assert.strictEqual(response.status, 200);
+						const body = (await response.json()) as {
+							readonly actorNames: Record<string, unknown>;
+						};
+						assert.ok(body.actorNames.TestActor);
+					})(response),
+				);
+			}),
+		),
+	);
+
+	it.effect("uses the custom base path to identify start requests", () =>
+		Effect.scoped(
+			Effect.gen(function* () {
+				const httpEffect = yield* Registry.toHttpEffect(RegistryLive, {
+					basePath: "/custom",
+					maxStartPayloadBytes: 1,
+				});
+				const handler = HttpEffect.toWebHandler(httpEffect);
+				const defaultPrefix = yield* Effect.promise(() =>
+					handler(
+						new Request("http://runner.test/api/rivet/start", {
+							method: "POST",
+							body: new Uint8Array([1, 2]),
+						}),
+					),
+				);
+				assert.notStrictEqual(defaultPrefix.status, 413);
+
+				const customPrefix = yield* Effect.promise(() =>
+					handler(
+						new Request("http://runner.test/custom/start", {
+							method: "POST",
+							body: new Uint8Array([1, 2]),
+						}),
+					),
+				);
+				yield* Effect.promise(() =>
+					(async (response: Response) => {
+						assert.strictEqual(response.status, 413);
+						const body = (await response.json()) as {
+							readonly group: string;
+							readonly code: string;
+							readonly message: string;
+						};
+						assert.deepStrictEqual(
+							{ group: body.group, code: body.code },
+							{ group: "message", code: "incoming_too_long" },
+						);
+						assert.match(body.message, /limit is 1 bytes/);
+					})(customPrefix),
+				);
+			}),
+		),
+	);
+
+	it.effect("uses a custom serverless start payload size limit", () =>
+		Effect.scoped(
+			Effect.gen(function* () {
+				const httpEffect = yield* Registry.toHttpEffect(RegistryLive, {
+					maxStartPayloadBytes: 1,
+				});
+				const handler = HttpEffect.toWebHandler(httpEffect);
+				const response = yield* Effect.promise(() =>
+					handler(
+						new Request("http://runner.test/api/rivet/start", {
+							method: "POST",
+							body: new Uint8Array([1, 2]),
+						}),
+					),
+				);
+
+				yield* Effect.promise(() =>
+					(async (response: Response) => {
+						assert.strictEqual(response.status, 413);
+						const body = (await response.json()) as {
+							readonly group: string;
+							readonly code: string;
+							readonly message: string;
+						};
+						assert.deepStrictEqual(
+							{ group: body.group, code: body.code },
+							{ group: "message", code: "incoming_too_long" },
+						);
+						assert.match(body.message, /limit is 1 bytes/);
+					})(response),
+				);
+			}),
+		),
+	);
+});

package/src/Registry.ts

@@ -0,0 +1,304 @@
+import { Context, Effect, Layer, type Scope } from "effect";
+import {
+	HttpEffect,
+	type HttpMiddleware,
+	type HttpServerError,
+	type HttpServerRequest,
+	type HttpServerResponse,
+} from "effect/unstable/http";
+import * as Rivetkit from "@ohos-ports/rivetkit";
+import * as RivetkitLog from "@ohos-ports/rivetkit/log";
+import * as Client from "./Client.ts";
+import { BaseLogger, getOrCreateBaseLogger } from "./internal/logging.ts";
+import * as RivetLogger from "./RivetLogger.ts";
+
+const TypeId = "~@rivetkit/effect/Registry";
+type ServerlessOptions = NonNullable<
+	Rivetkit.RegistryConfigInput<Rivetkit.RegistryActors>["serverless"]
+>;
+
+export type Options = Pick<
+	Rivetkit.RegistryConfigInput<Rivetkit.RegistryActors>,
+	"endpoint" | "token" | "namespace" | "noWelcome" | "sqlite"
+>;
+
+export interface Registry {
+	readonly [TypeId]: typeof TypeId;
+
+	readonly options: Options;
+
+	readonly baseLogger: RivetkitLog.Logger;
+
+	readonly rivetkitActors: Map<string, Rivetkit.AnyActorDefinition>;
+}
+
+export const Registry: Context.Service<Registry, Registry> =
+	Context.Service<Registry>("@rivetkit/effect/Registry");
+
+/**
+ * Creates the shared registry that actor layers register into.
+ *
+ * @remarks
+ * Actor layers created with {@link Actor.Actor.toLayer|`Actor.toLayer()`}
+ * register into this service. Registry entrypoints such as
+ * {@link serve|`Registry.serve()`}, {@link toWebHandler|`Registry.toWebHandler()`},
+ * and {@link toHttpEffect|`Registry.toHttpEffect()`} later use the collected
+ * actors to create the underlying RivetKit runtime.
+ *
+ * @param options - RivetKit runtime options shared by the registered actors.
+ *
+ * @returns A layer that provides the {@link Registry|`Registry.Registry`}
+ * service.
+ *
+ * @example
+ * ```ts
+ * import { Registry } from "@rivetkit/effect"
+ * import { Layer } from "effect"
+ *
+ * const ActorsLayer = Layer.mergeAll(ChatRoomLive, ModeratorLive)
+ *
+ * const MainLayer = Registry.serve(ActorsLayer).pipe(
+ *   Layer.provide(Registry.layer({ endpoint: "http://127.0.0.1:6420" }))
+ * )
+ * ```
+ *
+ * @see {@link serve|`Registry.serve()`} for starting a long-running actor
+ * server.
+ * @see {@link toWebHandler|`Registry.toWebHandler()`} for Fetch-compatible
+ * serverless handlers.
+ * @see {@link toHttpEffect|`Registry.toHttpEffect()`} for Effect HTTP handlers.
+ */
+export const layer = (options: Options = {}): Layer.Layer<Registry> =>
+	Layer.effect(
+		Registry,
+		Effect.map(getOrCreateBaseLogger, (baseLogger) =>
+			Registry.of({
+				[TypeId]: TypeId,
+				options,
+				baseLogger,
+				rivetkitActors: new Map(),
+			}),
+		),
+	);
+
+const setupRivetkitRegistry = (
+	registry: Registry,
+	options?: {
+		readonly serverless?: ServerlessOptions | undefined;
+	},
+) =>
+	Effect.sync(() =>
+		Rivetkit.setup({
+			use: Object.fromEntries(registry.rivetkitActors),
+			...registry.options,
+			logging: { baseLogger: registry.baseLogger },
+			...(options?.serverless === undefined
+				? {}
+				: { serverless: options.serverless }),
+		}),
+	);
+
+/**
+ * Serves the actors registered by `actorsLayer`.
+ *
+ * @remarks
+ * Provide this with {@link layer|`Registry.layer()`} at the application root.
+ * Building the returned layer evaluates the actor layer, collects its registered
+ * actors, and starts the underlying RivetKit runtime using the options from
+ * {@link layer|`Registry.layer()`}. Launch the resulting layer with
+ * {@link Layer.launch|`Layer.launch()`} to keep the server process alive.
+ *
+ * @param actorsLayer - A layer containing one or more
+ * {@link Actor.Actor.toLayer|`Actor.toLayer()`} registrations.
+ *
+ * @returns A side-effecting startup layer that requires the
+ * {@link Registry|`Registry.Registry`} service and the services required by
+ * `actorsLayer`.
+ *
+ * @example
+ * ```ts
+ * import { Registry } from "@rivetkit/effect"
+ * import { Layer } from "effect"
+ *
+ * const ActorsLayer = Layer.mergeAll(ChatRoomLive, ModeratorLive)
+ *
+ * const MainLayer = Registry.serve(ActorsLayer).pipe(
+ *   Layer.provide(Registry.layer({ endpoint: "http://127.0.0.1:6420" }))
+ * )
+ *
+ * Layer.launch(MainLayer).pipe(NodeRuntime.runMain);
+ * ```
+ *
+ * @see {@link toWebHandler|`Registry.toWebHandler()`} for Fetch-compatible
+ * serverless handlers.
+ * @see {@link toHttpEffect|`Registry.toHttpEffect()`} for Effect HTTP handlers.
+ *
+ */
+export const serve = <E, R>(
+	actorsLayer: Layer.Layer<never, E, R>,
+): Layer.Layer<never, E, R | Registry> =>
+	Layer.effectDiscard(
+		Effect.gen(function* () {
+			const registry = yield* Registry;
+			yield* Layer.build(
+				actorsLayer.pipe(
+					Layer.provideMerge(
+						RivetLogger.layerFromPino(registry.baseLogger),
+					),
+				),
+			);
+			const rivetkitRegistry = yield* setupRivetkitRegistry(registry);
+			yield* Effect.sync(() => rivetkitRegistry.start());
+		}),
+	);
+
+/**
+ * In-process test runtime. Boots the rivetkit registry against the
+ * configured engine, waits for `/health` to answer, and provides
+ * `Client` from the same Layer so consumers don't need to wire
+ * `Client.layer` separately. Mirrors `Registry.start` plus test-mode
+ * flags and a scoped client dispose. The registry itself is leaked
+ * to process exit because the public rivetkit `Registry` doesn't
+ * expose a public `shutdown()` today; only the SIGINT handler can
+ * drive `#runShutdown`. This matches `setupTest`'s existing behavior.
+ */
+export const test: Layer.Layer<Client.Client, never, Registry> = Layer.effect(
+	Client.Client,
+	Effect.gen(function* () {
+		const registry = yield* Registry;
+		const rivetkitRegistry = yield* setupRivetkitRegistry(registry);
+		rivetkitRegistry.config.test = {
+			...rivetkitRegistry.config.test,
+			enabled: true,
+		};
+		rivetkitRegistry.config.noWelcome = true;
+		// Auto-spawn the engine when no endpoint was provided, so
+		// `Registry.test` works out of the box without requiring the
+		// caller to start an engine externally. If the user wired an
+		// explicit endpoint via `Registry.layer({ endpoint: ... })`,
+		// honor it and skip the local spawn.
+		if (registry.options.endpoint === undefined) {
+			rivetkitRegistry.config.startEngine = true;
+		}
+		yield* Effect.sync(() => rivetkitRegistry.start());
+
+		// The rivetkitRegistry itself is leaked until process exit (matches
+		// setupTest's behavior). The public Rivetkit.Registry doesn't
+		// expose a shutdown method; only the SIGINT handler can drive the
+		// inner .shutdown(). Disposing the client is the only cleanup we
+		// can do cleanly today.
+		//
+		// When the engine was auto-spawned, propagate its resolved
+		// endpoint to the client so `createClient` doesn't fall back
+		// to its (warning-emitting) default.
+		const resolvedEndpoint = rivetkitRegistry.parseConfig().endpoint;
+
+		return yield* Client.make({
+			...registry.options,
+			endpoint: registry.options.endpoint ?? resolvedEndpoint,
+		}).pipe(Effect.provideService(BaseLogger, registry.baseLogger));
+	}),
+);
+
+const makeHttpEffect = (
+	registry: Registry,
+	options?: ToHttpEffectOptions,
+): Effect.Effect<
+	Effect.Effect<
+		HttpServerResponse.HttpServerResponse,
+		HttpServerError.HttpServerError,
+		HttpServerRequest.HttpServerRequest
+	>
+> =>
+	Effect.map(
+		setupRivetkitRegistry(registry, {
+			serverless: options,
+		}),
+		(rivetkitRegistry) =>
+			HttpEffect.fromWebHandler((request) =>
+				rivetkitRegistry.handler(request),
+			),
+	);
+
+export type ToHttpEffectOptions = ServerlessOptions;
+
+/**
+ * Builds a scoped Effect HTTP handler from a registry layer.
+ *
+ * The registry layer is built once in the surrounding scope. Registered Rivet
+ * Actors are materialized into a single underlying RivetKit registry, and each
+ * request is delegated to that registry's serverless handler.
+ */
+export const toHttpEffect = Effect.fnUntraced(function* <E>(
+	registryLayer: Layer.Layer<Registry, E>,
+	options?: ToHttpEffectOptions,
+): Effect.fn.Return<
+	Effect.Effect<
+		HttpServerResponse.HttpServerResponse,
+		HttpServerError.HttpServerError,
+		HttpServerRequest.HttpServerRequest
+	>,
+	E,
+	Scope.Scope
+> {
+	const context = yield* Layer.build(
+		registryLayer.pipe(Layer.provideMerge(RivetLogger.defaultLayer)),
+	);
+	const httpEffect = yield* makeHttpEffect(
+		Context.get(context, Registry),
+		options,
+	);
+	// @effect-diagnostics-next-line returnEffectInGen:off
+	return httpEffect.pipe(Effect.provide(context));
+});
+
+export type ToWebHandlerOptions = ServerlessOptions & {
+	/**
+	 * Effect HTTP middleware applied around the generated handler.
+	 */
+	readonly middleware?: HttpMiddleware.HttpMiddleware | undefined;
+	/**
+	 * Memo map used while building the registry layer.
+	 */
+	readonly memoMap?: Layer.MemoMap | undefined;
+};
+
+/**
+ * Builds a Fetch-compatible request handler from a registry layer.
+ *
+ * This is the serverless entrypoint for the Effect SDK. The registry layer must
+ * provide `Registry`, usually by composing actor layers with `Registry.layer`
+ * via `Layer.provideMerge`.
+ */
+export const toWebHandler = <E>(
+	registryLayer: Layer.Layer<Registry, E>,
+	options?: ToWebHandlerOptions,
+) => {
+	const { middleware, memoMap } = options ?? {};
+	let serverlessOptions: ServerlessOptions | undefined;
+	if (options !== undefined) {
+		const {
+			middleware: _middleware,
+			memoMap: _memoMap,
+			...handlerOptions
+		} = options;
+		serverlessOptions = handlerOptions;
+	}
+
+	const registryLayerWithLogging = registryLayer.pipe(
+		Layer.provideMerge(RivetLogger.defaultLayer),
+	);
+
+	return HttpEffect.toWebHandlerLayerWith(registryLayerWithLogging, {
+		toHandler: (context) =>
+			Effect.map(
+				makeHttpEffect(
+					Context.get(context, Registry),
+					serverlessOptions,
+				),
+				(httpEffect) => httpEffect.pipe(Effect.provide(context)),
+			),
+		middleware,
+		memoMap,
+	});
+};