@autter/otlp-ingester 0.1.0

package/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY package.json package-lock.json* ./
+COPY packages/otlp-ingester/package.json packages/otlp-ingester/
+RUN npm install --workspace @autter/otlp-ingester
+COPY packages/otlp-ingester packages/otlp-ingester
+RUN npm run build -w @autter/otlp-ingester
+
+FROM node:22-alpine
+ENV NODE_ENV=production
+WORKDIR /app
+COPY package.json package-lock.json* ./
+COPY packages/otlp-ingester/package.json packages/otlp-ingester/
+RUN npm install --workspace @autter/otlp-ingester --omit=dev && npm cache clean --force
+COPY --from=build /app/packages/otlp-ingester/dist packages/otlp-ingester/dist
+USER node
+EXPOSE 4318
+CMD ["node", "packages/otlp-ingester/dist/index.js"]

package/README.md

@@ -0,0 +1,114 @@
+# @autter/otlp-ingester
+
+Self-hostable ingest service for Autter Runtime. Receives OTLP/HTTP (JSON)
+traces and metrics plus compact browser error payloads, normalises them into
+one per-repo signal model, fingerprints errors, and writes ClickHouse.
+
+## Endpoints
+
+| Route | Payload | Purpose |
+| --- | --- | --- |
+| `POST /v1/traces` | OTLP/JSON `ExportTraceServiceRequest` | Error spans → occurrences; all spans → `runtime_spans`; server spans → usage rollups |
+| `POST /v1/metrics` | OTLP/JSON `ExportMetricsServiceRequest` | HTTP-server duration histograms → usage rollups |
+| `POST /v1/browser` | Browser payload `version: 1` | Errors/rejections → occurrences; session pings → rollups |
+| `GET /healthz` | — | Liveness + ClickHouse reachability |
+
+Auth on every ingest route: `Authorization: Bearer <ingest key>`,
+`x-autter-key`, or `?key=` (query param — for sendBeacon, which cannot set
+headers). OTLP endpoints accept **both protobuf and JSON** (`content-type:
+application/x-protobuf` or `application/json`), gzip/deflate bodies
+included — so any OpenTelemetry SDK (Go, Rust, Python, Java, .NET, JS)
+works with its default exporter settings.
+
+### Key scopes
+
+| Scope | Prefix convention | Valid on | Extras |
+| --- | --- | --- | --- |
+| `server` (default) | `autter_rt_…` (secret) | all endpoints | 300 req/min |
+| `client` | `autter_rtc_…` (publishable, safe in frontend bundles) | `/v1/browser` only | origin allow-list, 120 req/min |
+
+`/v1/browser` answers CORS preflights permissively; real enforcement (key +
+origin allow-list) happens on the POST. Cross-origin browsers send
+`text/plain` bodies (CORS-safelisted, no preflight per beacon) which the
+route parses as JSON.
+
+```json
+AUTTER_INGEST_KEYS='[
+  {"key":"autter_rt_…","orgId":"org1","repositoryId":"repo1"},
+  {"key":"autter_rtc_…","orgId":"org1","repositoryId":"repo1",
+   "scope":"client","allowedOrigins":["https://app.example.com"]}
+]'
+```
+
+The validator webhook may return the same extra fields:
+`{ orgId, repositoryId, scope?, allowedOrigins? }`.
+
+## Configuration
+
+| Env | Default | Description |
+| --- | --- | --- |
+| `PORT` | `4318` | Listen port (OTLP/HTTP convention) |
+| `CLICKHOUSE_URL` | — | e.g. `http://localhost:8123`; unset = ingest returns 503 |
+| `CLICKHOUSE_USER` / `CLICKHOUSE_PASSWORD` | `default` / empty | |
+| `CLICKHOUSE_DATABASE` | `autter_runtime` | Created automatically |
+| `AUTTER_INGEST_KEYS` | — | JSON: `[{"key":"...","orgId":"...","repositoryId":"..."}]` |
+| `AUTTER_KEY_VALIDATOR_URL` | — | Webhook: `POST {key}` → `{orgId, repositoryId}` (60 s cache) |
+| `AUTTER_KEY_VALIDATOR_TOKEN` | — | Bearer token sent to the validator |
+| `AUTTER_SINK_URL` | — | Webhook receiving fingerprinted occurrences for issue grouping |
+| `AUTTER_SINK_TOKEN` | — | Bearer token sent to the sink |
+| `MAX_BODY_BYTES` | `1048576` | Request body cap |
+| `RATE_LIMIT_PER_MINUTE` | `300` | Per-key fixed window (server keys) |
+| `CLIENT_RATE_LIMIT_PER_MINUTE` | `120` | Per-key fixed window (client keys) |
+| `OCCURRENCE_TTL_DAYS` / `SPAN_TTL_DAYS` / `METRICS_TTL_DAYS` | `14` / `7` / `90` | ClickHouse TTLs (applied at table creation) |
+
+## Schema migrations
+
+The ingester owns the ClickHouse schema and updates it **automatically on
+boot** — deploying a new ingester version is the schema deployment; there
+is no separate migration step to run.
+
+How it works: the baseline `CREATE TABLE IF NOT EXISTS` statements
+provision fresh databases; versioned migrations in `src/migrations.ts`
+alter existing ones. Applied migration ids are recorded in
+`<db>.schema_migrations`, so each runs exactly once per database, and every
+statement is written to be idempotent (`ADD COLUMN IF NOT EXISTS`, …) so
+concurrent replicas booting during a rolling deploy race harmlessly.
+
+To change the schema (e.g. add a column):
+
+1. Append a migration to `MIGRATIONS` in `src/migrations.ts` — new columns
+   need a `DEFAULT` so still-running old replicas can keep inserting.
+2. Update the baseline in `src/clickhouse.ts` `schemaStatements()` so fresh
+   databases come up with the final shape.
+3. Ship it — the next deploy applies it everywhere; the log line
+   `clickhouse migration applied: <id>` confirms.
+
+Never edit or reorder a shipped migration; append a corrective one.
+
+## Local development
+
+```bash
+docker compose up clickhouse   # from the repo root
+AUTTER_INGEST_KEYS='[{"key":"dev-key","orgId":"org1","repositoryId":"repo1"}]' \
+CLICKHOUSE_URL=http://localhost:8123 CLICKHOUSE_PASSWORD=dev \
+npm run dev
+```
+
+Send a test error span:
+
+```bash
+curl -s http://localhost:4318/v1/traces \
+  -H 'authorization: Bearer dev-key' -H 'content-type: application/json' \
+  -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"payments-api"}},{"key":"service.version","value":{"stringValue":"e4a218f"}}]},"scopeSpans":[{"spans":[{"traceId":"0123456789abcdef0123456789abcdef","spanId":"0123456789abcdef","name":"POST /orders/:id","kind":2,"startTimeUnixNano":"1753100000000000000","endTimeUnixNano":"1753100000120000000","status":{"code":2,"message":"boom"},"attributes":[{"key":"http.route","value":{"stringValue":"/orders/:id"}},{"key":"http.response.status_code","value":{"intValue":500}}],"events":[{"name":"exception","timeUnixNano":"1753100000100000000","attributes":[{"key":"exception.type","value":{"stringValue":"TypeError"}},{"key":"exception.message","value":{"stringValue":"cannot read x"}},{"key":"exception.stacktrace","value":{"stringValue":"TypeError: cannot read x\n    at handler (/app/dist/orders.js:12:3)"}}]}]}]}]}]}'
+```
+
+## Pointing OpenTelemetry at it
+
+```ts
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; // http/json
+
+new OTLPTraceExporter({
+  url: "https://otlp.your-domain.dev/v1/traces",
+  headers: { authorization: "Bearer <ingest key>" },
+});
+```

