@vishalsharma7nov/react-native-proto 0.2.2

package/src/transport.ts

@@ -0,0 +1,427 @@
+import { ProtoClientError, wrapUnknownError } from "./errors";
+import { tryParseConnectError } from "./connect/errors";
+import {
+  composeInterceptors,
+  type CallContext,
+  type Interceptor,
+} from "./interceptors";
+import { createPathForMethod } from "./path-templates";
+import type {
+  HeaderMap,
+  MethodMapEntry,
+  ProtoClientConfig,
+  UnaryCallInput,
+} from "./types";
+import type { CodecRegistry } from "./types";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const MAX_HEADER_ENTRIES = 64;
+
+export type ResolvedTransportConfig = {
+  baseUrl: string;
+  timeoutMs: number;
+  maxResponseBytes: number;
+  transport: NonNullable<ProtoClientConfig["transport"]>;
+  getHeaders?: ProtoClientConfig["getHeaders"];
+  fetchImpl: typeof fetch;
+  onError?: ProtoClientConfig["onError"];
+  pathForMethod: (entry: MethodMapEntry) => string;
+  interceptors: Interceptor[];
+  retryOnUnauthorized: boolean;
+};
+
+export function resolveConfig(
+  config: ProtoClientConfig,
+): ResolvedTransportConfig {
+  if (!config || typeof config !== "object") {
+    throw new ProtoClientError({
+      code: "INVALID_CONFIG",
+      message: "createClient requires a config object",
+    });
+  }
+
+  const baseUrl =
+    typeof config.baseUrl === "string" ? config.baseUrl.trim() : "";
+  if (!baseUrl) {
+    throw new ProtoClientError({
+      code: "INVALID_CONFIG",
+      message: "baseUrl is required and must be a non-empty string",
+    });
+  }
+
+  try {
+    // Throws if baseUrl is not absolute
+    // eslint-disable-next-line no-new
+    new URL(baseUrl);
+  } catch (cause) {
+    throw new ProtoClientError({
+      code: "INVALID_CONFIG",
+      message: `baseUrl must be an absolute URL, received: ${baseUrl}`,
+      cause,
+    });
+  }
+
+  const timeoutMs =
+    typeof config.timeoutMs === "number" && config.timeoutMs > 0
+      ? Math.min(config.timeoutMs, 600_000)
+      : DEFAULT_TIMEOUT_MS;
+
+  const maxResponseBytes =
+    typeof config.maxResponseBytes === "number" && config.maxResponseBytes > 0
+      ? Math.min(config.maxResponseBytes, 50 * 1024 * 1024)
+      : DEFAULT_MAX_RESPONSE_BYTES;
+
+  const transport = config.transport ?? "http";
+  if (
+    transport !== "http" &&
+    transport !== "connect" &&
+    transport !== "native-grpc"
+  ) {
+    throw new ProtoClientError({
+      code: "INVALID_CONFIG",
+      message: `Unsupported transport: ${String(transport)}`,
+    });
+  }
+
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new ProtoClientError({
+      code: "INVALID_CONFIG",
+      message: "fetch is not available; pass config.fetch",
+    });
+  }
+
+  const pathForMethod =
+    config.pathForMethod ?? createPathForMethod(config.pathPreset ?? "connect");
+
+  return {
+    baseUrl: baseUrl.replace(/\/$/, ""),
+    timeoutMs,
+    maxResponseBytes,
+    transport,
+    getHeaders: config.getHeaders,
+    fetchImpl,
+    onError: config.onError,
+    pathForMethod,
+    interceptors: config.interceptors ?? [],
+    retryOnUnauthorized: config.retryOnUnauthorized !== false,
+  };
+}
+
+export async function buildHeaders(
+  config: ResolvedTransportConfig,
+  contentType: string,
+  rpcPath: string,
+  extra?: HeaderMap,
+): Promise<Record<string, string>> {
+  const headers: Record<string, string> = {
+    "Content-Type": contentType,
+    Accept: contentType,
+  };
+
+  const merge = (source: HeaderMap | undefined) => {
+    if (!source || typeof source !== "object") return;
+    const keys = Object.keys(source);
+    if (keys.length > MAX_HEADER_ENTRIES) {
+      throw new ProtoClientError({
+        code: "INVALID_ARGUMENT",
+        message: `Too many headers (max ${MAX_HEADER_ENTRIES})`,
+        rpcPath,
+      });
+    }
+    for (let i = 0; i < keys.length; i += 1) {
+      const key = keys[i];
+      if (!key) continue;
+      const value = source[key];
+      if (typeof value === "string") {
+        headers[key] = value;
+      }
+    }
+  };
+
+  if (config.getHeaders) {
+    let fromConfig: HeaderMap;
+    try {
+      fromConfig = await config.getHeaders();
+    } catch (cause) {
+      throw new ProtoClientError({
+        code: "INVALID_ARGUMENT",
+        message: "getHeaders() failed",
+        rpcPath,
+        cause,
+      });
+    }
+    merge(fromConfig);
+  }
+
+  merge(extra);
+  return headers;
+}
+
+function mapHttpStatus(
+  status: number,
+  rpcPath: string,
+  bodyText: string,
+): ProtoClientError {
+  if (bodyText) {
+    const connectErr = tryParseConnectError(bodyText, rpcPath, status);
+    if (connectErr) {
+      return connectErr;
+    }
+  }
+  const retryable = status === 408 || status === 429 || status >= 500;
+  return new ProtoClientError({
+    code: "HTTP",
+    message: `HTTP ${status} for ${rpcPath}${bodyText ? `: ${bodyText.slice(0, 200)}` : ""}`,
+    status,
+    rpcPath,
+    retryable,
+  });
+}
+
+async function readBodyBytes(
+  response: Response,
+  maxResponseBytes: number,
+  rpcPath: string,
+): Promise<Uint8Array> {
+  const lengthHeader = response.headers.get("content-length");
+  if (lengthHeader) {
+    const declared = Number(lengthHeader);
+    if (Number.isFinite(declared) && declared > maxResponseBytes) {
+      throw new ProtoClientError({
+        code: "PAYLOAD_TOO_LARGE",
+        message: `Response Content-Length ${declared} exceeds maxResponseBytes ${maxResponseBytes}`,
+        rpcPath,
+        status: response.status,
+      });
+    }
+  }
+
+  const buffer = await response.arrayBuffer();
+  if (buffer.byteLength > maxResponseBytes) {
+    throw new ProtoClientError({
+      code: "PAYLOAD_TOO_LARGE",
+      message: `Response size ${buffer.byteLength} exceeds maxResponseBytes ${maxResponseBytes}`,
+      rpcPath,
+      status: response.status,
+    });
+  }
+
+  return new Uint8Array(buffer);
+}
+
+async function unaryCallCore(
+  config: ResolvedTransportConfig,
+  codecs: CodecRegistry,
+  input: UnaryCallInput,
+): Promise<Record<string, unknown>> {
+  const { entry, request, signal } = input;
+  const rpcPath = entry.rpcPath;
+
+  if (config.transport === "native-grpc") {
+    const { nativeGrpcUnary } = await import("./native-grpc");
+    return nativeGrpcUnary(config, codecs, input);
+  }
+
+  const requestCodec = codecs.get(entry.requestType);
+  const responseCodec = codecs.get(entry.responseType);
+  if (!requestCodec || !responseCodec) {
+    throw new ProtoClientError({
+      code: "INVALID_ARGUMENT",
+      message: `Missing codec for ${entry.requestType} or ${entry.responseType}`,
+      rpcPath,
+    });
+  }
+
+  let body: Uint8Array;
+  try {
+    body = requestCodec.encode(request ?? {});
+  } catch (cause) {
+    throw new ProtoClientError({
+      code: "INVALID_ARGUMENT",
+      message: `Failed to encode request for ${rpcPath}`,
+      rpcPath,
+      cause,
+    });
+  }
+
+  const path = config.pathForMethod(entry);
+  const url = `${config.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+  const contentType =
+    config.transport === "connect"
+      ? "application/proto"
+      : "application/x-protobuf";
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeoutMs);
+
+  const onAbort = () => controller.abort();
+  if (signal) {
+    if (signal.aborted) {
+      clearTimeout(timeoutId);
+      throw new ProtoClientError({
+        code: "ABORTED",
+        message: "Request was aborted before send",
+        rpcPath,
+      });
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  }
+
+  try {
+    const headers = await buildHeaders(
+      config,
+      contentType,
+      rpcPath,
+      input.headers,
+    );
+    if (config.transport === "connect") {
+      headers["Connect-Protocol-Version"] = "1";
+    }
+
+    let response: Response;
+    try {
+      response = await config.fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: body as unknown as BodyInit,
+        signal: controller.signal,
+      });
+    } catch (cause) {
+      if (controller.signal.aborted) {
+        const abortedByCaller = Boolean(signal?.aborted);
+        throw new ProtoClientError({
+          code: abortedByCaller ? "ABORTED" : "TIMEOUT",
+          message: abortedByCaller
+            ? "Request was aborted"
+            : `Request timed out after ${config.timeoutMs}ms`,
+          rpcPath,
+          cause,
+          retryable: !abortedByCaller,
+        });
+      }
+
+      throw new ProtoClientError({
+        code: "NETWORK",
+        message: `Network error calling ${rpcPath}`,
+        rpcPath,
+        cause,
+        retryable: true,
+      });
+    }
+
+    if (!response.ok) {
+      let text = "";
+      try {
+        text = await response.text();
+      } catch {
+        text = "";
+      }
+      throw mapHttpStatus(response.status, rpcPath, text);
+    }
+
+    const bytes = await readBodyBytes(
+      response,
+      config.maxResponseBytes,
+      rpcPath,
+    );
+
+    // Connect unary may still return raw proto; if JSON end-stream sneaks in, map it.
+    const contentTypeHeader = response.headers.get("content-type") || "";
+    if (
+      config.transport === "connect" &&
+      contentTypeHeader.includes("json") &&
+      bytes.byteLength > 0
+    ) {
+      const text = new TextDecoder().decode(bytes);
+      const connectErr = tryParseConnectError(text, rpcPath, response.status);
+      if (connectErr) {
+        throw connectErr;
+      }
+    }
+
+    try {
+      return responseCodec.decode(bytes);
+    } catch (cause) {
+      throw new ProtoClientError({
+        code: "DECODE",
+        message: `Failed to decode response for ${rpcPath}`,
+        rpcPath,
+        cause,
+        status: response.status,
+      });
+    }
+  } finally {
+    clearTimeout(timeoutId);
+    if (signal) {
+      signal.removeEventListener("abort", onAbort);
+    }
+  }
+}
+
+function notifyOnError(
+  config: ResolvedTransportConfig,
+  error: ReturnType<typeof wrapUnknownError>,
+): void {
+  if (!config.onError) {
+    return;
+  }
+  try {
+    config.onError(error);
+  } catch {
+    // Logging hooks must not replace throw behavior
+  }
+}
+
+export async function unaryCall(
+  config: ResolvedTransportConfig,
+  codecs: CodecRegistry,
+  input: UnaryCallInput,
+): Promise<Record<string, unknown>> {
+  const { entry, request, signal } = input;
+  const rpcPath = entry.rpcPath;
+
+  const core = async (ctx: CallContext) =>
+    unaryCallCore(config, codecs, {
+      entry: ctx.entry,
+      request: ctx.request,
+      signal: ctx.signal,
+      headers: ctx.headers,
+    });
+
+  const pipeline =
+    config.interceptors.length > 0
+      ? composeInterceptors(config.interceptors, core)
+      : core;
+
+  try {
+    return await pipeline({
+      entry,
+      request: request ?? {},
+      headers: input.headers ?? {},
+      signal,
+    });
+  } catch (error) {
+    const wrapped = wrapUnknownError(error, rpcPath);
+
+    // Optional transport-level single retry on 401 when no auth interceptor handled it
+    if (
+      config.retryOnUnauthorized &&
+      config.interceptors.length === 0 &&
+      wrapped.status === 401 &&
+      config.getHeaders
+    ) {
+      try {
+        return await unaryCallCore(config, codecs, input);
+      } catch (retryError) {
+        const retryWrapped = wrapUnknownError(retryError, rpcPath);
+        notifyOnError(config, retryWrapped);
+        throw retryWrapped;
+      }
+    }
+
+    notifyOnError(config, wrapped);
+    throw wrapped;
+  }
+}

package/src/types.ts

@@ -0,0 +1,94 @@
+import type { Type } from 'protobufjs';
+import type { Interceptor } from './interceptors';
+import type { PathTemplatePreset } from './path-templates';
+
+export type TransportKind = 'http' | 'connect' | 'native-grpc';
+
+export type HeaderMap = Record<string, string>;
+
+export type ProtoClientConfig = {
+  /** API origin, for example https://api.example.com */
+  baseUrl: string;
+  /** Optional per-request headers (auth tokens, app version, etc.) */
+  getHeaders?: () => HeaderMap | Promise<HeaderMap>;
+  /** Request timeout in milliseconds (default 30000) */
+  timeoutMs?: number;
+  /** Maximum accepted response body size in bytes (default 2 MiB) */
+  maxResponseBytes?: number;
+  /** How calls are sent to the server */
+  transport?: TransportKind;
+  /** Custom fetch implementation (tests / polyfills) */
+  fetch?: typeof fetch;
+  /** Optional logging hook — errors are still thrown */
+  onError?: (error: import('./errors').ProtoClientError) => void;
+  /**
+   * Builds the HTTP path for a service method.
+   * Default: /{package}.{Service}/{Method}
+   */
+  pathForMethod?: (entry: MethodMapEntry) => string;
+  /** Shortcut for built-in path presets (ignored if pathForMethod is set) */
+  pathPreset?: PathTemplatePreset;
+  /** Unary interceptor pipeline (auth, logging, etc.) */
+  interceptors?: Interceptor[];
+  /**
+   * When true (default), retry a unary call once after auth interceptor refresh
+   * is handled inside createAuthInterceptor — this flag reserved for transport-level 401.
+   */
+  retryOnUnauthorized?: boolean;
+};
+
+export type MethodKind = 'unary' | 'serverStreaming' | 'clientStreaming' | 'bidi';
+
+export type MethodMapEntry = {
+  serviceName: string;
+  methodName: string;
+  packageName: string;
+  rpcPath: string;
+  requestType: string;
+  responseType: string;
+  kind: MethodKind;
+};
+
+export type MethodMap = ReadonlyArray<MethodMapEntry>;
+
+export type MessageCodec = {
+  encode: (message: Record<string, unknown>) => Uint8Array;
+  decode: (bytes: Uint8Array) => Record<string, unknown>;
+};
+
+export type CodecRegistry = {
+  get(typeName: string): MessageCodec | undefined;
+  has(typeName: string): boolean;
+};
+
+export type UnaryCallInput = {
+  entry: MethodMapEntry;
+  request: Record<string, unknown>;
+  signal?: AbortSignal;
+  /** Extra headers merged for this call (from interceptors) */
+  headers?: HeaderMap;
+};
+
+export type StreamCallInput = UnaryCallInput & {
+  onMessage?: (message: Record<string, unknown>) => void;
+  /** Client-streaming / bidi: async iterable of request messages */
+  requests?: AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>;
+};
+
+export type ClientServices = {
+  [serviceName: string]: {
+    [methodName: string]: (
+      request?: Record<string, unknown>,
+      options?: { signal?: AbortSignal }
+    ) => Promise<Record<string, unknown>> | AsyncIterable<Record<string, unknown>>;
+  };
+};
+
+export type ProtoClient = ClientServices & {
+  readonly config: Readonly<Required<
+    Pick<ProtoClientConfig, 'baseUrl' | 'timeoutMs' | 'maxResponseBytes' | 'transport'>
+  >> &
+    ProtoClientConfig;
+};
+
+export type ProtobufTypeLike = Pick<Type, 'encode' | 'decode' | 'create' | 'fromObject'>;

package/src/validation/zod.ts

@@ -0,0 +1,75 @@
+import type { MessageCodec } from "../types";
+
+export type ZodLikeSchema<T = unknown> = {
+  parse: (data: unknown) => T;
+  safeParse?: (
+    data: unknown,
+  ) => { success: true; data: T } | { success: false; error: unknown };
+};
+
+/**
+ * Wrap a protobuf codec with optional Zod (or Zod-compatible) request/response
+ * validation. Peer dependency: install `zod` in your app.
+ */
+export function withZodValidation(
+  codec: MessageCodec,
+  options: {
+    request?: ZodLikeSchema<Record<string, unknown>>;
+    response?: ZodLikeSchema<Record<string, unknown>>;
+  },
+): MessageCodec {
+  return {
+    encode(message) {
+      const value = options.request ? options.request.parse(message) : message;
+      return codec.encode(value as Record<string, unknown>);
+    },
+    decode(bytes) {
+      const decoded = codec.decode(bytes);
+      return options.response
+        ? (options.response.parse(decoded) as Record<string, unknown>)
+        : decoded;
+    },
+  };
+}
+
+/**
+ * Apply Zod schemas to selected type names in a codec registry.
+ */
+export function wrapCodecRegistryWithZod(
+  registry: {
+    get(typeName: string): MessageCodec | undefined;
+    has(typeName: string): boolean;
+  },
+  schemas: Record<
+    string,
+    { request?: ZodLikeSchema; response?: ZodLikeSchema } | ZodLikeSchema
+  >,
+): {
+  get(typeName: string): MessageCodec | undefined;
+  has(typeName: string): boolean;
+} {
+  return {
+    has(typeName) {
+      return registry.has(typeName);
+    },
+    get(typeName) {
+      const base = registry.get(typeName);
+      if (!base) return undefined;
+      const entry = schemas[typeName];
+      if (!entry) return base;
+      if ("parse" in entry && typeof entry.parse === "function") {
+        return withZodValidation(base, {
+          request: entry as ZodLikeSchema<Record<string, unknown>>,
+          response: entry as ZodLikeSchema<Record<string, unknown>>,
+        });
+      }
+      return withZodValidation(
+        base,
+        entry as {
+          request?: ZodLikeSchema<Record<string, unknown>>;
+          response?: ZodLikeSchema<Record<string, unknown>>;
+        },
+      );
+    },
+  };
+}

package/src/version-check.ts

@@ -0,0 +1,121 @@
+import { ProtoClientError } from './errors';
+import type { HeaderMap } from './types';
+import type { Interceptor } from './interceptors';
+
+export const CLIENT_VERSION_HEADER = 'X-React-Native-Proto-Client-Version';
+export const SERVER_MIN_CLIENT_HEADER = 'X-React-Native-Proto-Min-Client-Version';
+export const METHOD_MAP_HASH_HEADER = 'X-React-Native-Proto-Method-Map-Hash';
+
+export type VersionCheckOptions = {
+  /** Semver or opaque version string sent on every request */
+  clientVersion: string;
+  /** Optional hash/fingerprint of the generated method map */
+  methodMapHash?: string;
+  /**
+   * If the response includes SERVER_MIN_CLIENT_HEADER and client is older,
+   * throw (default) or only warn via onMismatch.
+   */
+  mode?: 'throw' | 'warn';
+  onMismatch?: (info: {
+    clientVersion: string;
+    serverMinClientVersion: string;
+  }) => void;
+  compareVersions?: (client: string, serverMin: string) => number;
+};
+
+/** Simple dotted numeric compare: 1.2.0 vs 1.10.0. Non-numeric falls back to string cmp. */
+export function compareDottedVersions(a: string, b: string): number {
+  const pa = a.split('.').map((p) => Number.parseInt(p, 10));
+  const pb = b.split('.').map((p) => Number.parseInt(p, 10));
+  if (pa.some((n) => Number.isNaN(n)) || pb.some((n) => Number.isNaN(n))) {
+    return a === b ? 0 : a < b ? -1 : 1;
+  }
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i += 1) {
+    const av = pa[i] ?? 0;
+    const bv = pb[i] ?? 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+export function versionHeaders(options: {
+  clientVersion: string;
+  methodMapHash?: string;
+}): HeaderMap {
+  const headers: HeaderMap = {
+    [CLIENT_VERSION_HEADER]: options.clientVersion,
+  };
+  if (options.methodMapHash) {
+    headers[METHOD_MAP_HASH_HEADER] = options.methodMapHash;
+  }
+  return headers;
+}
+
+/**
+ * Attaches client version headers. Pair with `assertServerMinClient` after responses
+ * if you read response headers in a custom transport; for the default HTTP path,
+ * use `createVersionInterceptor` which only sends headers (response check needs
+ * fetch wrapper — see createVersionAwareFetch).
+ */
+export function createVersionInterceptor(
+  options: VersionCheckOptions
+): Interceptor {
+  return async (ctx, next) => {
+    const headers = {
+      ...ctx.headers,
+      ...versionHeaders({
+        clientVersion: options.clientVersion,
+        methodMapHash: options.methodMapHash,
+      }),
+    };
+    return next({ ...ctx, headers });
+  };
+}
+
+export function assertServerMinClient(
+  serverMinClientVersion: string | null | undefined,
+  options: VersionCheckOptions
+): void {
+  if (!serverMinClientVersion) return;
+  const compare = options.compareVersions ?? compareDottedVersions;
+  if (compare(options.clientVersion, serverMinClientVersion) < 0) {
+    const info = {
+      clientVersion: options.clientVersion,
+      serverMinClientVersion,
+    };
+    if (options.onMismatch) {
+      options.onMismatch(info);
+    }
+    if (options.mode === 'warn') {
+      return;
+    }
+    throw new ProtoClientError({
+      code: 'INVALID_CONFIG',
+      message: `Client version ${options.clientVersion} is older than server minimum ${serverMinClientVersion}`,
+    });
+  }
+}
+
+/**
+ * Wraps fetch to validate SERVER_MIN_CLIENT_HEADER on each response.
+ */
+export function createVersionAwareFetch(
+  baseFetch: typeof fetch,
+  options: VersionCheckOptions
+): typeof fetch {
+  return (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const headers = new Headers(init?.headers);
+    headers.set(CLIENT_VERSION_HEADER, options.clientVersion);
+    if (options.methodMapHash) {
+      headers.set(METHOD_MAP_HASH_HEADER, options.methodMapHash);
+    }
+    const response = await baseFetch(input, { ...init, headers });
+    assertServerMinClient(
+      response.headers.get(SERVER_MIN_CLIENT_HEADER),
+      options
+    );
+    return response;
+  }) as typeof fetch;
+}