@rivetkit/effect 0.0.0-codex-rivetkit-cli-preview.5e414a8

package/src/Client.test.ts

@@ -0,0 +1,210 @@
+import { assert, describe, it } from "@effect/vitest";
+import { Client, Logger, RivetError } 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 ActionErrorEnvelope from "./internal/ActionErrorEnvelope";
+
+function makeTestLogger(
+	entries?: Array<{
+		readonly level: string;
+		readonly fields: Record<string, unknown>;
+		readonly msg: string | undefined;
+	}>,
+): PinoLogger {
+	const logger: Record<string, unknown> = {
+		level: "debug",
+		child: () => logger,
+	};
+	for (const level of [
+		"trace",
+		"debug",
+		"info",
+		"warn",
+		"error",
+		"fatal",
+	]) {
+		logger[level] = (
+			fields: Record<string, unknown>,
+			msg?: string,
+		): void => {
+			entries?.push({ level, fields, msg });
+		};
+	}
+
+	return logger as unknown as PinoLogger;
+}
+
+describe("Client", () => {
+	it.effect("configures the underlying RivetKit client logger", () =>
+		Effect.scoped(
+			Effect.gen(function* () {
+				const baseLogger = makeTestLogger();
+
+				yield* Effect.addFinalizer(() =>
+					Effect.sync(() => configureDefaultLogger("silent")),
+				);
+				yield* Client.make({
+					endpoint: "http://127.0.0.1:6420",
+				}).pipe(Effect.provide(Logger.layerPino(baseLogger)));
+
+				assert.strictEqual(getBaseLogger(), baseLogger);
+			}),
+		),
+	);
+
+	it.effect("installs the RivetKit Effect logger for client programs", () =>
+		Effect.scoped(
+			Effect.gen(function* () {
+				const entries: Array<{
+					readonly level: string;
+					readonly fields: Record<string, unknown>;
+					readonly msg: string | undefined;
+				}> = [];
+				const baseLogger = makeTestLogger(entries);
+
+				yield* Effect.addFinalizer(() =>
+					Effect.sync(() => configureDefaultLogger("silent")),
+				);
+				yield* Effect.gen(function* () {
+					yield* Client.Client;
+					yield* Effect.logInfo("client effect log", {
+						clientId: "test-client",
+					});
+				}).pipe(
+					Effect.provide(
+						Client.layer({
+							endpoint: "http://127.0.0.1:6420",
+						}).pipe(
+							Layer.provideMerge(Logger.layerPino(baseLogger)),
+						),
+					),
+				);
+
+				assert.deepStrictEqual(entries[0], {
+					level: "info",
+					fields: { clientId: "test-client" },
+					msg: "client effect log",
+				});
+				assert.ok(
+					entries.some(
+						(entry) =>
+							entry.level === "debug" &&
+							(entry.fields as { msg?: unknown }).msg ===
+								"disposing client",
+					),
+				);
+			}),
+		),
+	);
+});
+
+describe("makeRivetkitActionFailureClassifier", () => {
+	const ExpectedError = Schema.Struct({
+		_tag: Schema.tag("CounterOverflow"),
+		message: Schema.String,
+		limit: Schema.Number,
+	});
+	const classifyRivetkitActionFailure =
+		Client.makeRivetkitActionFailureClassifier(ExpectedError);
+
+	it.effect("preserves non-Rivet failures as UnknownError", () =>
+		Effect.gen(function* () {
+			const cause = new Error("plain failure");
+			const error = yield* classifyRivetkitActionFailure(cause);
+
+			assert.instanceOf(error, RivetError.RivetError);
+			assert.instanceOf(error.reason, RivetError.UnknownError);
+			assert.strictEqual(error.reason.message, "plain failure");
+			assert.strictEqual(error.reason.cause, cause);
+		}),
+	);
+
+	it.effect("preserves structured non-action Rivet errors", () =>
+		Effect.gen(function* () {
+			const cause = new RivetkitErrors.RivetError(
+				"actor",
+				"not_found",
+				"actor not found",
+			);
+			const error = yield* classifyRivetkitActionFailure(cause);
+
+			assert.instanceOf(error, RivetError.RivetError);
+			assert.instanceOf(error.reason, RivetError.ActorNotFound);
+			assert.strictEqual(error.reason.cause.group, "actor");
+			assert.strictEqual(error.reason.cause.code, "not_found");
+			assert.strictEqual(error.reason.cause.message, "actor not found");
+		}),
+	);
+
+	it.effect(
+		"decodes action-error metadata into the declared error type",
+		() =>
+			Effect.gen(function* () {
+				const cause = new RivetkitErrors.RivetError(
+					"user",
+					"CounterOverflow",
+					"counter overflow",
+					{
+						public: true,
+						metadata: {
+							_tag: ActionErrorEnvelope.tag,
+							version: ActionErrorEnvelope.schemaVersion,
+							error: {
+								_tag: "CounterOverflow",
+								message: "counter overflow",
+								limit: 10,
+							},
+						},
+					},
+				);
+				const error = yield* classifyRivetkitActionFailure(cause);
+
+				assert.deepStrictEqual(error, {
+					_tag: "CounterOverflow",
+					message: "counter overflow",
+					limit: 10,
+				});
+			}),
+	);
+
+	it.effect(
+		"wraps invalid typed action-error payloads in ActionErrorDecodeFailed",
+		() =>
+			Effect.gen(function* () {
+				const cause = new RivetkitErrors.RivetError(
+					"user",
+					"CounterOverflow",
+					"counter overflow",
+					{
+						metadata: {
+							_tag: ActionErrorEnvelope.tag,
+							version: ActionErrorEnvelope.schemaVersion,
+							error: {
+								_tag: "CounterOverflow",
+								message: "counter overflow",
+								limit: "10",
+							},
+						},
+					},
+				);
+
+				const error = yield* classifyRivetkitActionFailure(cause);
+
+				assert.instanceOf(error, RivetError.RivetError);
+				assert.instanceOf(
+					error.reason,
+					RivetError.ActionErrorDecodeFailed,
+				);
+				assert.strictEqual(error.reason.rivetError.group, "user");
+				assert.strictEqual(
+					error.reason.rivetError.code,
+					"CounterOverflow",
+				);
+			}),
+	);
+});

