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

import * as Cause from "effect/Cause";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as HttpClientRequest from "effect/http/HttpClientRequest";
import type * as HttpClientResponse from "effect/http/HttpClientResponse";
import { HttpServerRequest } from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import * as Option from "effect/Option";
import * as Result from "effect/Result";
import * as Scope from "effect/Scope";
import * as Sink from "effect/Sink";
import * as Socket from "effect/socket/Socket";
import * as Stream from "effect/Stream";
import type { HttpEffect } from "./Http.ts";

export type Rpc<Shape> = {
  "~alchemy/rpc": Shape;
};

/**
 * Recover the user's RPC `Shape` from any of the forms a caller might pass
 * to {@link toRpcAsync}:
 *
 *   - the Worker class value's type, e.g. `typeof Backend`, which extends
 *     `Effect.Effect<Worker & Rpc<Shape>, …>`
 *   - the unwrapped `Worker & Rpc<Shape>` type
 *   - a bare `Shape` (when the caller types it explicitly)
 */
export declare namespace Rpc {
  export type Shape<W> =
    W extends Effect.Effect<infer R, any, any>
      ? R extends Rpc<infer Shape>
        ? Shape
        : R
      : W extends Rpc<infer Shape>
        ? Shape
        : W;
}

// ---------------------------------------------------------------------------
// Wire protocol shared by every transport (native Cloudflare JSRPC and the
// plain-`fetch` transport below). The marker tags travel as structured-clone
// objects over JSRPC, or as NDJSON / response headers over `fetch`.
// ---------------------------------------------------------------------------

export const StreamTag = "~alchemy/rpc/stream";
export const ErrorTag = "~alchemy/rpc/error";
export const StreamErrorTag = "~alchemy/rpc/stream-error";

export type StreamEncoding = "bytes" | "jsonl";

export type RpcStreamEnvelope = {
  _tag: typeof StreamTag;
  encoding: StreamEncoding;
  body: ReadableStream<Uint8Array>;
};

export type RpcErrorEnvelope = {
  _tag: typeof ErrorTag;
  error: unknown;
};

export type RpcStreamErrorMarker = {
  _tag: typeof StreamErrorTag;
  error: unknown;
};

export class RpcDecodeError extends Data.TaggedError("RpcDecodeError")<{
  readonly cause: unknown;
}> {
  override get message() {
    return this.cause instanceof Error ? this.cause.message : String(this.cause);
  }
}

export class RpcCallError extends Data.TaggedError("RpcCallError")<{
  readonly method: string;
  readonly cause: unknown;
}> {
  override get message() {
    return `RPC call to "${this.method}" failed: ${
      this.cause instanceof Error ? this.cause.message : String(this.cause)
    }`;
  }
}

export class RpcRemoteStreamError extends Data.TaggedError("RpcRemoteStreamError")<{
  readonly error: unknown;
}> {}

export const isRpcStreamErrorMarker = (value: unknown): value is RpcStreamErrorMarker =>
  typeof value === "object" &&
  value !== null &&
  "_tag" in value &&
  value._tag === StreamErrorTag &&
  "error" in value;

export const isRpcErrorEnvelope = (value: unknown): value is RpcErrorEnvelope =>
  typeof value === "object" &&
  value !== null &&
  "_tag" in value &&
  value._tag === ErrorTag &&
  "error" in value;

export const isRpcStreamEnvelope = (value: unknown): value is RpcStreamEnvelope =>
  typeof value === "object" &&
  value !== null &&
  "_tag" in value &&
  value._tag === StreamTag &&
  "encoding" in value &&
  (value.encoding === "bytes" || value.encoding === "jsonl") &&
  "body" in value &&
  value.body instanceof ReadableStream;

/**
 * Normalize an error value into a plain, structured-clone-safe object.
 * Tagged errors keep `_tag` and all own enumerable fields.
 * Plain `Error` instances keep `name`, `message`, and `stack`.
 */
