@hebo-ai/gateway 0.6.2-rc0 → 0.6.2

package/src/telemetry/stream.ts

@@ -1,64 +0,0 @@
-import { toOpenAIError } from "../errors/openai";
-
-const isErrorChunk = (v: unknown) => v instanceof Error || !!(v as any)?.error;
-
-export const wrapStream = (
-  src: ReadableStream,
-  hooks: { onDone?: (status: number, reason: unknown) => void },
-): ReadableStream => {
-  let finished = false;
-
-  const done = (
-    reader: ReadableStreamDefaultReader,
-    controller: ReadableStreamDefaultController,
-    status: number,
-    reason?: unknown,
-  ) => {
-    if (!finished) {
-      finished = true;
-      hooks.onDone?.(status, reason);
-    }
-    reader.cancel(reason).catch(() => {});
-    controller.close();
-  };
-
-  return new ReadableStream({
-    async start(controller) {
-      const reader = src.getReader();
-
-      try {
-        for (;;) {
-          // oxlint-disable-next-line no-await-in-loop
-          const { value, done: eof } = await reader.read();
-          if (eof) break;
-
-          const out = isErrorChunk(value) ? toOpenAIError(value) : value;
-          controller.enqueue(out);
-
-          if (out !== value) {
-            const status = out.error?.type === "invalid_request_error" ? 422 : 502;
-            done(reader, controller, status, value);
-            return;
-          }
-        }
-
-        done(reader, controller, 200);
-      } catch (err) {
-        controller.enqueue(toOpenAIError(err));
-        done(reader, controller, 502, err);
-      } finally {
-        try {
-          reader.releaseLock();
-        } catch {}
-      }
-    },
-
-    cancel(reason) {
-      if (!finished) {
-        finished = true;
-        hooks.onDone?.(499, reason);
-      }
-      src.cancel(reason).catch(() => {});
-    },
-  });
-};

package/src/types.ts

