@gscdump/cloudflare 1.5.0 → 1.5.1

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

@@ -1,5 +1,6 @@
 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 { R2SqlClient, R2SqlClientConfig, R2SqlError, R2SqlQueryError, R2SqlResult, R2SqlRow, R2SqlTimeoutError, createR2SqlClient, escapeSqlValue, inlineParams } 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 };
+import { R2SqlTransport, R2SqlTransportConfig, R2SqlTransportMetrics, R2SqlTransportResult, R2SqlTransportRow, createR2SqlTransport } from "./r2-sql-transport.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 R2SqlTransport, type R2SqlTransportConfig, type R2SqlTransportMetrics, type R2SqlTransportResult, type R2SqlTransportRow, type ServerTailDispatcher, type ServerTailDispatcherConfig, type ServerTailEngine, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createR2SqlClient, createR2SqlTransport, createServerTailDispatcher, escapeSqlValue, inlineParams, resolveServerTailEngine, resolveServerTailEngineResult };

package/dist/server-tail/index.mjs

@@ -1,5 +1,6 @@
 import { TABLE_PLACEHOLDER, buildArchetypeSql } from "./archetype-sql.mjs";
 import { ServerTailRoutingError, createServerTailDispatcher, resolveServerTailEngine, resolveServerTailEngineResult } from "./dispatcher.mjs";
 import { DuckDbIcebergError, DuckDbIcebergTimeoutError, createDuckDbIcebergExecutor } from "./duckdb-iceberg-executor.mjs";
-import { R2SqlError, R2SqlTimeoutError, createR2SqlClient } from "./r2-sql-client.mjs";
-export { DuckDbIcebergError, DuckDbIcebergTimeoutError, R2SqlError, R2SqlTimeoutError, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createR2SqlClient, createServerTailDispatcher, resolveServerTailEngine, resolveServerTailEngineResult };
+import { createR2SqlTransport } from "./r2-sql-transport.mjs";
+import { R2SqlError, R2SqlTimeoutError, createR2SqlClient, escapeSqlValue, inlineParams } from "./r2-sql-client.mjs";
+export { DuckDbIcebergError, DuckDbIcebergTimeoutError, R2SqlError, R2SqlTimeoutError, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createR2SqlClient, createR2SqlTransport, createServerTailDispatcher, escapeSqlValue, inlineParams, resolveServerTailEngine, resolveServerTailEngineResult };

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