export const encodeRpcError = (error: unknown): unknown => {
  if (error === null || error === undefined) return error;
  if (typeof error !== "object") return error;

  const obj = error as Record<string, unknown>;
  if ("_tag" in obj && typeof obj._tag === "string") {
    const out: Record<string, unknown> = {};
    for (const key of Object.keys(obj)) {
      out[key] = obj[key];
    }
    if (error instanceof Error && !("message" in out)) {
      out.message = (error as Error).message;
    }
    return out;
  }

  if (error instanceof Error) {
    return { name: error.name, message: error.message, stack: error.stack };
  }

  return error;
};

// ---------------------------------------------------------------------------
// Stream decoding (client side): turn a wire byte-stream into a typed Effect
// `Stream`, lifting embedded error markers into the error channel.
// ---------------------------------------------------------------------------

/**
 * Decode a wire byte stream into the original values. `bytes` streams pass
 * through untouched; `jsonl` streams are split per-line, JSON-parsed, and any
 * embedded {@link RpcStreamErrorMarker} is lifted into the error channel.
 */
export const decodeRpcByteStream = <E>(
  bytes: Stream.Stream<Uint8Array, E>,
  encoding: StreamEncoding,
): Stream.Stream<any, E | RpcDecodeError | RpcRemoteStreamError> => {
  if (encoding === "bytes") {
    return bytes;
  }
  return bytes.pipe(
    Stream.decodeText,
    Stream.splitLines,
    Stream.filter((line) => line.length > 0),
    Stream.mapEffect((line) =>
      Effect.try({
        try: () => JSON.parse(line),
        catch: (cause) => new RpcDecodeError({ cause }),
      }),
    ),
    Stream.flatMap((value) =>
      isRpcStreamErrorMarker(value)
        ? Stream.fail(new RpcRemoteStreamError({ error: value.error }))
        : Stream.succeed(value),
    ),
  );
};

export const fromRpcReadableStream = (
  body: ReadableStream<Uint8Array>,
  encoding: StreamEncoding,
): Stream.Stream<any, Socket.SocketError | RpcDecodeError | RpcRemoteStreamError> =>
  decodeRpcByteStream(
    Stream.fromReadableStream({
      evaluate: () => body,
      onError: (cause) =>
        Socket.isSocketError(cause)
          ? cause
          : Socket.SocketError.make({
              reason: Socket.SocketReadError.make({ cause }),
            }),
    }),
    encoding,
  );

export const fromRpcStreamEnvelope = (
  envelope: RpcStreamEnvelope,
): Stream.Stream<any, Socket.SocketError | RpcDecodeError | RpcRemoteStreamError> =>
  fromRpcReadableStream(envelope.body, envelope.encoding);

export const decodeRpcValue = (value: unknown) => {
  if (isRpcStreamEnvelope(value)) {
    return fromRpcReadableStream(value.body, value.encoding);
  }

  if (value instanceof ReadableStream) {
    return fromRpcReadableStream(value, "bytes");
  }

  return value;
};

/**
 * A tagged-error class an RPC surface can declare (e.g. a Durable Object's
 * `errors` prop) so failures crossing the RPC boundary are reconstructed as
 * real class instances instead of the plain `{ _tag, ...fields }` objects
 * {@link encodeRpcError} produces. `identifier` is the static tag that
 * `Schema.TaggedError` classes carry; other classes match by class `name`.
 */
export interface RpcErrorClass {
  new (props: never): unknown;
  readonly identifier?: string;
}

/**
 * Build a reviver from declared error classes: a failure shaped
 * `{ _tag, ...fields }` whose tag matches a declared class is
 * reconstructed via that class's constructor (both sides of the RPC import
 * the same class declaration, so the schema is shared by construction).
 * Unmatched or already-revived errors pass through untouched.
 */
