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

package/src/internal/ActorInstanceManager.ts

@@ -0,0 +1,137 @@
+import { Context, Effect, Exit, type Fiber, FiberSet, Scope } from "effect";
+import type * as Rivetkit from "@ohos-ports/rivetkit";
+import type * as RivetkitDb from "@ohos-ports/rivetkit/db";
+import type * as ActorStateAdapter from "./ActorStateAdapter.ts";
+import type * as StateOptions from "./StateOptions.ts";
+
+type RivetkitDefinitionFor<
+	StateDefinition extends StateOptions.Any,
+	Database extends RivetkitDb.AnyDatabaseProvider,
+> = Rivetkit.ActorDefinition<
+	StateOptions.Encoded<StateDefinition>,
+	undefined,
+	undefined,
+	undefined,
+	undefined,
+	Database,
+	Record<never, never>,
+	Record<never, never>,
+	any
+>;
+
+type WakeContext<
+	StateDefinition extends StateOptions.Any,
+	Database extends RivetkitDb.AnyDatabaseProvider,
+> = Rivetkit.WakeContextOf<RivetkitDefinitionFor<StateDefinition, Database>>;
+
+export type Instance<
+	ActionHandlers,
+	StateDefinition extends StateOptions.Any,
+> = {
+	readonly actionHandlers: ActionHandlers;
+	readonly runFork: <A, E>(
+		effect: Effect.Effect<A, E, any>,
+		options?: Effect.RunOptions,
+	) => Fiber.Fiber<A, E>;
+	readonly scope: Scope.Closeable;
+	readonly state?: ActorStateAdapter.ActorState<StateDefinition>;
+};
+
+export const make = Effect.fnUntraced(function* <
+	ActionHandlers,
+	StateDefinition extends StateOptions.Any,
+	Database extends RivetkitDb.AnyDatabaseProvider,
+	WakeOptions,
+>({
+	wakeHandler,
+	stateAdapter,
+	makeContext,
+	makeWakeOptions,
+}: {
+	readonly wakeHandler: (
+		wakeOptions: WakeOptions,
+	) => Effect.Effect<ActionHandlers, never, any>;
+	readonly stateAdapter:
+		| ActorStateAdapter.Adapter<StateDefinition>
+		| undefined;
+	readonly makeContext: (
+		c: WakeContext<StateDefinition, Database>,
+		scope: Scope.Closeable,
+	) => Context.Context<any>;
+	readonly makeWakeOptions: (
+		c: WakeContext<StateDefinition, Database>,
+		state: ActorStateAdapter.ActorState<StateDefinition> | undefined,
+	) => WakeOptions;
+}) {
+	const instances = new Map<
+		string,
+		Instance<ActionHandlers, StateDefinition>
+	>();
+
+	const services = yield* Effect.context<any>();
+	const runPromise = Effect.runPromiseWith(services);
+
+	const makeInstance = Effect.fnUntraced(function* (
+		c: WakeContext<StateDefinition, Database>,
+	): Effect.fn.Return<Instance<ActionHandlers, StateDefinition>, never, any> {
+		const scope = yield* Scope.make();
+		return yield* Effect.gen(function* () {
+			const state = stateAdapter
+				? yield* stateAdapter
+						.makeStateView(c)
+						.pipe(Effect.provideService(Scope.Scope, scope))
+				: undefined;
+			const context = makeContext(c, scope);
+			const actionHandlers = yield* wakeHandler(
+				makeWakeOptions(c, state),
+			).pipe(Effect.provide(context));
+			const runFork = yield* FiberSet.makeRuntime<
+				any,
+				unknown,
+				unknown
+			>().pipe(Effect.provide(Context.merge(services, context)));
+
+			return {
+				actionHandlers,
+				runFork,
+				scope,
+				state,
+			};
+		}).pipe(
+			Effect.onError((cause) =>
+				Scope.close(scope, Exit.failCause(cause)),
+			),
+		);
+	});
+
+	return {
+		get: (actorId: string) => instances.get(actorId),
+		onWake: async (c: WakeContext<StateDefinition, Database>) => {
+			instances.set(c.actorId, await runPromise(makeInstance(c)));
+		},
+		onStateChange: stateAdapter
+			? (
+					c: WakeContext<StateDefinition, Database>,
+					newState: unknown,
+				) => {
+					const instance = instances.get(c.actorId);
+					// State changes can arrive after teardown removes the instance.
+					if (!instance) return;
+
+					stateAdapter.publishChange(instance, newState);
+				}
+			: undefined,
+		onTeardown: async (c: { readonly actorId: string }) => {
+			return runPromise(
+				Effect.gen(function* () {
+					const instance = instances.get(c.actorId);
+					// Teardown can be reported through multiple lifecycle callbacks.
+					if (!instance) return;
+
+					instances.delete(c.actorId);
+					yield* Scope.close(instance.scope, Exit.void);
+				}),
+			);
+		},
+	};
+});

