@rivetkit/effect 0.0.0-main.879b6a2 → 0.0.0-main.b2d3b94

package/src/Client.test.ts

@@ -1,12 +1,8 @@
 import { assert, describe, it } from "@effect/vitest";
-import { Client, Logger, RivetError } from "@rivetkit/effect";
+import { Client, RivetError, RivetLogger } from "@rivetkit/effect";
 import { Effect, Layer, Schema } from "effect";
 import * as RivetkitErrors from "rivetkit/errors";
-import {
-	configureDefaultLogger,
-	getBaseLogger,
-	type Logger as PinoLogger,
-} from "rivetkit/log";
+import * as RivetkitLog from "rivetkit/log";
 import * as ActionErrorEnvelope from "./internal/ActionErrorEnvelope";
 
 function makeTestLogger(
@@ -15,19 +11,12 @@ function makeTestLogger(
 		readonly fields: Record<string, unknown>;
 		readonly msg: string | undefined;
 	}>,
-): PinoLogger {
+): RivetkitLog.Logger {
 	const logger: Record<string, unknown> = {
 		level: "debug",
 		child: () => logger,
 	};
-	for (const level of [
-		"trace",
-		"debug",
-		"info",
-		"warn",
-		"error",
-		"fatal",
-	]) {
+	for (const level of ["trace", "debug", "info", "warn", "error", "fatal"]) {
 		logger[level] = (
 			fields: Record<string, unknown>,
 			msg?: string,
@@ -36,7 +25,7 @@ function makeTestLogger(
 		};
 	}
 
-	return logger as unknown as PinoLogger;
+	return logger as unknown as RivetkitLog.Logger;
 }
 
 describe("Client", () => {
@@ -46,13 +35,15 @@ describe("Client", () => {
 				const baseLogger = makeTestLogger();
 
 				yield* Effect.addFinalizer(() =>
-					Effect.sync(() => configureDefaultLogger("silent")),
+					Effect.sync(() =>
+						RivetkitLog.configureDefaultLogger("silent"),
+					),
 				);
 				yield* Client.make({
 					endpoint: "http://127.0.0.1:6420",
-				}).pipe(Effect.provide(Logger.layerPino(baseLogger)));
+				}).pipe(Effect.provide(RivetLogger.layerFromPino(baseLogger)));
 
-				assert.strictEqual(getBaseLogger(), baseLogger);
+				assert.strictEqual(RivetkitLog.getBaseLogger(), baseLogger);
 			}),
 		),
 	);