export const makeRpcErrorReviver = (
  errors: ReadonlyArray<RpcErrorClass> | undefined,
): ((error: unknown) => unknown) => {
  if (errors === undefined || errors.length === 0) {
    return (error) => error;
  }
  const byTag = new Map<string, RpcErrorClass>();
  for (const cls of errors) {
    byTag.set(cls.identifier ?? cls.name, cls);
  }
  return (error) => {
    if (typeof error !== "object" || error === null || !("_tag" in error)) {
      return error;
    }
    const cls = byTag.get((error as { _tag: string })._tag);
    if (cls === undefined || error instanceof cls) {
      return error;
    }
    try {
      return new (cls as new (props: unknown) => unknown)(error);
    } catch {
      // A malformed wire object must not turn into a defect here — the
      // caller still sees the raw envelope error.
      return error;
    }
  };
};

/**
 * Decode an RPC return value, lifting error envelopes into the Effect
 * error channel so that remote `Effect.fail(...)` values are recoverable.
 * When `revive` is given (see {@link makeRpcErrorReviver}), envelope errors
 * are reconstructed as their declared error classes.
 */
export const decodeRpcResult = (
  value: unknown,
  revive?: (error: unknown) => unknown,
): Effect.Effect<unknown, unknown> => {
  if (isRpcErrorEnvelope(value)) {
    return Effect.fail(revive === undefined ? value.error : revive(value.error));
  }
  return Effect.succeed(decodeRpcValue(value));
};

// ---------------------------------------------------------------------------
// Stream encoding (server side): turn a typed Effect `Stream` into a wire
// byte stream, embedding any failure as a trailing error marker.
// ---------------------------------------------------------------------------

const encodeStreamErrorMarker = (cause: Cause.Cause<unknown>): string => {
  const failReason = cause.reasons.find(Cause.isFailReason);
  const error = failReason ? encodeRpcError(failReason.error) : undefined;
  return (
    JSON.stringify({
      _tag: StreamErrorTag,
      error,
    } satisfies RpcStreamErrorMarker) + "\n"
  );
};

const appendStreamErrors = <R>(s: Stream.Stream<string, unknown, R>) =>
  s.pipe(Stream.catchCause((cause) => cause.pipe(encodeStreamErrorMarker, Stream.succeed)));

export const toRpcStream = (stream: Stream.Stream<any, any, any>) =>
  Effect.suspend(() => {
    // A peeled remainder is only valid while its scope is open. Transfer
    // that scope to the response body instead of closing it on return.
    const scope = Scope.makeUnsafe();
    const toBody = (body: Stream.Stream<Uint8Array, any>) =>
      body.pipe(
        Stream.onExit((exit) => Scope.close(scope, exit)),
        Stream.toReadableStream(),
      );
    return Effect.gen(function* () {
      const [head, rest] = yield* Stream.peel(stream, Sink.head()).pipe(
        Effect.provideService(Scope.Scope, scope),
      );

      if (Option.isSome(head) && head.value instanceof Uint8Array) {
        return {
          _tag: StreamTag,
          encoding: "bytes",
          body: toBody(rest.pipe(Stream.prepend([head.value]))),
        } satisfies RpcStreamEnvelope;
      }

      const body = Option.isSome(head) ? rest.pipe(Stream.prepend([head.value])) : rest;

      return {
        _tag: StreamTag,
        encoding: "jsonl",
        body: toBody(
          body.pipe(
            Stream.map((value) => JSON.stringify(value) + "\n"),
            appendStreamErrors,
            Stream.encodeText,
          ),
        ),
      } satisfies RpcStreamEnvelope;
    }).pipe(
      Effect.onExit((exit) => (Exit.isFailure(exit) ? Scope.close(scope, exit) : Effect.void)),
    );
  }).pipe(
    Effect.catchCause((cause) => {
      const failReason = cause.reasons.find(Cause.isFailReason);
      if (failReason) {
        return Effect.succeed({
          _tag: StreamTag,
          encoding: "jsonl",
          body: cause.pipe(
            encodeStreamErrorMarker,
            Stream.succeed,
            Stream.encodeText,
            Stream.toReadableStream(),
          ),
        } satisfies RpcStreamEnvelope);
      }
      return cause.pipe(Cause.squash, Effect.die);
    }),
  );