@@ -63,6 +63,18 @@ declare class R2SqlTimeoutError extends Error {
  * modelled here; they keep throwing `R2SqlError` synchronously.
  */
 type R2SqlQueryError = R2SqlError | R2SqlTimeoutError;
+/**
+ * Escape a JS value for inline embedding in R2 SQL. R2 SQL has no bound-param
+ * channel, so `buildArchetypeSql`'s `?` placeholders are substituted here.
+ * Numbers go in bare; strings are single-quote-escaped; null → `NULL`.
+ */
+declare function escapeSqlValue(value: unknown): string;
+/**
+ * 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;
 /** A configured R2 SQL client. */
 interface R2SqlClient {
   /** Run a raw SQL string (table reference already resolved). */
@@ -86,4 +98,4 @@ interface R2SqlClient {
  * production; tests inject `fetchImpl` returning a recorded envelope.
  */
 declare function createR2SqlClient(config: R2SqlClientConfig): R2SqlClient;
-export { R2SqlClient, R2SqlClientConfig, R2SqlError, R2SqlQueryError, R2SqlResult, R2SqlRow, R2SqlTimeoutError, createR2SqlClient };
+export { R2SqlClient, R2SqlClientConfig, R2SqlError, R2SqlQueryError, R2SqlResult, R2SqlRow, R2SqlTimeoutError, createR2SqlClient, escapeSqlValue, inlineParams };

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

@@ -1,4 +1,5 @@
 import { TABLE_PLACEHOLDER, buildArchetypeSql } from "./archetype-sql.mjs";
+import { createR2SqlTransport } from "./r2-sql-transport.mjs";
 import { err, ok, unwrapResult } from "gscdump/result";
 import { SEARCH_TYPE_INT } from "@gscdump/engine/iceberg";
 function r2TableRef(namespace, table) {
@@ -21,8 +22,6 @@ var R2SqlTimeoutError = class extends Error {
 function r2SqlErrorToException(error) {
 	return error;
 }
-const DEFAULT_API_BASE = "https://api.sql.cloudflarestorage.com/api/v1";
-const DEFAULT_TIMEOUT_MS = 25e3;
 const PARTITION_PREDICATE_RE = /\b(site_id|search_type)(\s*=)/g;
 function workaroundPartitionEquality(sql) {
 	return sql.replace(PARTITION_PREDICATE_RE, (_m, col, eq) => `CONCAT(${col}, '')${eq}`);
@@ -63,21 +62,6 @@ function inlineParams(sql, params) {
 	if (paramIndex !== params.length) throw new R2SqlError(`SQL has ${paramIndex} ? placeholders but ${params.length} params supplied`);
 	return out;
 }
-function normalizeRows(result) {
-	if (!result) return [];
-	if (Array.isArray(result.rows)) return result.rows;
-	if (Array.isArray(result.columns) && Array.isArray(result.data)) {
-		const cols = result.columns;
-		return result.data.map((tuple) => {
-			const row = {};
-			cols.forEach((col, idx) => {
-				row[col] = tuple[idx] ?? null;
-			});
-			return row;
-		});
-	}
-	return [];
-}
 function coerceIntSiteId(siteId, mapper) {
 	const mapped = mapper ? mapper(siteId) : siteId;
 	const n = Number(mapped);
@@ -96,43 +80,24 @@ function withEncodedPartitions(query, encoding, siteIdMapper) {
 	};
 }
 function createR2SqlClient(config) {
-	const fetchImpl = config.fetchImpl ?? globalThis.fetch;
-	const apiBase = config.apiBase ?? DEFAULT_API_BASE;
-	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const timeoutMs = config.timeoutMs ?? 25e3;
 	const partitionKeyEncoding = config.partitionKeyEncoding ?? "int";
-	const endpoint = `${apiBase}/accounts/${config.accountId}/r2-sql/query/${config.bucket}`;
+	const transport = createR2SqlTransport({
+		accountId: config.accountId,
+		bucket: config.bucket,
+		token: config.token,
+		apiBase: config.apiBase,
+		fetchImpl: config.fetchImpl,
+		timeoutMs
+	});
 	async function queryResult(sql) {
-		const started = Date.now();
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(new R2SqlTimeoutError(timeoutMs)), timeoutMs);
-		let response;
-		try {
-			response = await fetchImpl(endpoint, {
-				method: "POST",
-				headers: {
-					"authorization": `Bearer ${config.token}`,
-					"content-type": "application/json",
-					"user-agent": "gscdump-cloudflare-r2sql/1.0"
-				},
-				body: JSON.stringify({ query: sql }),
-				signal: controller.signal
-			});
-		} catch (error) {
-			if (error instanceof R2SqlTimeoutError || error?.name === "AbortError") return err(new R2SqlTimeoutError(timeoutMs));
-			return err(new R2SqlError(`R2 SQL request failed: ${error.message}`));
-		} finally {
-			clearTimeout(timer);
-		}
-		if (!response.ok) {
-			const text = await response.text().catch(() => "");
-			return err(new R2SqlError(`R2 SQL HTTP ${response.status}: ${text}`, response.status));
-		}
-		const envelope = await response.json();
-		if (!envelope.success) return err(new R2SqlError(`R2 SQL query rejected: ${envelope.errors?.map((e) => e.message).join("; ") ?? "unknown R2 SQL error"}`));
+		const result = await transport.query(sql);
+		if (result._tag === "timeout") return err(new R2SqlTimeoutError(result.timeoutMs));
+		if (result._tag === "error") return err(new R2SqlError(result.message, result.status));
 		return ok({
-			rows: normalizeRows(envelope.result),
+			rows: result.rows,
 			sql,
-			queryMs: Date.now() - started
+			queryMs: result.queryMs
 		});
 	}
 	async function query(sql) {

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

@@ -0,0 +1,35 @@
+type R2SqlTransportRow = Record<string, unknown>;
+type R2SqlTransportMetrics = Record<string, number | undefined>;
+type R2SqlTransportResult = {
+  _tag: 'ok';
+  rows: R2SqlTransportRow[];
+  metrics: R2SqlTransportMetrics | null;
+  sql: string;
+  queryMs: number;
+} | {
+  _tag: 'timeout';
+  timeoutMs: number;
+} | {
+  _tag: 'error';
+  kind: 'network' | 'http' | 'rejected' | 'invalid_response';
+  message: string;
+  status?: number;
+  body?: string;
+  retryAfterMs?: number;
+};
+interface R2SqlTransportConfig {
+  accountId: string;
+  bucket: string;
+  token: string;
+  apiBase?: string;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  userAgent?: string;
+  now?: () => number;
+}
+interface R2SqlTransport {
+  endpoint: string;
+  query: (sql: string) => Promise<R2SqlTransportResult>;
+}
+declare function createR2SqlTransport(config: R2SqlTransportConfig): R2SqlTransport;
+export { R2SqlTransport, R2SqlTransportConfig, R2SqlTransportMetrics, R2SqlTransportResult, R2SqlTransportRow, createR2SqlTransport };

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

@@ -0,0 +1,132 @@
+const DEFAULT_API_BASE = "https://api.sql.cloudflarestorage.com/api/v1";
+const DEFAULT_TIMEOUT_MS = 25e3;
+const MAX_RETRY_AFTER_MS = 6e4;
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function parseEnvelope(value) {
+	return value && typeof value === "object" ? value : null;
+}
+function normalizeRows(result) {
+	if (Array.isArray(result?.rows)) return result.rows;
+	if (!Array.isArray(result?.columns) || !Array.isArray(result.data)) return [];
+	return result.data.map((tuple) => {
+		const row = {};
+		for (let index = 0; index < result.columns.length; index++) row[result.columns[index]] = tuple[index] ?? null;
+		return row;
+	});
+}
+function retryAfterMs(response, now) {
+	const raw = response.headers?.get?.("retry-after");
+	if (!raw) return void 0;
+	const seconds = Number(raw.trim());
+	const value = Number.isFinite(seconds) ? seconds * 1e3 : Date.parse(raw) - now();
+	if (!Number.isFinite(value) || value <= 0) return void 0;
+	return Math.min(value, MAX_RETRY_AFTER_MS);
+}
+function createR2SqlTransport(config) {
+	const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const now = config.now ?? Date.now;
+	const endpoint = `${(config.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "")}/accounts/${config.accountId}/r2-sql/query/${config.bucket}`;
+	async function query(sql) {
+		const startedAt = now();
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const responseResult = await fetchImpl(endpoint, {
+				method: "POST",
+				headers: {
+					"authorization": `Bearer ${config.token}`,
+					"content-type": "application/json",
+					"user-agent": config.userAgent ?? "gscdump-cloudflare-r2sql/1.0"
+				},
+				body: JSON.stringify({ query: sql }),
+				signal: controller.signal
+			}).then((response) => ({
+				_tag: "ok",
+				response
+			}), (error) => ({
+				_tag: "error",
+				error
+			}));
+			if (responseResult._tag === "error") {
+				if (controller.signal.aborted || responseResult.error?.name === "AbortError") return {
+					_tag: "timeout",
+					timeoutMs
+				};
+				return {
+					_tag: "error",
+					kind: "network",
+					message: `R2 SQL request failed: ${errorMessage(responseResult.error)}`
+				};
+			}
+			const { response } = responseResult;
+			if (!response.ok) {
+				const bodyResult = await response.text().then((body) => ({
+					_tag: "ok",
+					body
+				}), (error) => ({
+					_tag: "error",
+					error
+				}));
+				if (bodyResult._tag === "error") 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",
+					kind: "http",
+					message: `R2 SQL HTTP ${response.status}: ${bodyResult.body}`,
+					status: response.status,
+					body: bodyResult.body,
+					...retryAfter !== void 0 ? { retryAfterMs: retryAfter } : {}
+				};
+			}
+			const envelopeResult = await response.json().then((value) => ({
+				_tag: "ok",
+				value
+			}), (error) => ({
+				_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
+			};
+			const envelope = parseEnvelope(envelopeResult.value);
+			if (!envelope) return {
+				_tag: "error",
+				kind: "invalid_response",
+				message: "R2 SQL returned an invalid response",
+				status: response.status
+			};
+			if (!envelope.success) return {
+				_tag: "error",
+				kind: "rejected",
+				message: `R2 SQL query rejected: ${envelope.errors?.map((error) => error.message).filter(Boolean).join("; ") || "unknown R2 SQL error"}`,
+				status: response.status,
+				body: JSON.stringify(envelope)
+			};
+			return {
+				_tag: "ok",
+				rows: normalizeRows(envelope.result),
+				metrics: envelope.result?.metrics ?? null,
+				sql,
+				queryMs: now() - startedAt
+			};
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	return {
+		endpoint,
+		query
+	};
+}
+export { createR2SqlTransport };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cloudflare",
   "type": "module",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Cloudflare-Workers-flavored helpers for the gscdump analytics stack: AnalyticsEnv binding contract, R2 SigV4 presigner, DuckDB Workers shims, engine factory.",
   "author": {
     "name": "Harlan Wilton",
@@ -47,10 +47,10 @@
   },
   "dependencies": {
     "@uwdata/flechette": "^2.5.0",
-    "@gscdump/contracts": "^1.5.0",
-    "@gscdump/engine": "^1.5.0",
-    "@gscdump/engine-sqlite": "^1.5.0",
-    "gscdump": "^1.5.0"
+    "@gscdump/contracts": "^1.5.1",
+    "@gscdump/engine": "^1.5.1",
+    "gscdump": "^1.5.1",
+    "@gscdump/engine-sqlite": "^1.5.1"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.18.8",