@@ -1,223 +0,0 @@
-import type { ProviderV3 } from "@ai-sdk/provider";
-import type { Tracer } from "@opentelemetry/api";
-
-import type {
-  ChatCompletions,
-  ChatCompletionsBody,
-  ChatCompletionsChunk,
-} from "./endpoints/chat-completions/schema";
-import type { Embeddings, EmbeddingsBody } from "./endpoints/embeddings/schema";
-import type { Model, ModelList } from "./endpoints/models";
-import type { Logger, LoggerConfig } from "./logger";
-import type { ModelCatalog, ModelId } from "./models/types";
-import type { ProviderId, ProviderRegistry } from "./providers/types";
-
-/**
- * Per-request context shared across handlers and hooks.
- */
-export type GatewayContext = {
-  /**
-   * Mutable bag for passing data between hooks.
-   */
-  state: Record<string, unknown>;
-  /**
-   * Provider registry from config.
-   */
-  providers: ProviderRegistry;
-  /**
-   * Model catalog from config.
-   */
-  models: ModelCatalog;
-  /**
-   * Incoming request for the handler.
-   */
-  request: Request;
-  /**
-   * Resolved request ID for logging and telemetry.
-   */
-  requestId: string;
-  /**
-   * Parsed body from the request.
-   */
-  body?: ChatCompletionsBody | EmbeddingsBody;
-  /**
-   * Incoming model ID.
-   */
-  modelId?: ModelId;
-  /**
-   * Resolved model ID.
-   */
-  resolvedModelId?: ModelId;
-  /**
-   * Operation type.
-   */
-  operation?: "chat" | "embeddings" | "models";
-  /**
-   * Resolved provider instance.
-   */
-  provider?: ProviderV3;
-  /**
-   * Resolved provider ID.
-   */
-  resolvedProviderId?: ProviderId;
-  /**
-   * Result returned by the handler (pre-response).
-   */
-  result?:
-    | ChatCompletions
-    | ReadableStream<ChatCompletionsChunk | Error>
-    | Embeddings
-    | Model
-    | ModelList;
-  /**
-   * Response object returned by the handler.
-   */
-  response?: Response;
-};
-
-/**
- * Hook context: all fields readonly except `state`.
- */
-export type HookContext = Omit<Readonly<GatewayContext>, "state"> & {
-  state: GatewayContext["state"];
-};
-
-type RequiredHookContext<K extends keyof GatewayContext> = Omit<HookContext, K> &
-  Required<Pick<HookContext, K>>;
-export type OnRequestHookContext = RequiredHookContext<"request">;
-export type BeforeHookContext = RequiredHookContext<"request" | "operation" | "body">;
-export type ResolveModelHookContext = RequiredHookContext<
-  "request" | "operation" | "body" | "modelId"
->;
-export type ResolveProviderHookContext = RequiredHookContext<
-  "request" | "operation" | "body" | "modelId" | "resolvedModelId"
->;
-export type AfterHookContext = RequiredHookContext<
-  | "request"
-  | "operation"
-  | "body"
-  | "modelId"
-  | "resolvedModelId"
-  | "provider"
-  | "resolvedProviderId"
-  | "result"
->;
-export type OnResponseHookContext = RequiredHookContext<"request" | "response">;
-
-/**
- * Hooks to plugin to the gateway lifecycle.
- */
-export type GatewayHooks = {
-  /**
-   * Runs before any endpoint handler logic.
-   * @returns Optional Response to short-circuit the request.
-   */
-  onRequest?: (ctx: OnRequestHookContext) => void | Response | Promise<void | Response>;
-  /**
-   * Runs after request JSON is parsed and validated for chat completions / embeddings.
-   * @returns Replacement parsed body, or undefined to keep original.
-   */
-  before?: (
-    ctx: BeforeHookContext,
-  ) =>
-    | void
-    | ChatCompletionsBody
-    | EmbeddingsBody
-    | Promise<void | ChatCompletionsBody | EmbeddingsBody>;
-  /**
-   * Maps a user-provided model ID or alias to a canonical ID.
-   * @returns Canonical model ID or undefined to keep original.
-   */
-  resolveModelId?: (ctx: ResolveModelHookContext) => ModelId | void | Promise<ModelId | void>;
-  /**
-   * Picks a provider instance for the request.
-   * @returns ProviderV3 to override, or undefined to use default.
-   */
-  resolveProvider?: (
-    ctx: ResolveProviderHookContext,
-  ) => ProviderV3 | void | Promise<ProviderV3 | void>;
-  /**
-   * Runs after the endpoint handler.
-   * @returns Result to replace, or undefined to keep original.
-   */
-  after?: (
-    ctx: AfterHookContext,
-  ) =>
-    | void
-    | ChatCompletions
-    | ReadableStream<ChatCompletionsChunk | Error>
-    | Embeddings
-    | Promise<void | ChatCompletions | ReadableStream<ChatCompletionsChunk | Error> | Embeddings>;
-  /**
-   * Runs after the lifecycle has produced the final Response.
-   * @returns Replacement Response, or undefined to keep original.
-   */
-  onResponse?: (ctx: OnResponseHookContext) => void | Response | Promise<void | Response>;
-};
-
-export type TelemetrySignalLevel = "off" | "required" | "recommended" | "full";
-
-/**
- * Main configuration object for the gateway.
- */
-export type GatewayConfig = {
-  /**
-   * Optional base path the gateway is mounted under (e.g. "/v1/gateway").
-   */
-  basePath?: string;
-  /**
-   * Provider registry keyed by canonical provider IDs.
-   */
-  providers: ProviderRegistry;
-  /**
-   * Model catalog keyed by canonical model IDs.
-   */
-  models: ModelCatalog;
-  /**
-   * Optional lifecycle hooks for routing, auth, and response shaping.
-   */
-  hooks?: GatewayHooks;
-  /**
-   * Preferred logger configuration: custom logger or default logger settings.
-   */
-  logger?: Logger | LoggerConfig | null;
-  /**
-   * Optional AI SDK telemetry configuration.
-   */
-  telemetry?: {
-    /**
-     * Enable AI SDK OpenTelemetry instrumentation.
-     * Disabled by default.
-     */
-    enabled?: boolean;
-    /**
-     * Optional custom OpenTelemetry tracer passed to AI SDK telemetry.
-     */
-    tracer?: Tracer;
-    /**
-     * Telemetry signal levels by namespace.
-     * - off: disable the namespace
-     * - required: minimal baseline
-     * - recommended: practical defaults
-     * - full: include all available details
-     */
-    signals?: {
-      gen_ai?: TelemetrySignalLevel;
-      http?: TelemetrySignalLevel;
-      hebo?: TelemetrySignalLevel;
-    };
-  };
-};
-
-export const kParsed = Symbol("hebo.gateway.parsed");
-export type GatewayConfigParsed = GatewayConfig & {
-  [kParsed]: true;
-};
-
-export interface Endpoint {
-  handler: (request: Request, state?: Record<string, unknown>) => Promise<Response>;
-}
-
-export interface HeboGateway<Routes extends Record<string, Endpoint>> extends Endpoint {
-  routes: Routes;
-}