// ---------------------------------------------------------------------------
// `fetch`-transport stream codec. Unlike the JSRPC path above (which can peel
// to pick a raw-`bytes` vs `jsonl` encoding because its `ReadableStream` body
// is materialized eagerly), an HTTP response body is consumed lazily AFTER the
// handler returns — so peeling here would tie the source to the handler scope
// and truncate the body to its first element once that scope closes. Instead
// this codec is uniformly NDJSON and FULLY LAZY (no peel, no scope): each line
// is a JSON value, `Uint8Array` chunks are tagged + base64-encoded so binary
// streams round-trip, and a failure is appended as a trailing error marker.
// ---------------------------------------------------------------------------

const BytesTag = "~alchemy/rpc/bytes";

type RpcBytesChunk = { _tag: typeof BytesTag; b64: string };

const isRpcBytesChunk = (value: unknown): value is RpcBytesChunk =>
  typeof value === "object" &&
  value !== null &&
  "_tag" in value &&
  value._tag === BytesTag &&
  "b64" in value;

const toBase64 = (bytes: Uint8Array): string => {
  const encode = (bytes as Uint8Array & { toBase64?: () => string }).toBase64;
  if (typeof encode === "function") return encode.call(bytes);

  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary);
};

const fromBase64 = (b64: string): Uint8Array => {
  const decode = (
    Uint8Array as Uint8ArrayConstructor & { fromBase64?: (value: string) => Uint8Array }
  ).fromBase64;
  if (typeof b64 === "string" && typeof decode === "function") {
    try {
      return decode.call(Uint8Array, b64);
    } catch {
      // Preserve atob's InvalidCharacterError and coercion semantics for bad
      // wire values; fromBase64 uses SyntaxError instead. Valid input stays
      // on the native path without an intermediate binary string.
    }
  }
  const binary = atob(b64);
  const out = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
  return out;
};

/**
 * Encode a `Stream` as a lazy NDJSON byte stream for an HTTP response body.
 * No peeking, so nothing is held open across the handler→body-streaming
 * boundary. `Uint8Array` elements are tagged + base64-encoded; a source
 * failure is appended as a trailing {@link RpcStreamErrorMarker}.
 */
export const encodeRpcResponseStream = (
  stream: Stream.Stream<any, any, any>,
): Stream.Stream<Uint8Array, never, any> =>
  appendStreamErrors(
    stream.pipe(
      Stream.map((value) =>
        value instanceof Uint8Array
          ? JSON.stringify({ _tag: BytesTag, b64: toBase64(value) }) + "\n"
          : JSON.stringify(value) + "\n",
      ),
    ),
  ).pipe(Stream.encodeText);

/**
 * Decode an NDJSON byte stream produced by {@link encodeRpcResponseStream}:
 * tagged byte chunks become `Uint8Array`, a {@link RpcStreamErrorMarker} is
 * lifted into the error channel, everything else is the decoded JSON value.
 */
export const decodeRpcResponseStream = <E>(
  bytes: Stream.Stream<Uint8Array, E>,
): Stream.Stream<any, E | RpcDecodeError | RpcRemoteStreamError> =>
  bytes.pipe(
    Stream.decodeText,
    Stream.splitLines,
    Stream.filter((line) => line.length > 0),
    Stream.mapEffect((line) =>
      Effect.try({
        try: () => JSON.parse(line),
        catch: (cause) => new RpcDecodeError({ cause }),
      }),
    ),
    Stream.flatMap((value) =>
      isRpcStreamErrorMarker(value)
        ? Stream.fail(new RpcRemoteStreamError({ error: value.error }))
        : Stream.succeed(isRpcBytesChunk(value) ? fromBase64(value.b64) : value),
    ),
  );

