@rivetkit/effect 2.3.2 → 2.3.3-rc.2

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,7 +11,7 @@ function makeTestLogger(
 		readonly fields: Record<string, unknown>;
 		readonly msg: string | undefined;
 	}>,
-): PinoLogger {
+): RivetkitLog.Logger {
 	const logger: Record<string, unknown> = {
 		level: "debug",
 		child: () => logger,
@@ -29,7 +25,7 @@ function makeTestLogger(
 		};
 	}
 
-	return logger as unknown as PinoLogger;
+	return logger as unknown as RivetkitLog.Logger;
 }
 
 describe("Client", () => {
@@ -39,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);
 			}),
 		),
 	);
@@ -61,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;
@@ -73,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,7 +24,7 @@ const RegistryLive = ActorsLayer.pipe(
 	),
 );
 
-function makeTestLogger(): PinoLogger {
+function makeTestLogger(): RivetkitLog.Logger {
 	const logger: Record<string, unknown> = {
 		level: "debug",
 		child: () => logger,
@@ -37,7 +33,7 @@ function makeTestLogger(): PinoLogger {
 		logger[level] = (): void => {};
 	}
 
-	return logger as unknown as PinoLogger;
+	return logger as unknown as RivetkitLog.Logger;
 }
 
 describe("Registry.toWebHandler", () => {
@@ -224,7 +220,7 @@ 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,
@@ -236,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,10 +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<
@@ -19,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 {
@@ -27,7 +27,7 @@ export interface Registry {
 
 	readonly options: Options;
 
-	readonly baseLogger: PinoLogger;
+	readonly baseLogger: RivetkitLog.Logger;
 
 	readonly rivetkitActors: Map<string, Rivetkit.AnyActorDefinition>;
 }
@@ -35,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(),
+			}),
 		),
 	);
 
@@ -57,24 +86,53 @@ 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>,
@@ -82,13 +140,14 @@ export const serve = <E, R>(
 	Layer.effectDiscard(
 		Effect.gen(function* () {
 			const registry = yield* Registry;
-			const baseLogger = registry.baseLogger;
 			yield* Layer.build(
 				actorsLayer.pipe(
-					Layer.provideMerge(Logger.layerPino(baseLogger)),
+					Layer.provideMerge(
+						RivetLogger.layerFromPino(registry.baseLogger),
+					),
 				),
 			);
-			const rivetkitRegistry = setupRivetkitRegistry(registry);
+			const rivetkitRegistry = yield* setupRivetkitRegistry(registry);
 			yield* Effect.sync(() => rivetkitRegistry.start());
 		}),
 	);
@@ -107,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,
@@ -145,17 +204,21 @@ 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;
 
@@ -179,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 & {
@@ -221,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,

package/src/RivetError.ts

@@ -426,6 +426,38 @@ export class GuardActorReadyTimeout extends Schema.TaggedErrorClass<GuardActorRe
 	}
 }
 
+export class GuardActorWakeRetriesExceeded extends Schema.TaggedErrorClass<GuardActorWakeRetriesExceeded>(
+	`${ReasonTypeId}/GuardActorWakeRetriesExceeded`,
+)("GuardActorWakeRetriesExceeded", {
+	cause: Schema.instanceOf(RivetkitErrors.RivetError),
+}) {
+	readonly [ReasonTypeId] = ReasonTypeId;
+	override get message() {
+		return this.cause.message;
+	}
+	get group() {
+		return this.cause.group;
+	}
+	get code() {
+		return this.cause.code;
+	}
+	get metadata() {
+		return this.cause.metadata;
+	}
+	get actor() {
+		return this.cause.actor;
+	}
+	get statusCode() {
+		return this.cause.statusCode;
+	}
+	get public() {
+		return this.cause.public;
+	}
+	get isRetryable(): boolean {
+		return true;
+	}
+}
+
 export class GuardActorRunnerFailed extends Schema.TaggedErrorClass<GuardActorRunnerFailed>(
 	`${ReasonTypeId}/GuardActorRunnerFailed`,
 )("GuardActorRunnerFailed", {
@@ -816,6 +848,7 @@ export type RivetErrorReason =
 	| InvalidEncoding
 	| InvalidRequest
 	| GuardActorReadyTimeout
+	| GuardActorWakeRetriesExceeded
 	| GuardActorRunnerFailed
 	| GuardServiceUnavailable
 	| GuardActorStoppedWhileWaiting
@@ -843,6 +876,7 @@ export const RivetErrorReason: Schema.Union<
 		typeof InvalidEncoding,
 		typeof InvalidRequest,
 		typeof GuardActorReadyTimeout,
+		typeof GuardActorWakeRetriesExceeded,
 		typeof GuardActorRunnerFailed,
 		typeof GuardServiceUnavailable,
 		typeof GuardActorStoppedWhileWaiting,
@@ -869,6 +903,7 @@ export const RivetErrorReason: Schema.Union<
 	InvalidEncoding,
 	InvalidRequest,
 	GuardActorReadyTimeout,
+	GuardActorWakeRetriesExceeded,
 	GuardActorRunnerFailed,
 	GuardServiceUnavailable,
 	GuardActorStoppedWhileWaiting,
@@ -993,6 +1028,8 @@ const reasonByCode: { [key: string]: MakeRivetErrorReason | undefined } = {
 	"request.invalid": (error) => new InvalidRequest({ cause: error }),
 	"guard.actor_ready_timeout": (error) =>
 		new GuardActorReadyTimeout({ cause: error }),
+	"guard.actor_wake_retries_exceeded": (error) =>
+		new GuardActorWakeRetriesExceeded({ cause: error }),
 	"guard.actor_runner_failed": (error) =>
 		new GuardActorRunnerFailed({ cause: error }),
 	"guard.service_unavailable": (error) =>

package/src/RivetLogger.ts

@@ -0,0 +1,60 @@
+import { Effect, Logger, Layer } from "effect";
+import * as RivetkitLog from "rivetkit/log";
+import {
+	BaseLogger,
+	getOrCreateBaseLogger,
+	makeLogger,
+} from "./internal/logging.ts";
+
+/**
+ * Builds an Effect logger from a custom Pino-compatible logger.
+ *
+ * Use this with Effect's `Logger.layer` when you only need to customize Effect
+ * log output. Use {@link layerFromPino} when RivetKit's underlying TypeScript SDK
+ * logs should use the same logger too.
+ *
+ * @example
+ * ```ts
+ * import { Logger } from "effect"
+ * import { RivetLogger } from "@rivetkit/effect"
+ * import { pino } from "pino"
+ *
+ * const baseLogger = pino({ transport: { target: "pino-pretty" } })
+ * const LoggerLive = Logger.layer([RivetLogger.fromPino(baseLogger)])
+ * ```
+ */
+export const fromPino = (
+	baseLogger: RivetkitLog.Logger,
+): Logger.Logger<unknown, void> => makeLogger(baseLogger);
+
+/**
+ * Builds a logging layer from a custom Pino-compatible logger.
+ *
+ * The layer installs the matching Effect logger and configures the underlying
+ * RivetKit TypeScript SDK logs to go through the same logger. The Effect tracer
+ * logger is installed alongside the Pino adapter so log events remain attached
+ * to active traces.
+ */
+export const layerFromPino = (
+	baseLogger: RivetkitLog.Logger,
+	options?: {
+		readonly mergeWithExisting?: boolean | undefined;
+	},
+): Layer.Layer<BaseLogger> =>
+	Layer.mergeAll(
+		Layer.succeed(BaseLogger, baseLogger),
+		Logger.layer([Logger.tracerLogger, fromPino(baseLogger)], {
+			mergeWithExisting: options?.mergeWithExisting,
+		}),
+	);
+
+/**
+ * Default RivetKit Effect logging layer.
+ *
+ * The layer creates a base logger from RivetKit log configuration and installs
+ * the Effect logger adapter. Applications that want custom formatting or
+ * transports should provide {@link layerFromPino} instead.
+ */
+export const defaultLayer: Layer.Layer<never> = Layer.unwrap(
+	Effect.map(getOrCreateBaseLogger, layerFromPino),
+);