package/src/utils/env.ts

@@ -1,7 +0,0 @@
-const NODE_ENV =
-  typeof process === "undefined"
-    ? ((globalThis as any).NODE_ENV ?? (globalThis as any).ENV?.NODE_ENV)
-    : process.env?.NODE_ENV;
-
-export const isProduction = () => NODE_ENV === "production";
-export const isTest = () => NODE_ENV === "test";

package/src/utils/headers.ts

@@ -1,27 +0,0 @@
-export const REQUEST_ID_HEADER = "x-request-id";
-
-type HeaderSource = Request | ResponseInit | undefined;
-
-export const resolveRequestId = (source: HeaderSource): string | undefined => {
-  if (!source) return undefined;
-
-  if (source instanceof Request) {
-    return source.headers.get(REQUEST_ID_HEADER) ?? undefined;
-  }
-
-  const headers = source.headers;
-  if (!headers) return undefined;
-
-  if (headers instanceof Headers) {
-    return headers.get(REQUEST_ID_HEADER) ?? undefined;
-  }
-
-  if (Array.isArray(headers)) {
-    for (const [key, value] of headers) {
-      if (key.toLowerCase() === REQUEST_ID_HEADER) return value;
-    }
-    return undefined;
-  }
-
-  return headers[REQUEST_ID_HEADER];
-};

package/src/utils/preset.ts

@@ -1,65 +0,0 @@
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
-  const proto = Object.getPrototypeOf(v);
-  return proto === Object.prototype || proto === null;
-}
-
-export type DeepPartial<T> = T extends (...args: unknown[]) => unknown
-  ? T
-  : T extends readonly (infer U)[]
-    ? readonly DeepPartial<U>[]
-    : T extends object
-      ? { [K in keyof T]?: DeepPartial<T[K]> }
-      : T;
-
-/**
- * Deep merge where overrides win.
- * Arrays are replaced.
- */
-export function deepMerge<A extends object, B extends object>(base: A, override?: B): A & B {
-  if (override === null || override === undefined) return base as A & B;
-
-  if (!isPlainObject(base) || !isPlainObject(override)) {
-    return override as unknown as A & B;
-  }
-
-  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
-
-  for (const [key, ov] of Object.entries(override as Record<string, unknown>)) {
-    if (ov === undefined) continue;
-
-    const bv = out[key];
-
-    if (Array.isArray(ov)) {
-      out[key] = ov;
-      continue;
-    }
-
-    if (isPlainObject(bv) && isPlainObject(ov)) {
-      out[key] = deepMerge(bv as object, ov as object);
-      continue;
-    }
-
-    out[key] = ov;
-  }
-
-  return out as unknown as A & B;
-}
-
-export type Preset<
-  Id extends string,
-  T extends Record<string, unknown>,
-  Base extends DeepPartial<T>,
-> = <O extends DeepPartial<T>>(override?: O) => Record<Id, Base & O>;
-
-export function presetFor<Ids extends string, T extends Record<string, unknown>>() {
-  return function preset<const Id extends Ids, const Base extends DeepPartial<T>>(
-    id: Id,
-    base: Base,
-  ): Preset<Id, T, Base> {
-    return <const O extends DeepPartial<T>>(override?: O) => {
-      const merged = deepMerge(base, override ?? ({} as O));
-      return { [id]: merged } as Record<Id, Base & O>;
-    };
-  };
-}

package/src/utils/request.test.ts

