@gscdump/cloudflare 3.5.0 → 3.6.0

package/README.md

@@ -0,0 +1,48 @@
+# @gscdump/cloudflare
+
+Cloudflare helpers for server-tail queries and concurrent request deduplication.
+
+## Install
+
+```bash
+npm install @gscdump/cloudflare
+```
+
+The package has two public subpaths and no root export.
+
+| Subpath | Purpose |
+| --- | --- |
+| `@gscdump/cloudflare/server-tail` | Route queries through R2 SQL or a DuckDB service |
+| `@gscdump/cloudflare/inflight-dedupe` | Share pending requests with identical keys |
+
+## Deduplicate pending requests
+
+```ts
+import { createInflightDedupe, getHostedR2QueryKey } from '@gscdump/cloudflare/inflight-dedupe'
+
+const requests = createInflightDedupe<string[]>()
+const key = getHostedR2QueryKey({
+  userId: 'u_01',
+  siteId: 's_01',
+  state: { dimensions: ['page'] },
+})
+const rows = await requests.dedupe(key, async () => ['https://example.com/docs'])
+console.log(rows)
+```
+
+Concurrent calls with the same key share one promise.
+After it settles, the next call runs again.
+Include the authenticated user, Site, query state, and comparison inputs in the key.
+
+## Server-tail queries
+
+`createServerTailDispatcher` selects a configured R2 SQL or DuckDB executor.
+The subpath exports the executor factories, transport helpers, SQL compilation, and typed routing errors.
+Your host supplies credentials, transport, authorization, and the DuckDB service binding.
+
+For storage contracts, see [`@gscdump/engine`](../engine/README.md).
+For hosted HTTP integrations, use [`@gscdump/sdk`](../sdk/README.md).
+
+## License
+
+[MIT](../../LICENSE)

package/dist/inflight-dedupe.d.mts