@@ -68,7 +59,9 @@ describe("Client", () => {
 				const baseLogger = makeTestLogger(entries);
 
 				yield* Effect.addFinalizer(() =>
-					Effect.sync(() => configureDefaultLogger("silent")),
+					Effect.sync(() =>
+						RivetkitLog.configureDefaultLogger("silent"),
+					),
 				);
 				yield* Effect.gen(function* () {
 					yield* Client.Client;
@@ -80,16 +73,19 @@ describe("Client", () => {
 						Client.layer({
 							endpoint: "http://127.0.0.1:6420",
 						}).pipe(
-							Layer.provideMerge(Logger.layerPino(baseLogger)),
+							Layer.provideMerge(
+								RivetLogger.layerFromPino(baseLogger),
+							),
 						),
 					),
 				);
 
-				assert.deepStrictEqual(entries[0], {
-					level: "info",
-					fields: { clientId: "test-client" },
-					msg: "client effect log",
-				});
+				const entry = entries[0];
+				assert.ok(entry !== undefined);
+				assert.strictEqual(entry.level, "info");
+				assert.strictEqual(entry.msg, "client effect log");
+				assert.strictEqual(entry.fields.clientId, "test-client");
+				assert.strictEqual(typeof entry.fields.fiberId, "string");
 				assert.ok(
 					entries.some(
 						(entry) =>

package/src/Client.ts

@@ -1,13 +1,13 @@
 import { Context, Effect, Layer, Record, Result, Schema } from "effect";
 import * as RivetkitClient from "rivetkit/client";
 import * as RivetkitErrors from "rivetkit/errors";
-import { configureBaseLogger } from "rivetkit/log";
+import * as RivetkitLog from "rivetkit/log";
 import type * as Action from "./Action.ts";
 import type * as Actor from "./Actor.ts";
 import * as ActionErrorEnvelope from "./internal/ActionErrorEnvelope.ts";
 import { getOrCreateBaseLogger } from "./internal/logging.ts";
 import { rpcSystem, type TraceMeta } from "./internal/tracing.ts";
-import * as Logger from "./Logger.ts";
+import * as RivetLogger from "./RivetLogger.ts";
 import * as RivetError from "./RivetError.ts";
 
 const TypeId = "~@rivetkit/effect/Client";
@@ -49,7 +49,9 @@ export const make = Effect.fnUntraced(function* (options: Options = {}) {
 	const baseLogger = yield* getOrCreateBaseLogger;
 	const rivetkitClient = yield* Effect.acquireRelease(
 		Effect.sync(() => {
-			configureBaseLogger(baseLogger);
+			// Raw RivetKit clients do not accept a logger in their config,
+			// so install the Effect-selected logger before construction.
+			RivetkitLog.configureBaseLogger(baseLogger);
 			return RivetkitClient.createClient(options);
 		}),
 		(c) => Effect.promise(() => c.dispose()),
@@ -146,7 +148,7 @@ export const layer = (options: Options = {}): Layer.Layer<Client> =>
 	Layer.unwrap(
 		Effect.map(getOrCreateBaseLogger, (baseLogger) =>
 			Layer.effect(Client, make(options)).pipe(
-				Layer.provideMerge(Logger.layerPino(baseLogger)),
+				Layer.provideMerge(RivetLogger.layerFromPino(baseLogger)),
 			),
 		),
 	);

package/src/Registry.test.ts

@@ -1,12 +1,8 @@
 import { assert, describe, it } from "@effect/vitest";
-import { Action, Actor, Logger, Registry } from "@rivetkit/effect";
+import { Action, Actor, Registry, RivetLogger } from "@rivetkit/effect";
 import { Effect, Layer } from "effect";
 import { HttpEffect } from "effect/unstable/http";
-import {
-	configureDefaultLogger,
-	getBaseLogger,
-	type Logger as PinoLogger,
-} from "rivetkit/log";
+import * as RivetkitLog from "rivetkit/log";
 import { vi } from "vitest";
 
 const TestActor = Actor.make("TestActor", {
@@ -28,23 +24,16 @@ const RegistryLive = ActorsLayer.pipe(
 	),
 );
 
-function makeTestLogger(): PinoLogger {
+function makeTestLogger(): RivetkitLog.Logger {
 	const logger: Record<string, unknown> = {
 		level: "debug",
 		child: () => logger,
 	};
-	for (const level of [
-		"trace",
-		"debug",
-		"info",
-		"warn",
-		"error",
-		"fatal",
-	]) {
+	for (const level of ["trace", "debug", "info", "warn", "error", "fatal"]) {
 		logger[level] = (): void => {};
 	}
 
-	return logger as unknown as PinoLogger;
+	return logger as unknown as RivetkitLog.Logger;
 }
 
 describe("Registry.toWebHandler", () => {
@@ -207,8 +196,7 @@ describe("Registry.toWebHandler", () => {
 				}),
 			),
 		);
-		const { handler, dispose } =
-			Registry.toWebHandler(WelcomeRegistryLive);
+		const { handler, dispose } = Registry.toWebHandler(WelcomeRegistryLive);
 
 		try {
 			const first = await handler(
@@ -232,10 +220,11 @@ describe("Registry.toWebHandler", () => {
 	it("uses a custom logger layer for the underlying RivetKit registry", async () => {
 		const baseLogger = makeTestLogger();
 		const CustomLoggerRegistryLive = RegistryLive.pipe(
-			Layer.provide(Logger.layerPino(baseLogger)),
+			Layer.provide(RivetLogger.layerFromPino(baseLogger)),
+		);
+		const { handler, dispose } = Registry.toWebHandler(
+			CustomLoggerRegistryLive,
 		);
-		const { handler, dispose } =
-			Registry.toWebHandler(CustomLoggerRegistryLive);
 
 		try {
 			const response = await handler(
@@ -243,10 +232,10 @@ describe("Registry.toWebHandler", () => {
 			);
 
 			assert.strictEqual(response.status, 200);
-			assert.strictEqual(getBaseLogger(), baseLogger);
+			assert.strictEqual(RivetkitLog.getBaseLogger(), baseLogger);
 		} finally {
 			await dispose();
-			configureDefaultLogger("silent");
+			RivetkitLog.configureDefaultLogger("silent");
 		}
 	});
 

package/src/Registry.ts

@@ -7,13 +7,10 @@ import {
 	type HttpServerResponse,
 } from "effect/unstable/http";
 import * as Rivetkit from "rivetkit";
-import {
-	configureBaseLogger,
-	type Logger as PinoLogger,
-} from "rivetkit/log";
+import * as RivetkitLog from "rivetkit/log";
 import * as Client from "./Client.ts";
 import { BaseLogger, getOrCreateBaseLogger } from "./internal/logging.ts";
-import * as Logger from "./Logger.ts";
+import * as RivetLogger from "./RivetLogger.ts";
 
 const TypeId = "~@rivetkit/effect/Registry";
 type ServerlessOptions = NonNullable<
@@ -22,7 +19,7 @@ type ServerlessOptions = NonNullable<
 
 export type Options = Pick<
 	Rivetkit.RegistryConfigInput<Rivetkit.RegistryActors>,
-	"endpoint" | "token" | "namespace" | "noWelcome"
+	"endpoint" | "token" | "namespace" | "noWelcome" | "sqlite"
 >;
 
 export interface Registry {
@@ -30,7 +27,7 @@ export interface Registry {
 
 	readonly options: Options;
 
-	readonly baseLogger: PinoLogger;
+	readonly baseLogger: RivetkitLog.Logger;
 
 	readonly rivetkitActors: Map<string, Rivetkit.AnyActorDefinition>;
 }
@@ -38,20 +35,49 @@ export interface Registry {
 export const Registry: Context.Service<Registry, Registry> =
 	Context.Service<Registry>("@rivetkit/effect/Registry");
 
-const make = (options: Options, baseLogger: PinoLogger): Registry => {
-	return Registry.of({
-		[TypeId]: TypeId,
-		options,
-		baseLogger,
-		rivetkitActors: new Map(),
-	});
-};
-
+/**
+ * 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) =>
-			make(options, baseLogger),
+			Registry.of({
+				[TypeId]: TypeId,
+				options,
+				baseLogger,
+				rivetkitActors: new Map(),
+			}),
 		),
 	);
 
@@ -60,40 +86,70 @@ const setupRivetkitRegistry = (
 	options?: {
 		readonly serverless?: ServerlessOptions | undefined;
 	},
-) => {
-	configureBaseLogger(registry.baseLogger);
-	return Rivetkit.setup({
-		use: Object.fromEntries(registry.rivetkitActors),
-		...registry.options,
-		logging: { baseLogger: registry.baseLogger },
-		...(options?.serverless === undefined
-			? {}
-			: { serverless: options.serverless }),
-	});
-};
+) =>
+	Effect.sync(() =>
+		Rivetkit.setup({
+			use: Object.fromEntries(registry.rivetkitActors),
+			...registry.options,
+			logging: { baseLogger: registry.baseLogger },
+			...(options?.serverless === undefined
+				? {}
+				: { serverless: options.serverless }),
+		}),
+	);
 
 /**
- * Runs an actor registration layer against the configured engine.
+ * 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.
  *
- * The actor layer is built in the server layer scope. Registered Rivet Actors
- * are collected from `Registry`, materialized into a single underlying RivetKit
- * registry, and started.
  */
 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;
-				const baseLogger = registry.baseLogger;
-				yield* Layer.build(
-					actorsLayer.pipe(
-						Layer.provideMerge(Logger.layerPino(baseLogger)),
+): 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 = setupRivetkitRegistry(registry);
-				yield* Effect.sync(() => rivetkitRegistry.start());
-			}),
+				),
+			);
+			const rivetkitRegistry = yield* setupRivetkitRegistry(registry);
+			yield* Effect.sync(() => rivetkitRegistry.start());
+		}),
 	);
 
 /**
@@ -110,7 +166,7 @@ export const test: Layer.Layer<Client.Client, never, Registry> = Layer.effect(
 	Client.Client,
 	Effect.gen(function* () {
 		const registry = yield* Registry;
-		const rivetkitRegistry = setupRivetkitRegistry(registry);
+		const rivetkitRegistry = yield* setupRivetkitRegistry(registry);
 		rivetkitRegistry.config.test = {
 			...rivetkitRegistry.config.test,
 			enabled: true,
@@ -137,30 +193,32 @@ export const test: Layer.Layer<Client.Client, never, Registry> = Layer.effect(
 		// 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),
-			);
-		}),
-	);
+		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<
-	HttpServerResponse.HttpServerResponse,
-	HttpServerError.HttpServerError,
-	HttpServerRequest.HttpServerRequest
-> => {
-	const rivetkitRegistry = setupRivetkitRegistry(registry, {
-		serverless: options,
-	});
-	return HttpEffect.fromWebHandler((request) =>
-		rivetkitRegistry.handler(request),
+	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;
 
@@ -184,12 +242,14 @@ export const toHttpEffect = Effect.fnUntraced(function* <E>(
 	Scope.Scope
 > {
 	const context = yield* Layer.build(
-		registryLayer.pipe(Layer.provideMerge(Logger.layer)),
+		registryLayer.pipe(Layer.provideMerge(RivetLogger.defaultLayer)),
 	);
-	// @effect-diagnostics-next-line returnEffectInGen:off
-	return makeHttpEffect(Context.get(context, Registry), options).pipe(
-		Effect.provide(context),
+	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 & {
@@ -226,16 +286,17 @@ export const toWebHandler = <E>(
 	}
 
 	const registryLayerWithLogging = registryLayer.pipe(
-		Layer.provideMerge(Logger.layer),
+		Layer.provideMerge(RivetLogger.defaultLayer),
 	);
 
 	return HttpEffect.toWebHandlerLayerWith(registryLayerWithLogging, {
 		toHandler: (context) =>
-			Effect.succeed(
+			Effect.map(
 				makeHttpEffect(
 					Context.get(context, Registry),
 					serverlessOptions,
-				).pipe(Effect.provide(context)),
+				),
+				(httpEffect) => httpEffect.pipe(Effect.provide(context)),
 			),
 		middleware,
 		memoMap,

package/src/RivetError.test.ts

@@ -121,6 +121,13 @@ describe("RivetError", () => {
 				"actor ready timeout",
 			),
 		);
+		const wakeRetriesExceeded = RivetError.fromUnknown(
+			new RivetkitErrors.RivetError(
+				"guard",
+				"actor_wake_retries_exceeded",
+				"actor wake retries exceeded",
+			),
+		);
 		const tunnelTimeout = RivetError.fromUnknown(
 			new RivetkitErrors.RivetError(
 				"guard",
@@ -137,6 +144,10 @@ describe("RivetError", () => {
 			readyTimeout.reason,
 			RivetError.GuardActorReadyTimeout,
 		);
+		assert.instanceOf(
+			wakeRetriesExceeded.reason,
+			RivetError.GuardActorWakeRetriesExceeded,
+		);
 		assert.instanceOf(
 			tunnelTimeout.reason,
 			RivetError.GuardTunnelMessageTimeout,