import * as NodeUtil from "node:util"; import * as Cause from "effect/Cause"; import * as Context from "effect/Context"; import * as Duration from "effect/Duration"; import * as Effect from "effect/Effect"; import * as Exit from "effect/Exit"; import { flow } from "effect/Function"; import * as Redacted from "effect/Redacted"; import * as Schema from "effect/Schema"; import type * as Scope from "effect/Scope"; import * as Stream from "effect/Stream"; import { stripUnowned, Unowned, Unresolved } from "../AdoptPolicy.ts"; import * as Output from "../Output.ts"; import { isRedactedMarker, type RedactedMarker } from "../RuntimeContext.ts"; import { decodeDuration, DURATION_MARKER, encodeState } from "../State/StateEncoding.ts"; import { currentTraceParent, type TraceParent, withStreamTraceParent, withTraceParent, } from "../Util/TraceParent.ts"; type RpcEffectHandler, Success, Error> = ( ...args: Args ) => Effect.Effect; // `parent`: the caller's span, so the sidecar's work joins its trace. type RpcWrappedEffectHandler, Success, Error> = ( args: Args, parent?: TraceParent, ) => Promise>; type RpcStreamHandler, Success, Error> = ( ...args: Args ) => Stream.Stream; type RpcWrappedStreamHandler, Success, Error> = ( args: Args, parent?: TraceParent, ) => RpcSerializedStream; type RpcSerializedStream = ReadableStream; type RpcSerializedExit = | { _tag: "Success"; value: Success } | { _tag: "Failure"; cause: Array> }; type RpcSerializedCause = | { _tag: "Fail"; error: Error } | { _tag: "Die"; defect: unknown } | { _tag: "Interrupt"; fiberId: number | undefined }; export type RpcWrapped = T extends RpcEffectHandler ? RpcWrappedEffectHandler : T extends RpcStreamHandler ? RpcWrappedStreamHandler : T extends Record ? { [K in keyof T]: RpcWrapped } : T; export type RpcUnwrapped = T extends RpcWrappedEffectHandler ? RpcEffectHandler : T extends RpcWrappedStreamHandler ? RpcStreamHandler : T extends Record ? { [K in keyof T]: RpcUnwrapped } : T; export const wrapRpcHandlers = >( handlers: T, streamKeys?: Array, registerCall?: Effect.Effect, ): RpcWrapped => Object.fromEntries( Object.entries(handlers).map(([key, value]) => [ key, typeof value === "function" ? streamKeys?.includes(key) ? wrapRpcStreamHandler(value, registerCall) : wrapRpcEffectHandler(value, registerCall) : typeof value === "object" && value !== null && !Array.isArray(value) ? wrapRpcHandlers(value, undefined, registerCall) : value, ]), ) as RpcWrapped; export const unwrapRpcHandlers = >( handlers: RpcWrapped, streamKeys?: Array, ): RpcUnwrapped => Object.fromEntries( Object.entries(handlers).map(([key, value]) => [ key, typeof value === "function" ? streamKeys?.includes(key) ? unwrapRpcStreamHandler(value) : unwrapRpcEffectHandler(value) : typeof value === "object" && value !== null && !Array.isArray(value) ? unwrapRpcHandlers(value) : value, ]), ) as RpcUnwrapped; const serializeError = (value: unknown) => Schema.encodeEffect(Schema.Defect())(value).pipe(Effect.orDie); /** Wire form of a tagged failure: its tag plus every field the error carries. */ interface TaggedErrorMarker { readonly _tag: "~alchemy/Rpc/TaggedError"; readonly tag: string; readonly name: string | undefined; readonly message: string | undefined; readonly stack: string | undefined; readonly fields: Record; } const taggedErrorClasses = new Map object>(); /** * Registers tagged error classes that a provider may fail with across the RPC * sidecar boundary, so the caller receives instances of the real class (for * `instanceof`) rather than plain tagged objects. Registration is by `_tag`; * call it next to the class definitions so both processes register them. */ export const registerRpcErrorClasses = ( ...classes: ReadonlyArray { readonly _tag: string }> ): void => { for (const cls of classes) { // `Data.TaggedError` sets `_tag` per instance, so read it from a probe. const probe = Reflect.construct(cls, [{}]) as { readonly _tag: string }; taggedErrorClasses.set(probe._tag, cls); } }; const hasStringTag = (value: unknown): value is { readonly _tag: string } => typeof value === "object" && value !== null && "_tag" in value && typeof value._tag === "string"; const serializeFailure = (error: unknown): Effect.Effect => { // Keep a tagged failure's tag and fields so the caller can still // `catchTag` on it (Schema.Defect alone reduces it to name + message). if (!hasStringTag(error)) return serializeError(error); const fields: Record = {}; for (const [key, value] of Object.entries(error)) { if (key === "_tag") continue; fields[key] = serializeRpcArgs(value); } const asError = error instanceof Error ? error : undefined; return Effect.succeed({ _tag: "~alchemy/Rpc/TaggedError", tag: error._tag, name: asError?.name, message: asError?.message, stack: asError?.stack, fields, } satisfies TaggedErrorMarker); }; const isTaggedErrorMarker = (value: unknown): value is TaggedErrorMarker => typeof value === "object" && value !== null && "_tag" in value && value._tag === "~alchemy/Rpc/TaggedError" && "tag" in value && typeof value.tag === "string"; const deserializeFailure = (error: unknown): unknown => { if (!isTaggedErrorMarker(error)) return error; const fields = deserializeRpcArgs(error.fields) as Record; const cls = taggedErrorClasses.get(error.tag); const revived: Record = cls === undefined ? error.message === undefined ? {} : (new Error(error.message) as unknown as Record) : (Object.create(cls.prototype) as Record); Object.assign(revived, fields); revived._tag = error.tag; for (const key of ["name", "message", "stack"] as const) { const value = error[key]; if (value !== undefined && !(key in fields)) { Object.defineProperty(revived, key, { value, writable: true, configurable: true, enumerable: false, }); } } return revived; }; const wrapRpcEffectHandler = , Success, Error>( handler: RpcEffectHandler, registerCall?: Effect.Effect, ): RpcWrappedEffectHandler => flow( (args, parent) => { const call = Effect.suspend(() => handler(...(deserializeRpcArgs(args) as Args))); return ( registerCall === undefined ? call : Effect.scoped(registerCall.pipe(Effect.andThen(call))) ).pipe(withTraceParent(parent)); }, Effect.exit, Effect.flatMap((exit): Effect.Effect> => { if (exit._tag === "Success") { // Success values need the same marker treatment as args: provider // attributes can legitimately carry `Redacted` secrets (e.g. a local // container's bound env), and a raw Redacted reaching capnweb dies // with `TypeError: Cannot serialize value: `. return Effect.succeed({ _tag: "Success", value: serializeRpcArgs(exit.value) as Success, }); } return Effect.forEach( exit.cause.reasons, (reason): Effect.Effect> => { switch (reason._tag) { case "Fail": return serializeFailure(reason.error).pipe( Effect.map((error) => ({ _tag: "Fail", error: error as Error })), ); case "Die": return serializeError(reason.defect).pipe( Effect.map((defect) => ({ _tag: "Die", defect })), ); case "Interrupt": return Effect.succeed({ _tag: "Interrupt", fiberId: reason.fiberId }); } }, ).pipe(Effect.map((cause) => ({ _tag: "Failure", cause }))); }), Effect.runPromise, ); const wrapRpcStreamHandler = , Success, Error>( handler: RpcStreamHandler, registerCall?: Effect.Effect, ): RpcWrappedStreamHandler => flow( (args, parent) => { const call = Effect.sync(() => handler(...(deserializeRpcArgs(args) as Args))); return Stream.unwrap( registerCall === undefined ? call : registerCall.pipe(Effect.andThen(call)), ).pipe(withStreamTraceParent(parent)); }, (stream) => Stream.toReadableStream(stream), ); const unwrapRpcEffectHandler = , Success, Error>( handler: RpcWrappedEffectHandler, ): RpcEffectHandler => flow( (...args) => serializeRpcArgs(args) as Args, (args) => Effect.flatMap(currentTraceParent, (parent) => Effect.promise(() => handler(args, parent))), Effect.flatMap((exit): Exit.Exit => { if (exit._tag === "Success") { // Mirror of the wrap side: rebuild `Redacted` wrappers from their // wire markers so callers get the same shape an in-process provider // returns. return Exit.succeed(deserializeRpcArgs(exit.value) as Success); } return Exit.failCause( Cause.fromReasons( exit.cause.map((reason): Cause.Reason => { switch (reason._tag) { case "Fail": return Cause.makeFailReason(deserializeFailure(reason.error) as Error); case "Die": return Cause.makeDieReason(reason.defect); case "Interrupt": return Cause.makeInterruptReason(reason.fiberId); } }), ), ); }), ); const unwrapRpcStreamHandler = , Success, Error>( handler: RpcWrappedStreamHandler, ): RpcStreamHandler => flow( (...args) => serializeRpcArgs(args) as Args, (args) => Stream.unwrap( Effect.map(currentTraceParent, (parent) => Stream.fromReadableStream({ evaluate: () => handler(args, parent), onError: (error) => error as Error, }), ), ), ); const serializeRpcArgs = (value: unknown): unknown => { // `read` and `observe` answers: `Unresolved` is a symbol and `Unowned` a // non-enumerable symbol brand, neither of which survives the wire. Lost, // an engine in the parent took a foreign resource for its own. if (value === Unresolved) { return { _tag: "~alchemy/Rpc/Unresolved" } satisfies UnresolvedMarker; } if (Unowned.is(value)) { return { _tag: "~alchemy/Rpc/Unowned", value: serializeRpcArgs(stripUnowned(value as object)), } satisfies UnownedMarker; } if (Redacted.isRedacted(value)) { return { _tag: "Redacted", value: Redacted.value(value), } satisfies RedactedMarker; } // Output must be tested BEFORE Effect.isEffect — Output exprs are yieldable // and would otherwise be misclassified as plain Effects. if (Output.isOutput(value)) { return { _tag: "Output", description: NodeUtil.inspect(value), }; } // Runtime-only effect values riding in props (e.g. a Worker's `exports` // carries each DO's `constructor` Effect and captured `services` Context — // passed through prop resolution by identity since #1094). They cannot // cross the wire (function-valued internals kill capnweb) and the sidecar // never runs them (`stripEffects` drops them from `news` provider-side), so // ship a marker that deserializes back into an equivalent leaf: an Effect // that dies loudly if it IS ever run, keeping `isResolved`/`stripEffects` // semantics identical on both sides of the boundary. if (Effect.isEffect(value)) { return { _tag: "~alchemy/Rpc/Effect", description: NodeUtil.inspect(value), } satisfies EffectMarker; } if (Context.isContext(value)) { return { _tag: "~alchemy/Rpc/Context", description: NodeUtil.inspect(value), } satisfies ContextMarker; } // Duration has `toJSON` (so the structural walk below skips it) but // capnweb cannot serialize the live Effect Duration object — it dies // with `TypeError: Cannot serialize value: 15000 millis`. Use the same // `{ __duration__: toJSON() }` envelope as persisted state. if (Duration.isDuration(value)) { return encodeState(value); } if (typeof value === "function") { return null; } if (Array.isArray(value)) { return value.map(serializeRpcArgs); } if (value && typeof value === "object" && !("toJSON" in value)) { return Object.fromEntries( Object.entries(value).map(([key, child]) => [key, serializeRpcArgs(child)]), ); } return value; }; interface UnresolvedMarker { readonly _tag: "~alchemy/Rpc/Unresolved"; } interface UnownedMarker { readonly _tag: "~alchemy/Rpc/Unowned"; readonly value: unknown; } const isUnresolvedMarker = (value: object): value is UnresolvedMarker => "_tag" in value && value._tag === "~alchemy/Rpc/Unresolved" && Object.keys(value).length === 1; const isUnownedMarker = (value: object): value is UnownedMarker => "_tag" in value && value._tag === "~alchemy/Rpc/Unowned" && "value" in value; interface EffectMarker { readonly _tag: "~alchemy/Rpc/Effect"; readonly description: string; } interface ContextMarker { readonly _tag: "~alchemy/Rpc/Context"; readonly description: string; } const isEffectMarker = (value: object): value is EffectMarker => "_tag" in value && value._tag === "~alchemy/Rpc/Effect" && "description" in value && typeof value.description === "string"; const isContextMarker = (value: object): value is ContextMarker => "_tag" in value && value._tag === "~alchemy/Rpc/Context" && "description" in value && typeof value.description === "string"; const isDurationEnvelope = (value: object): value is { [DURATION_MARKER]: unknown } => DURATION_MARKER in value && Object.keys(value).length === 1; const deserializeRpcArgs = (value: unknown): unknown => { if (Array.isArray(value)) { return value.map(deserializeRpcArgs); } else if (typeof value === "object" && value !== null) { // These values are serialized as `{_tag: "Redacted", value: ...}` and `{_tag: "Output", description: ...}`, // so we need to detect them manually - Redacted.isRedacted and Output.isOutput do not work. if (isUnresolvedMarker(value)) { return Unresolved; } else if (isUnownedMarker(value)) { const attrs = deserializeRpcArgs(value.value); return typeof attrs === "object" && attrs !== null ? Unowned(attrs) : attrs; } else if (isRedactedMarker(value)) { return Redacted.make(value.value); } else if ( "_tag" in value && value._tag === "Output" && "description" in value && typeof value.description === "string" ) { return new Output.NamedExpr( new Output.EffectExpr(Output.VoidExpr, () => Effect.never), value.description, ); } else if (isEffectMarker(value)) { // Rebuild an Effect-typed leaf so `isResolved`/`stripEffects` classify // it exactly like the original; dies loudly if anything ever runs it. const description = value.description; return Effect.suspend(() => Effect.die( new Error( `An Effect from the resource's props cannot cross the RPC provider boundary and was replaced by a placeholder: ${description}`, ), ), ); } else if (isContextMarker(value)) { return Context.empty(); } else if (isDurationEnvelope(value)) { return decodeDuration(value[DURATION_MARKER]) ?? value; } return Object.fromEntries( Object.entries(value).map(([key, child]) => [key, deserializeRpcArgs(child)]), ); } return value; };