@zintrust/trace 0.9.3 → 0.9.4

package/dist/storage/DebuggerStorage.js

@@ -0,0 +1,195 @@
+import { familyHash } from '../utils/familyHash.js';
+const TABLE_ENTRIES = 'zin_trace_entries';
+const TABLE_TAGS = 'zin_trace_entries_tags';
+const TABLE_MONITORING = 'zin_trace_monitoring';
+const generateUuid = () => crypto.randomUUID();
+const rowToEntry = (row, tags) => ({
+    uuid: row.uuid,
+    batchId: row.batch_id,
+    familyHash: row.family_hash ?? undefined,
+    type: row.type,
+    content: JSON.parse(row.content),
+    tags,
+    isLatest: Boolean(row.is_latest),
+    createdAt: row.created_at,
+});
+const insertTags = async (db, uuid, tags) => {
+    if (tags.length === 0)
+        return;
+    await Promise.all(tags.map(async (tag) => {
+        await db.execute(`INSERT OR IGNORE INTO ${TABLE_TAGS} (entry_uuid, tag) VALUES (?, ?)`, [
+            uuid,
+            tag,
+        ]);
+    }));
+};
+const buildEntryFilters = (opts) => {
+    const conditions = [];
+    const params = [];
+    if (opts.type) {
+        conditions.push('e.type = ?');
+        params.push(opts.type);
+    }
+    if (opts.batchId) {
+        conditions.push('e.batch_id = ?');
+        params.push(opts.batchId);
+    }
+    if (opts.from) {
+        conditions.push('e.created_at >= ?');
+        params.push(opts.from);
+    }
+    if (opts.to) {
+        conditions.push('e.created_at <= ?');
+        params.push(opts.to);
+    }
+    let joinClause = '';
+    if (opts.tag) {
+        joinClause = `INNER JOIN ${TABLE_TAGS} t ON t.entry_uuid = e.uuid AND t.tag = ?`;
+        params.unshift(opts.tag);
+    }
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const countParams = opts.tag ? [opts.tag, ...params.slice(1)] : [...params];
+    return { joinClause, whereClause, params, countParams };
+};
+const loadTagsByUuid = async (db, uuids) => {
+    const tagsByUuid = new Map();
+    if (uuids.length === 0)
+        return tagsByUuid;
+    const tagRows = (await db.query(`SELECT entry_uuid, tag FROM ${TABLE_TAGS} WHERE entry_uuid IN (${uuids.map(() => '?').join(',')})`, uuids));
+    for (const tagRow of tagRows) {
+        const tags = tagsByUuid.get(tagRow.entry_uuid) ?? [];
+        tags.push(tagRow.tag);
+        tagsByUuid.set(tagRow.entry_uuid, tags);
+    }
+    return tagsByUuid;
+};
+// The storage facade intentionally groups related DB operations in one factory.
+// eslint-disable-next-line max-lines-per-function
+const createStorage = (db) => {
+    const writeEntry = async (entry) => {
+        const uuid = entry.uuid || generateUuid();
+        await db.execute(`INSERT INTO ${TABLE_ENTRIES} (uuid, batch_id, family_hash, type, content, is_latest, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+            uuid,
+            entry.batchId,
+            entry.familyHash ?? null,
+            entry.type,
+            JSON.stringify(entry.content),
+            entry.isLatest ? 1 : 0,
+            entry.createdAt,
+        ]);
+        await insertTags(db, uuid, entry.tags);
+    };
+    const updateEntry = async (uuid, patch) => {
+        const sets = [];
+        const params = [];
+        if (patch.content !== undefined) {
+            sets.push('content = ?');
+            params.push(JSON.stringify(patch.content));
+        }
+        if (patch.isLatest !== undefined) {
+            sets.push('is_latest = ?');
+            params.push(patch.isLatest ? 1 : 0);
+        }
+        if (sets.length === 0)
+            return;
+        params.push(uuid);
+        await db.execute(`UPDATE ${TABLE_ENTRIES} SET ${sets.join(', ')} WHERE uuid = ?`, params);
+    };
+    const markFamilyStale = async (hash, exceptUuid) => {
+        await db.execute(`UPDATE ${TABLE_ENTRIES} SET is_latest = 0
+       WHERE family_hash = ? AND uuid != ? AND is_latest = 1`, [hash, exceptUuid]);
+    };
+    const queryEntries = async (opts) => {
+        const page = opts.page ?? 1;
+        const perPage = opts.perPage ?? 50;
+        const offset = (page - 1) * perPage;
+        const { joinClause, whereClause, params, countParams } = buildEntryFilters(opts);
+        const countResult = (await db.queryOne(`SELECT COUNT(*) as cnt FROM ${TABLE_ENTRIES} e ${joinClause} ${whereClause}`, countParams));
+        const total = countResult?.cnt ?? 0;
+        const rows = (await db.query(`SELECT e.id, e.uuid, e.batch_id, e.family_hash, e.type, e.content, e.is_latest, e.created_at
+       FROM ${TABLE_ENTRIES} e ${joinClause} ${whereClause}
+       ORDER BY e.created_at DESC, e.id DESC
+       LIMIT ? OFFSET ?`, [...params, perPage, offset]));
+        const tagsByUuid = await loadTagsByUuid(db, rows.map((row) => row.uuid));
+        return {
+            data: rows.map((row) => rowToEntry(row, tagsByUuid.get(row.uuid) ?? [])),
+            total,
+        };
+    };
+    const getEntry = async (uuid) => {
+        const row = (await db.queryOne(`SELECT id, uuid, batch_id, family_hash, type, content, is_latest, created_at
+       FROM ${TABLE_ENTRIES}
+       WHERE uuid = ?`, [uuid]));
+        if (!row)
+            return null;
+        const tags = (await db.query(`SELECT tag FROM ${TABLE_TAGS} WHERE entry_uuid = ?`, [
+            uuid,
+        ]));
+        return rowToEntry(row, tags.map((tag) => tag.tag));
+    };
+    const getBatch = async (batchId) => {
+        const rows = (await db.query(`SELECT id, uuid, batch_id, family_hash, type, content, is_latest, created_at
+       FROM ${TABLE_ENTRIES}
+       WHERE batch_id = ?
+       ORDER BY created_at ASC, id ASC`, [batchId]));
+        if (rows.length === 0)
+            return [];
+        const tagsByUuid = await loadTagsByUuid(db, rows.map((row) => row.uuid));
+        return rows.map((row) => rowToEntry(row, tagsByUuid.get(row.uuid) ?? []));
+    };
+    const prune = async (olderThanMs, keepExceptions = false) => {
+        const countResult = (await db.queryOne(`SELECT COUNT(*) as cnt FROM ${TABLE_ENTRIES}
+       WHERE created_at < ?
+       ${keepExceptions ? "AND type != 'exception'" : ''}`, [olderThanMs]));
+        const deleted = countResult?.cnt ?? 0;
+        if (deleted === 0)
+            return 0;
+        await db.execute(`DELETE FROM ${TABLE_ENTRIES}
+       WHERE created_at < ?
+       ${keepExceptions ? "AND type != 'exception'" : ''}`, [olderThanMs]);
+        return deleted;
+    };
+    const clear = async () => {
+        await db.execute(`DELETE FROM ${TABLE_ENTRIES}`, []);
+    };
+    const getMonitoring = async () => {
+        const rows = (await db.query(`SELECT tag FROM ${TABLE_MONITORING}`, []));
+        return rows.map((row) => row.tag);
+    };
+    const addMonitoring = async (tag) => {
+        await db.execute(`INSERT OR IGNORE INTO ${TABLE_MONITORING} (tag) VALUES (?)`, [tag]);
+    };
+    const removeMonitoring = async (tag) => {
+        await db.execute(`DELETE FROM ${TABLE_MONITORING} WHERE tag = ?`, [tag]);
+    };
+    const stats = async () => {
+        const rows = (await db.query(`SELECT type, COUNT(*) as cnt FROM ${TABLE_ENTRIES} GROUP BY type`, []));
+        const output = {};
+        for (const row of rows) {
+            output[row.type] = row.cnt;
+        }
+        return output;
+    };
+    return {
+        writeEntry,
+        updateEntry,
+        markFamilyStale,
+        queryEntries,
+        getEntry,
+        getBatch,
+        prune,
+        clear,
+        getMonitoring,
+        addMonitoring,
+        removeMonitoring,
+        stats,
+    };
+};
+const resolveStorage = (db) => {
+    return createStorage(db);
+};
+const reset = () => {
+    return;
+};
+export const TraceStorage = Object.freeze({ resolveStorage, reset, familyHash });

package/dist/storage/ProxyTraceStorage.d.ts

@@ -0,0 +1,12 @@
+import type { ITraceStorage } from '../types';
+type ProxyTraceStorageSettings = {
+    baseUrl: string;
+    path: string;
+    keyId: string;
+    secret: string;
+    timeoutMs: number;
+};
+export declare const ProxyTraceStorage: Readonly<{
+    create(settings: ProxyTraceStorageSettings): ITraceStorage;
+}>;
+export default ProxyTraceStorage;

package/dist/storage/ProxyTraceStorage.js

@@ -0,0 +1,102 @@
+import { ErrorFactory, RemoteSignedJson } from '@zintrust/core';
+const ensureConfigured = (settings) => {
+    if (settings.baseUrl.trim() === '') {
+        throw ErrorFactory.createConfigError('TRACE_PROXY_URL is required when TRACE_PROXY=true');
+    }
+    if (settings.keyId.trim() === '' || settings.secret.trim() === '') {
+        throw ErrorFactory.createConfigError('TRACE_PROXY signing credentials are required when TRACE_PROXY=true');
+    }
+};
+const normalizePath = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return '/zin/trace/write';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+const createUnsupportedReadError = () => ErrorFactory.createConfigError('Trace proxy sender storage does not expose dashboard/query operations. Use the trace server for reads.');
+const buildSettings = (settings) => {
+    ensureConfigured(settings);
+    const normalizedPath = normalizePath(settings.path);
+    return {
+        baseUrl: settings.baseUrl,
+        keyId: settings.keyId,
+        secret: settings.secret,
+        timeoutMs: settings.timeoutMs,
+        signaturePathPrefixToStrip: new URL(settings.baseUrl).pathname,
+        missingUrlMessage: 'TRACE_PROXY_URL is required when TRACE_PROXY=true',
+        missingCredentialsMessage: 'TRACE_PROXY signing credentials are required when TRACE_PROXY=true',
+        messages: {
+            unauthorized: 'Trace proxy rejected the request credentials',
+            forbidden: 'Trace proxy rejected the request signature',
+            rateLimited: 'Trace proxy rate-limited the request',
+            rejected: 'Trace proxy rejected the request payload',
+            error: 'Trace proxy request failed',
+            timedOut: 'Trace proxy request timed out',
+        },
+        normalizedPath,
+    };
+};
+const appendSuffix = (path, suffix) => {
+    const base = normalizePath(path).replace(/\/+$/, '');
+    const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
+    return `${base}${tail}`;
+};
+const unsupportedQueryEntries = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedGetEntry = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedGetBatch = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedQueryBatchEntries = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedPrune = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedClear = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedGetMonitoring = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedAddMonitoring = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedRemoveMonitoring = async () => {
+    throw createUnsupportedReadError();
+};
+const unsupportedStats = async () => {
+    throw createUnsupportedReadError();
+};
+export const ProxyTraceStorage = Object.freeze({
+    create(settings) {
+        const normalized = buildSettings(settings);
+        return Object.freeze({
+            async writeEntry(entry) {
+                await RemoteSignedJson.request(normalized, normalized.normalizedPath, {
+                    entry,
+                });
+            },
+            async updateEntry(uuid, patch) {
+                await RemoteSignedJson.request(normalized, appendSuffix(normalized.normalizedPath, '/update'), { uuid, patch });
+            },
+            async markFamilyStale(familyHash, exceptUuid) {
+                await RemoteSignedJson.request(normalized, appendSuffix(normalized.normalizedPath, '/mark-family-stale'), { familyHash, exceptUuid });
+            },
+            queryEntries: unsupportedQueryEntries,
+            getEntry: unsupportedGetEntry,
+            getBatch: unsupportedGetBatch,
+            queryBatchEntries: unsupportedQueryBatchEntries,
+            prune: unsupportedPrune,
+            clear: unsupportedClear,
+            getMonitoring: unsupportedGetMonitoring,
+            addMonitoring: unsupportedAddMonitoring,
+            removeMonitoring: unsupportedRemoveMonitoring,
+            stats: unsupportedStats,
+        });
+    },
+});
+export default ProxyTraceStorage;

package/dist/storage/TraceContentBudget.js

@@ -179,6 +179,7 @@ const getCoreRuntime = async () => {
 };
 const getQueueWorkerApi = async () => {
     try {
+        // @ts-ignore
         const mod = (await import('@zintrust/workers'));
         return typeof mod.createQueueWorker === 'function' ? mod : null;
     }

package/dist/storage/TraceServiceTag.d.ts

@@ -0,0 +1,5 @@
+import type { ITraceConfig, ITraceStorage } from '../types';
+export declare const TraceServiceTag: Readonly<{
+    wrapStorage(storage: ITraceStorage, config: ITraceConfig): ITraceStorage;
+}>;
+export default TraceServiceTag;

package/dist/storage/TraceServiceTag.js

@@ -0,0 +1,43 @@
+import { ErrorFactory } from '@zintrust/core';
+const appendServiceTag = (entry, serviceTag) => {
+    const normalizedTag = serviceTag?.trim() ?? '';
+    if (normalizedTag === '' || entry.tags.includes(normalizedTag)) {
+        return entry;
+    }
+    return {
+        ...entry,
+        tags: [...entry.tags, normalizedTag],
+    };
+};
+const unsupportedRead = async () => {
+    throw ErrorFactory.createConfigError('Trace proxy mode only supports runtime persistence on the sender. Query the trace server database or dashboard directly.');
+};
+const bindOrUnsupported = (method) => {
+    if (method === undefined) {
+        return unsupportedRead;
+    }
+    return method;
+};
+export const TraceServiceTag = Object.freeze({
+    wrapStorage(storage, config) {
+        const writeEntry = async (entry) => {
+            await storage.writeEntry(appendServiceTag(entry, config.serviceTag));
+        };
+        return Object.freeze({
+            writeEntry,
+            updateEntry: storage.updateEntry.bind(storage),
+            markFamilyStale: storage.markFamilyStale.bind(storage),
+            queryEntries: bindOrUnsupported(storage.queryEntries?.bind(storage)),
+            getEntry: bindOrUnsupported(storage.getEntry?.bind(storage)),
+            getBatch: bindOrUnsupported(storage.getBatch?.bind(storage)),
+            queryBatchEntries: bindOrUnsupported(storage.queryBatchEntries?.bind(storage)),
+            prune: bindOrUnsupported(storage.prune?.bind(storage)),
+            clear: bindOrUnsupported(storage.clear?.bind(storage)),
+            getMonitoring: bindOrUnsupported(storage.getMonitoring?.bind(storage)),
+            addMonitoring: bindOrUnsupported(storage.addMonitoring?.bind(storage)),
+            removeMonitoring: bindOrUnsupported(storage.removeMonitoring?.bind(storage)),
+            stats: bindOrUnsupported(storage.stats?.bind(storage)),
+        });
+    },
+});
+export default TraceServiceTag;

package/dist/storage/index.d.ts

@@ -1,2 +1,4 @@
 export { TraceStorage } from './TraceStorage';
 export type { ITraceStorage } from './TraceStorage';
+export { ProxyTraceStorage } from './ProxyTraceStorage';
+export { TraceServiceTag } from './TraceServiceTag';

package/dist/storage/index.js

@@ -1 +1,3 @@
 export { TraceStorage } from './TraceStorage.js';
+export { ProxyTraceStorage } from './ProxyTraceStorage.js';
+export { TraceServiceTag } from './TraceServiceTag.js';

package/dist/types.d.ts

@@ -316,6 +316,14 @@ export type TraceContentDispatchConfig = {
     enqueueTimeoutMs: number;
     worker: TraceContentDispatchWorkerConfig;
 };
+export type TraceProxyConfig = {
+    enabled: boolean;
+    url?: string;
+    path: string;
+    keyId?: string;
+    secret?: string;
+    timeoutMs: number;
+};
 export type TraceWatcherToggle = boolean | TraceFilterRule;
 export type TraceRequestWatcherToggle = boolean | TraceRequestWatcherConfig;
 export type TraceClientRequestWatcherToggle = boolean | TraceClientRequestWatcherConfig;
@@ -345,6 +353,8 @@ export interface ITraceConfig {
     enabled: boolean;
     connection?: string;
     observeConnection?: string;
+    serviceTag?: string;
+    proxy: TraceProxyConfig;
     pruneAfterHours: number;
     ignoreRoutes: string[];
     ignorePaths: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.9.2"
+    "@zintrust/core": "^0.9.4"
   },
   "publishConfig": {
     "access": "public"

package/src/config.ts

@@ -8,6 +8,7 @@ import type {
   TraceConfigOverrides,
   TraceContentDispatchConfig,
   TraceFilterRule,
+  TraceProxyConfig,
   TraceRequestWatcherConfig,
   TraceWatcherToggle,
 } from './types';
@@ -253,10 +254,31 @@ const mergeContentDispatch = (
   };
 };
 
+const mergeProxyConfig = (
+  base: TraceProxyConfig,
+  override?: TraceConfigOverrides['proxy']
+): TraceProxyConfig => {
+  if (override === undefined) return base;
+
+  return {
+    ...base,
+    ...override,
+  };
+};
+
 const DEFAULTS: ITraceConfig = Object.freeze({
   enabled: false,
   connection: undefined,
   observeConnection: undefined,
+  serviceTag: undefined,
+  proxy: {
+    enabled: false,
+    url: undefined,
+    path: '/zin/trace/write',
+    keyId: undefined,
+    secret: undefined,
+    timeoutMs: 30000,
+  },
   pruneAfterHours: 24,
   ignoreRoutes: ['/trace', '/health', '/ping'],
   ignorePaths: [],
@@ -342,6 +364,7 @@ export const TraceConfig = Object.freeze({
     return Object.freeze({
       ...DEFAULTS,
       ...overrides,
+      proxy: mergeProxyConfig(DEFAULTS.proxy, overrides.proxy),
       contentDispatch: mergeContentDispatch(DEFAULTS.contentDispatch, overrides.contentDispatch),
       watchers: mergeWatchers(DEFAULTS.watchers, overrides.watchers),
       redaction: {

package/src/index.ts

@@ -31,6 +31,7 @@ export { TraceContext } from './context';
 // ---------------------------------------------------------------------------
 export { registerTraceDashboard, registerTraceRoutes } from './dashboard/routes';
 export type { TraceDashboardOptions, TraceDashboardRegistrationOptions } from './dashboard/routes';
+export { registerTraceIngestGateway, TraceIngestGateway } from './ingest/TraceIngestGateway';
 
 // ---------------------------------------------------------------------------
 // Watchers (named re-exports for use with custom wiring)