package/src/Client.ts

@@ -0,0 +1,216 @@
+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 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 RivetError from "./RivetError.ts";
+
+const TypeId = "~@rivetkit/effect/Client";
+
+/**
+ * Connection options for the Rivet Engine client transport. Mirrors
+ * the `(endpoint, token, namespace)` subset of rivetkit's
+ * `ClientConfigInput`.
+ */
+export type Options = Pick<
+	RivetkitClient.ClientConfigInput,
+	"endpoint" | "token" | "namespace"
+>;
+
+/**
+ * Per-call metadata envelope shipped as `args[1]` alongside the encoded
+ * payload. The SDK currently uses it for trace propagation (`trace`),
+ * but it's intentionally extensible so future cross-cutting concerns —
+ * idempotency keys, deadlines, custom headers — can land as additional
+ * optional fields without changing the wire shape.
+ */
+export interface ActionMeta {
+	readonly trace?: TraceMeta;
+}
+
+export interface Client {
+	readonly [TypeId]: typeof TypeId;
+
+	readonly makeActorAccessor: <Actions extends Action.AnyWithProps>(
+		actor: Actor.Actor<string, Actions>,
+	) => Actor.Accessor<Actions>;
+}
+
+export const Client: Context.Service<Client, Client> = Context.Service<Client>(
+	"@rivetkit/effect/Client",
+);
+
+export const make = Effect.fnUntraced(function* (options: Options = {}) {
+	const baseLogger = yield* getOrCreateBaseLogger;
+	const rivetkitClient = yield* Effect.acquireRelease(
+		Effect.sync(() => {
+			configureBaseLogger(baseLogger);
+			return RivetkitClient.createClient(options);
+		}),
+		(c) => Effect.promise(() => c.dispose()),
+	);
+
+	return Client.of({
+		[TypeId]: TypeId,
+		makeActorAccessor: (actor) => ({
+			getOrCreate: (key) => {
+				const rivetkitActorHandle = rivetkitClient.getOrCreate(
+					actor.name,
+					key,
+				);
+
+				return Record.fromIterableWith(actor.actions, (action) => {
+					const encodePayload = Schema.encodeEffect(
+						Schema.toCodecJson(action.payloadSchema),
+					);
+					const decodeSuccess = Schema.decodeUnknownEffect(
+						Schema.toCodecJson(action.successSchema),
+					);
+					const classifyRivetkitActionFailure =
+						makeRivetkitActionFailureClassifier(action.errorSchema);
+
+					const rpcMethod = `${actor.name}/${action._tag}`;
+
+					return [
+						action._tag,
+						Effect.fn(rpcMethod, {
+							kind: "client",
+							attributes: {
+								"rpc.system.name": rpcSystem,
+								"rpc.method": rpcMethod,
+							},
+						})(function* (payload: unknown) {
+							const span = yield* Effect.currentSpan;
+							const meta: ActionMeta = {
+								trace: {
+									traceId: span.traceId,
+									spanId: span.spanId,
+									sampled: span.sampled,
+								},
+							};
+							const encodedPayload = yield* encodePayload(
+								payload,
+							).pipe(
+								Effect.mapError(
+									(cause) =>
+										new RivetError.RivetError({
+											reason: new RivetError.InvalidEncoding(
+												{
+													cause: new RivetkitErrors.RivetError(
+														"encoding",
+														"invalid",
+														"Could not encode action payload",
+														{
+															public: true,
+															metadata: cause,
+														},
+													),
+												},
+											),
+										}),
+								),
+							);
+
+							const encodedSuccess = yield* Effect.tryPromise(
+								(abortSignal) =>
+									rivetkitActorHandle.action({
+										name: action._tag,
+										args: [encodedPayload, meta],
+										signal: abortSignal,
+									}),
+							).pipe(
+								Effect.catch((unknownError) =>
+									classifyRivetkitActionFailure(
+										unknownError.cause,
+									).pipe(Effect.flatMap(Effect.fail)),
+								),
+							);
+
+							return yield* decodeSuccess(encodedSuccess).pipe(
+								Effect.orDie,
+							);
+						}),
+					];
+				}) as Actor.Handle<(typeof actor.actions)[number]>;
+			},
+		}),
+	});
+});
+
+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)),
+			),
+		),
+	);
+
+const decodeActionErrorEnvelope = Schema.decodeUnknownEffect(
+	ActionErrorEnvelope.ActionErrorEnvelope,
+);
+
+/** @internal */
+export const makeRivetkitActionFailureClassifier = <
+	ActionErrorSchema extends Schema.Codec<unknown, unknown, unknown, unknown>,
+>(
+	actionErrorSchema: ActionErrorSchema,
+): ((
+	cause: unknown,
+) => Effect.Effect<
+	ActionErrorSchema["Type"] | RivetError.RivetError,
+	never,
+	ActionErrorSchema["DecodingServices"]
+>) => {
+	const decodeActionError = Schema.decodeUnknownEffect(
+		Schema.toCodecJson(actionErrorSchema),
+	);
+
+	return Effect.fnUntraced(function* (
+		cause: unknown,
+	): Effect.fn.Return<
+		ActionErrorSchema["Type"] | RivetError.RivetError,
+		never,
+		ActionErrorSchema["DecodingServices"]
+	> {
+		// In the case where the `cause` is not a `RivetError`. In principle, this shouldn't happen.
+		if (!RivetkitErrors.isRivetErrorLike(cause)) {
+			return RivetError.fromUnknown(cause);
+		}
+
+		const rivetkitRivetError = RivetkitErrors.toRivetError(cause);
+
+		const actionErrorEnvelope = yield* Effect.result(
+			decodeActionErrorEnvelope(rivetkitRivetError.metadata),
+		);
+
+		// If the error's `metadata` is not a valid action error envelope, then
+		// it means it's not a user-declared action error.
+		if (Result.isFailure(actionErrorEnvelope)) {
+			return RivetError.fromRivetkitRivetError(rivetkitRivetError);
+		}
+
+		const actionErrorResult = yield* Effect.result(
+			decodeActionError(actionErrorEnvelope.success.error),
+		);
+
+		// The envelope was valid, but the inner payload doesn't match the
+		// declared schema — surface as `ActionErrorDecodeFailed`
+		if (Result.isFailure(actionErrorResult)) {
+			return new RivetError.RivetError({
+				reason: new RivetError.ActionErrorDecodeFailed({
+					cause: actionErrorResult.failure,
+					rivetError: rivetkitRivetError,
+				}),
+			});
+		}
+
+		// Successfully decoded user-declared action error
+		return actionErrorResult.success;
+	});
+};

