@trevrpc/trevrpc-js 0.2.3 → 1.1.0

package/src/native-loader.js

@@ -1,118 +0,0 @@
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import process from "node:process";
-import { fileURLToPath } from "node:url";
-
-const require = createRequire(import.meta.url);
-const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
-const packageVersion = (() => {
-  try {
-    return require(join(packageRoot, "package.json")).version ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-})();
-const SupportedOptionalTarget = "linux/x64/glibc";
-const LinuxX64GnuPackage = "@trevrpc/trevrpc-js-native-linux-x64-gnu";
-
-/** Loads the target-specific native addon without building during installation. */
-export function loadNativeAddon({ loadOptionalPackage = true, loadBundledAddon = true } = {}) {
-  const target = nativeTarget();
-  const packageName = nativePackageName(target);
-  let packageError;
-  let packageState = "unsupported";
-
-  if (loadOptionalPackage && packageName != null) {
-    try {
-      return require(packageName);
-    } catch (error) {
-      packageError = error;
-      packageState = isMissingPackage(error, packageName) ? "missing" : "failed to load";
-    }
-  }
-
-  const bundled = loadBundledAddon ? bundledNativePath() : null;
-  let bundledError;
-  if (bundled != null) {
-    try {
-      return require(bundled);
-    } catch (error) {
-      bundledError = error;
-    }
-  }
-
-  const fallback = developmentFallbackPath();
-  let fallbackError;
-  if (fallback != null) {
-    try {
-      return require(fallback);
-    } catch (error) {
-      fallbackError = error;
-    }
-  }
-
-  const detected = targetName(target);
-  const expected = packageName ?? "no optional package (unsupported target)";
-  const bundledState =
-    bundled == null ? "no Nix-bundled addon was present" : "the Nix-bundled addon failed to load";
-  const fallbackState =
-    fallback == null
-      ? "no source-checkout fallback was present"
-      : fallbackError == null
-        ? "the source-checkout fallback was unavailable"
-        : "the source-checkout fallback failed to load";
-  throw new Error(
-    `TrevRPC native addon is unavailable for detected target ${detected}. ` +
-      `Supported optional-package targets: ${SupportedOptionalTarget}. Expected optional package: ${expected}@${packageVersion}; ` +
-      `package state: ${packageState}; ${bundledState}; ${fallbackState}. ` +
-      "Install the matching optional package or build build/native/trevrpc_native.node explicitly in a source checkout; npm installation never starts a source build.",
-    { cause: fallbackError ?? bundledError ?? packageError },
-  );
-}
-
-/** Returns the normalized native npm target. */
-export function nativeTarget() {
-  return Object.freeze({
-    platform: process.platform,
-    arch: process.arch,
-    libc: process.platform === "linux" ? linuxLibc() : undefined,
-  });
-}
-
-function nativePackageName(target) {
-  if (target.platform === "linux" && target.arch === "x64" && target.libc === "glibc") {
-    return LinuxX64GnuPackage;
-  }
-  return null;
-}
-
-function bundledNativePath() {
-  const path = join(packageRoot, "native", "trevrpc_native.node");
-  return existsSync(path) ? path : null;
-}
-
-function developmentFallbackPath() {
-  if (!existsSync(join(packageRoot, "native", "CMakeLists.txt"))) {
-    return null;
-  }
-  const path = join(packageRoot, "build", "native", "trevrpc_native.node");
-  return existsSync(path) ? path : null;
-}
-
-function targetName(target) {
-  return `${target.platform}/${target.arch}${target.libc == null ? "" : `/${target.libc}`}`;
-}
-
-function linuxLibc() {
-  const report = process.report?.getReport?.();
-  return report?.header?.glibcVersionRuntime == null ? "musl" : "glibc";
-}
-
-function isMissingPackage(error, packageName) {
-  return (
-    error?.code === "MODULE_NOT_FOUND" &&
-    typeof error.message === "string" &&
-    error.message.includes(packageName)
-  );
-}

package/src/node-advanced.d.ts

@@ -1,27 +0,0 @@
-import type { RpcResponseMessage, RpcStreamFrameMessage, Transport } from "./index.js";
-import type { NodeChannelTarget, NodeConnectOptions } from "./node.js";
-
-export interface RawNodeCloseInfo {
-  nativeCode: number;
-}
-
-/** Raw single-connection Node transport backed by trevrpc-c and MsQuic. */
-export class RawNodeTransport implements Transport {
-  maxFrameSize?: number;
-  readonly closed: Promise<RawNodeCloseInfo>;
-
-  static connect(
-    target: string | URL | NodeChannelTarget,
-    options?: NodeConnectOptions,
-  ): Promise<RawNodeTransport>;
-  call(
-    request: Parameters<Transport["call"]>[0],
-    options?: Parameters<Transport["call"]>[1],
-  ): Promise<RpcResponseMessage>;
-  streamingCall(
-    request: Parameters<Transport["streamingCall"]>[0],
-    requestBody: AsyncIterable<Uint8Array>,
-    options?: Parameters<Transport["streamingCall"]>[2],
-  ): Promise<AsyncIterableIterator<RpcStreamFrameMessage>>;
-  close(): void;
-}

package/src/node-advanced.js

@@ -1 +0,0 @@
-export { RawNodeTransport } from "./node.js";

package/src/node-generated.d.ts

@@ -1,24 +0,0 @@
-import type { Root, Type } from "protobufjs";
-
-import type { RpcMethodKind, RpcServiceDescriptor } from "./index.js";
-import type { NodeServer, NodeServerCall } from "./node.js";
-
-export type { StreamingServerResponse, UnaryServerResponse } from "./index.js";
-export type { NodeServer, NodeServerCall } from "./node.js";
-
-/** Registers typed generated handlers on a Node server. */
-export function registerTypedService(
-  server: NodeServer,
-  root: Root,
-  service: RpcServiceDescriptor,
-  handlers: Record<string, unknown>,
-): NodeServer;
-
-/** Dispatches one typed generated Node handler. */
-export function dispatchTypedNodeHandler(
-  call: NodeServerCall,
-  handler: (...args: unknown[]) => unknown,
-  kind: RpcMethodKind,
-  requestType: Type,
-  responseType: Type,
-): Promise<void>;

package/src/node-generated.js

@@ -1,126 +0,0 @@
-import { marshalMessage, unmarshalMessage } from "./framing.js";
-import { isStreamingServerResponse, isUnaryServerResponse } from "./server-response.js";
-import { Code, statusError } from "./status.js";
-import { RpcStreamFrameKind } from "./wire.js";
-
-/** Registers typed generated handlers on a Node server. */
-export function registerTypedService(server, root, service, handlers) {
-  for (const [jsName, method] of Object.entries(service.methods)) {
-    const handler = handlers[jsName] ?? handlers[method.name];
-    if (handler == null) {
-      continue;
-    }
-    const requestType = root.lookupType(method.inputType);
-    const responseType = root.lookupType(method.outputType);
-    server.register(service.fullName, method.name, method.kind, async (call) => {
-      await dispatchTypedNodeHandler(call, handler, method.kind, requestType, responseType);
-    });
-  }
-  return server;
-}
-
-/** Dispatches one typed generated Node handler. */
-export async function dispatchTypedNodeHandler(call, handler, kind, requestType, responseType) {
-  if (kind === "unary") {
-    const request = unmarshalMessage(requestType, call.request.body ?? new Uint8Array(0));
-    const response = await handler(request, call);
-    const envelope = isUnaryServerResponse(response) ? response : null;
-    await call.respond({
-      body: marshalMessage(responseType, envelope == null ? response : envelope.message),
-      metadata: envelope?.metadata ?? {},
-    });
-    return;
-  }
-
-  if (kind === "clientStreaming") {
-    const response = await handler(decodeTypedNodeRequests(call, requestType), call);
-    const envelope = isUnaryServerResponse(response) ? response : null;
-    await call.sendMessage(
-      marshalMessage(responseType, envelope == null ? response : envelope.message),
-    );
-    await call.finishStream(Code.Ok, "", envelope?.metadata ?? {});
-    return;
-  }
-
-  const request =
-    kind === "serverStreaming"
-      ? unmarshalMessage(requestType, call.request.body ?? new Uint8Array(0))
-      : decodeTypedNodeRequests(call, requestType);
-  const response = await handler(request, call);
-  const envelope = isStreamingServerResponse(response) ? response : null;
-  await writeTypedResponseMessages(
-    call,
-    envelope == null ? response : envelope.messages,
-    responseType,
-  );
-  const status = envelope?.status;
-  await call.finishStream(status?.code ?? Code.Ok, status?.message ?? "", status?.metadata ?? {});
-}
-
-async function writeTypedResponseMessages(call, messages, responseType) {
-  const iterator = responseIterator(messages ?? []);
-  try {
-    for (;;) {
-      const result = await nextTypedResponseBatch(iterator, call.writeBatchMaxMessages ?? 16);
-      if (result.done) {
-        return;
-      }
-      await call.sendMany(result.value.map((message) => marshalMessage(responseType, message)));
-    }
-  } catch (error) {
-    try {
-      await iterator.return?.();
-    } catch {
-      // Preserve the send or iterator error, matching for-await cleanup behavior.
-    }
-    throw error;
-  }
-}
-
-function responseIterator(messages) {
-  if (typeof messages?.[Symbol.asyncIterator] === "function") {
-    return messages[Symbol.asyncIterator]();
-  }
-  if (typeof messages?.[Symbol.iterator] === "function") {
-    const iterator = messages[Symbol.iterator]();
-    return {
-      next: () => Promise.resolve(iterator.next()),
-      return: () =>
-        Promise.resolve(
-          typeof iterator.return === "function"
-            ? iterator.return()
-            : { done: true, value: undefined },
-        ),
-    };
-  }
-  throw new TypeError("streaming handler must return an iterable or async iterable");
-}
-
-async function nextTypedResponseBatch(iterator, maxMessages) {
-  if (typeof iterator.nextBatch === "function") {
-    return await iterator.nextBatch(maxMessages);
-  }
-  const result = await iterator.next();
-  return result.done ? result : { done: false, value: [result.value] };
-}
-
-async function* decodeTypedNodeRequests(call, requestType) {
-  for (;;) {
-    const frame = await call.recv();
-    if (frame == null) {
-      return;
-    }
-    if (frame.kind === RpcStreamFrameKind.Message) {
-      yield unmarshalMessage(requestType, frame.body ?? new Uint8Array(0));
-      continue;
-    }
-    if (frame.kind === RpcStreamFrameKind.Status) {
-      const code = frame.status ?? Code.Ok;
-      if (code !== Code.Ok) {
-        throw statusError(code, frame.message ?? "", frame.metadata ?? {});
-      }
-      return;
-    }
-    throw statusError(Code.InvalidArgument, "request stream contained an unknown frame kind");
-  }
-}

package/src/node-index.d.ts

@@ -1 +0,0 @@
-export * from "./node.js";

package/src/node-index.js

@@ -1,7 +0,0 @@
-export {
-  Channel,
-  NodeServer,
-  NodeServerCall,
-  bearerAuthorizer,
-  metadataValueAuthorizer,
-} from "./node.js";

package/src/node.d.ts

@@ -1,298 +0,0 @@
-import type {
-  ChannelLifecycleEvent,
-  ChannelLifecycleOptions,
-  ChannelState,
-  RpcChannel,
-  MetadataInput,
-  RpcKindValue,
-  RpcMethodKind,
-  RpcResponseMessage,
-  RpcServiceDescriptor,
-  RpcStreamFrameMessage,
-  Transport,
-} from "./index.js";
-
-type TrevRpcEventListener = ((event: Event) => void) | { handleEvent(event: Event): void };
-interface TrevRpcEventListenerOptions {
-  capture?: boolean;
-}
-interface TrevRpcAddEventListenerOptions extends TrevRpcEventListenerOptions {
-  once?: boolean;
-  passive?: boolean;
-  signal?: AbortSignal;
-}
-
-export interface NodeEndpoint {
-  host: string;
-  port: number;
-}
-
-export interface NodeConnectOptions {
-  caCertFile?: string;
-  skipCertificateValidation?: boolean;
-  maxStreamsPerSession?: number;
-  idleTimeoutMs?: number;
-  maxFrameSize?: number;
-  maxPendingSendBytes?: number;
-  maxPendingSendCount?: number;
-  signal?: AbortSignal;
-}
-
-export interface NodeChannelOptions extends NodeConnectOptions, ChannelLifecycleOptions {
-  /** Bounds initial readiness only. Later reconnects continue until close(). */
-  timeoutMs?: number;
-}
-
-export interface NodeChannelTarget extends NodeChannelOptions {
-  host: string;
-  port?: number;
-}
-
-export interface NodeRpcStartedEvent {
-  service: string;
-  method: string;
-  requestBodyLength: number;
-  kind: RpcKindValue;
-}
-
-export interface NodeRpcFinishedEvent extends NodeRpcStartedEvent {
-  responseBodyLength: number;
-  status: number;
-  elapsedMs?: number;
-}
-
-export interface NodeLogEvent {
-  level: "debug" | "info" | "warn" | "error" | string;
-  event: string;
-  message?: string;
-  service?: string;
-  method?: string;
-  status?: number;
-}
-
-export interface NodeServerMetrics {
-  rpcStarted?(event: NodeRpcStartedEvent): void;
-  rpcFinished?(event: NodeRpcFinishedEvent): void;
-  started?(event: NodeRpcStartedEvent): void;
-  finished?(event: NodeRpcFinishedEvent): void;
-}
-
-export interface NodeServerLogger {
-  log?(event: NodeLogEvent): void;
-  debug?(event: NodeLogEvent): void;
-  info?(event: NodeLogEvent): void;
-  warn?(event: NodeLogEvent): void;
-  error?(event: NodeLogEvent): void;
-}
-
-export type NodeServerAuthorizationResult =
-  | void
-  | boolean
-  | {
-      code?: number;
-      status?: number;
-      message?: string;
-      statusMessage?: string;
-      metadata?: MetadataInput;
-    };
-
-export type NodeServerAuthorizer = (
-  call: NodeServerCall,
-) => NodeServerAuthorizationResult | Promise<NodeServerAuthorizationResult>;
-
-export interface NodeHttp3AdmissionRequest {
-  path: string;
-  authority: string;
-  secure: boolean;
-}
-
-export type NodeHttp3Admission = (request: NodeHttp3AdmissionRequest) => boolean;
-
-export interface NodeListenOptions extends NodeConnectOptions {
-  host?: string;
-  port?: number;
-  path?: string;
-  origin?: string;
-  certFile?: string;
-  keyFile?: string;
-  maxSessionsPerConnection?: number;
-  /** Enables ordinary HTTP/3 POST requests. Disabled by default. */
-  enableHttp3?: boolean;
-  /** HTTP/3 POST path. Defaults to /trevrpc. */
-  http3Path?: string;
-  /**
-   * Synchronous request admission hook run before RPC framing is read. The
-   * native wait is bounded by initialRequestTimeoutMs.
-   */
-  http3Admission?: NodeHttp3Admission;
-  authorizer?: NodeServerAuthorizer;
-  metrics?: NodeServerMetrics;
-  logger?: NodeServerLogger | ((event: NodeLogEvent) => void);
-  maxStreamMessages?: number;
-  /** Initial HTTP/RPC request timeout. Defaults to 10000 ms. */
-  initialRequestTimeoutMs?: number;
-  streamIdleTimeoutMs?: number;
-}
-
-/** Native Node channel with background connection reconnection. */
-export class Channel extends EventTarget implements RpcChannel {
-  readonly endpoint: Readonly<NodeEndpoint>;
-  readonly options: Readonly<NodeChannelOptions>;
-  readonly ready: boolean;
-  readonly state: ChannelState;
-  readonly generation: number;
-
-  constructor(target: string | URL | NodeChannelTarget, options?: NodeChannelOptions);
-
-  /** Creates a native channel and waits for its first ready generation. */
-  static connect(
-    target: string | URL | NodeChannelTarget,
-    options?: NodeChannelOptions,
-  ): Promise<Channel>;
-  /** Waits for the current or next connection generation to become ready. */
-  waitUntilReady(): Promise<void>;
-  /** Sends a unary call on the current generation without replaying it. */
-  call(
-    request: Parameters<Transport["call"]>[0],
-    options?: Parameters<Transport["call"]>[1],
-  ): Promise<RpcResponseMessage>;
-  /** Starts a streaming call on the current generation without resuming it later. */
-  streamingCall(
-    request: Parameters<Transport["streamingCall"]>[0],
-    requestBody: AsyncIterable<Uint8Array>,
-    options?: Parameters<Transport["streamingCall"]>[2],
-  ): Promise<AsyncIterableIterator<RpcStreamFrameMessage>>;
-  /** Stops reconnecting and closes the current generation. */
-  close(): void;
-  addEventListener(
-    type: "statechange" | ChannelState,
-    callback: (event: ChannelLifecycleEvent) => void,
-    options?: boolean | TrevRpcAddEventListenerOptions,
-  ): void;
-  addEventListener(
-    type: string,
-    callback: TrevRpcEventListener | null,
-    options?: boolean | TrevRpcAddEventListenerOptions,
-  ): void;
-  removeEventListener(
-    type: "statechange" | ChannelState,
-    callback: (event: ChannelLifecycleEvent) => void,
-    options?: boolean | TrevRpcEventListenerOptions,
-  ): void;
-  removeEventListener(
-    type: string,
-    callback: TrevRpcEventListener | null,
-    options?: boolean | TrevRpcEventListenerOptions,
-  ): void;
-}
-
-export type NodeServerUnaryResult =
-  | RpcResponseMessage
-  | Uint8Array
-  | ArrayBuffer
-  | ArrayBufferView
-  | readonly number[];
-export type NodeServerStreamingResult = AsyncIterable<
-  Uint8Array | ArrayBuffer | ArrayBufferView | readonly number[]
->;
-
-export type NodeServerHandler = (
-  call: NodeServerCall,
-) =>
-  | void
-  | NodeServerUnaryResult
-  | NodeServerStreamingResult
-  | Promise<void | NodeServerUnaryResult | NodeServerStreamingResult>;
-
-/** Raw server call passed to NodeServer handlers. */
-export class NodeServerCall {
-  request: {
-    service: string;
-    method: string;
-    body: Uint8Array;
-    metadata: Record<string, Uint8Array>;
-    kind: RpcKindValue;
-    version: number;
-    timeoutNanos?: string;
-  };
-  completed: boolean;
-  deferred: boolean;
-  responseBodyLength: number;
-  finalStatus: number;
-  startedAt: number;
-  completedAt: number | null;
-  /** Aborts when the deadline, cancellation, or server shutdown settles first. */
-  readonly signal: AbortSignal;
-  /** Absolute peer deadline captured from the native call context, or null when absent. */
-  readonly deadline: Date | null;
-
-  /** Keeps the call open after the handler returns. */
-  defer(): this;
-  /** Sends a unary response and completes the call. */
-  respond(
-    response?: RpcResponseMessage | Uint8Array | ArrayBuffer | ArrayBufferView | readonly number[],
-  ): Promise<void>;
-  /** Sends one streaming response message. */
-  sendMessage(body: Uint8Array | ArrayBuffer | ArrayBufferView | readonly number[]): Promise<void>;
-  /** Sends multiple streaming response messages. */
-  sendMany(
-    bodies: Iterable<Uint8Array | ArrayBuffer | ArrayBufferView | readonly number[]>,
-  ): Promise<void>;
-  /** Receives one streaming request frame, or null after EOF. */
-  recv(): Promise<RpcStreamFrameMessage | null>;
-  /** Sends the terminal streaming status and completes the call. */
-  finishStream(status?: number, message?: string, metadata?: MetadataInput): Promise<void>;
-  /** Cancels and closes the call. */
-  close(reason?: unknown): void;
-}
-
-/** Native Node server backed by trevrpc-c and MsQuic. */
-export class NodeServer {
-  port: number;
-  maxFrameSize?: number;
-  closed: Promise<void> | null;
-
-  /** Creates a native QUIC and WebTransport TrevRPC server backed by trevrpc-c. */
-  static listen(
-    urlOrOptions: string | URL | NodeListenOptions,
-    options?: NodeListenOptions,
-  ): Promise<NodeServer>;
-
-  /** Registers one raw RPC handler. */
-  register(
-    service: string,
-    method: string,
-    kind: RpcKindValue | RpcMethodKind,
-    handler: NodeServerHandler,
-  ): this;
-
-  /** Registers handlers for a generated service descriptor. */
-  registerService(service: RpcServiceDescriptor, handlers: Record<string, NodeServerHandler>): this;
-
-  /** Sets an async authorizer that runs before registered handlers. */
-  setAuthorizer(authorizer?: NodeServerAuthorizer | null): this;
-  /** Clears the server authorizer. */
-  clearAuthorizer(): this;
-  /** Sets metrics callbacks. */
-  setMetrics(metrics?: NodeServerMetrics | null): this;
-  /** Clears metrics callbacks. */
-  clearMetrics(): this;
-  /** Sets a logger function or logger object. */
-  setLogger(logger?: NodeServerLogger | ((event: NodeLogEvent) => void) | null): this;
-  /** Clears the logger. */
-  clearLogger(): this;
-
-  /** Starts accepting RPCs. The returned promise resolves after close. */
-  serve(): Promise<void>;
-  /** Requests graceful server shutdown and drains already admitted calls. */
-  close(): void;
-}
-
-/** Creates an authorizer requiring one metadata key/value pair. */
-export function metadataValueAuthorizer(
-  key: string,
-  value: string | Uint8Array | ArrayBuffer | ArrayBufferView | readonly number[],
-): NodeServerAuthorizer;
-
-/** Creates an authorizer requiring an Authorization: Bearer token metadata value. */
-export function bearerAuthorizer(token: string): NodeServerAuthorizer;