// ---------------------------------------------------------------------------
// `asEffectOrStream`: a single value usable as BOTH an `Effect` and a `Stream`.
// ---------------------------------------------------------------------------

// Effect's internal Stream brand. `Stream.isStream` recognises a value by
// this property and reads its `channel`. An RPC stub method can't know
// synchronously whether the remote method returns a value or a `Stream`
// (the call is async), yet its declared type mirrors the remote `Shape`
// verbatim — value methods are typed `Effect<A>`, streaming methods `Stream<A>`.
// We satisfy BOTH by handing back the call `Effect` augmented with the Stream
// brand + channel, so the single return value can be `yield*`-ed / `.pipe`d as
// an Effect (value methods, e.g. `stub.put(k, v).pipe(Effect.orDie)`) AND piped
// through `Stream.*` combinators (streaming methods, e.g.
// `stub.tick(n).pipe(Stream.map(...))`).
const StreamTypeId = "~effect/Stream";

export const asEffectOrStream = (
  call: Effect.Effect<unknown, unknown>,
): Effect.Effect<unknown, unknown> => {
  const streamForm = Stream.unwrap(
    Effect.map(call, (value) => (Stream.isStream(value) ? value : Stream.succeed(value))),
  );
  return Object.assign(call, {
    [StreamTypeId]: (streamForm as any)[StreamTypeId],
    channel: (streamForm as any).channel,
  });
};

// ---------------------------------------------------------------------------
// `fetch` transport: a transport-agnostic RPC over plain HTTP. Each method is
// a `POST {RPC_PATH_PREFIX}{name}` whose request body is the JSON-encoded
// argument array; the response is either a JSON value, a JSON error envelope,
// or a streamed body (NDJSON / raw bytes) flagged by response headers.
// ---------------------------------------------------------------------------

/** Path prefix under which RPC methods are dispatched. */
export const RPC_PATH_PREFIX = "/__rpc__/";
/** Response header flag marking an NDJSON streamed body (vs a JSON value). */
export const RPC_STREAM_HEADER = "x-alchemy-rpc-stream";

/**
 * Build a typed RPC stub over a plain `fetch` transport. Any property that
 * isn't an own property of `base` is treated as a remote method: calling it
 * `POST`s `{baseUrl}{RPC_PATH_PREFIX}{name}` with the JSON-encoded arguments
 * and decodes the response into an {@link asEffectOrStream} value (so value
 * methods `yield*` as `Effect`s and streaming methods pipe as `Stream`s).
 */
