@wtfalch/reporting 0.1.0 → 0.1.2

package/dist/alerts.js

@@ -32,12 +32,8 @@ export function projectDetail(detail) {
                 out[key] = Number.isFinite(value) ? value : String(value);
             else if (typeof value === 'string')
                 out[key] = value.slice(0, 500);
-            else if (Array.isArray(value))
-                out[key] = `[${value.length} items]`;
             else
                 out[key] = '[nested]';
-            if (Object.keys(out).length >= 40)
-                break;
         }
         return out;
     }

package/dist/bin/migrations.js

@@ -12,11 +12,5 @@ import { copyMigrations, describeCopy } from './copy.js';
 const here = dirname(fileURLToPath(import.meta.url));
 const from = join(here, '..', 'migrations');
 const to = resolve(process.cwd(), process.argv[2] ?? 'drizzle');
-let version;
-try {
-    version = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8')).version;
-}
-catch {
-    version = undefined;
-}
+const { version } = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
 console.log(describeCopy(copyMigrations({ from, to, version })));

package/dist/fake/index.js

@@ -16,11 +16,6 @@ export function createFakeReporting(opts = {}) {
         tables,
         rows,
         alerts,
-        // Not a database; a host's test that reaches `db` through the fake is
-        // testing the wrong thing, and this makes that loud.
-        get db() {
-            throw new Error('createFakeReporting has no database');
-        },
         event(input) {
             const v = eventInputSchema.parse(input);
             id += 1;
@@ -93,7 +88,7 @@ export function createFakeReporting(opts = {}) {
                 return { before, after: settings, by, changed };
             },
         },
-        stats: () => ({ queued: 0, dropped: 0, invalid: 0, flushed: rows.length, failedFlushes: 0 }),
+        stats: () => ({ queued: 0, dropped: 0, invalid: 0, flushed: rows.length }),
         reset() {
             rows.length = 0;
             alerts.length = 0;

package/dist/housekeeping/index.d.ts

@@ -43,12 +43,10 @@ export interface TaskContext {
 }
 export interface HousekeepingOptions {
     reporting: Reporting;
-    db?: Db;
+    db: Db;
     now?: () => Date;
     /** Per process. Default 60,000 ms. */
     debounceMs?: number;
-    /** Tasks run at once. Default 2. */
-    concurrency?: number;
 }
 export interface Housekeeping {
     /** Idempotent by name. The row is created on the next tick. */

package/dist/housekeeping/index.js

@@ -2,12 +2,13 @@ import { eq, sql } from 'drizzle-orm';
 import { KIND_PATTERN } from '../schema.js';
 import { reportingTasks } from '../tables.js';
 import { describe } from '../writer.js';
+/** Tasks run at once: enough that a slow prune does not delay the alerts, few enough to be one connection each. */
+const CONCURRENCY = 2;
 export function createHousekeeping(options) {
     const { reporting } = options;
-    const db = options.db ?? reporting.db;
+    const db = options.db;
     const now = options.now ?? (() => new Date());
     const debounceMs = options.debounceMs ?? 60_000;
-    const concurrency = Math.max(1, options.concurrency ?? 2);
     const registry = new Map();
     let lastTick = 0;
     let ticking = null;
@@ -132,7 +133,7 @@ export function createHousekeeping(options) {
         const settings = await reporting.settings.get();
         const queue = [...registry.values()];
         const counts = { claimed: 0, skipped: 0, ran: 0, failed: 0 };
-        const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+        const workers = Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
             for (let task = queue.shift(); task; task = queue.shift()) {
                 try {
                     const outcome = await runOne(task, settings);

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export * from './schema.js';
 export * from './tables.js';
 export * from './types.js';
 export { alertKind, projectDetail } from './alerts.js';
-export { DEFAULT_SETTINGS, RETENTION_BOUNDS, SETTING_KEYS } from './settings.js';
+export { DEFAULT_SETTINGS, RETENTION_BOUNDS } from './settings.js';
 /**
  * The host's one instance, built once over its drizzle handle and its
  * logger. Framework-neutral: `defer` is how the host says "after this unit of

package/dist/index.js

@@ -8,7 +8,7 @@ export * from './schema.js';
 export * from './tables.js';
 export * from './types.js';
 export { alertKind, projectDetail } from './alerts.js';
-export { DEFAULT_SETTINGS, RETENTION_BOUNDS, SETTING_KEYS } from './settings.js';
+export { DEFAULT_SETTINGS, RETENTION_BOUNDS } from './settings.js';
 function modeFromEnv() {
     const env = process.env.NODE_ENV;
     return env === 'development' || env === 'test' ? env : 'production';
@@ -39,7 +39,6 @@ export function createReporting(options) {
     });
     const reporting = {
         site,
-        db: options.db,
         log: options.log,
         tables,
         event: (input) => writer.event(input),

package/dist/migrations/0001_reporting.sql

@@ -48,7 +48,9 @@ create table if not exists reporting_events (
   -- provider response or a request body sneaks in whole. `strict`, because
   -- lax mode unwraps an array before the filter sees it and would never
   -- call one an array.
-  constraint reporting_events_data_flat_check check (not jsonb_path_exists(data, 'strict $.* ? (@.type() == "object" || @.type() == "array")')),
+  -- `silent`, so a non-object `data` fails the object check by name rather
+  -- than raising 22033 from this one, whichever the planner evaluates first.
+  constraint reporting_events_data_flat_check check (not jsonb_path_exists(data, 'strict $.* ? (@.type() == "object" || @.type() == "array")', '{}', true)),
   -- The keys that carry a person or a secret by name. A guardrail, not a
   -- proof: src/schema.ts refuses the same list before a row is queued, and
   -- schema.test.ts pins the two lists equal.
@@ -86,9 +88,6 @@ create table if not exists reporting_tasks (
   claim_token       uuid,
   last_outcome      text,
   last_error        text,
-  -- Free for a task's own bookkeeping: the analytics rollup keeps its
-  -- completed-day watermark here.
-  watermark         text,
   constraint reporting_tasks_task_check check (task ~ '^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$'),
   constraint reporting_tasks_outcome_check check (last_outcome is null or last_outcome in ('ok', 'error', 'skipped')),
   constraint reporting_tasks_error_check check (last_error is null or length(last_error) <= 512)

package/dist/next/index.js

@@ -19,6 +19,8 @@ export function healthHandler(housekeeping) {
         return Response.json({ ok: true, ts: new Date().toISOString() });
     };
 }
+/** `<16 hex>-<colo>`, as Cloudflare emits it. */
+const RAY_PATTERN = /^[0-9a-f]{16}-[A-Z0-9]{3,6}$/;
 /**
  * Read once where a request enters (a Server Action, a route handler, a
  * page's data component) and handed down. Outside a request scope it returns
@@ -30,8 +32,12 @@ export async function requestContext() {
     try {
         const h = await headers();
         const country = h.get('cf-ipcountry');
+        // A ray id is Cloudflare's or it is nothing: a request that reached the
+        // origin some other way (the Docker network, a preview host) could
+        // otherwise choose the id stamped on the audit rows of this request.
+        const ray = h.get('cf-ray');
         return {
-            id: (h.get('cf-ray') ?? randomUUID()).slice(0, 128),
+            id: ray && RAY_PATTERN.test(ray) ? ray : randomUUID(),
             ip: h.get('cf-connecting-ip'),
             userAgent: h.get('user-agent'),
             country: country && /^[A-Z]{2}$/.test(country) ? country : null,

package/dist/schema.d.ts

@@ -28,9 +28,16 @@ export declare const LIMITS: {
     readonly dataBytes: 16384;
     readonly site: 64;
 };
-/** Flat, bounded, and free of the banned keys. Numbers must be finite: JSON has no NaN. */
+/** Flat, bounded, banned keys refused, numbers finite. */
 export declare const flatDataSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
 export type FlatData = z.infer<typeof flatDataSchema>;
+/**
+ * `z.object`, not strict: a host hands over its resolved principal, which
+ * carries a display name and an address beside `class` and `id`, and those
+ * must be dropped rather than refused. Stripping is the privacy behaviour;
+ * refusing would make every host's call site narrow by hand, and the first
+ * one did not.
+ */
 export declare const actorSchema: z.ZodObject<{
     class: z.ZodEnum<{
         human: "human";
@@ -39,12 +46,12 @@ export declare const actorSchema: z.ZodObject<{
         service: "service";
     }>;
     id: z.ZodString;
-}, z.core.$strict>;
+}, z.core.$strip>;
 export type Actor = z.infer<typeof actorSchema>;
 export declare const targetSchema: z.ZodObject<{
     type: z.ZodString;
     id: z.ZodString;
-}, z.core.$strict>;
+}, z.core.$strip>;
 /** What a caller hands `event()`. Everything else on the row is the writer's. */
 export declare const eventInputSchema: z.ZodObject<{
     kind: z.ZodString;
@@ -64,12 +71,12 @@ export declare const eventInputSchema: z.ZodObject<{
             service: "service";
         }>;
         id: z.ZodString;
-    }, z.core.$strict>>>;
+    }, z.core.$strip>>>;
     requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     target: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         type: z.ZodString;
         id: z.ZodString;
-    }, z.core.$strict>>>;
+    }, z.core.$strip>>>;
     data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
     occurredAt: z.ZodOptional<z.ZodDate>;
 }, z.core.$strict>;

package/dist/schema.js

@@ -36,7 +36,7 @@ export const LIMITS = {
     site: 64,
 };
 const scalar = z.union([z.string(), z.number(), z.boolean(), z.null()]);
-/** Flat, bounded, and free of the banned keys. Numbers must be finite: JSON has no NaN. */
+/** Flat, bounded, banned keys refused, numbers finite. */
 export const flatDataSchema = z.record(z.string(), scalar).superRefine((data, ctx) => {
     for (const key of Object.keys(data)) {
         if (BANNED_KEYS.includes(key)) {
@@ -55,11 +55,18 @@ export const flatDataSchema = z.record(z.string(), scalar).superRefine((data, ct
     }
 });
 const bounded = (max) => z.string().min(1).max(max);
-export const actorSchema = z.strictObject({
+/**
+ * `z.object`, not strict: a host hands over its resolved principal, which
+ * carries a display name and an address beside `class` and `id`, and those
+ * must be dropped rather than refused. Stripping is the privacy behaviour;
+ * refusing would make every host's call site narrow by hand, and the first
+ * one did not.
+ */
+export const actorSchema = z.object({
     class: z.enum(ACTOR_CLASSES),
     id: bounded(LIMITS.actorId),
 });
-export const targetSchema = z.strictObject({
+export const targetSchema = z.object({
     type: bounded(LIMITS.targetType),
     id: bounded(LIMITS.targetId),
 });

package/dist/settings.d.ts

@@ -9,7 +9,6 @@ export declare const RETENTION_BOUNDS: {
     readonly min: 7;
     readonly max: 400;
 };
-export declare const SETTING_KEYS: (keyof Settings)[];
 export declare const DEFAULT_SETTINGS: Settings;
 export declare function getSettings(db: Db): Promise<Settings>;
 /** Validates every key, writes the changed ones in one transaction, returns before and after. Throws on an out-of-bounds value: the caller is a form. */

package/dist/settings.js

@@ -14,7 +14,6 @@ const DEFS = {
         default: 30,
     },
 };
-export const SETTING_KEYS = Object.keys(DEFS);
 export const DEFAULT_SETTINGS = Object.freeze({
     'events.retention_days': DEFS['events.retention_days'].default,
 });

package/dist/tables.d.ts

@@ -240,7 +240,7 @@ export declare const reportingEvents: import("drizzle-orm/pg-core").PgTableWithC
             data: Record<string, string | number | boolean | null>;
             driverParam: unknown;
             notNull: true;
-            hasDefault: false;
+            hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -411,23 +411,6 @@ export declare const reportingTasks: import("drizzle-orm/pg-core").PgTableWithCo
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        watermark: import("drizzle-orm/pg-core").PgColumn<{
-            name: "watermark";
-            tableName: "reporting_tasks";
-            dataType: "string";
-            columnType: "PgText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
     };
     dialect: "pg";
 }>;
@@ -745,7 +728,7 @@ export declare const tables: {
                 data: Record<string, string | number | boolean | null>;
                 driverParam: unknown;
                 notNull: true;
-                hasDefault: false;
+                hasDefault: true;
                 isPrimaryKey: false;
                 isAutoincrement: false;
                 hasRuntimeDefault: false;
@@ -916,23 +899,6 @@ export declare const tables: {
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
-            watermark: import("drizzle-orm/pg-core").PgColumn<{
-                name: "watermark";
-                tableName: "reporting_tasks";
-                dataType: "string";
-                columnType: "PgText";
-                data: string;
-                driverParam: string;
-                notNull: false;
-                hasDefault: false;
-                isPrimaryKey: false;
-                isAutoincrement: false;
-                hasRuntimeDefault: false;
-                enumValues: [string, ...string[]];
-                baseColumn: never;
-                identity: undefined;
-                generated: undefined;
-            }, {}, {}>;
         };
         dialect: "pg";
     }>;

package/dist/tables.js

@@ -21,15 +21,23 @@ export const reportingEvents = pgTable('reporting_events', {
     targetType: text('target_type'),
     targetId: text('target_id'),
     message: text('message').notNull(),
-    data: jsonb('data').$type().notNull(),
+    data: jsonb('data')
+        .$type()
+        .notNull()
+        .default(sql `'{}'::jsonb`),
     schemaVersion: smallint('schema_version').notNull().default(1),
 }, (t) => [
     index('reporting_events_time_idx').on(t.occurredAt.desc(), t.id.desc()),
-    // The partial predicates live in the SQL; these declare the columns.
-    index('reporting_events_tenant_time_idx').on(t.tenantId, t.occurredAt.desc(), t.id.desc()),
+    index('reporting_events_tenant_time_idx')
+        .on(t.tenantId, t.occurredAt.desc(), t.id.desc())
+        .where(sql `${t.tenantId} is not null`),
     index('reporting_events_ns_time_idx').on(t.kindNs, t.occurredAt.desc(), t.id.desc()),
-    index('reporting_events_problem_time_idx').on(t.occurredAt.desc(), t.id.desc()),
-    index('reporting_events_request_idx').on(t.requestId, t.occurredAt.desc()),
+    index('reporting_events_problem_time_idx')
+        .on(t.occurredAt.desc(), t.id.desc())
+        .where(sql `${t.level} in ('error', 'alert')`),
+    index('reporting_events_request_idx')
+        .on(t.requestId, t.occurredAt.desc())
+        .where(sql `${t.requestId} is not null`),
 ]);
 export const reportingTasks = pgTable('reporting_tasks', {
     task: text('task').primaryKey(),
@@ -40,7 +48,6 @@ export const reportingTasks = pgTable('reporting_tasks', {
     claimToken: uuid('claim_token'),
     lastOutcome: text('last_outcome'),
     lastError: text('last_error'),
-    watermark: text('watermark'),
 });
 export const reportingSettings = pgTable('reporting_settings', {
     key: text('key').primaryKey(),

package/dist/types.d.ts

@@ -79,7 +79,6 @@ export interface Stats {
     readonly dropped: number;
     readonly invalid: number;
     readonly flushed: number;
-    readonly failedFlushes: number;
 }
 export interface Reporting {
     /** Never throws in production; see writer.ts. */
@@ -99,7 +98,6 @@ export interface Reporting {
     };
     readonly tables: typeof tables;
     readonly site: string;
-    readonly db: Db;
     readonly log: Logger;
     stats(): Stats;
 }

package/dist/writer.d.ts

@@ -20,18 +20,24 @@ export declare class Writer {
     private droppedSinceReport;
     private invalid;
     private flushed;
-    private failedFlushes;
     constructor(o: WriterOptions);
     event(input: EventInput): void;
     private toRow;
     private enqueue;
     /** Once per idle period through `defer`, and always on the timer. */
     private schedule;
-    /** Drain until empty or the deadline. One flush in flight at a time; a second call waits on the first. */
+    /**
+     * Drain until the queue is empty and nothing is in flight, or the deadline.
+     * Two callers overlap all the time (the timer and a request's `after()`,
+     * the tick and its own timer), so "empty" is not enough: a row another
+     * flush spliced off the queue a moment ago is still on its way, and a
+     * caller that returned on an empty queue would read the table too early.
+     * Every caller therefore waits for whatever is in flight and looks again.
+     */
     flush(opts?: {
         deadlineMs?: number;
     }): Promise<void>;
-    private lastFailed;
+    /** One insert of one batch. Resolves true on success; never throws. */
     private flushOnce;
     stats(): Stats;
 }

package/dist/writer.js

@@ -10,7 +10,6 @@ export class Writer {
     droppedSinceReport = 0;
     invalid = 0;
     flushed = 0;
-    failedFlushes = 0;
     constructor(o) {
         this.o = o;
     }
@@ -95,25 +94,40 @@ export class Writer {
             this.timer.unref?.();
         }
     }
-    /** Drain until empty or the deadline. One flush in flight at a time; a second call waits on the first. */
+    /**
+     * Drain until the queue is empty and nothing is in flight, or the deadline.
+     * Two callers overlap all the time (the timer and a request's `after()`,
+     * the tick and its own timer), so "empty" is not enough: a row another
+     * flush spliced off the queue a moment ago is still on its way, and a
+     * caller that returned on an empty queue would read the table too early.
+     * Every caller therefore waits for whatever is in flight and looks again.
+     */
     async flush(opts = {}) {
         const deadline = Date.now() + (opts.deadlineMs ?? 5000);
-        if (this.inFlight)
-            await this.inFlight;
-        while (this.queue.length > 0 && Date.now() < deadline) {
-            this.inFlight = this.flushOnce();
-            try {
+        while (Date.now() < deadline) {
+            if (this.inFlight) {
                 await this.inFlight;
+                continue;
+            }
+            if (this.queue.length === 0)
+                break;
+            const attempt = this.flushOnce();
+            this.inFlight = attempt;
+            let ok = false;
+            try {
+                ok = await attempt;
             }
             finally {
                 this.inFlight = null;
             }
-            if (this.failedFlushes > 0 && this.queue.length > 0 && this.lastFailed)
+            // A failed insert leaves its rows queued; do not spin on the database
+            // inside one call. The timer and the next defer try again.
+            if (!ok)
                 break;
         }
         this.deferred = false;
     }
-    lastFailed = false;
+    /** One insert of one batch. Resolves true on success; never throws. */
     async flushOnce() {
         const batch = this.queue.splice(0, this.o.batchSize);
         if (this.droppedSinceReport > 0) {
@@ -133,11 +147,9 @@ export class Writer {
         try {
             await this.o.db.insert(reportingEvents).values(batch);
             this.flushed += batch.length;
-            this.lastFailed = false;
+            return true;
         }
         catch (error) {
-            this.failedFlushes += 1;
-            this.lastFailed = true;
             // Back at the front, so order survives; the bound still applies, and
             // whatever does not fit is counted as dropped rather than kept for ever.
             const room = Math.max(0, this.o.queueLimit - this.queue.length);
@@ -146,6 +158,7 @@ export class Writer {
             this.droppedSinceReport += batch.length - kept.length;
             this.queue.unshift(...kept);
             this.o.log.error({ err: describe(error), rows: batch.length, queued: this.queue.length }, 'reporting: flush failed; rows stay queued');
+            return false;
         }
     }
     stats() {
@@ -154,7 +167,6 @@ export class Writer {
             dropped: this.dropped,
             invalid: this.invalid,
             flushed: this.flushed,
-            failedFlushes: this.failedFlushes,
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/reporting",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The estate's operational event log and housekeeping tick: a writer that never fails a request, a claim protocol that needs no scheduler, and the readers an operator opens. Per-app Postgres, host-supplied logger, framework-neutral core with a Next entry.",
   "repository": {
     "type": "git",