@@ -1,75 +0,0 @@
-import { describe, expect, test } from "bun:test";
-
-import { prepareForwardHeaders } from "./request";
-
-describe("prepareForwardHeaders", () => {
-  test("always appends gateway user-agent suffix", () => {
-    const request = new Request("https://example.com", {
-      headers: { "user-agent": "client/1.0" },
-    });
-
-    const headers = prepareForwardHeaders(request);
-
-    expect(headers["user-agent"].startsWith("client/1.0 @hebo-ai/gateway/")).toBe(true);
-  });
-
-  test("falls back to gateway user-agent when incoming user-agent is missing", () => {
-    const request = new Request("https://example.com");
-
-    const headers = prepareForwardHeaders(request);
-
-    expect(headers["user-agent"].startsWith("@hebo-ai/gateway/")).toBe(true);
-  });
-
-  test("forwards allowlisted provider headers without provider context", () => {
-    const request = new Request("https://example.com", {
-      headers: {
-        "openai-beta": "responses=v1",
-        "openai-organization": "org_123",
-        "openai-project": "proj_123",
-        "anthropic-beta": "interleaved-thinking-2025-05-14",
-        "x-amzn-bedrock-performanceconfig-latency": "optimized",
-        "x-amzn-bedrock-trace": "ENABLED_FULL",
-        "x-client-name": "hebo-gateway-test",
-        "x-vertex-ai-endpoint-id": "projects/1/locations/us-central1/endpoints/123",
-        "x-vertex-ai-llm-request-type": "dedicated",
-        "x-vertex-ai-llm-shared-request-type": "provisioned-throughput",
-        "x-title": "Gateway App",
-        "x-unrelated-header": "blocked",
-      },
-    });
-
-    const headers = prepareForwardHeaders(request);
-
-    expect(headers["openai-beta"]).toBe("responses=v1");
-    expect(headers["openai-organization"]).toBe("org_123");
-    expect(headers["openai-project"]).toBe("proj_123");
-    expect(headers["anthropic-beta"]).toBe("interleaved-thinking-2025-05-14");
-    expect(headers["x-amzn-bedrock-performanceconfig-latency"]).toBe("optimized");
-    expect(headers["x-amzn-bedrock-trace"]).toBe("ENABLED_FULL");
-    expect(headers["x-client-name"]).toBe("hebo-gateway-test");
-    expect(headers["x-vertex-ai-endpoint-id"]).toBe(
-      "projects/1/locations/us-central1/endpoints/123",
-    );
-    expect(headers["x-vertex-ai-llm-request-type"]).toBe("dedicated");
-    expect(headers["x-vertex-ai-llm-shared-request-type"]).toBe("provisioned-throughput");
-    expect(headers["x-title"]).toBe("Gateway App");
-    expect(headers["x-unrelated-header"]).toBeUndefined();
-  });
-
-  test("does not forward headers outside the allowlist", () => {
-    const request = new Request("https://example.com", {
-      headers: {
-        authorization: "Bearer user-token",
-        cookie: "session=abc",
-        "x-custom-header": "blocked",
-      },
-    });
-
-    const headers = prepareForwardHeaders(request);
-
-    expect(headers.authorization).toBeUndefined();
-    expect(headers.cookie).toBeUndefined();
-    expect(headers["x-custom-header"]).toBeUndefined();
-  });
-});

package/src/utils/request.ts

@@ -1,52 +0,0 @@
-import pkg from "../../package.json" with { type: "json" };
-import { resolveRequestId } from "./headers";
-
-const GATEWAY_VERSION = pkg.version;
-
-const FORWARD_HEADER_ALLOWLIST = [
-  // OpenAI + OpenAI-compatible providers (Azure, Groq, Together, Fireworks, etc.)
-  "openai-beta",
-  "openai-organization",
-  "openai-project",
-  // OpenRouter
-  "x-openrouter-categories",
-  "x-openrouter-title",
-  "x-title",
-  // Anthropic
-  "anthropic-beta",
-  // AWS Bedrock
-  "x-amzn-bedrock-guardrailidentifier",
-  "x-amzn-bedrock-guardrailversion",
-  "x-amzn-bedrock-performanceconfig-latency",
-  "x-amzn-bedrock-trace",
-  // Cohere
-  "x-client-name",
-  // Vertex provisioned throughput / endpoint routing
-  "x-vertex-ai-endpoint-id",
-  "x-vertex-ai-llm-request-type",
-  "x-vertex-ai-llm-shared-request-type",
-] as const;
-
-const createRequestId = () =>
-  "req_" + crypto.getRandomValues(new Uint32Array(2)).reduce((s, n) => s + n.toString(36), "");
-
-export const resolveOrCreateRequestId = (request: Request) =>
-  resolveRequestId(request) ?? createRequestId();
-
-export const prepareForwardHeaders = (request: Request): Record<string, string> => {
-  const userAgent = request.headers.get("user-agent");
-  const appendedUserAgent = userAgent
-    ? `${userAgent} @hebo-ai/gateway/${GATEWAY_VERSION}`
-    : `@hebo-ai/gateway/${GATEWAY_VERSION}`;
-
-  const headers: Record<string, string> = {
-    "user-agent": appendedUserAgent,
-  };
-
-  for (const key of FORWARD_HEADER_ALLOWLIST) {
-    const value = request.headers.get(key);
-    if (value !== null) headers[key] = value;
-  }
-
-  return headers;
-};

