@elisra-devops/docgen-data-provider 1.141.0 → 1.142.0

package/src/tests/utils/logger.test.ts

@@ -169,6 +169,117 @@ describe('DiagnosticsTransport (Phase 6a)', () => {
   });
 });
 
+describe('DiagnosticsTransport request context', () => {
+  function makeLogger() {
+    return winston.createLogger({
+      level: 'silly',
+      format: winston.format.combine(
+        winston.format.errors({ stack: true }),
+        winston.format.timestamp(),
+        redact(),
+        winston.format.splat(),
+        winston.format.json()
+      ),
+      transports: [new DiagnosticsTransport()],
+    });
+  }
+
+  test('persists an annotated error\'s request as event.context, however the call site words its message', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const err = Object.assign(new Error('Request failed with status code 404'), {
+      adoRequest: { method: 'GET', url: 'https://dev.azure.com/org/_apis/x', status: 404, attempt: 1, responseExcerpt: 'nope' },
+    });
+
+    makeLogger().error(err); // the bare-error shape (3 call sites) — no stable message at all
+
+    expect(events[0].context).toEqual({
+      method: 'GET',
+      url: 'https://dev.azure.com/org/_apis/x',
+      status: 404,
+      attempt: 1,
+      responseExcerpt: 'nope',
+    });
+  });
+
+  test('also works for the stable-message + error shape and for the explicit meta shape', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const logger = makeLogger();
+    const ctx = { method: 'POST', url: 'https://h/wiql', requestBody: '{"query":"q"}' };
+
+    logger.error('Failed querying work items', Object.assign(new Error('boom'), { adoRequest: ctx }));
+    logger.error('ADO request failed', { message: 'boom', stack: 'at x', adoRequest: ctx });
+
+    expect(events[0].context).toEqual(ctx);
+    expect(events[1].context).toEqual(ctx);
+  });
+
+  test('an event with no request context has no context field', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    makeLogger().error('plain failure', new Error('boom'));
+    expect(events[0].context).toBeUndefined();
+  });
+
+  test('re-validates the shape at the transport: unknown keys, wrong types and oversize values are dropped or bounded', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const err = Object.assign(new Error('x'), {
+      adoRequest: {
+        method: 'GET',
+        url: 'u'.repeat(5000),
+        status: 'not-a-number',
+        attempt: 2,
+        requestBody: 'b'.repeat(5000),
+        secretHeader: 'Bearer abc',
+      },
+    });
+
+    makeLogger().error('m', err);
+
+    const ctx = events[0].context!;
+    expect(ctx.url!.length).toBe(1000);
+    expect(ctx.requestBody!.length).toBe(2000);
+    expect(ctx.status).toBeUndefined();
+    expect(ctx.attempt).toBe(2);
+    expect(ctx).not.toHaveProperty('secretHeader');
+  });
+});
+
+describe('text format request suffix', () => {
+  // The default (LOG_FORMAT unset) prints only the message — without this the URL would never
+  // reach stdout for a record whose own message doesn't carry it. A stream transport on the
+  // real logger receives the already-formatted line, independent of how jest wires console.
+  test('appends the request to the printed line when the error carries one, and never throws', () => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const logger = require('../../utils/logger').default;
+    const { Writable } = require('stream');
+    const lines: string[] = [];
+    const sink = new winston.transports.Stream({
+      stream: new Writable({
+        write(chunk: Buffer, _enc: string, cb: () => void) {
+          lines.push(chunk.toString());
+          cb();
+        },
+      }),
+    });
+    logger.add(sink);
+    try {
+      const err = Object.assign(new Error('Request failed with status code 404'), {
+        adoRequest: { method: 'GET', url: 'https://dev.azure.com/org/_apis/x', status: 404 },
+      });
+      expect(() => logger.error('Failed fetching', err)).not.toThrow();
+      expect(() => logger.error('odd', Object.assign(new Error('e'), { adoRequest: { url: 123 } }))).not.toThrow();
+    } finally {
+      logger.remove(sink);
+    }
+    const joined = lines.join('');
+    expect(joined).toContain('[GET https://dev.azure.com/org/_apis/x -> 404]');
+    expect(joined).toContain('Failed fetching');
+  });
+});
+
 describe('textFormat safety (regression)', () => {
   // The hostile-input matrix above exercises makeTestLogger()'s json() pipeline — it never
   // touched the real singleton logger's text-format branch (LOG_FORMAT's default), which is

package/src/utils/logSink.ts

@@ -2,9 +2,16 @@
 
 // The one queryable-error-store event shape, emitted by DiagnosticsTransport (logger.ts).
 // This package never installs a sink itself — it only reads whatever the host process
-// (docgen-content-control's index.ts) installed. err is intentionally narrow —
-// {message, code, stack} — per the settled Phase 6 schema decision: no generic
-// extra-fields bucket.
+// (docgen-content-control's index.ts) installed. err stays narrow — {message, code, stack}.
+// `context` is the one deliberate exception to "no extra-fields bucket": a sanitized
+// description of the failed outbound request (method, url, status, attempt, request-body
+// summary, response excerpt) — without it a 404 in the dashboard can't be traced to the call
+// that produced it. A fixed, allowlisted shape, not a free-form bag.
+// Bounds for DiagnosticEvent.context. Single source for this package (requestContext.ts and the
+// logger transport); docgen-api-gate's DiagnosticsController.sanitizeContext re-validates at
+// ingest with its own copy — keep the two in step.
+export const CONTEXT_LIMITS = { method: 10, url: 1000, requestBody: 2000, responseExcerpt: 300 } as const;
+
 export interface DiagnosticEvent {
   ts: string;
   level: string;
@@ -19,6 +26,14 @@ export interface DiagnosticEvent {
   userId?: string;
   message: string;
   err?: { message: string; code?: string; stack?: string };
+  context?: {
+    method?: string;
+    url?: string;
+    status?: number;
+    attempt?: number;
+    requestBody?: string;
+    responseExcerpt?: string;
+  };
   // Phase 6b — set on a debug/info event captured under retain-on-failure. Deleted by
   // api-gate at the run's one success point; left alone (and thus permanent, subject to the
   // normal TTL) if the run fails.

package/src/utils/logger.ts

@@ -4,7 +4,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as Transport from 'winston-transport';
 import { runContextStore } from './runContext';
-import { getLogSink, DiagnosticEvent } from './logSink';
+import { getLogSink, DiagnosticEvent, CONTEXT_LIMITS } from './logSink';
 let logger: winston.Logger;
 
 // Merges the ambient runId (set by content-control's request middleware, once Phase 3 lands
@@ -44,7 +44,7 @@ function safeRead(obj: Record<string, unknown>, key: string): { ok: true; value:
     return { ok: false };
   }
 }
-function redactValue(value: unknown, depth = 0, seen = new WeakSet<object>()): unknown {
+export function redactValue(value: unknown, depth = 0, seen = new WeakSet<object>()): unknown {
   if (depth > 6 || value === null || typeof value !== 'object') return value;
   if (seen.has(value as object)) return '[Circular]';
   seen.add(value as object);
@@ -116,7 +116,26 @@ function readOwnVersion(): string {
 const safeMessageString = (value: unknown): string =>
   typeof value === 'symbol' ? value.toString() : String(value);
 
-const textFormat = winston.format.printf((info) => `${info.timestamp} - ${info.level}: ${safeMessageString(info.message)}`);
+// A failed ADO request's description (helpers/requestContext.ts), attached to the thrown error
+// and merged onto the record by winston. In text mode — the default, which prints only the
+// message — this is the only way the URL reaches stdout for a record whose own message doesn't
+// carry it. Never throws: this runs inside the formatter, which has no try/catch around it.
+const requestSuffix = (ctx: unknown): string => {
+  try {
+    if (!ctx || typeof ctx !== 'object') return '';
+    const c = ctx as Record<string, unknown>;
+    if (typeof c.url !== 'string') return '';
+    const method = typeof c.method === 'string' ? `${c.method} ` : '';
+    const status = typeof c.status === 'number' ? ` -> ${c.status}` : '';
+    return ` [${method}${c.url}${status}]`;
+  } catch {
+    return '';
+  }
+};
+
+const textFormat = winston.format.printf(
+  (info) => `${info.timestamp} - ${info.level}: ${safeMessageString(info.message)}${requestSuffix(info.adoRequest)}`
+);
 
 // Bounded so one oversized message/stack can't produce an unbounded LogEvent document.
 const MAX_MESSAGE_LEN = 2000;
@@ -126,6 +145,26 @@ function clamp(value: unknown, max: number): string | undefined {
   return value.length > max ? value.slice(0, max) : value;
 }
 
+// Re-validates the request description at the transport instead of trusting its shape — it
+// arrives via an Error's own properties, which anything upstream could have set. Allowlisted
+// keys only, each type-checked and bounded.
+function pickContext(raw: unknown): DiagnosticEvent['context'] {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const c = raw as Record<string, unknown>;
+  const context: NonNullable<DiagnosticEvent['context']> = {};
+  const method = clamp(c.method, CONTEXT_LIMITS.method);
+  const url = clamp(c.url, CONTEXT_LIMITS.url);
+  const requestBody = clamp(c.requestBody, CONTEXT_LIMITS.requestBody);
+  const responseExcerpt = clamp(c.responseExcerpt, CONTEXT_LIMITS.responseExcerpt);
+  if (method) context.method = method;
+  if (url) context.url = url;
+  if (requestBody) context.requestBody = requestBody;
+  if (responseExcerpt) context.responseExcerpt = responseExcerpt;
+  if (typeof c.status === 'number' && Number.isFinite(c.status)) context.status = c.status;
+  if (typeof c.attempt === 'number' && Number.isFinite(c.attempt)) context.attempt = c.attempt;
+  return Object.keys(context).length ? context : undefined;
+}
+
 // Ships warn/error records to whatever LogSink the host process (docgen-content-control's
 // index.ts) has installed — this package never installs one itself, only reads it. This is
 // the dominant source of real ADO error records (tfs.ts's executeWithRetry is the single
@@ -182,6 +221,7 @@ export class DiagnosticsTransport extends Transport {
                 stack: clamp(info.stack, MAX_STACK_LEN),
               }
             : undefined,
+          context: pickContext(info.adoRequest),
           retainPending: !isWarnOrError && captureMode === 'retain-on-failure' ? true : undefined,
         };
         getLogSink()?.push(event);