package/dist/auth.d.ts

@@ -0,0 +1,18 @@
+import type { Request } from "express";
+import type { IngesterConfig } from "./config.js";
+import type { IngestContext } from "./types.js";
+export declare class KeyResolver {
+    private readonly config;
+    private readonly staticKeys;
+    private readonly cache;
+    constructor(config: IngesterConfig);
+    extractKey(req: Request): string | null;
+    resolve(key: string): Promise<IngestContext | null>;
+}
+/** Fixed-window per-key rate limiter (single-node; Redis backing is M1). */
+export declare class RateLimiter {
+    private readonly limitPerMinute;
+    private windows;
+    constructor(limitPerMinute: number);
+    allow(key: string): boolean;
+}

package/dist/auth.js

@@ -0,0 +1,103 @@
+const VALIDATOR_CACHE_TTL_MS = 60_000;
+export class KeyResolver {
+    config;
+    staticKeys = new Map();
+    cache = new Map();
+    constructor(config) {
+        this.config = config;
+        for (const entry of config.ingestKeys) {
+            this.staticKeys.set(entry.key, {
+                orgId: entry.orgId,
+                repositoryId: entry.repositoryId,
+                scope: entry.scope ?? "server",
+                allowedOrigins: entry.allowedOrigins ?? [],
+            });
+        }
+    }
+    extractKey(req) {
+        const header = req.headers.authorization;
+        if (header?.toLowerCase().startsWith("bearer ")) {
+            return header.slice(7).trim() || null;
+        }
+        const alt = req.headers["x-autter-key"];
+        if (typeof alt === "string" && alt.trim())
+            return alt.trim();
+        // Query param — the only channel available to navigator.sendBeacon
+        // (it cannot set headers). Intended for publishable client keys.
+        const q = req.query.key;
+        if (typeof q === "string" && q.trim())
+            return q.trim();
+        return null;
+    }
+    async resolve(key) {
+        const staticCtx = this.staticKeys.get(key);
+        if (staticCtx)
+            return staticCtx;
+        if (!this.config.keyValidatorUrl)
+            return null;
+        const cached = this.cache.get(key);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.ctx;
+        let ctx = null;
+        try {
+            const response = await fetch(this.config.keyValidatorUrl, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(this.config.keyValidatorToken
+                        ? { authorization: `Bearer ${this.config.keyValidatorToken}` }
+                        : {}),
+                },
+                body: JSON.stringify({ key }),
+                signal: AbortSignal.timeout(5000),
+            });
+            if (response.ok) {
+                const body = (await response.json());
+                if (body.orgId && body.repositoryId) {
+                    ctx = {
+                        orgId: body.orgId,
+                        repositoryId: body.repositoryId,
+                        scope: body.scope ?? "server",
+                        allowedOrigins: body.allowedOrigins ?? [],
+                    };
+                }
+            }
+        }
+        catch {
+            // Validator unreachable: fail closed for unknown keys, but reuse a
+            // stale cache entry if we have one so transient validator outages
+            // don't drop telemetry from known-good keys.
+            if (cached)
+                return cached.ctx;
+            return null;
+        }
+        this.cache.set(key, { ctx, expiresAt: Date.now() + VALIDATOR_CACHE_TTL_MS });
+        if (this.cache.size > 10_000) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+        return ctx;
+    }
+}
+/** Fixed-window per-key rate limiter (single-node; Redis backing is M1). */
+export class RateLimiter {
+    limitPerMinute;
+    windows = new Map();
+    constructor(limitPerMinute) {
+        this.limitPerMinute = limitPerMinute;
+    }
+    allow(key) {
+        const now = Date.now();
+        const windowStart = Math.floor(now / 60_000) * 60_000;
+        const entry = this.windows.get(key);
+        if (!entry || entry.windowStart !== windowStart) {
+            this.windows.set(key, { windowStart, count: 1 });
+            if (this.windows.size > 50_000)
+                this.windows.clear();
+            return true;
+        }
+        entry.count += 1;
+        return entry.count <= this.limitPerMinute;
+    }
+}

