sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Local/ RpcSerialization.ts

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 * 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<Args extends Array<any>, Success, Error> = (
  ...args: Args
) => Effect.Effect<Success, Error>;

// `parent`: the caller's span, so the sidecar's work joins its trace.
type RpcWrappedEffectHandler<Args extends Array<any>, Success, Error> = (
  args: Args,
  parent?: TraceParent,
) => Promise<RpcSerializedExit<Success, Error>>;

type RpcStreamHandler<Args extends Array<any>, Success, Error> = (
  ...args: Args
) => Stream.Stream<Success, Error>;

type RpcWrappedStreamHandler<Args extends Array<any>, Success, Error> = (
  args: Args,
  parent?: TraceParent,
) => RpcSerializedStream<Success, Error>;

type RpcSerializedStream<Success, _Error> = ReadableStream<Success>;

type RpcSerializedExit<Success, Error> =
  | { _tag: "Success"; value: Success }
  | { _tag: "Failure"; cause: Array<RpcSerializedCause<Error>> };

type RpcSerializedCause<Error> =
  | { _tag: "Fail"; error: Error }
  | { _tag: "Die"; defect: unknown }
  | { _tag: "Interrupt"; fiberId: number | undefined };

export type RpcWrapped<T> =
  T extends RpcEffectHandler<infer Args, infer Success, infer Error>
    ? RpcWrappedEffectHandler<Args, Success, Error>
    : T extends RpcStreamHandler<infer Args, infer Success, infer Error>
      ? RpcWrappedStreamHandler<Args, Success, Error>
      : T extends Record<string, any>
        ? { [K in keyof T]: RpcWrapped<T[K]> }
        : T;

export type RpcUnwrapped<T> =
  T extends RpcWrappedEffectHandler<infer Args, infer Success, infer Error>
    ? RpcEffectHandler<Args, Success, Error>
    : T extends RpcWrappedStreamHandler<infer Args, infer Success, infer Error>
      ? RpcStreamHandler<Args, Success, Error>
      : T extends Record<string, any>
        ? { [K in keyof T]: RpcUnwrapped<T[K]> }
        : T;

export const wrapRpcHandlers = <T extends Record<string, any>>(
  handlers: T,
  streamKeys?: Array<keyof T>,
  registerCall?: Effect.Effect<void, never, Scope.Scope>,
): RpcWrapped<T> =>
  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<T>;

export const unwrapRpcHandlers = <T extends Record<string, any>>(
  handlers: RpcWrapped<T>,
  streamKeys?: Array<keyof T>,
): RpcUnwrapped<T> =>
  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<T>;

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<string, unknown>;
}

const taggedErrorClasses = new Map<string, new (...args: any) => 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<new (...args: any) => { 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<unknown> => {
  // 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<string, unknown> = {};
  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<string, unknown>;
  const cls = taggedErrorClasses.get(error.tag);
  const revived: Record<string, unknown> =
    cls === undefined
      ? error.message === undefined
        ? {}
        : (new Error(error.message) as unknown as Record<string, unknown>)
      : (Object.create(cls.prototype) as Record<string, unknown>);
  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 = <Args extends Array<any>, Success, Error>(
  handler: RpcEffectHandler<Args, Success, Error>,
  registerCall?: Effect.Effect<void, never, Scope.Scope>,
): RpcWrappedEffectHandler<Args, Success, Error> =>
  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<RpcSerializedExit<Success, Error>> => {
      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: <redacted>`.
        return Effect.succeed({
          _tag: "Success",
          value: serializeRpcArgs(exit.value) as Success,
        });
      }
      return Effect.forEach(
        exit.cause.reasons,
        (reason): Effect.Effect<RpcSerializedCause<Error>> => {
          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 = <Args extends Array<any>, Success, Error>(
  handler: RpcStreamHandler<Args, Success, Error>,
  registerCall?: Effect.Effect<void, never, Scope.Scope>,
): RpcWrappedStreamHandler<Args, Success, Error> =>
  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 = <Args extends Array<any>, Success, Error>(
  handler: RpcWrappedEffectHandler<Args, Success, Error>,
): RpcEffectHandler<Args, Success, Error> =>
  flow(
    (...args) => serializeRpcArgs(args) as Args,
    (args) =>
      Effect.flatMap(currentTraceParent, (parent) => Effect.promise(() => handler(args, parent))),
    Effect.flatMap((exit): Exit.Exit<Success, Error> => {
      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<Error> => {
            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 = <Args extends Array<any>, Success, Error>(
  handler: RpcWrappedStreamHandler<Args, Success, Error>,
): RpcStreamHandler<Args, Success, Error> =>
  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 => {
  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 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 (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;
};