lopata 0.19.2 → 0.20.0

package/dist/types/bindings/analytics-engine-sql.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Local emulation of the Cloudflare Workers Analytics Engine **SQL API**.
+ *
+ * Cloudflare has no Worker binding for *reading* Analytics Engine data — you
+ * POST a ClickHouse-flavoured SQL string to
+ *   https://api.cloudflare.com/client/v4/accounts/<acc>/analytics_engine/sql
+ * with `Authorization: Bearer <token>`. Lopata intercepts that fetch (see
+ * `plugin.ts`) and serves it from the local `analytics_engine` SQLite table so
+ * the *same* worker code runs locally and in production unchanged.
+ *
+ * Interception is gated on the token: a missing `Authorization` header or the
+ * sentinel `Bearer local` is served locally; any real bearer token falls
+ * through to the actual Cloudflare API. Drive the token from env (e.g. `local`
+ * in `.dev.vars`, the real secret in prod) to keep one code path. Note that
+ * `writeDataPoint` always writes locally — only the query fetch is gated.
+ *
+ * SPIKE SCOPE — this is a pragmatic subset, not a full ClickHouse engine:
+ *   SELECT <items> FROM <dataset>
+ *   [WHERE <cond>] [GROUP BY <exprs>] [ORDER BY <exprs>] [LIMIT n] [FORMAT f]
+ * with the functions/operators people actually use for dashboards (counts,
+ * sums, time filters, time bucketing). Unsupported constructs throw a clear
+ * error instead of silently returning wrong numbers.
+ *
+ * Key local simplifications (correct *because* there's no sampling locally):
+ *   - `_sample_interval` is always 1, so `sum(_sample_interval)` == `count()`.
+ *   - The `timestamp` column is stored as **ms epoch**; ClickHouse treats it as
+ *     a `DateTime` (seconds). We canonicalise to **seconds** on read so
+ *     `now()` / `INTERVAL` arithmetic lines up, then render `DateTime` *output*
+ *     columns as ClickHouse `YYYY-MM-DD HH:MM:SS` (UTC) strings to match the real
+ *     SQL API — so `new Date(row.bucket)` behaves the same locally as in prod.
+ */
+import type { Database } from 'bun:sqlite';
+/** True for the Cloudflare Analytics Engine SQL API endpoint. */
+export declare function isAnalyticsEngineSqlUrl(url: string): boolean;
+/**
+ * Whether an AE SQL API request should be served from the local store rather
+ * than forwarded to Cloudflare. A missing `Authorization` header or the
+ * `Bearer local` sentinel means local; any real bearer token passes through.
+ */
+export declare function isLocalAnalyticsEngineToken(auth: string | null | undefined): boolean;
+/** A quantile that's collected per-group via `group_concat` and computed in JS. */
+interface QuantileSpec {
+    /** Internal SQLite column holding the comma-joined values for the group. */
+    tempCol: string;
+    /** Output column name. */
+    outputName: string;
+    /** Quantile level in [0, 1]. */
+    level: number;
+    /**
+     * `quantile`/`quantileWeighted` interpolate linearly (ClickHouse default);
+     * the `*Exact*` variants return an actual element (nearest-rank).
+     */
+    interpolate: boolean;
+}
+/**
+ * Post-processing applied in JS when the query uses quantile functions.
+ * `bun:sqlite` has no UDFs and no percentile aggregate, so we collect the
+ * per-group values with `group_concat` and finish the computation here. ORDER BY
+ * / LIMIT then also have to run in JS (they may reference a computed quantile).
+ */
+interface PostProcess {
+    quantiles: QuantileSpec[];
+    orderBy: {
+        name: string;
+        desc: boolean;
+    }[];
+    limit?: number;
+}
+export interface TranslatedQuery {
+    sqlite: string;
+    columns: {
+        name: string;
+        type: string;
+    }[];
+    format: string;
+    /** `SELECT *` — column metadata is derived from the result rows at run time. */
+    hasStar?: boolean;
+    /** Present only when the query uses quantile functions. */
+    postProcess?: PostProcess;
+    /** The query uses LIKE — run it with `PRAGMA case_sensitive_like=ON` (ClickHouse semantics). */
+    caseSensitiveLike?: boolean;
+}
+/** Translate a Cloudflare Analytics Engine SQL string into a SQLite query. */
+export declare function translateAnalyticsEngineSql(sql: string, nowSeconds: number): TranslatedQuery;
+export interface AnalyticsEngineSqlResult {
+    meta: {
+        name: string;
+        type: string;
+    }[];
+    data: Record<string, unknown>[];
+    rows: number;
+    rows_before_limit_at_least: number;
+}
+/** Translate + execute a Cloudflare Analytics Engine SQL query against SQLite. */
+export declare function runAnalyticsEngineSql(db: Database, sql: string, nowMs?: number): AnalyticsEngineSqlResult;
+/**
+ * Run an Analytics Engine SQL string and build a Cloudflare-shaped `Response`
+ * (JSON by default, NDJSON for `FORMAT JSONEachRow`, or a 400 with the error
+ * message). Synchronous so callers can wrap it in their own tracing span.
+ */
+export declare function buildAnalyticsEngineSqlResponse(db: Database, sql: string): Response;
+/**
+ * Handle an intercepted POST to the Analytics Engine SQL API. Returns a
+ * Cloudflare-shaped JSON `Response` (or a 400 with the error message).
+ */
+export declare function handleAnalyticsEngineSqlRequest(db: Database, request: Request): Promise<Response>;
+export {};