package/dist/clickhouse.d.ts

@@ -0,0 +1,27 @@
+import type { IngesterConfig } from "./config.js";
+import { type Migration } from "./migrations.js";
+import type { IngestContext, RuntimeMetricPoint, RuntimeOccurrence, RuntimeSpanRow } from "./types.js";
+export declare class ClickHouseStore {
+    private readonly config;
+    private client;
+    private ensurePromise;
+    constructor(config: IngesterConfig);
+    get configured(): boolean;
+    private getClient;
+    private table;
+    private schemaStatements;
+    /**
+     * Baseline `CREATE ... IF NOT EXISTS` for fresh databases, then the
+     * versioned migrations from migrations.ts for existing ones — the
+     * CREATEs no-op on tables that already exist, so schema changes only
+     * reach deployed databases through migrations. Runs once per process
+     * (boot + lazily before first ingest); a failure clears the memo so the
+     * next request retries.
+     */
+    ensureSchema(migrations?: Migration[]): Promise<void>;
+    ping(): Promise<boolean>;
+    insertOccurrences(ctx: IngestContext, occurrences: RuntimeOccurrence[]): Promise<void>;
+    insertSpans(ctx: IngestContext, spans: RuntimeSpanRow[]): Promise<void>;
+    insertMetricPoints(ctx: IngestContext, points: RuntimeMetricPoint[]): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/clickhouse.js

@@ -0,0 +1,261 @@
+import { createClient, } from "@clickhouse/client";
+import { MIGRATIONS, migrationsTableDDL, } from "./migrations.js";
+/**
+ * ClickHouse persistence. The schema is idempotent and applied lazily once
+ * per process. Every row is keyed by (org_id, repository_id) — tenant
+ * isolation is enforced by always writing the authenticated context, never
+ * anything from the payload.
+ */
+const INSERT_SETTINGS = {
+    date_time_input_format: "best_effort",
+    async_insert: 1,
+    wait_for_async_insert: 1,
+};
+export class ClickHouseStore {
+    config;
+    client = null;
+    ensurePromise = null;
+    constructor(config) {
+        this.config = config;
+    }
+    get configured() {
+        return Boolean(this.config.clickhouseUrl);
+    }
+    getClient() {
+        if (!this.config.clickhouseUrl) {
+            throw new Error("CLICKHOUSE_URL is not configured");
+        }
+        if (!this.client) {
+            this.client = createClient({
+                url: this.config.clickhouseUrl,
+                username: this.config.clickhouseUser,
+                password: this.config.clickhousePassword,
+                application: "autter-otlp-ingester",
+                clickhouse_settings: { date_time_input_format: "best_effort" },
+            });
+        }
+        return this.client;
+    }
+    table(name) {
+        return `${this.config.clickhouseDatabase}.${name}`;
+    }
+    schemaStatements() {
+        const db = this.config.clickhouseDatabase;
+        const { occurrenceTtlDays, spanTtlDays, metricsTtlDays } = this.config;
+        return [
+            `CREATE DATABASE IF NOT EXISTS ${db}`,
+            `CREATE TABLE IF NOT EXISTS ${db}.runtime_error_occurrences (
+				org_id             String,
+				repository_id      String,
+				occurrence_id      String,
+				fingerprint        String,
+				source             LowCardinality(String),
+				severity           LowCardinality(String) DEFAULT 'error',
+				service            LowCardinality(String),
+				environment        LowCardinality(String),
+				release            String DEFAULT '',
+				error_type         String,
+				message            String CODEC(ZSTD(1)),
+				message_normalized String DEFAULT '',
+				stack              String DEFAULT '' CODEC(ZSTD(3)),
+				top_frames         Array(String) DEFAULT [],
+				first_frame        String DEFAULT '',
+				route              String DEFAULT '',
+				route_normalized   String DEFAULT '',
+				method             LowCardinality(String) DEFAULT '',
+				status_code        UInt16 DEFAULT 0,
+				trace_id           String DEFAULT '',
+				session_id         String DEFAULT '',
+				attributes         String DEFAULT '{}' CODEC(ZSTD(1)),
+				occurred_at        DateTime64(3, 'UTC'),
+				ingested_at        DateTime64(3, 'UTC') DEFAULT now64(3)
+			)
+			ENGINE = MergeTree
+			PARTITION BY toDate(occurred_at)
+			ORDER BY (org_id, repository_id, fingerprint, occurred_at)
+			TTL toDateTime(occurred_at) + INTERVAL ${occurrenceTtlDays} DAY`,
+            `CREATE TABLE IF NOT EXISTS ${db}.runtime_spans (
+				org_id           String,
+				repository_id    String,
+				service          LowCardinality(String),
+				environment      LowCardinality(String),
+				release          String DEFAULT '',
+				trace_id         String,
+				span_id          String,
+				parent_span_id   String DEFAULT '',
+				name             String,
+				kind             LowCardinality(String) DEFAULT 'internal',
+				status           LowCardinality(String) DEFAULT 'ok',
+				route            String DEFAULT '',
+				status_code      UInt16 DEFAULT 0,
+				duration_ms      Float64,
+				attributes       String DEFAULT '{}' CODEC(ZSTD(1)),
+				started_at       DateTime64(3, 'UTC')
+			)
+			ENGINE = MergeTree
+			PARTITION BY toDate(started_at)
+			ORDER BY (org_id, repository_id, trace_id, started_at)
+			TTL toDateTime(started_at) + INTERVAL ${spanTtlDays} DAY`,
+            `CREATE TABLE IF NOT EXISTS ${db}.runtime_metrics_1m (
+				org_id           String,
+				repository_id    String,
+				service          LowCardinality(String),
+				environment      LowCardinality(String),
+				release          String DEFAULT '',
+				route            String DEFAULT '',
+				bucket_at        DateTime('UTC'),
+				request_count    UInt64,
+				error_count      UInt64,
+				duration_sum_ms  Float64,
+				session_count    UInt64 DEFAULT 0
+			)
+			ENGINE = SummingMergeTree((request_count, error_count, duration_sum_ms, session_count))
+			PARTITION BY toYYYYMM(bucket_at)
+			ORDER BY (org_id, repository_id, service, environment, release, route, bucket_at)
+			TTL bucket_at + INTERVAL ${metricsTtlDays} DAY`,
+        ];
+    }
+    /**
+     * Baseline `CREATE ... IF NOT EXISTS` for fresh databases, then the
+     * versioned migrations from migrations.ts for existing ones — the
+     * CREATEs no-op on tables that already exist, so schema changes only
+     * reach deployed databases through migrations. Runs once per process
+     * (boot + lazily before first ingest); a failure clears the memo so the
+     * next request retries.
+     */
+    ensureSchema(migrations = MIGRATIONS) {
+        if (this.ensurePromise)
+            return this.ensurePromise;
+        this.ensurePromise = (async () => {
+            const client = this.getClient();
+            const db = this.config.clickhouseDatabase;
+            for (const statement of this.schemaStatements()) {
+                await client.command({ query: statement });
+            }
+            await client.command({ query: migrationsTableDDL(db) });
+            const rows = await client.query({
+                query: `SELECT DISTINCT id FROM ${db}.schema_migrations`,
+                format: "JSONEachRow",
+            });
+            const applied = new Set((await rows.json()).map((row) => row.id));
+            for (const migration of migrations) {
+                if (applied.has(migration.id))
+                    continue;
+                for (const statement of migration.statements) {
+                    await client.command({
+                        query: statement.replaceAll("{db}", db),
+                    });
+                }
+                await client.insert({
+                    table: `${db}.schema_migrations`,
+                    format: "JSONEachRow",
+                    values: [{ id: migration.id }],
+                });
+                console.log(`clickhouse migration applied: ${migration.id}`);
+            }
+        })().catch((err) => {
+            this.ensurePromise = null;
+            throw err;
+        });
+        return this.ensurePromise;
+    }
+    async ping() {
+        if (!this.configured)
+            return false;
+        const result = await this.getClient().ping();
+        return result.success;
+    }
+    async insertOccurrences(ctx, occurrences) {
+        if (occurrences.length === 0 || !this.configured)
+            return;
+        await this.ensureSchema();
+        await this.getClient().insert({
+            table: this.table("runtime_error_occurrences"),
+            format: "JSONEachRow",
+            clickhouse_settings: INSERT_SETTINGS,
+            values: occurrences.map((o) => ({
+                org_id: ctx.orgId,
+                repository_id: ctx.repositoryId,
+                occurrence_id: o.occurrenceId,
+                fingerprint: o.fingerprint,
+                source: o.source,
+                severity: o.severity,
+                service: o.service,
+                environment: o.environment,
+                release: o.release ?? "",
+                error_type: o.errorType,
+                message: o.message.slice(0, 4000),
+                message_normalized: o.messageNormalized,
+                stack: (o.stack ?? "").slice(0, 32000),
+                top_frames: o.topFrames,
+                first_frame: o.firstFrame,
+                route: o.route ?? "",
+                route_normalized: o.routeNormalized,
+                method: o.method ?? "",
+                status_code: o.statusCode ?? 0,
+                trace_id: o.traceId ?? "",
+                session_id: o.sessionId ?? "",
+                attributes: JSON.stringify(o.attributes ?? {}),
+                occurred_at: o.occurredAt.toISOString(),
+            })),
+        });
+    }
+    async insertSpans(ctx, spans) {
+        if (spans.length === 0 || !this.configured)
+            return;
+        await this.ensureSchema();
+        await this.getClient().insert({
+            table: this.table("runtime_spans"),
+            format: "JSONEachRow",
+            clickhouse_settings: INSERT_SETTINGS,
+            values: spans.map((s) => ({
+                org_id: ctx.orgId,
+                repository_id: ctx.repositoryId,
+                service: s.service,
+                environment: s.environment,
+                release: s.release ?? "",
+                trace_id: s.traceId,
+                span_id: s.spanId,
+                parent_span_id: s.parentSpanId ?? "",
+                name: s.name.slice(0, 500),
+                kind: s.kind,
+                status: s.status,
+                route: s.route ?? "",
+                status_code: s.statusCode ?? 0,
+                duration_ms: s.durationMs,
+                attributes: JSON.stringify(s.attributes ?? {}),
+                started_at: s.startedAt.toISOString(),
+            })),
+        });
+    }
+    async insertMetricPoints(ctx, points) {
+        if (points.length === 0 || !this.configured)
+            return;
+        await this.ensureSchema();
+        await this.getClient().insert({
+            table: this.table("runtime_metrics_1m"),
+            format: "JSONEachRow",
+            clickhouse_settings: INSERT_SETTINGS,
+            values: points.map((p) => ({
+                org_id: ctx.orgId,
+                repository_id: ctx.repositoryId,
+                service: p.service,
+                environment: p.environment,
+                release: p.release ?? "",
+                route: p.route,
+                bucket_at: p.bucketAt.toISOString(),
+                request_count: Math.max(0, Math.round(p.requestCount)),
+                error_count: Math.max(0, Math.round(p.errorCount)),
+                duration_sum_ms: p.durationSumMs,
+                session_count: Math.max(0, Math.round(p.sessionCount)),
+            })),
+        });
+    }
+    async close() {
+        if (!this.client)
+            return;
+        const client = this.client;
+        this.client = null;
+        await client.close().catch(() => { });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+export interface StaticIngestKey {
+    key: string;
+    orgId: string;
+    repositoryId: string;
+    /** "server" (default) = secret backend key; "client" = publishable browser key. */
+    scope?: "client" | "server";
+    /** client keys: exact origins allowed to send (e.g. https://app.example.com). */
+    allowedOrigins?: string[];
+}
+export interface IngesterConfig {
+    port: number;
+    /** e.g. http://localhost:8123 or https://xyz.clickhouse.cloud:8443 */
+    clickhouseUrl: string | null;
+    clickhouseUser: string;
+    clickhousePassword: string;
+    clickhouseDatabase: string;
+    /** Static key → tenant mapping (self-host). JSON array. */
+    ingestKeys: StaticIngestKey[];
+    /** Webhook that maps a key to a tenant (cloud). POST {key} → {orgId, repositoryId}. */
+    keyValidatorUrl: string | null;
+    keyValidatorToken: string | null;
+    /** Optional webhook receiving fingerprinted occurrences for issue grouping. */
+    sinkUrl: string | null;
+    sinkToken: string | null;
+    maxBodyBytes: number;
+    /** Per-key requests per minute (server keys). */
+    rateLimitPerMinute: number;
+    /** Per-key requests per minute for publishable client keys. */
+    clientRateLimitPerMinute: number;
+    /** Retention, overridable per deployment. */
+    occurrenceTtlDays: number;
+    spanTtlDays: number;
+    metricsTtlDays: number;
+}
+export declare function loadConfig(): IngesterConfig;

package/dist/config.js

@@ -0,0 +1,51 @@
+function intEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function parseIngestKeys(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((entry) => entry &&
+            typeof entry.key === "string" &&
+            typeof entry.orgId === "string" &&
+            typeof entry.repositoryId === "string");
+    }
+    catch {
+        console.error("AUTTER_INGEST_KEYS is not valid JSON — ignoring");
+        return [];
+    }
+}
+export function loadConfig() {
+    const config = {
+        port: intEnv("PORT", 4318),
+        clickhouseUrl: process.env.CLICKHOUSE_URL || null,
+        clickhouseUser: process.env.CLICKHOUSE_USER || "default",
+        clickhousePassword: process.env.CLICKHOUSE_PASSWORD || "",
+        clickhouseDatabase: process.env.CLICKHOUSE_DATABASE || "autter_runtime",
+        ingestKeys: parseIngestKeys(process.env.AUTTER_INGEST_KEYS),
+        keyValidatorUrl: process.env.AUTTER_KEY_VALIDATOR_URL || null,
+        keyValidatorToken: process.env.AUTTER_KEY_VALIDATOR_TOKEN || null,
+        sinkUrl: process.env.AUTTER_SINK_URL || null,
+        sinkToken: process.env.AUTTER_SINK_TOKEN || null,
+        maxBodyBytes: intEnv("MAX_BODY_BYTES", 1024 * 1024),
+        rateLimitPerMinute: intEnv("RATE_LIMIT_PER_MINUTE", 300),
+        clientRateLimitPerMinute: intEnv("CLIENT_RATE_LIMIT_PER_MINUTE", 120),
+        occurrenceTtlDays: intEnv("OCCURRENCE_TTL_DAYS", 14),
+        spanTtlDays: intEnv("SPAN_TTL_DAYS", 7),
+        metricsTtlDays: intEnv("METRICS_TTL_DAYS", 90),
+    };
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(config.clickhouseDatabase)) {
+        throw new Error(`Invalid CLICKHOUSE_DATABASE name: ${config.clickhouseDatabase}`);
+    }
+    if (config.ingestKeys.length === 0 && !config.keyValidatorUrl) {
+        console.warn("No AUTTER_INGEST_KEYS and no AUTTER_KEY_VALIDATOR_URL configured — all ingest requests will be rejected with 401");
+    }
+    return config;
+}

package/dist/fingerprint.d.ts

@@ -0,0 +1,19 @@
+import type { RuntimeOccurrenceInput } from "./types.js";
+export declare function normalizeMessage(message: string): string;
+/** Replace id-like path segments so /orders/812 and /orders/44 group. */
+export declare function normalizeRoute(route: string | null): string;
+export declare function normalizeStackFrames(stack: string | null, topN?: number): string[];
+export declare function fingerprintOccurrence(input: RuntimeOccurrenceInput): string;
+/**
+ * Derived, aggregation-ready fields, computed from the SAME normalisers the
+ * fingerprint hashes — so a stored fingerprint can always be explained by
+ * the stored columns next to it. Severity is deliberately excluded from
+ * the fingerprint (a warning that escalates to an error stays one group).
+ */
+export interface DerivedFields {
+    routeNormalized: string;
+    messageNormalized: string;
+    topFrames: string[];
+    firstFrame: string;
+}
+export declare function deriveFields(input: RuntimeOccurrenceInput): DerivedFields;