package/src/internal/ActorStateAdapter.ts

@@ -0,0 +1,82 @@
+import { Effect, type Fiber, Schema } from "effect";
+import * as State from "../State.ts";
+import type * as StateOptions from "./StateOptions.ts";
+
+export type ActorState<StateDefinition extends StateOptions.Any> = State.State<
+	StateOptions.Decoded<StateDefinition>,
+	Schema.SchemaError,
+	StateOptions.Services<StateDefinition>
+>;
+
+type StateInstance<StateDefinition extends StateOptions.Any> = {
+	readonly runFork: <A, E>(
+		effect: Effect.Effect<A, E, any>,
+		options?: Effect.RunOptions,
+	) => Fiber.Fiber<A, E>;
+	readonly state?: ActorState<StateDefinition>;
+};
+
+export type Adapter<StateDefinition extends StateOptions.Any> = {
+	readonly makeStateView: (c: {
+		state: StateOptions.Encoded<StateDefinition>;
+	}) => Effect.Effect<ActorState<StateDefinition>, never, any>;
+	readonly createInitialState: () => Promise<
+		StateOptions.Encoded<StateDefinition>
+	>;
+	readonly publishChange: (
+		instance: StateInstance<StateDefinition>,
+		newState: unknown,
+	) => void;
+};
+
+export const make = Effect.fnUntraced(function* <
+	StateDefinition extends StateOptions.Any,
+>(
+	stateOptions: StateDefinition,
+): Effect.fn.Return<Adapter<StateDefinition>, never, any> {
+	const services = yield* Effect.context<any>();
+
+	const stateCodec = {
+		decodeUnknown: Schema.decodeUnknownEffect(
+			Schema.toCodecJson(stateOptions.schema),
+		),
+		encode: Schema.encodeEffect(Schema.toCodecJson(stateOptions.schema)),
+	};
+
+	return {
+		makeStateView: (c) =>
+			State.make(
+				() => stateCodec.decodeUnknown(c.state),
+				(next) =>
+					stateCodec.encode(next).pipe(
+						Effect.tap((encoded) =>
+							Effect.sync(() => {
+								c.state = encoded;
+							}),
+						),
+						Effect.asVoid,
+					),
+			).pipe(
+				Effect.orDie,
+				Effect.map((state) => state as ActorState<StateDefinition>),
+			),
+		createInitialState: () =>
+			Effect.runPromiseWith(services)(
+				stateCodec
+					.encode(stateOptions.initialValue())
+					.pipe(Effect.orDie),
+			),
+		publishChange: (instance, newState) => {
+			instance.runFork(
+				Effect.gen(function* () {
+					const state = yield* Effect.fromNullishOr(
+						instance.state,
+					).pipe(Effect.orDie);
+					yield* state[State.RuntimeTypeId].publishEffect(
+						stateCodec.decodeUnknown(newState).pipe(Effect.orDie),
+					);
+				}),
+			);
+		},
+	};
+});

package/src/internal/StateOptions.ts

