@zintrust/trace 0.4.95 → 0.5.0

package/src/storage/TraceContentBudget.ts

@@ -27,6 +27,87 @@ const describeValueType = (value: unknown): string => {
   return typeof value;
 };
 
+type TracePathSegment = string | number;
+
+type TracePathCandidate = {
+  path: TracePathSegment[];
+  size: number;
+};
+
+const chooseLargerCandidate = (
+  left: TracePathCandidate | null,
+  right: TracePathCandidate | null
+): TracePathCandidate | null => {
+  if (left === null) return right;
+  if (right === null) return left;
+  return right.size > left.size ? right : left;
+};
+
+const fallbackCandidate = (value: unknown, path: TracePathSegment[]): TracePathCandidate | null => {
+  return path.length === 0 ? null : { path, size: serializedSize(value) };
+};
+
+const findLargestDroppablePathInArray = (
+  value: unknown[],
+  path: TracePathSegment[]
+): TracePathCandidate | null => {
+  let best: TracePathCandidate | null = null;
+
+  for (const [index, item] of value.entries()) {
+    best = chooseLargerCandidate(best, findLargestDroppablePath(item, [...path, index]));
+  }
+
+  return best ?? fallbackCandidate(value, path);
+};
+
+const findLargestDroppablePathInObject = (
+  value: Record<string, unknown>,
+  path: TracePathSegment[]
+): TracePathCandidate | null => {
+  let best: TracePathCandidate | null = null;
+
+  for (const [key, entryValue] of Object.entries(value)) {
+    if (key === '__traceNotice') continue;
+    best = chooseLargerCandidate(best, findLargestDroppablePath(entryValue, [...path, key]));
+  }
+
+  return best ?? fallbackCandidate(value, path);
+};
+
+const findLargestDroppablePath = (
+  value: unknown,
+  path: TracePathSegment[] = []
+): TracePathCandidate | null => {
+  if (Array.isArray(value)) return findLargestDroppablePathInArray(value, path);
+  if (typeof value === 'object' && value !== null) {
+    return findLargestDroppablePathInObject(value as Record<string, unknown>, path);
+  }
+
+  return fallbackCandidate(value, path);
+};
+
+const replaceAtPath = (value: unknown, path: TracePathSegment[], replacement: unknown): unknown => {
+  if (path.length === 0) return replacement;
+
+  const [segment, ...rest] = path;
+
+  if (Array.isArray(value) && typeof segment === 'number') {
+    const next = value.slice();
+    next[segment] = replaceAtPath(next[segment], rest, replacement);
+    return next;
+  }
+
+  if (typeof value === 'object' && value !== null && typeof segment === 'string') {
+    const current = value as Record<string, unknown>;
+    return {
+      ...current,
+      [segment]: replaceAtPath(current[segment], rest, replacement),
+    };
+  }
+
+  return value;
+};
+
 const compactValue = (value: unknown, depth: number): unknown => {
   if (depth >= DEFAULT_MAX_DEPTH) {
     return DROPPED_FIELD_MESSAGE;
@@ -69,19 +150,19 @@ const compactValue = (value: unknown, depth: number): unknown => {
   return Object.fromEntries(compactedEntries);
 };
 
-const compactTopLevelObjectToBudget = (value: Record<string, unknown>): Record<string, unknown> => {
-  const compacted: Record<string, unknown> = {
-    ...value,
-    __traceNotice: COMPACTED_CONTENT_MESSAGE,
-  };
-
-  const keysByDescendingSize = Object.keys(compacted)
-    .filter((key) => key !== '__traceNotice')
-    .sort((left, right) => serializedSize(compacted[right]) - serializedSize(compacted[left]));
-
-  for (const key of keysByDescendingSize) {
-    if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES) break;
-    compacted[key] = DROPPED_FIELD_MESSAGE;
+const compactStructuredValueToBudget = (value: unknown): unknown => {
+  let compacted: unknown =
+    typeof value === 'object' && value !== null && !Array.isArray(value)
+      ? {
+          ...(value as Record<string, unknown>),
+          __traceNotice: COMPACTED_CONTENT_MESSAGE,
+        }
+      : value;
+
+  while (serializedSize(compacted) > DEFAULT_MAX_ENTRY_BYTES) {
+    const candidate = findLargestDroppablePath(compacted);
+    if (candidate === null) break;
+    compacted = replaceAtPath(compacted, candidate.path, DROPPED_FIELD_MESSAGE);
   }
 
   return compacted;
@@ -97,10 +178,10 @@ const fitContentToBudget = (content: unknown): unknown => {
     return compacted;
   }
 
-  if (typeof compacted === 'object' && compacted !== null && !Array.isArray(compacted)) {
-    const topLevelCompacted = compactTopLevelObjectToBudget(compacted as Record<string, unknown>);
-    if (serializedSize(topLevelCompacted) <= DEFAULT_MAX_ENTRY_BYTES) {
-      return topLevelCompacted;
+  if (typeof compacted === 'object' && compacted !== null) {
+    const budgetCompacted = compactStructuredValueToBudget(compacted);
+    if (serializedSize(budgetCompacted) <= DEFAULT_MAX_ENTRY_BYTES) {
+      return budgetCompacted;
     }
   }
 

package/src/types.ts

@@ -209,6 +209,7 @@ export interface ViewContent {
 }
 
 export interface ClientRequestContent {
+  source?: string;
   method: string;
   url: string;
   requestHeaders: Record<string, string>;
@@ -222,6 +223,7 @@ export interface ClientRequestContent {
 }
 
 export interface ClientRequestTraceInput {
+  source?: string;
   method: string;
   url: string;
   requestHeaders: Record<string, string>;
@@ -315,6 +317,13 @@ export type TraceFilterRule = {
   exclude?: string[];
 };
 
+export type TraceClientRequestCaptureRule = TraceFilterRule & {
+  requestHeaders?: boolean;
+  requestBody?: boolean;
+  responseHeaders?: boolean;
+  responseBody?: boolean;
+};
+
 export type TraceRequestWatcherConfig = TraceFilterRule & {
   all?: TraceFilterRule;
   get?: TraceFilterRule;
@@ -324,8 +333,13 @@ export type TraceRequestWatcherConfig = TraceFilterRule & {
   delete?: TraceFilterRule;
 };
 
+export type TraceClientRequestWatcherConfig = TraceClientRequestCaptureRule & {
+  sources?: Record<string, TraceClientRequestCaptureRule>;
+};
+
 export type TraceWatcherToggle = boolean | TraceFilterRule;
 export type TraceRequestWatcherToggle = boolean | TraceRequestWatcherConfig;
+export type TraceClientRequestWatcherToggle = boolean | TraceClientRequestWatcherConfig;
 
 export type WatcherToggles = {
   request?: TraceRequestWatcherToggle;
@@ -347,7 +361,7 @@ export type WatcherToggles = {
   batch?: TraceWatcherToggle;
   dump?: TraceWatcherToggle;
   view?: TraceWatcherToggle;
-  clientRequest?: TraceWatcherToggle;
+  clientRequest?: TraceClientRequestWatcherToggle;
 };
 
 export interface ITraceConfig {

package/src/utils/entryFilter.ts

@@ -1,6 +1,7 @@
 import type {
   ITraceConfig,
   ITraceEntry,
+  TraceClientRequestWatcherConfig,
   TraceFilterRule,
   TraceRequestWatcherConfig,
   WatcherToggles,
@@ -22,6 +23,7 @@ const normalizeTerms = (terms?: string[]): string[] => {
 
 const matchesRule = (haystack: string, rule?: TraceFilterRule): boolean => {
   if (!rule) return true;
+  if (rule.enabled === false) return false;
 
   const include = normalizeTerms(rule.include);
   const exclude = normalizeTerms(rule.exclude);
@@ -86,6 +88,20 @@ const getRequestMethodRule = (
   return watcher.all;
 };
 
+const getClientRequestSourceRule = (
+  watcher: TraceClientRequestWatcherConfig,
+  entry: ITraceEntry
+): TraceFilterRule | undefined => {
+  if (entry.type !== EntryType.CLIENT_REQUEST) return undefined;
+
+  const content = isObjectValue(entry.content) ? entry.content : undefined;
+  const sourceValue = content?.['source'];
+  const source = typeof sourceValue === 'string' ? sourceValue.trim().toLowerCase() : '';
+
+  if (source === '') return undefined;
+  return watcher.sources?.[source];
+};
+
 export const TraceEntryFilter = Object.freeze({
   shouldCapture(entry: ITraceEntry, config: ITraceConfig): boolean {
     const watcherKey = watcherKeyByEntryType[entry.type];
@@ -103,6 +119,13 @@ export const TraceEntryFilter = Object.freeze({
       if (!matchesRule(haystack, methodRule)) return false;
     }
 
+    if (watcherKey === 'clientRequest') {
+      const clientRequestWatcher = watcher as TraceClientRequestWatcherConfig;
+      const sourceRule = getClientRequestSourceRule(clientRequestWatcher, entry);
+      if (sourceRule?.enabled === false) return false;
+      if (!matchesRule(haystack, sourceRule)) return false;
+    }
+
     return true;
   },
 });

package/src/watchers/HttpClientWatcher.ts

@@ -1,11 +1,14 @@
+import { generateUuid } from '@zintrust/core';
 import { TraceContext } from '../context';
-import type {
-  ClientRequestContent,
-  ClientRequestTraceInput,
-  ITraceWatcher,
-  ITraceWatcherConfig,
+import {
+  EntryType,
+  type ClientRequestContent,
+  type ClientRequestTraceInput,
+  type ITraceWatcher,
+  type ITraceWatcherConfig,
+  type TraceClientRequestCaptureRule,
+  type TraceClientRequestWatcherConfig,
 } from '../types';
-import { EntryType } from '../types';
 import { AuthTag } from '../utils/authTag';
 import { redactHeaders, redactUnknown } from '../utils/redact';
 import { RequestFilter } from '../utils/requestFilter';
@@ -14,8 +17,137 @@ let _storage: ITraceWatcherConfig['storage'] | null = null;
 let _redactHeaderNames: string[] = [];
 let _redactBodyFields: string[] = [];
 let _ignoreRoutes: string[] = [];
+let _clientRequestWatcher: TraceClientRequestWatcherConfig | undefined;
+
+const isObjectValue = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+const resolveSource = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.trim().toLowerCase();
+  return normalized === '' ? undefined : normalized;
+};
+
+const resolveSourceRule = (
+  source: string | undefined
+): TraceClientRequestCaptureRule | undefined => {
+  if (source === undefined) return undefined;
+  return _clientRequestWatcher?.sources?.[source];
+};
+
+const shouldCaptureField = (
+  field: keyof Pick<
+    TraceClientRequestCaptureRule,
+    'requestHeaders' | 'requestBody' | 'responseHeaders' | 'responseBody'
+  >,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): boolean => {
+  const scoped = sourceRule?.[field];
+  if (typeof scoped === 'boolean') return scoped;
+  const global = _clientRequestWatcher?.[field];
+  if (typeof global === 'boolean') return global;
+  return true;
+};
+
+const buildRequestHeaders = (
+  requestHeaders: Record<string, string>,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): Pick<ClientRequestContent, 'requestHeaders'> => {
+  return shouldCaptureField('requestHeaders', sourceRule)
+    ? { requestHeaders: redactHeaders(requestHeaders, _redactHeaderNames) }
+    : { requestHeaders: {} };
+};
+
+const buildRequestBody = (
+  requestBody: unknown,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): Partial<Pick<ClientRequestContent, 'requestBody'>> => {
+  if (requestBody === undefined) return {};
+  if (!shouldCaptureField('requestBody', sourceRule)) return {};
+  return { requestBody: redactUnknown(requestBody, _redactBodyFields) };
+};
+
+const buildResponseHeaders = (
+  responseHeaders: Record<string, string> | undefined,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): Partial<Pick<ClientRequestContent, 'responseHeaders'>> => {
+  if (responseHeaders === undefined) return {};
+  if (!shouldCaptureField('responseHeaders', sourceRule)) return {};
+  return { responseHeaders: redactHeaders(responseHeaders, _redactHeaderNames) };
+};
+
+const buildResponseBody = (
+  responseBody: unknown,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): Partial<Pick<ClientRequestContent, 'responseBody'>> => {
+  if (responseBody === undefined) return {};
+  if (!shouldCaptureField('responseBody', sourceRule)) return {};
+  return { responseBody: redactUnknown(responseBody, _redactBodyFields) };
+};
+
+const applySource = (content: ClientRequestContent, normalizedSource: string | undefined): void => {
+  if (normalizedSource !== undefined) {
+    content.source = normalizedSource;
+  }
+};
+
+const applyResponseStatus = (
+  content: ClientRequestContent,
+  responseStatus: number | undefined
+): void => {
+  if (responseStatus !== undefined) {
+    content.responseStatus = responseStatus;
+  }
+};
+
+const applyError = (content: ClientRequestContent, error: unknown): void => {
+  if (typeof error === 'string' && error !== '') {
+    content.error = error;
+  }
+};
+
+const mergePartialContent = (
+  content: ClientRequestContent,
+  partial: Partial<ClientRequestContent>
+): void => {
+  Object.assign(content, partial);
+};
+
+const buildClientRequestContent = (
+  input: ClientRequestTraceInput,
+  sourceRule: TraceClientRequestCaptureRule | undefined,
+  normalizedSource: string | undefined
+): ClientRequestContent => {
+  const content: ClientRequestContent = {
+    method: input.method.toUpperCase(),
+    url: input.url,
+    requestHeaders: {},
+    duration: input.duration,
+    hostname: TraceContext.getHostname(),
+  };
+
+  applySource(content, normalizedSource);
+  mergePartialContent(content, buildRequestHeaders(input.requestHeaders, sourceRule));
+  mergePartialContent(content, buildRequestBody(input.requestBody, sourceRule));
+  applyResponseStatus(content, input.responseStatus);
+  mergePartialContent(content, buildResponseHeaders(input.responseHeaders, sourceRule));
+  mergePartialContent(content, buildResponseBody(input.responseBody, sourceRule));
+  applyError(content, input.error);
+
+  return content;
+};
+
+const isWatcherEnabled = (
+  value: ITraceWatcherConfig['config']['watchers']['clientRequest']
+): boolean => {
+  if (value === false) return false;
+  if (isObjectValue(value) && value.enabled === false) return false;
+  return true;
+};
 
 const emit = ({
+  source,
   method,
   url,
   requestHeaders,
@@ -28,29 +160,31 @@ const emit = ({
 }: ClientRequestTraceInput): void => {
   if (!_storage) return;
   if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const normalizedSource = resolveSource(source);
+  const sourceRule = resolveSourceRule(normalizedSource);
+  if (sourceRule?.enabled === false) return;
   const tags = AuthTag.append([method.toUpperCase()]);
   if ((responseStatus ?? 0) >= 400 || error) tags.push('failed');
-  const content: ClientRequestContent = {
-    method: method.toUpperCase(),
-    url,
-    requestHeaders: redactHeaders(requestHeaders, _redactHeaderNames),
-    ...(requestBody === undefined
-      ? {}
-      : { requestBody: redactUnknown(requestBody, _redactBodyFields) }),
-    ...(responseStatus === undefined ? {} : { responseStatus }),
-    ...(responseHeaders === undefined
-      ? {}
-      : { responseHeaders: redactHeaders(responseHeaders, _redactHeaderNames) }),
-    ...(responseBody === undefined
-      ? {}
-      : { responseBody: redactUnknown(responseBody, _redactBodyFields) }),
-    ...(typeof error === 'string' && error !== '' ? { error } : {}),
-    duration,
-    hostname: TraceContext.getHostname(),
-  };
+  if (normalizedSource !== undefined) tags.push(normalizedSource);
+  const content = buildClientRequestContent(
+    {
+      source,
+      method,
+      url,
+      requestHeaders,
+      responseStatus,
+      duration,
+      requestBody,
+      responseHeaders,
+      responseBody,
+      error,
+    },
+    sourceRule,
+    normalizedSource
+  );
   _storage
     .writeEntry({
-      uuid: crypto.randomUUID(),
+      uuid: generateUuid(),
       batchId: TraceContext.getBatchId(),
       type: EntryType.CLIENT_REQUEST,
       content,
@@ -64,13 +198,18 @@ const emit = ({
 export const HttpClientWatcher: ITraceWatcher & { emit: typeof emit } = Object.freeze({
   emit,
   register({ storage, config }: ITraceWatcherConfig): () => void {
-    if (config.watchers.clientRequest === false) return () => undefined;
+    if (!isWatcherEnabled(config.watchers.clientRequest)) return () => undefined;
     _storage = storage;
+    _clientRequestWatcher =
+      typeof config.watchers.clientRequest === 'object' && config.watchers.clientRequest !== null
+        ? config.watchers.clientRequest
+        : undefined;
     _redactHeaderNames = [...(config.redaction?.keys ?? []), ...(config.redaction?.headers ?? [])];
     _redactBodyFields = [...(config.redaction?.keys ?? []), ...(config.redaction?.body ?? [])];
     _ignoreRoutes = config.ignoreRoutes;
     return () => {
       _storage = null;
+      _clientRequestWatcher = undefined;
       _redactBodyFields = [];
       _ignoreRoutes = [];
     };