export const makeFetchRpcStub = <Shape>(options: {
  readonly fetch: (
    request: HttpClientRequest.HttpClientRequest,
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, unknown>;
  readonly baseUrl?: string;
  /** Own properties that take precedence over remote-method dispatch. */
  readonly base?: Record<string, unknown>;
}): Shape => {
  const baseUrl = options.baseUrl ?? "http://alchemy-rpc";
  const target: Record<string, unknown> = options.base ?? {};

  return new Proxy(target, {
    get: (obj, prop) => {
      if (prop in obj) return obj[prop as keyof typeof obj];
      if (typeof prop !== "string") return undefined;
      return (...args: unknown[]) =>
        asEffectOrStream(
          Effect.gen(function* () {
            const request = HttpClientRequest.post(
              `${baseUrl}${RPC_PATH_PREFIX}${encodeURIComponent(prop)}`,
            ).pipe(HttpClientRequest.bodyText(JSON.stringify(args), "application/json"));
            const response = yield* options
              .fetch(request)
              .pipe(Effect.mapError((cause) => new RpcCallError({ method: prop, cause })));

            const headers = response.headers as Record<string, string | undefined>;
            if (headers[RPC_STREAM_HEADER] !== undefined) {
              return decodeRpcResponseStream(response.stream);
            }

            const value = yield* response.json.pipe(
              Effect.mapError((cause) => new RpcCallError({ method: prop, cause })),
            );
            return yield* decodeRpcResult(value);
          }),
        );
    },
  }) as Shape;
};

/**
 * Serve the RPC methods on `shape` over the {@link RPC_PATH_PREFIX} route,
 * delegating every other request to `fallback`. The mirror of {@link
 * makeFetchRpcStub}: method arguments are read from the JSON request body, the
 * method is invoked, and the result is encoded as a JSON value, a JSON error
 * envelope, or a streamed body (flagged via {@link RPC_STREAM_HEADER}).
 */
export const serveRpc = <Req = never>(
  shape: Record<string, unknown>,
  fallback: HttpEffect<Req>,
): HttpEffect<Req> =>
  Effect.gen(function* () {
    const request = yield* HttpServerRequest;
    const prefixAt = request.url.indexOf(RPC_PATH_PREFIX);
    if (prefixAt === -1) {
      return yield* fallback;
    }

    let name = request.url.slice(prefixAt + RPC_PATH_PREFIX.length);
    const queryAt = name.indexOf("?");
    if (queryAt !== -1) name = name.slice(0, queryAt);
    name = decodeURIComponent(name);

    const method = shape[name];
    if (typeof method !== "function") {
      return HttpServerResponse.text(`Unknown RPC method "${name}"`, {
        status: 404,
      });
    }

    const text = yield* request.text;
    // Keep arg-decode failures out of the handler's error channel — a
    // malformed argument payload is a client error, so answer 400.
    const argsResult = yield* Effect.result(
      Effect.try({
        try: () => (text.length > 0 ? (JSON.parse(text) as unknown[]) : []),
        catch: (cause) => new RpcDecodeError({ cause }),
      }),
    );
    if (Result.isFailure(argsResult)) {
      return HttpServerResponse.text(
        `Invalid RPC arguments for "${name}": ${argsResult.failure.message}`,
        { status: 400 },
      );
    }
    const args = argsResult.success;

    const invoked = (method as (...a: unknown[]) => unknown)(...args);

    // Fully-lazy NDJSON body: nothing is held open across the
    // handler→body-streaming boundary, so the stream isn't truncated. The
    // body's requirements are the shape method's phantom `R` (e.g.
    // `RuntimeContext`), satisfied by the surrounding runtime; erase it for
    // the response constructor.
    const streamResponse = (stream: Stream.Stream<unknown, unknown, unknown>) =>
      HttpServerResponse.stream(
        encodeRpcResponseStream(stream) as Stream.Stream<Uint8Array, never>,
        { headers: { [RPC_STREAM_HEADER]: "ndjson" } },
      );

    // A *genuine* `Stream` (not an Effect) is encoded directly. A nested-RPC
    // value built by {@link asEffectOrStream} is BOTH an Effect and a Stream —
    // it MUST be run as an effect (below), otherwise a forwarded value method
    // (e.g. a DO method returning `container.readObject(key)`) would be
    // mis-served as a stream envelope and decoded by the caller as a `Stream`
    // instead of the value.
    if (Stream.isStream(invoked) && !Effect.isEffect(invoked)) {
      return streamResponse(invoked);
    }

    const result = yield* Effect.result(invoked as Effect.Effect<unknown, unknown>);
    if (Result.isSuccess(result)) {
      // The resolved value may itself be a `Stream` (e.g. a forwarded nested
      // *streaming* RPC, where the inner call resolves to a `Stream`) — encode
      // that as a stream body too.
      return Stream.isStream(result.success)
        ? streamResponse(result.success)
        : yield* HttpServerResponse.json(result.success ?? null);
    }
    return yield* HttpServerResponse.json({
      _tag: ErrorTag,
      error: encodeRpcError(result.failure),
    } satisfies RpcErrorEnvelope);
  });