package/src/Logger.ts

@@ -0,0 +1,43 @@
+import { Effect, Logger as EffectLogger, Layer } from "effect";
+import type { Logger as PinoLogger } from "rivetkit/log";
+import {
+	BaseLogger,
+	getOrCreateBaseLogger,
+	makeEffectLogger,
+} from "./internal/logging.ts";
+
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { Logger } from "@rivetkit/effect"
+ * import { pino } from "pino"
+ *
+ * const LoggerLive = Logger.layerPino(
+ *   pino({ transport: { target: "pino-pretty" } })
+ * )
+ * ```
+ */
+export const layerPino = (baseLogger: PinoLogger) =>
+	Layer.mergeAll(
+		Layer.succeed(BaseLogger, baseLogger),
+		EffectLogger.layer([
+			EffectLogger.tracerLogger,
+			makeEffectLogger(baseLogger),
+		]),
+	);
+
+/**
+ * Default RivetKit Effect logging layer.
+ *
+ * The layer creates a base logger from `References.MinimumLogLevel` and installs
+ * the Effect logger adapter. Applications that want custom formatting or
+ * transports should provide {@link layerPino} instead.
+ */
+export const layer: Layer.Layer<never> = Layer.unwrap(
+	Effect.map(getOrCreateBaseLogger, layerPino),
+);

package/src/Registry.test-d.ts

@@ -0,0 +1,126 @@
+import { Action, Actor, Registry } from "@rivetkit/effect";
+import { type Context, Effect, Layer, type Scope } from "effect";
+import type {
+	HttpServerError,
+	HttpServerRequest,
+	HttpServerResponse,
+} from "effect/unstable/http";
+import { describe, expectTypeOf, test } from "vitest";
+
+const TestActor = Actor.make("TestActor", {
+	actions: [Action.make("Test")],
+});
+
+const TestActorLive = TestActor.toLayer({
+	Test: () => Effect.void,
+});
+
+const RegistryLive = TestActorLive.pipe(
+	Layer.provideMerge(Registry.layer({ endpoint: "http://127.0.0.1:6420" })),
+);
+
+describe("Registry.layer", () => {
+	test("accepts connection options", () => {
+		expectTypeOf(Registry.layer).toBeCallableWith({
+			endpoint: "http://127.0.0.1:6420",
+			token: "dev-token",
+			namespace: "default",
+			noWelcome: true,
+		});
+	});
+
+	test("does not accept serverless options", () => {
+		Registry.layer({
+			// @ts-expect-error: serverless routing belongs to toWebHandler and toHttpEffect options.
+			serverless: {
+				basePath: "/",
+			},
+		});
+	});
+});
+
+describe("Registry.serve", () => {
+	test("accepts an actor registration layer", () => {
+		expectTypeOf(Registry.serve).toBeCallableWith(TestActorLive);
+	});
+
+	test("returns a server layer that requires Registry", () => {
+		expectTypeOf(Registry.serve(TestActorLive)).toEqualTypeOf<
+			Layer.Layer<never, never, Registry.Registry>
+		>();
+	});
+});
+
+describe("Registry.toWebHandler", () => {
+	test("accepts a registry layer", () => {
+		expectTypeOf(Registry.toWebHandler).toBeCallableWith(RegistryLive);
+	});
+
+	test("rejects actor registration layers that do not provide Registry", () => {
+		// @ts-expect-error: actor registration layers require Registry but do not provide it.
+		// @effect-diagnostics effect/missingLayerContext:off effect/floatingEffect:off
+		Registry.toWebHandler(TestActorLive);
+	});
+
+	test("accepts serverless routing options", () => {
+		expectTypeOf(Registry.toWebHandler).toBeCallableWith(RegistryLive, {
+			basePath: "/",
+			maxStartPayloadBytes: 1024,
+		});
+	});
+
+	test("rejects registry options", () => {
+		Registry.toWebHandler(RegistryLive, {
+			// @ts-expect-error: noWelcome belongs to Registry.layer options.
+			noWelcome: true,
+		});
+	});
+
+	test("returns a Fetch-compatible handler", () => {
+		const handler = Registry.toWebHandler(RegistryLive);
+
+		expectTypeOf(handler.handler).toEqualTypeOf<
+			(
+				request: Request,
+				context?: Context.Context<never> | undefined,
+			) => Promise<Response>
+		>();
+		expectTypeOf(handler.dispose).toEqualTypeOf<() => Promise<void>>();
+	});
+});
+
+describe("Registry.toHttpEffect", () => {
+	test("accepts serverless routing options", () => {
+		expectTypeOf(Registry.toHttpEffect).toBeCallableWith(RegistryLive, {
+			basePath: "/",
+			maxStartPayloadBytes: 1024,
+		});
+	});
+
+	test("rejects registry options", () => {
+		Registry.toHttpEffect(RegistryLive, {
+			// @ts-expect-error: noWelcome belongs to Registry.layer options.
+			noWelcome: true,
+		});
+	});
+
+	test("rejects actor registration layers that do not provide Registry", () => {
+		// @ts-expect-error: actor registration layers require Registry but do not provide it.
+		// @effect-diagnostics effect/missingLayerContext:off effect/floatingEffect:off
+		Registry.toHttpEffect(TestActorLive);
+	});
+
+	test("returns a scoped Effect HTTP handler", () => {
+		expectTypeOf(Registry.toHttpEffect(RegistryLive)).toEqualTypeOf<
+			Effect.Effect<
+				Effect.Effect<
+					HttpServerResponse.HttpServerResponse,
+					HttpServerError.HttpServerError,
+					HttpServerRequest.HttpServerRequest
+				>,
+				never,
+				Scope.Scope
+			>
+		>();
+	});
+});