@@ -0,0 +1,21 @@
+import type { Schema } from "effect";
+
+export interface StateOptions<in out S extends Schema.Top> {
+	readonly schema: S;
+	readonly initialValue: () => S["Type"];
+}
+
+export interface Any {
+	readonly schema: Schema.Top;
+	readonly initialValue: () => unknown;
+}
+
+export type Services<State extends Any> =
+	| State["schema"]["DecodingServices"]
+	| State["schema"]["EncodingServices"];
+
+export type Encoded<State extends Any> =
+	| State["schema"]["Encoded"]
+	| ([State] extends [never] ? undefined : never);
+
+export type Decoded<State extends Any> = State["schema"]["Type"];

package/src/internal/logging.test.ts

@@ -0,0 +1,274 @@
+import { assert, describe, it } from "@effect/vitest";
+import { ConfigProvider, Effect, Logger, References } from "effect";
+import * as RivetkitLog from "@ohos-ports/rivetkit/log";
+import * as Logging from "./logging.ts";
+
+type LogEntry = {
+	readonly level: string;
+	readonly fields: Record<string, unknown>;
+	readonly msg: string | undefined;
+};
+
+function makeTestLogger(entries: Array<LogEntry>): RivetkitLog.Logger {
+	const logger: Record<string, unknown> = {};
+	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 RivetkitLog.Logger;
+}
+
+describe("internal/logging", () => {
+	it("serializes actor keys like the RivetKit actor runtime logger", () => {
+		assert.strictEqual(Logging.serializeActorKey([]), "/");
+		assert.strictEqual(Logging.serializeActorKey(["room", "1"]), "room/1");
+		assert.strictEqual(Logging.serializeActorKey(["room/1"]), "room\\/1");
+		assert.strictEqual(Logging.serializeActorKey([""]), "\\0");
+		assert.strictEqual(Logging.serializeActorKey(["a\\b"]), "a\\\\b");
+	});
+
+	it("builds actor log annotations with serialized keys", () => {
+		assert.deepStrictEqual(
+			Logging.makeActorLogAnnotations({
+				name: "ChatRoom",
+				key: ["room/1"],
+				actorId: "actor-1",
+			}),
+			{
+				actor: "ChatRoom",
+				key: "room\\/1",
+				actorId: "actor-1",
+			},
+		);
+	});
+
+	it.effect("writes Effect logs through the RivetKit base logger", () =>
+		Effect.gen(function* () {
+			const entries: Array<LogEntry> = [];
+			const baseLogger = makeTestLogger(entries);
+
+			yield* Effect.logInfo("room awake", { roomId: "abc" }).pipe(
+				Effect.annotateLogs({
+					actor: "ChatRoom",
+					key: "room-1",
+					actorId: "actor-1",
+				}),
+				Effect.provide(Logger.layer([Logging.makeLogger(baseLogger)])),
+			);
+
+			const entry = entries[0];
+			assert.ok(entry !== undefined);
+			assert.strictEqual(entry.level, "info");
+			assert.strictEqual(entry.msg, "room awake");
+			assert.deepStrictEqual(entry.fields, {
+				roomId: "abc",
+				actor: "ChatRoom",
+				key: "room-1",
+				actorId: "actor-1",
+				fiberId: entry.fields.fiberId,
+			});
+			assert.strictEqual(typeof entry.fields.fiberId, "string");
+		}),
+	);
+
+	it.effect("preserves Error log messages as structured error fields", () =>
+		Effect.gen(function* () {
+			const entries: Array<LogEntry> = [];
+			const baseLogger = makeTestLogger(entries);
+			const error = new Error("room failed to wake");
+
+			yield* Effect.logError(error).pipe(
+				Effect.provide(Logger.layer([Logging.makeLogger(baseLogger)])),
+			);
+
+			const entry = entries[0];
+			assert.ok(entry !== undefined);
+			assert.strictEqual(entry.level, "error");
+			assert.strictEqual(entry.fields.error, error);
+			assert.strictEqual(entry.msg, error.message);
+		}),
+	);
+
+	it.effect("preserves Error log messages with additional fields", () =>
+		Effect.gen(function* () {
+			const entries: Array<LogEntry> = [];
+			const baseLogger = makeTestLogger(entries);
+			const error = new Error("action dispatch failed");
+
+			yield* Effect.logError(error, {
+				actorId: "actor-1",
+				action: "SendMessage",
+			}).pipe(
+				Effect.provide(Logger.layer([Logging.makeLogger(baseLogger)])),
+			);
+
+			const entry = entries[0];
+			assert.ok(entry !== undefined);
+			assert.strictEqual(entry.level, "error");
+			assert.strictEqual(entry.fields.error, error);
+			assert.strictEqual(entry.fields.actorId, "actor-1");
+			assert.strictEqual(entry.fields.action, "SendMessage");
+			assert.strictEqual(entry.msg, error.message);
+		}),
+	);
+
+	it.effect("accepts RIVET_LOG_LEVEL values", () =>
+		Effect.gen(function* () {
+			const baseLogger = yield* Logging.makeDefaultBaseLogger;
+
+			assert.strictEqual(baseLogger.level, "silent");
+		}).pipe(
+			Effect.provideService(
+				ConfigProvider.ConfigProvider,
+				ConfigProvider.fromEnv({
+					env: {
+						RIVET_LOG_LEVEL: "silent",
+					},
+				}),
+			),
+		),
+	);
+
+	it.effect("accepts uppercase RIVET_LOG_LEVEL values", () =>
+		Effect.gen(function* () {
+			const baseLogger = yield* Logging.makeDefaultBaseLogger;
+
+			assert.strictEqual(baseLogger.level, "debug");
+		}).pipe(
+			Effect.provideService(
+				ConfigProvider.ConfigProvider,
+				ConfigProvider.fromEnv({
+					env: {
+						RIVET_LOG_LEVEL: "DEBUG",
+					},
+				}),
+			),
+		),
+	);
+
+	it.effect("ignores Effect-only RIVET_LOG_LEVEL values", () =>
+		Effect.gen(function* () {
+			const baseLogger = yield* Logging.makeDefaultBaseLogger;
+
+			assert.strictEqual(baseLogger.level, "info");
+		}).pipe(
+			Effect.provideService(References.MinimumLogLevel, "Info"),
+			Effect.provideService(
+				ConfigProvider.ConfigProvider,
+				ConfigProvider.fromEnv({
+					env: {
+						RIVET_LOG_LEVEL: "None",
+					},
+				}),
+			),
+		),
+	);
+
+	it.effect("falls back to References.MinimumLogLevel without env", () =>
+		Effect.gen(function* () {
+			const baseLogger = yield* Logging.makeDefaultBaseLogger;
+
+			assert.strictEqual(baseLogger.level, "debug");
+		}).pipe(
+			Effect.provideService(References.MinimumLogLevel, "Debug"),
+			Effect.provideService(
+				ConfigProvider.ConfigProvider,
+				ConfigProvider.fromEnv({
+					env: {},
+				}),
+			),
+		),
+	);
+
+	it.effect("RIVET_LOG_LEVEL overrides References.MinimumLogLevel", () =>
+		Effect.gen(function* () {
+			const baseLogger = yield* Logging.makeDefaultBaseLogger;
+
+			assert.strictEqual(baseLogger.level, "silent");
+		}).pipe(
+			Effect.provideService(References.MinimumLogLevel, "Debug"),
+			Effect.provideService(
+				ConfigProvider.ConfigProvider,
+				ConfigProvider.fromEnv({
+					env: {
+						RIVET_LOG_LEVEL: "silent",
+					},
+				}),
+			),
+		),
+	);
+
+	it.effect(
+		"uses References.CurrentLogLevel for plain Effect.log calls",
+		() =>
+			Effect.gen(function* () {
+				const entries: Array<LogEntry> = [];
+				const baseLogger = makeTestLogger(entries);
+
+				yield* Effect.log("plain log").pipe(
+					Effect.provideService(References.CurrentLogLevel, "Debug"),
+					Effect.provideService(References.MinimumLogLevel, "Debug"),
+					Effect.provide(
+						Logger.layer([Logging.makeLogger(baseLogger)]),
+					),
+				);
+
+				const entry = entries[0];
+				assert.ok(entry !== undefined);
+				assert.strictEqual(entry.level, "debug");
+				assert.strictEqual(entry.msg, "plain log");
+				assert.deepStrictEqual(entry.fields, {
+					fiberId: entry.fields.fiberId,
+				});
+				assert.strictEqual(typeof entry.fields.fiberId, "string");
+			}),
+	);
+
+	it.effect(
+		"does not call a Pino method for the None current log level",
+		() =>
+			Effect.gen(function* () {
+				const entries: Array<LogEntry> = [];
+				const baseLogger = makeTestLogger(entries);
+
+				yield* Effect.log("hidden log").pipe(
+					Effect.provideService(References.CurrentLogLevel, "None"),
+					Effect.provideService(References.MinimumLogLevel, "All"),
+					Effect.provide(
+						Logger.layer([Logging.makeLogger(baseLogger)]),
+					),
+				);
+
+				assert.deepStrictEqual(entries, []);
+			}),
+	);
+
+	it.effect(
+		"emits References.CurrentLogSpans as structured span durations",
+		() =>
+			Effect.gen(function* () {
+				const entries: Array<LogEntry> = [];
+				const baseLogger = makeTestLogger(entries);
+
+				yield* Effect.logInfo("checkout complete").pipe(
+					Effect.withLogSpan("checkout"),
+					Effect.provide(
+						Logger.layer([Logging.makeLogger(baseLogger)]),
+					),
+				);
+
+				assert.strictEqual(entries.length, 1);
+				assert.strictEqual(entries[0]?.level, "info");
+				assert.strictEqual(entries[0]?.msg, "checkout complete");
+				const spans = entries[0]?.fields.spans as
+					| Record<string, unknown>
+					| undefined;
+				assert.strictEqual(typeof spans?.checkout, "number");
+			}),
+	);
+});

