@zintrust/trace 0.9.2 → 0.9.4

package/src/storage/ProxyTraceStorage.ts

@@ -0,0 +1,182 @@
+import { ErrorFactory, RemoteSignedJson } from '@zintrust/core';
+import type { ITraceEntry, ITraceStorage } from '../types';
+
+type ProxyTraceStorageSettings = {
+  baseUrl: string;
+  path: string;
+  keyId: string;
+  secret: string;
+  timeoutMs: number;
+};
+
+type TraceProxyWriteRequest = {
+  entry: ITraceEntry;
+};
+
+type TraceProxyUpdateRequest = {
+  uuid: string;
+  patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>;
+};
+
+type TraceProxyMarkFamilyStaleRequest = {
+  familyHash: string;
+  exceptUuid: string;
+};
+
+const ensureConfigured = (settings: ProxyTraceStorageSettings): void => {
+  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: string): string => {
+  const trimmed = value.trim();
+  if (trimmed === '') return '/zin/trace/write';
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+
+const createUnsupportedReadError = (): Error =>
+  ErrorFactory.createConfigError(
+    'Trace proxy sender storage does not expose dashboard/query operations. Use the trace server for reads.'
+  );
+
+type ProxyRequestSettings = {
+  baseUrl: string;
+  keyId: string;
+  secret: string;
+  timeoutMs: number;
+  signaturePathPrefixToStrip: string;
+  missingUrlMessage: string;
+  missingCredentialsMessage: string;
+  messages: {
+    unauthorized: string;
+    forbidden: string;
+    rateLimited: string;
+    rejected: string;
+    error: string;
+    timedOut: string;
+  };
+  normalizedPath: string;
+};
+
+const buildSettings = (settings: ProxyTraceStorageSettings): ProxyRequestSettings => {
+  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: string, suffix: string): string => {
+  const base = normalizePath(path).replace(/\/+$/, '');
+  const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
+  return `${base}${tail}`;
+};
+
+const unsupportedQueryEntries: ITraceStorage['queryEntries'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedGetEntry: ITraceStorage['getEntry'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedGetBatch: ITraceStorage['getBatch'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedQueryBatchEntries: ITraceStorage['queryBatchEntries'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedPrune: ITraceStorage['prune'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedClear: ITraceStorage['clear'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedGetMonitoring: ITraceStorage['getMonitoring'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedAddMonitoring: ITraceStorage['addMonitoring'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedRemoveMonitoring: ITraceStorage['removeMonitoring'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+const unsupportedStats: ITraceStorage['stats'] = async () => {
+  throw createUnsupportedReadError();
+};
+
+export const ProxyTraceStorage = Object.freeze({
+  create(settings: ProxyTraceStorageSettings): ITraceStorage {
+    const normalized = buildSettings(settings);
+
+    return Object.freeze({
+      async writeEntry(entry: ITraceEntry): Promise<void> {
+        await RemoteSignedJson.request<{ ok: true }>(normalized, normalized.normalizedPath, {
+          entry,
+        } satisfies TraceProxyWriteRequest);
+      },
+
+      async updateEntry(
+        uuid: string,
+        patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+      ): Promise<void> {
+        await RemoteSignedJson.request<{ ok: true }>(
+          normalized,
+          appendSuffix(normalized.normalizedPath, '/update'),
+          { uuid, patch } satisfies TraceProxyUpdateRequest
+        );
+      },
+
+      async markFamilyStale(familyHash: string, exceptUuid: string): Promise<void> {
+        await RemoteSignedJson.request<{ ok: true }>(
+          normalized,
+          appendSuffix(normalized.normalizedPath, '/mark-family-stale'),
+          { familyHash, exceptUuid } satisfies TraceProxyMarkFamilyStaleRequest
+        );
+      },
+
+      queryEntries: unsupportedQueryEntries,
+      getEntry: unsupportedGetEntry,
+      getBatch: unsupportedGetBatch,
+      queryBatchEntries: unsupportedQueryBatchEntries,
+      prune: unsupportedPrune,
+      clear: unsupportedClear,
+      getMonitoring: unsupportedGetMonitoring,
+      addMonitoring: unsupportedAddMonitoring,
+      removeMonitoring: unsupportedRemoveMonitoring,
+      stats: unsupportedStats,
+    });
+  },
+});
+
+export default ProxyTraceStorage;

package/src/storage/TraceContentBudget.ts

@@ -285,6 +285,7 @@ const getCoreRuntime = async (): Promise<{
 
 const getQueueWorkerApi = async (): Promise<QueueWorkerApi | null> => {
   try {
+    // @ts-ignore
     const mod = (await import('@zintrust/workers')) as unknown as QueueWorkerApi;
     return typeof mod.createQueueWorker === 'function' ? mod : null;
   } catch {

package/src/storage/TraceServiceTag.ts

@@ -0,0 +1,56 @@
+import { ErrorFactory } from '@zintrust/core';
+import type { ITraceConfig, ITraceEntry, ITraceStorage } from '../types';
+
+const appendServiceTag = (entry: ITraceEntry, serviceTag?: string): ITraceEntry => {
+  const normalizedTag = serviceTag?.trim() ?? '';
+  if (normalizedTag === '' || entry.tags.includes(normalizedTag)) {
+    return entry;
+  }
+
+  return {
+    ...entry,
+    tags: [...entry.tags, normalizedTag],
+  };
+};
+
+const unsupportedRead = async <T>(): Promise<T> => {
+  throw ErrorFactory.createConfigError(
+    'Trace proxy mode only supports runtime persistence on the sender. Query the trace server database or dashboard directly.'
+  );
+};
+
+const bindOrUnsupported = <T extends (...args: never[]) => Promise<unknown>>(
+  method: T | undefined
+): T => {
+  if (method === undefined) {
+    return unsupportedRead as unknown as T;
+  }
+
+  return method;
+};
+
+export const TraceServiceTag = Object.freeze({
+  wrapStorage(storage: ITraceStorage, config: ITraceConfig): ITraceStorage {
+    const writeEntry = async (entry: ITraceEntry): Promise<void> => {
+      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/src/storage/index.ts

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

package/src/types.ts

@@ -373,6 +373,15 @@ export type TraceContentDispatchConfig = {
   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;
@@ -404,6 +413,8 @@ export interface ITraceConfig {
   enabled: boolean;
   connection?: string;
   observeConnection?: string;
+  serviceTag?: string;
+  proxy: TraceProxyConfig;
   pruneAfterHours: number;
   ignoreRoutes: string[];
   ignorePaths: string[];