package/src/utils/response.ts

@@ -1,84 +0,0 @@
-import { REQUEST_ID_HEADER } from "./headers";
-
-const TEXT_ENCODER = new TextEncoder();
-
-class JsonToSseTransformStream extends TransformStream<unknown, string> {
-  constructor() {
-    super({
-      transform(part, controller) {
-        controller.enqueue(`data: ${JSON.stringify(part)}\n\n`);
-      },
-      flush(controller) {
-        controller.enqueue("data: [DONE]\n\n");
-      },
-    });
-  }
-}
-
-export const prepareResponseInit = (requestId: string): ResponseInit => ({
-  headers: { [REQUEST_ID_HEADER]: requestId },
-});
-
-export const mergeResponseInit = (
-  defaultHeaders: HeadersInit,
-  responseInit?: ResponseInit,
-): ResponseInit => {
-  const headers = new Headers(defaultHeaders);
-  const override = responseInit?.headers;
-  if (override) {
-    new Headers(override).forEach((value, key) => headers.set(key, value));
-  }
-  if (!responseInit) return { headers };
-
-  return {
-    status: responseInit.status,
-    statusText: responseInit.statusText,
-    headers,
-  };
-};
-
-export const toResponse = (
-  result: ReadableStream | Uint8Array<ArrayBuffer> | object | string,
-  responseInit?: ResponseInit,
-): Response => {
-  let body: BodyInit;
-
-  const isStream = result instanceof ReadableStream;
-  if (isStream) {
-    body = result.pipeThrough(new JsonToSseTransformStream()).pipeThrough(new TextEncoderStream());
-  } else if (result instanceof Uint8Array) {
-    body = result;
-  } else if (typeof result === "string") {
-    body = TEXT_ENCODER.encode(result);
-  } else if (result instanceof Error) {
-    body = TEXT_ENCODER.encode(JSON.stringify({ message: result.message }));
-  } else {
-    body = TEXT_ENCODER.encode(JSON.stringify(result));
-  }
-
-  if (!responseInit?.statusText) {
-    const isError = result instanceof Error;
-
-    const status = responseInit?.status ?? (isError ? 500 : 200);
-    const statusText = isError ? "REQUEST_FAILED" : "OK";
-    const headers = responseInit?.headers;
-
-    responseInit = headers ? { status, statusText, headers } : { status, statusText };
-  }
-
-  const init = mergeResponseInit(
-    isStream
-      ? {
-          "content-type": "text/event-stream",
-          "cache-control": "no-cache",
-          connection: "keep-alive",
-        }
-      : {
-          "content-type": "application/json",
-          "content-length": String((body as Uint8Array).byteLength),
-        },
-    responseInit,
-  );
-
-  return new Response(body, init);
-};

package/src/utils/url.ts

@@ -1,26 +0,0 @@
-export const parseDataUrl = (url: string): { mimeType: string; dataStart: number } => {
-  if (url.slice(0, 5).toLowerCase() !== "data:") {
-    return { mimeType: "", dataStart: 0 };
-  }
-
-  const MAX_HEADER_LENGTH = 1024;
-  const headerEnd = Math.min(url.length, 5 + MAX_HEADER_LENGTH);
-
-  const comma = url.indexOf(",", 5);
-  if (comma <= 5 || comma > headerEnd) {
-    return { mimeType: "", dataStart: 0 };
-  }
-
-  const semi = url.indexOf(";", 5);
-  const mimeEnd = semi !== -1 && semi < comma ? semi : comma;
-
-  const mimeType = url.slice(5, mimeEnd).trim();
-  if (!mimeType) {
-    return { mimeType: "", dataStart: 0 };
-  }
-
-  return {
-    mimeType,
-    dataStart: comma + 1,
-  };
-};