package/src/internal/logging.ts

@@ -0,0 +1,197 @@
+import {
+	Config,
+	Context,
+	Effect,
+	Logger,
+	Option,
+	Predicate,
+	Record as EffectRecord,
+	type LogLevel,
+	References,
+} from "effect";
+import type * as Rivetkit from "@ohos-ports/rivetkit";
+import * as RivetkitLog from "@ohos-ports/rivetkit/log";
+
+const EMPTY_KEY = "/";
+const KEY_SEPARATOR = "/";
+
+type ActorLogContext = {
+	readonly name: string;
+	readonly key: Rivetkit.ActorKey;
+	readonly actorId: string;
+};
+
+export class BaseLogger extends Context.Service<
+	BaseLogger,
+	RivetkitLog.Logger
+>()("@rivetkit/effect/RivetLogger/BaseLogger") {}
+
+const RivetkitLogLevels = RivetkitLog.LogLevelSchema.options;
+
+const EffectLevelByRivetkitLevel = {
+	trace: "Trace",
+	debug: "Debug",
+	info: "Info",
+	warn: "Warn",
+	error: "Error",
+	fatal: "Fatal",
+	silent: "None",
+} as const satisfies Record<
+	RivetkitLog.LogLevel,
+	Exclude<LogLevel.LogLevel, "All">
+>;
+
+const RivetkitLevelByEffectLevel = {
+	...Object.fromEntries(
+		RivetkitLogLevels.map((level) => [
+			EffectLevelByRivetkitLevel[level],
+			level,
+		]),
+	),
+	All: "trace",
+} as Record<LogLevel.LogLevel, RivetkitLog.LogLevel>;
+
+const rivetLogLevelFromEnv = Config.string("RIVET_LOG_LEVEL").pipe(
+	Effect.option,
+	Effect.map((maybeRivetLogLevel) => {
+		if (Option.isNone(maybeRivetLogLevel)) return Option.none();
+
+		const parsed = RivetkitLog.LogLevelSchema.safeParse(
+			maybeRivetLogLevel.value.toLowerCase(),
+		);
+		return parsed.success ? Option.some(parsed.data) : Option.none();
+	}),
+);
+
+export const makeDefaultBaseLogger: Effect.Effect<RivetkitLog.Logger> =
+	Effect.gen(function* () {
+		const maybeRivetLogLevel = yield* rivetLogLevelFromEnv;
+		const logLevel = Option.isSome(maybeRivetLogLevel)
+			? maybeRivetLogLevel.value
+			: RivetkitLevelByEffectLevel[yield* References.MinimumLogLevel];
+
+		return yield* Effect.sync(() =>
+			RivetkitLog.makeDefaultLogger(logLevel),
+		);
+	});
+
+export const getOrCreateBaseLogger: Effect.Effect<RivetkitLog.Logger> =
+	Effect.gen(function* () {
+		const maybeBaseLogger = yield* Effect.serviceOption(BaseLogger);
+		if (Option.isSome(maybeBaseLogger)) {
+			return maybeBaseLogger.value;
+		}
+
+		return yield* makeDefaultBaseLogger;
+	});
+
+export function makeActorLogAnnotations(context: ActorLogContext): {
+	readonly actor: string;
+	readonly key: string;
+	readonly actorId: string;
+} {
+	return {
+		actor: context.name,
+		key: serializeActorKey(context.key),
+		actorId: context.actorId,
+	};
+}
+
+export function serializeActorKey(key: Rivetkit.ActorKey): string {
+	if (key.length === 0) {
+		return EMPTY_KEY;
+	}
+
+	return key
+		.map((part) => {
+			if (part === "") {
+				return "\\0";
+			}
+
+			return part
+				.replace(/\\/g, "\\\\")
+				.replace(/\//g, `\\${KEY_SEPARATOR}`);
+		})
+		.join(KEY_SEPARATOR);
+}
+
+export function makeLogger(
+	baseLogger: RivetkitLog.Logger,
+): Logger.Logger<unknown, void> {
+	return Logger.make((options) => {
+		if (options.logLevel === "None") return;
+		const rivetkitLevel = RivetkitLevelByEffectLevel[options.logLevel];
+		const structured = Logger.formatStructured.log(options);
+		const { msg, fields: messageFields } = extractMessage(
+			structured.message,
+		);
+		const fields: Record<string, unknown> = {
+			...messageFields,
+			...structured.annotations,
+			fiberId: structured.fiberId,
+		};
+
+		if (!EffectRecord.isEmptyRecord(structured.spans)) {
+			fields.spans = structured.spans;
+		}
+		if (structured.cause !== undefined) {
+			fields.cause = structured.cause;
+		}
+
+		const logger = baseLogger[rivetkitLevel];
+		if (msg === undefined) {
+			logger.call(baseLogger, fields);
+		} else {
+			logger.call(baseLogger, fields, msg);
+		}
+	});
+}
+
+function extractMessage(message: unknown): {
+	readonly msg: string | undefined;
+	readonly fields: Record<string, unknown>;
+} {
+	const values = Array.isArray(message) ? message : [message];
+	const fields: Record<string, unknown> = {};
+	const args: Array<unknown> = [];
+	let msg: string | undefined;
+
+	for (const [index, value] of values.entries()) {
+		if (Predicate.isError(value)) {
+			fields.error = value;
+			if (index === 0) msg = value.message;
+		} else if (isStructuredError(value)) {
+			fields.error = value;
+			if (index === 0) msg = value.error;
+		} else if (Predicate.isObject(value)) {
+			if (index === 0) {
+				const { msg: valueMsg, ...rest } = value;
+				Object.assign(fields, rest);
+				if (valueMsg !== undefined) msg = String(valueMsg);
+			} else {
+				Object.assign(fields, value);
+			}
+		} else if (index === 0) {
+			msg = value === undefined ? undefined : String(value);
+		} else {
+			args.push(value);
+		}
+	}
+
+	if (args.length > 0) {
+		fields.args = args;
+	}
+
+	return { msg, fields };
+}
+
+function isStructuredError(
+	value: unknown,
+): value is { readonly error: string; readonly name: string } {
+	return (
+		Predicate.hasProperty(value, "error") &&
+		Predicate.hasProperty(value, "name") &&
+		Predicate.isString(value.error) &&
+		Predicate.isString(value.name)
+	);
+}