@@ -1,15 +1,14 @@
-interface InflightDedupe<T> {
+export interface InflightDedupe<T> {
   dedupe: (key: string, run: () => Promise<T>) => Promise<T>;
   has: (key: string) => boolean;
   clear: () => void;
 }
-declare function createInflightDedupe<T>(): InflightDedupe<T>;
-interface HostedR2QueryKeyInput {
+export declare function createInflightDedupe<T>(): InflightDedupe<T>;
+export interface HostedR2QueryKeyInput {
   userId: string | number;
   siteId: string;
   state: unknown;
   comparison?: unknown;
   comparisonFilter?: string;
 }
-declare function getHostedR2QueryKey(input: HostedR2QueryKeyInput): string;
-export { HostedR2QueryKeyInput, InflightDedupe, createInflightDedupe, getHostedR2QueryKey };
+export declare function getHostedR2QueryKey(input: HostedR2QueryKeyInput): string;

package/dist/server-tail/archetype-sql.d.mts

@@ -1,14 +1,14 @@
 import { ArchetypeQuery } from "@gscdump/contracts/archetypes";
-declare const TABLE_PLACEHOLDER = "{{TABLE}}";
-type ArchetypeFactTable = 'pages' | 'queries' | 'countries' | 'page_queries' | 'dates';
-interface ArchetypeSqlPlan {
+export declare const TABLE_PLACEHOLDER = "{{TABLE}}";
+export type ArchetypeFactTable = 'pages' | 'queries' | 'countries' | 'page_queries' | 'dates';
+export interface ArchetypeSqlPlan {
   sql: string;
   params: unknown[];
   table: ArchetypeFactTable;
 }
-type PartitionPredicateMode = 'bare' | 'r2-sql-concat';
-type PartitionKeyEncoding = 'int' | 'string';
-interface BuildArchetypeSqlOptions {
+export type PartitionPredicateMode = 'bare' | 'r2-sql-concat';
+export type PartitionKeyEncoding = 'int' | 'string';
+export interface BuildArchetypeSqlOptions {
   /**
    * Set by the DuckDB file-list executor, which reads raw Iceberg parquet
    * directly via `read_parquet([...])`, bypassing the catalog metadata layer
@@ -34,5 +34,4 @@ interface BuildArchetypeSqlOptions {
   /** Preferred input for new callers. Defaults to `'int'`. */
   partitionKeyEncoding?: PartitionKeyEncoding;
 }
-declare function buildArchetypeSql(query: ArchetypeQuery, opts?: BuildArchetypeSqlOptions): ArchetypeSqlPlan;
-export { ArchetypeFactTable, ArchetypeSqlPlan, BuildArchetypeSqlOptions, PartitionKeyEncoding, PartitionPredicateMode, TABLE_PLACEHOLDER, buildArchetypeSql };
+export declare function buildArchetypeSql(query: ArchetypeQuery, opts?: BuildArchetypeSqlOptions): ArchetypeSqlPlan;

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

@@ -4,13 +4,13 @@ import { ArchetypeQuery, ArchetypeResult, ArchetypeResultRow } from "@gscdump/co
 import { Result } from "gscdump/result";
 import { ServerTailDirective } from "@gscdump/contracts";
 /** The two engines the server tail can route to. */
-type ServerTailEngine = 'r2-sql' | 'duckdb';
+export type ServerTailEngine = 'r2-sql' | 'duckdb';
 /** Executors the dispatcher routes between. */
-interface ServerTailDispatcherConfig {
+export interface ServerTailDispatcherConfig {
   r2Sql: R2SqlClient;
   duckdb: DuckDbIcebergExecutor;
 }
-declare class ServerTailRoutingError extends Error {
+export declare class ServerTailRoutingError extends Error {
   name: string;
 }
 /**
@@ -19,7 +19,7 @@ declare class ServerTailRoutingError extends Error {
  * (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>;
+export 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`
@@ -27,9 +27,9 @@ declare function resolveServerTailEngineResult(query: ArchetypeQuery): Result<Se
  * `ServerTailRoutingError` for a `cloud-only` archetype; see
  * {@link resolveServerTailEngineResult} for the errors-as-values core.
  */
-declare function resolveServerTailEngine(query: ArchetypeQuery): ServerTailEngine;
+export declare function resolveServerTailEngine(query: ArchetypeQuery): ServerTailEngine;
 /** A configured server-tail dispatcher. */
-interface ServerTailDispatcher {
+export interface ServerTailDispatcher {
   /** Decide the engine for a query without running it. */
   route: (query: ArchetypeQuery) => ServerTailEngine;
   /**
@@ -43,5 +43,4 @@ interface ServerTailDispatcher {
  * 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;
-export { ServerTailDispatcher, ServerTailDispatcherConfig, ServerTailEngine, ServerTailRoutingError, createServerTailDispatcher, resolveServerTailEngine, resolveServerTailEngineResult };
+export declare function createServerTailDispatcher(config: ServerTailDispatcherConfig): ServerTailDispatcher;

package/dist/server-tail/duckdb-iceberg-executor.d.mts

@@ -2,12 +2,12 @@ import { ArchetypeSqlPlan } from "./archetype-sql.mjs";
 import { ArchetypeQuery } from "@gscdump/contracts/archetypes";
 import { Result } from "gscdump/result";
 /** Row returned by the DuckDB sibling. */
-type DuckDbIcebergRow = Record<string, string | number | null>;
+export type DuckDbIcebergRow = Record<string, string | number | null>;
 /**
  * The minimal `DUCKDB_SVC` shape this executor needs. Any binding with
  * `runSQL` satisfies it.
  */
-interface DuckDbSvc {
+export interface DuckDbSvc {
   runSQL: (args: {
     sql: string;
     deadlineAt?: number;
@@ -17,7 +17,7 @@ interface DuckDbSvc {
   }>;
 }
 /** Configuration for the DuckDB-over-Iceberg executor. */
-interface DuckDbIcebergExecutorConfig {
+export interface DuckDbIcebergExecutorConfig {
   /** The DuckDB service binding (the sibling Worker RPC). */
   svc: DuckDbSvc;
   /**
@@ -38,16 +38,16 @@ interface DuckDbIcebergExecutorConfig {
   timeoutMs?: number;
 }
 /** Result of a DuckDB-over-Iceberg query. */
-interface DuckDbIcebergResult {
+export interface DuckDbIcebergResult {
   rows: DuckDbIcebergRow[];
   /** The exact SQL sent to the sibling. */
   sql: string;
   queryMs: number;
 }
-declare class DuckDbIcebergError extends Error {
+export declare class DuckDbIcebergError extends Error {
   name: string;
 }
-declare class DuckDbIcebergTimeoutError extends Error {
+export declare class DuckDbIcebergTimeoutError extends Error {
   name: string;
   constructor(timeoutMs: number);
 }
@@ -60,9 +60,9 @@ declare class DuckDbIcebergTimeoutError extends Error {
  * throwing wrappers preserve the identity/message tests assert
  * (`rejects.toThrow(/OOM in sibling/)`, `rejects.toThrow(DuckDbIcebergError)`).
  */
-type DuckDbIcebergQueryError = DuckDbIcebergError | DuckDbIcebergTimeoutError;
+export type DuckDbIcebergQueryError = DuckDbIcebergError | DuckDbIcebergTimeoutError;
 /** A configured DuckDB-over-Iceberg executor. */
-interface DuckDbIcebergExecutor {
+export 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. */
@@ -83,5 +83,4 @@ interface DuckDbIcebergExecutor {
 /**
  * Create a DuckDB-over-Iceberg-files executor.
  */
-declare function createDuckDbIcebergExecutor(config: DuckDbIcebergExecutorConfig): DuckDbIcebergExecutor;
-export { DuckDbIcebergError, DuckDbIcebergExecutor, DuckDbIcebergExecutorConfig, DuckDbIcebergQueryError, DuckDbIcebergResult, DuckDbIcebergRow, DuckDbIcebergTimeoutError, DuckDbSvc, createDuckDbIcebergExecutor };
+export declare function createDuckDbIcebergExecutor(config: DuckDbIcebergExecutorConfig): DuckDbIcebergExecutor;

package/dist/server-tail/r2-sql-client.d.mts

@@ -2,7 +2,7 @@ import { ArchetypeSqlPlan, PartitionKeyEncoding } from "./archetype-sql.mjs";
 import { ArchetypeQuery } from "@gscdump/contracts/archetypes";
 import { Result } from "gscdump/result";
 /** Configuration for an R2 SQL client. */
-interface R2SqlClientConfig {
+export interface R2SqlClientConfig {
   /** Cloudflare account id. */
   accountId: string;
   /** R2 bucket backing the Iceberg catalog — R2 SQL addresses the catalog by bucket. */
@@ -33,21 +33,21 @@ interface R2SqlClientConfig {
   partitionSiteId?: (siteId: string) => string | number;
 }
 /** A row as returned by R2 SQL — flat dimension + metric values. */
-type R2SqlRow = Record<string, string | number | null>;
+export type R2SqlRow = Record<string, string | number | null>;
 /** Result of an R2 SQL query. */
-interface R2SqlResult {
+export 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 {
+export declare class R2SqlError extends Error {
   readonly status?: number | undefined;
   name: string;
   constructor(message: string, status?: number | undefined);
 }
-declare class R2SqlTimeoutError extends Error {
+export declare class R2SqlTimeoutError extends Error {
   name: string;
   constructor(timeoutMs: number);
 }
@@ -62,15 +62,15 @@ declare class R2SqlTimeoutError extends Error {
  * the client malformed params (`escapeSqlValue` / `inlineParams`) — are NOT
  * modelled here; they keep throwing `R2SqlError` synchronously.
  */
-type R2SqlQueryError = R2SqlError | R2SqlTimeoutError;
+export type R2SqlQueryError = R2SqlError | R2SqlTimeoutError;
 /**
  * Inline a plan's `?`-bound params into its SQL, in order. R2 SQL accepts only
  * a literal query string. Quote-aware so a `?` inside a string literal is not
  * mistaken for a placeholder.
  */
-declare function inlineParams(sql: string, params: readonly unknown[]): string;
+export declare function inlineParams(sql: string, params: readonly unknown[]): string;
 /** A configured R2 SQL client. */
-interface R2SqlClient {
+export interface R2SqlClient {
   /** Run a raw SQL string (table reference already resolved). */
   query: (sql: string) => Promise<R2SqlResult>;
   /**
@@ -91,5 +91,4 @@ interface R2SqlClient {
  * 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;
-export { R2SqlClient, R2SqlClientConfig, R2SqlError, R2SqlQueryError, R2SqlResult, R2SqlRow, R2SqlTimeoutError, createR2SqlClient, inlineParams };
+export declare function createR2SqlClient(config: R2SqlClientConfig): R2SqlClient;

package/dist/server-tail/r2-sql-transport.d.mts

@@ -1,6 +1,6 @@
-type R2SqlTransportRow = Record<string, unknown>;
-type R2SqlTransportMetrics = Record<string, number | undefined>;
-type R2SqlTransportResult = {
+export type R2SqlTransportRow = Record<string, unknown>;
+export type R2SqlTransportMetrics = Record<string, number | undefined>;
+export type R2SqlTransportResult = {
   _tag: 'ok';
   rows: R2SqlTransportRow[];
   metrics: R2SqlTransportMetrics | null;
@@ -17,7 +17,7 @@ type R2SqlTransportResult = {
   body?: string;
   retryAfterMs?: number;
 };
-interface R2SqlTransportConfig {
+export interface R2SqlTransportConfig {
   accountId: string;
   bucket: string;
   token: string;
@@ -27,9 +27,8 @@ interface R2SqlTransportConfig {
   userAgent?: string;
   now?: () => number;
 }
-interface R2SqlTransport {
+export interface R2SqlTransport {
   endpoint: string;
   query: (sql: string) => Promise<R2SqlTransportResult>;
 }
-declare function createR2SqlTransport(config: R2SqlTransportConfig): R2SqlTransport;
-export { R2SqlTransport, R2SqlTransportConfig, R2SqlTransportMetrics, R2SqlTransportResult, R2SqlTransportRow, createR2SqlTransport };
+export declare function createR2SqlTransport(config: R2SqlTransportConfig): R2SqlTransport;

package/dist/server-tail/r2-sql-transport.mjs

@@ -4,8 +4,25 @@ const MAX_RETRY_AFTER_MS = 6e4;
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function parseEnvelope(value) {
-	return value && typeof value === "object" ? value : null;
+	if (!isRecord(value) || typeof value.success !== "boolean") return null;
+	if (!value.success) {
+		if (value.errors !== void 0 && (!Array.isArray(value.errors) || !value.errors.every((error) => isRecord(error) && (error.message === void 0 || typeof error.message === "string")))) return null;
+		return value;
+	}
+	const result = value.result;
+	if (!isRecord(result)) return null;
+	if (result.rows !== void 0) {
+		if (!Array.isArray(result.rows) || !result.rows.every(isRecord)) return null;
+	} else {
+		const columns = result.columns;
+		const data = result.data;
+		if (!Array.isArray(columns) || !columns.every((column) => typeof column === "string") || !Array.isArray(data) || !data.every((tuple) => Array.isArray(tuple) && tuple.length === columns.length)) return null;
+	}
+	return value;
 }
 function normalizeRows(result) {
 	if (Array.isArray(result?.rows)) return result.rows;
@@ -70,12 +87,18 @@ function createR2SqlTransport(config) {
 					_tag: "error",
 					error
 				}));
-				if (bodyResult._tag === "error") return {
-					_tag: "error",
-					kind: "network",
-					message: `R2 SQL response read failed: ${errorMessage(bodyResult.error)}`,
-					status: response.status
-				};
+				if (bodyResult._tag === "error") {
+					if (controller.signal.aborted || bodyResult.error?.name === "AbortError") return {
+						_tag: "timeout",
+						timeoutMs
+					};
+					return {
+						_tag: "error",
+						kind: "network",
+						message: `R2 SQL response read failed: ${errorMessage(bodyResult.error)}`,
+						status: response.status
+					};
+				}
 				const retryAfter = retryAfterMs(response, now);
 				return {
 					_tag: "error",
@@ -93,12 +116,18 @@ function createR2SqlTransport(config) {
 				_tag: "error",
 				error
 			}));
-			if (envelopeResult._tag === "error") return {
-				_tag: "error",
-				kind: "invalid_response",
-				message: `R2 SQL returned invalid JSON: ${errorMessage(envelopeResult.error)}`,
-				status: response.status
-			};
+			if (envelopeResult._tag === "error") {
+				if (controller.signal.aborted || envelopeResult.error?.name === "AbortError") return {
+					_tag: "timeout",
+					timeoutMs
+				};
+				return {
+					_tag: "error",
+					kind: "invalid_response",
+					message: `R2 SQL returned invalid JSON: ${errorMessage(envelopeResult.error)}`,
+					status: response.status
+				};
+			}
 			const envelope = parseEnvelope(envelopeResult.value);
 			if (!envelope) return {
 				_tag: "error",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cloudflare",
   "type": "module",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Cloudflare Workers helpers for server-tail queries and in-flight request deduplication.",
   "author": {
     "name": "Harlan Wilton",
@@ -39,20 +39,24 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@gscdump/contracts": "^3.5.0",
-    "@gscdump/engine": "^3.5.0",
-    "gscdump": "^3.5.0"
+    "@gscdump/contracts": "^3.6.0",
+    "@gscdump/engine": "^3.6.0",
+    "gscdump": "^3.6.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",
-    "@cloudflare/workers-types": "^5.20260831.1",
-    "typescript": "^7.0.2",
-    "wrangler": "^4.127.1"
+    "@cloudflare/workers-types": "^5.20260910.1",
+    "@vitest/browser-playwright": "^4.1.11",
+    "@vitest/ui": "^4.1.11",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.11",
+    "wrangler": "^4.130.0"
   },
   "scripts": {
     "build": "obuild",
     "dev": "obuild --stub",
     "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
     "test:workers": "GSCDUMP_E2E=1 vitest --run --config vitest.workers.config.ts"
   }
 }