@gscdump/cloudflare 1.4.0 → 1.4.2

package/dist/server-tail/index.d.mts

@@ -1,250 +1,5 @@
-import { ArchetypeQuery, ArchetypeResult, ArchetypeResultRow } from "@gscdump/contracts/archetypes";
-import { Result } from "gscdump/result";
-import { ServerTailDirective } from "@gscdump/contracts";
-declare const TABLE_PLACEHOLDER = "{{TABLE}}";
-type ArchetypeFactTable = 'pages' | 'queries' | 'countries' | 'page_queries' | 'dates';
-interface ArchetypeSqlPlan {
-  sql: string;
-  params: unknown[];
-  table: ArchetypeFactTable;
-}
-type PartitionPredicateMode = 'bare' | 'r2-sql-concat';
-type PartitionKeyEncoding = 'int' | 'string';
-interface BuildArchetypeSqlOptions {
-  /**
-   * Set by the DuckDB file-list executor, which reads raw Iceberg parquet
-   * directly via `read_parquet([...])`, bypassing the catalog metadata layer
-   * that synthesizes the identity-partition columns. `site_id` / `search_type`
-   * are partition identities NOT materialized in the data files (see engine
-   * `iceberg/schema.ts`: "carried implicitly in the object-key prefix"), so a
-   * `WHERE site_id = ?` predicate fails with `Referenced column "site_id" not
-   * found in FROM clause`. Those files are already pruned to (site_id,
-   * search_type) at resolution time, so the predicate is redundant — emit only
-   * the row-level `date` range (a real stored column; `month(date)` is the
-   * partition transform, not `date` itself).
-   *
-   * The R2 SQL catalog path (default `false`) exposes partition columns as
-   * virtual columns and needs the full predicate.
-   */
-  partitionPruned?: boolean;
-  /**
-   * Int-partition catalogs are the default and use bare equality. Legacy
-   * string-partition catalogs can request CONCAT-wrapped predicates directly
-   * instead of post-processing generated SQL.
-   */
-  partitionPredicateMode?: PartitionPredicateMode;
-  /** Preferred input for new callers. Defaults to `'int'`. */
-  partitionKeyEncoding?: PartitionKeyEncoding;
-}
-declare function buildArchetypeSql(query: ArchetypeQuery, opts?: BuildArchetypeSqlOptions): ArchetypeSqlPlan;
-/** Row returned by the DuckDB sibling. */
-type DuckDbIcebergRow = Record<string, string | number | null>;
-/**
- * The minimal `DUCKDB_SVC` shape this executor needs — a structural subset of
- * the binding in `workers-duckdb.ts` / `env.ts`. Any binding with `runSQL`
- * satisfies it.
- */
-interface DuckDbSvc {
-  runSQL: (args: {
-    sql: string;
-    deadlineAt?: number;
-  }) => Promise<{
-    rows: unknown[];
-    sql: string;
-  }>;
-}
-/** Configuration for the DuckDB-over-Iceberg executor. */
-interface DuckDbIcebergExecutorConfig {
-  /** The DuckDB service binding (the sibling Worker RPC). */
-  svc: DuckDbSvc;
-  /**
-   * R2 Data Catalog warehouse identifier. The sibling resolves Iceberg table
-   * locations from `<warehouse>` + `<namespace>` + table name.
-   */
-  warehouse: string;
-  /** Iceberg namespace the 5 fact tables live in. */
-  namespace: string;
-  /**
-   * How the sibling addresses an Iceberg table in a `FROM` clause. Defaults to
-   * DuckDB's `iceberg_scan('<warehouse>/<namespace>/<table>')`. Overridable so
-   * a sibling configured with the Iceberg REST catalog can use
-   * `iceberg_scan('<namespace>.<table>')` or an attached-catalog reference.
-   */
-  tableRefStyle?: 'path' | 'catalog';
-  /** Per-query wall-clock deadline (ms). Default 25s. */
-  timeoutMs?: number;
-}
-/** Result of a DuckDB-over-Iceberg query. */
-interface DuckDbIcebergResult {
-  rows: DuckDbIcebergRow[];
-  /** The exact SQL sent to the sibling. */
-  sql: string;
-  queryMs: number;
-}
-declare class DuckDbIcebergError extends Error {
-  name: string;
-}
-declare class DuckDbIcebergTimeoutError extends Error {
-  name: string;
-  constructor(timeoutMs: number);
-}
-/**
- * The modelled, caller-actionable failure channel for a DuckDB-over-Iceberg
- * query. As with the R2 SQL client, callers branch on which class came back: a
- * `DuckDbIcebergTimeoutError` is the retry-able deadline overrun, a
- * `DuckDbIcebergError` is a hard sibling-RPC failure (or the `aux-cloud-only`
- * routing reject). The error variant IS the existing throwable class, so the
- * throwing wrappers preserve the identity/message tests assert
- * (`rejects.toThrow(/OOM in sibling/)`, `rejects.toThrow(DuckDbIcebergError)`).
- */
-type DuckDbIcebergQueryError = DuckDbIcebergError | DuckDbIcebergTimeoutError;
-/** A configured DuckDB-over-Iceberg executor. */
-interface DuckDbIcebergExecutor {
-  /** Run a raw SQL string with `{{TABLE_<name>}}` placeholders resolved. */
-  runSql: (sql: string, params?: readonly unknown[]) => Promise<DuckDbIcebergResult>;
-  /** Run a dialect-neutral plan: resolve `{{TABLE}}`, bind params, send. */
-  runPlan: (plan: ArchetypeSqlPlan) => Promise<DuckDbIcebergResult>;
-  /** Translate + run an archetype query. Handles `arbitrary-sql` verbatim. */
-  runArchetype: (query: ArchetypeQuery) => Promise<DuckDbIcebergResult>;
-  /**
-   * Errors-as-values core for {@link DuckDbIcebergExecutor.runArchetype}:
-   * returns the modelled timeout-vs-hard-fail `DuckDbIcebergQueryError` instead
-   * of throwing, so the dispatcher can branch on retry-ability (a timeout may be
-   * worth a fallback) without `instanceof` over a `catch`. Optional so a
-   * hand-rolled executor (e.g. a host app's own service-binding executor) can
-   * implement only the throwing surface; {@link createDuckDbIcebergExecutor}
-   * always provides it.
-   */
-  runArchetypeResult?: (query: ArchetypeQuery) => Promise<Result<DuckDbIcebergResult, DuckDbIcebergQueryError>>;
-}
-/**
- * Create a DuckDB-over-Iceberg-files executor.
- */
-declare function createDuckDbIcebergExecutor(config: DuckDbIcebergExecutorConfig): DuckDbIcebergExecutor;
-/** Configuration for an R2 SQL client. */
-interface R2SqlClientConfig {
-  /** Cloudflare account id. */
-  accountId: string;
-  /** R2 bucket backing the Iceberg catalog — R2 SQL addresses the catalog by bucket. */
-  bucket: string;
-  /** Iceberg namespace the 5 fact tables live in. */
-  namespace: string;
-  /** Cloudflare API token with R2 Data Catalog read scope. */
-  token: string;
-  /**
-   * Override the HTTP endpoint base. Defaults to the public CF API. Tests
-   * point this at a local recorder.
-   */
-  apiBase?: string;
-  /**
-   * Injectable fetch. Defaults to global `fetch`. Tests pass a fake that
-   * returns a recorded CF envelope without a network round-trip.
-   */
-  fetchImpl?: typeof fetch;
-  /** Per-query wall-clock deadline (ms). Default 25s — under the Worker CPU budget. */
-  timeoutMs?: number;
-  /** Partition-key encoding of the target catalog. Defaults to `'int'`. */
-  partitionKeyEncoding?: PartitionKeyEncoding;
-  /**
-   * Host-owned mapping from public site id to the INT `site_id` partition
-   * value. Required for non-numeric public ids when `partitionKeyEncoding` is
-   * `'int'`.
-   */
-  partitionSiteId?: (siteId: string) => string | number;
-}
-/** A row as returned by R2 SQL — flat dimension + metric values. */
-type R2SqlRow = Record<string, string | number | null>;
-/** Result of an R2 SQL query. */
-interface R2SqlResult {
-  rows: R2SqlRow[];
-  /** The exact SQL sent (params already inlined). For diagnostics. */
-  sql: string;
-  /** Wall-clock duration of the HTTP round-trip. */
-  queryMs: number;
-}
-declare class R2SqlError extends Error {
-  readonly status?: number | undefined;
-  name: string;
-  constructor(message: string, status?: number | undefined);
-}
-declare class R2SqlTimeoutError extends Error {
-  name: string;
-  constructor(timeoutMs: number);
-}
-/**
- * The modelled, caller-actionable failure channel for an R2 SQL query. Callers
- * branch on which class came back — a `R2SqlTimeoutError` is a transient retry
- * candidate (the query outran the per-query deadline), while a `R2SqlError`
- * (HTTP 4xx/5xx, a rejected envelope, a transport blow-up) is a hard failure.
- * The error variant IS the existing throwable class, so the throwing wrapper
- * preserves the exact identity/message tests assert (`rejects.toThrow(/HTTP 403/)`,
- * `rejects.toBeInstanceOf(R2SqlTimeoutError)`). Defects — a programmer handing
- * the client malformed params (`escapeSqlValue` / `inlineParams`) — are NOT
- * modelled here; they keep throwing `R2SqlError` synchronously.
- */
-type R2SqlQueryError = R2SqlError | R2SqlTimeoutError;
-/** A configured R2 SQL client. */
-interface R2SqlClient {
-  /** Run a raw SQL string (table reference already resolved). */
-  query: (sql: string) => Promise<R2SqlResult>;
-  /**
-   * Errors-as-values core for {@link R2SqlClient.query}: returns the modelled
-   * timeout-vs-hard-fail `R2SqlQueryError` instead of throwing, so callers can
-   * branch on retry-ability without `instanceof` over a `catch`. Optional so a
-   * hand-rolled `R2SqlClient` (e.g. a host app's own endpoint-backed client) can
-   * implement only the throwing surface; {@link createR2SqlClient} always
-   * provides it.
-   */
-  queryResult?: (sql: string) => Promise<Result<R2SqlResult, R2SqlQueryError>>;
-  /** Run a dialect-neutral plan: resolve `{{TABLE}}`, inline params, send. */
-  runPlan: (plan: ArchetypeSqlPlan) => Promise<R2SqlResult>;
-  /** Translate + run an archetype query end to end. */
-  runArchetype: (query: ArchetypeQuery) => Promise<R2SqlResult>;
-}
-/**
- * Create an R2 SQL client. The endpoint requires a real CF token in
- * production; tests inject `fetchImpl` returning a recorded envelope.
- */
-declare function createR2SqlClient(config: R2SqlClientConfig): R2SqlClient;
-/** The two engines the server tail can route to. */
-type ServerTailEngine = 'r2-sql' | 'duckdb';
-/** Executors the dispatcher routes between. */
-interface ServerTailDispatcherConfig {
-  r2Sql: R2SqlClient;
-  duckdb: DuckDbIcebergExecutor;
-}
-declare class ServerTailRoutingError extends Error {
-  name: string;
-}
-/**
- * Errors-as-values core for {@link resolveServerTailEngine}: returns a
- * `ServerTailRoutingError` instead of throwing when an archetype is `cloud-only`
- * (the one caller-actionable routing failure — the consumer must route that
- * query through the cloud endpoints, not the server tail). Pure — no I/O.
- */
-declare function resolveServerTailEngineResult(query: ArchetypeQuery): Result<ServerTailEngine, ServerTailRoutingError>;
-/**
- * Decide which engine answers an archetype query. Pure — no I/O. Exposed so
- * the file-resolution endpoint can compute the `ServerTailDirective.engine`
- * with the SAME logic the dispatcher uses at execution time. Throws
- * `ServerTailRoutingError` for a `cloud-only` archetype; see
- * {@link resolveServerTailEngineResult} for the errors-as-values core.
- */
-declare function resolveServerTailEngine(query: ArchetypeQuery): ServerTailEngine;
-/** A configured server-tail dispatcher. */
-interface ServerTailDispatcher {
-  /** Decide the engine for a query without running it. */
-  route: (query: ArchetypeQuery) => ServerTailEngine;
-  /**
-   * Execute a query, routing by execution class. If `directive` is supplied
-   * its `engine` is honoured only when consistent with the archetype's class
-   * (a `duckdb`-class archetype always runs on DuckDB regardless).
-   */
-  execute: <R extends ArchetypeResultRow = ArchetypeResultRow>(query: ArchetypeQuery, directive?: ServerTailDirective) => Promise<ArchetypeResult<R>>;
-}
-/**
- * Create the server-tail dispatcher. Holds an R2 SQL client and a DuckDB
- * executor and routes every `ArchetypeQuery` to one of them.
- */
-declare function createServerTailDispatcher(config: ServerTailDispatcherConfig): ServerTailDispatcher;
+import { ArchetypeSqlPlan, BuildArchetypeSqlOptions, TABLE_PLACEHOLDER, buildArchetypeSql } from "./archetype-sql.mjs";
+import { DuckDbIcebergError, DuckDbIcebergExecutor, DuckDbIcebergExecutorConfig, DuckDbIcebergQueryError, DuckDbIcebergResult, DuckDbIcebergRow, DuckDbIcebergTimeoutError, DuckDbSvc, createDuckDbIcebergExecutor } from "./duckdb-iceberg-executor.mjs";
+import { R2SqlClient, R2SqlClientConfig, R2SqlError, R2SqlQueryError, R2SqlResult, R2SqlRow, R2SqlTimeoutError, createR2SqlClient } from "./r2-sql-client.mjs";
+import { ServerTailDispatcher, ServerTailDispatcherConfig, ServerTailEngine, ServerTailRoutingError, createServerTailDispatcher, resolveServerTailEngine, resolveServerTailEngineResult } from "./dispatcher.mjs";
 export { type ArchetypeSqlPlan, type BuildArchetypeSqlOptions, DuckDbIcebergError, type DuckDbIcebergExecutor, type DuckDbIcebergExecutorConfig, type DuckDbIcebergQueryError, type DuckDbIcebergResult, type DuckDbIcebergRow, DuckDbIcebergTimeoutError, type DuckDbSvc, type R2SqlClient, type R2SqlClientConfig, R2SqlError, type R2SqlQueryError, type R2SqlResult, type R2SqlRow, R2SqlTimeoutError, type ServerTailDispatcher, type ServerTailDispatcherConfig, type ServerTailEngine, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createR2SqlClient, createServerTailDispatcher, resolveServerTailEngine, resolveServerTailEngineResult };