Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

29.7 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import {
  ServerError,
  normalizeError,
  emitErrorEvent,
  errorEvents,
  errorMiddleware,
  createServiceErrorMapper,
  asyncHandler,
  buildErrorEnvelope,
  sendErrorResponse
} from './errorHandler.js';

// Build a fake Express req/res pair. `res.status()` and `res.json()` are
// chainable (they return `res`) to mirror Express, and `req.app.get('io')`
// resolves to whatever io stub the test supplies (or null for the no-io path).
function makeReqRes(io) {
  const res = { status: vi.fn(() => res), json: vi.fn(() => res) };
  const req = { method: 'GET', originalUrl: '/api/thing', app: { get: vi.fn(() => io) } };
  return { req, res };
}

// asyncHandler wires the rejection handling onto a `.catch()` microtask and the
// returned middleware does not itself return that promise — so flush the
// microtask queue before asserting the response/emit happened.
const flushMicrotasks = () => new Promise((r) => setImmediate(r));

describe('errorHandler.js', () => {
  describe('ServerError', () => {
    it('should create error with default options', () => {
      const error = new ServerError('Test error');
      expect(error.message).toBe('Test error');
      expect(error.name).toBe('ServerError');
      expect(error.status).toBe(500);
      expect(error.code).toBe('INTERNAL_ERROR');
      expect(error.severity).toBe('error');
      expect(error.canAutoFix).toBe(false);
      expect(error.timestamp).toBeDefined();
      expect(error.context).toEqual({});
      expect(error.responseMessage).toBeNull();
    });

    it('should create error with custom options', () => {
      const error = new ServerError('Not found', {
        status: 404,
        code: 'NOT_FOUND',
        severity: 'warning',
        canAutoFix: true,
        context: { resource: 'user' },
        responseMessage: 'Resource not found',
      });
      expect(error.status).toBe(404);
      expect(error.code).toBe('NOT_FOUND');
      expect(error.severity).toBe('warning');
      expect(error.canAutoFix).toBe(true);
      expect(error.context).toEqual({ resource: 'user' });
      expect(error.responseMessage).toBe('Resource not found');
    });

    it('should derive code from status when no explicit code is passed', () => {
      expect(new ServerError('nope', { status: 404 }).code).toBe('NOT_FOUND');
      expect(new ServerError('bad', { status: 400 }).code).toBe('BAD_REQUEST');
      expect(new ServerError('conflict', { status: 409 }).code).toBe('CONFLICT');
      expect(new ServerError('down', { status: 503 }).code).toBe('SERVICE_UNAVAILABLE');
    });

    it('should let an explicit code override the status-derived one', () => {
      const error = new ServerError('dup', { status: 409, code: 'DUPLICATE_ENTRY' });
      expect(error.code).toBe('DUPLICATE_ENTRY');
    });

    it('should be an instance of Error', () => {
      const error = new ServerError('Test');
      expect(error instanceof Error).toBe(true);
      expect(error instanceof ServerError).toBe(true);
    });

    it('should have stack trace', () => {
      const error = new ServerError('Test');
      expect(error.stack).toBeDefined();
      expect(error.stack).toContain('ServerError');
    });
  });

  describe('normalizeError', () => {
    it('should return ServerError as-is', () => {
      const serverError = new ServerError('Original', { status: 400 });
      const normalized = normalizeError(serverError);
      expect(normalized).toBe(serverError);
    });

    it('should convert regular Error to ServerError', () => {
      const error = new Error('Regular error');
      const normalized = normalizeError(error);
      expect(normalized instanceof ServerError).toBe(true);
      expect(normalized.message).toBe('Regular error');
      expect(normalized.status).toBe(500);
      expect(normalized.context.originalError).toBe('Error');
    });

    it('should preserve status from Error if present', () => {
      const error = new Error('Not found');
      error.status = 404;
      const normalized = normalizeError(error);
      expect(normalized.status).toBe(404);
      expect(normalized.code).toBe('NOT_FOUND');
    });

    it('should preserve code from Error if present', () => {
      const error = new Error('Conflict');
      error.code = 'DUPLICATE_ENTRY';
      const normalized = normalizeError(error);
      expect(normalized.code).toBe('DUPLICATE_ENTRY');
    });

    it.each(['ENOENT', 'EACCES', 'EISDIR', 'ENOTDIR', 'EPERM'])('hides filesystem details for %s errors', (code) => {
      const error = Object.assign(new Error(`${code}: open /private/install/data/example.json`), { code });
      const normalized = normalizeError(error);

      expect(normalized.message).toBe('Filesystem operation failed');
      expect(normalized.originalMessage).toContain('/private/install/data/example.json');
      expect(buildErrorEnvelope(normalized, {})).not.toMatchObject({ error: expect.stringContaining('/private/install') });
    });

    it('keeps the original filesystem detail available to server-side logging', () => {
      const error = Object.assign(new Error('ENOENT: open /private/install/data/example.json'), { code: 'ENOENT' });
      const normalized = normalizeError(error);
      expect(normalized.originalMessage).toBe(error.message);
    });

    it('redacts filesystem-coded ServerErrors created by route services', () => {
      const normalized = normalizeError(new ServerError('EACCES: open /private/install/data/example.json', {
        status: 500,
        code: 'EACCES',
      }));

      expect(normalized.message).toBe('Filesystem operation failed');
      expect(normalized.originalMessage).toContain('/private/install/data/example.json');
    });

    it('maps a raw ZodError to a 400 VALIDATION_ERROR', async () => {
      const { z } = await import('zod');
      const parsed = z.object({ a: z.string() }).safeParse({});
      const normalized = normalizeError(parsed.error);
      expect(normalized.status).toBe(400);
      expect(normalized.code).toBe('VALIDATION_ERROR');
      expect(normalized.context.details[0].path).toBe('a');
    });

    it('should convert string to ServerError', () => {
      const normalized = normalizeError('String error');
      expect(normalized instanceof ServerError).toBe(true);
      expect(normalized.message).toBe('String error');
      expect(normalized.status).toBe(500);
    });

    it('should convert other types to ServerError', () => {
      const normalized = normalizeError({ someObject: true });
      expect(normalized instanceof ServerError).toBe(true);
      expect(normalized.message).toBe('[object Object]');
    });

    it('should map status codes to error codes', () => {
      const testCases = [
        { status: 400, code: 'BAD_REQUEST' },
        { status: 401, code: 'UNAUTHORIZED' },
        { status: 403, code: 'FORBIDDEN' },
        { status: 404, code: 'NOT_FOUND' },
        { status: 409, code: 'CONFLICT' },
        { status: 422, code: 'VALIDATION_ERROR' },
        { status: 502, code: 'BAD_GATEWAY' },
        { status: 503, code: 'SERVICE_UNAVAILABLE' }
      ];

      for (const tc of testCases) {
        const error = new Error('Test');
        error.status = tc.status;
        const normalized = normalizeError(error);
        expect(normalized.code).toBe(tc.code);
      }
    });

    it('should default to INTERNAL_ERROR for unknown status', () => {
      const error = new Error('Test');
      error.status = 418; // I'm a teapot
      const normalized = normalizeError(error);
      expect(normalized.code).toBe('INTERNAL_ERROR');
    });

    it('preserves a request-safe response message from a service error', () => {
      const error = Object.assign(new Error('Unreadable JSON file: /private/data.json'), {
        status: 500,
        code: 'UNREADABLE_STORE',
        responseMessage: 'Durable data store is unreadable',
      });

      const normalized = normalizeError(error);

      expect(normalized.message).toContain('/private/data.json');
      expect(normalized.responseMessage).toBe('Durable data store is unreadable');
      expect(buildErrorEnvelope(normalized, {}).error).toBe('Durable data store is unreadable');
    });

    it('should unwrap err.cause chain and capture system fields', () => {
      const root = Object.assign(new Error('getaddrinfo ENOTFOUND foo.example'), {
        code: 'ENOTFOUND',
        errno: -3008,
        syscall: 'getaddrinfo',
        hostname: 'foo.example'
      });
      const wrapped = Object.assign(new TypeError('fetch failed'), { cause: root });
      const normalized = normalizeError(wrapped);
      expect(normalized.message).toBe('fetch failed');
      expect(normalized.context.causeChain).toContain('getaddrinfo ENOTFOUND foo.example');
      expect(normalized.context.cause[0]).toMatchObject({
        message: 'getaddrinfo ENOTFOUND foo.example',
        code: 'ENOTFOUND',
        errno: -3008,
        syscall: 'getaddrinfo',
        hostname: 'foo.example'
      });
    });

    it('should not loop on self-referential cause chains', () => {
      const a = new Error('a');
      const b = new Error('b');
      a.cause = b;
      b.cause = a;
      const normalized = normalizeError(a);
      expect(normalized.context.cause.length).toBeLessThanOrEqual(5);
    });
  });

  describe('errorMiddleware', () => {
    const makeRes = () => {
      const res = {};
      res.status = vi.fn(() => res);
      res.json = vi.fn(() => res);
      return res;
    };
    const makeReq = () => ({ method: 'GET', originalUrl: '/x', app: { get: () => null } });

    it('emits the standard envelope and includes non-empty sanitized context', () => {
      const res = makeRes();
      errorMiddleware(
        new ServerError('boom', { status: 404, context: { modelId: 'm', apiKey: 'secret' } }),
        makeReq(),
        res,
        () => {}
      );
      expect(res.status).toHaveBeenCalledWith(404);
      const body = res.json.mock.calls[0][0];
      expect(body.error).toBe('boom');
      expect(body.code).toBe('NOT_FOUND');
      expect(body.timestamp).toBeDefined();
      // context is forwarded but sensitive keys are stripped.
      expect(body.context).toEqual({ modelId: 'm' });
    });

    it('omits context when it is empty', () => {
      const res = makeRes();
      errorMiddleware(new ServerError('nope', { status: 400 }), makeReq(), res, () => {});
      const body = res.json.mock.calls[0][0];
      expect(body).not.toHaveProperty('context');
    });

    // A streaming/SSE route that fails mid-response has no envelope left to
    // write — delegate to Express's finalhandler so it destroys the socket
    // rather than leaving the request hanging until a timeout.
    it('delegates to next(err) when the response is already streaming', () => {
      const res = makeRes();
      res.headersSent = true;
      const next = vi.fn();
      const err = new ServerError('mid-stream', { status: 500 });
      errorMiddleware(err, makeReq(), res, next);

      expect(res.json).not.toHaveBeenCalled();
      // The normalized error is forwarded, so a falsy throw can't read as success.
      expect(next).toHaveBeenCalledWith(err);
    });

    it('does not delegate to next when the envelope was written', () => {
      const res = makeRes();
      // Express flips headersSent once the body is written — mirror that so the
      // middleware can't mistake its own write for a mid-stream failure.
      res.json = vi.fn(() => { res.headersSent = true; return res; });
      const next = vi.fn();
      errorMiddleware(new ServerError('nope', { status: 400 }), makeReq(), res, next);

      expect(res.json).toHaveBeenCalled();
      expect(next).not.toHaveBeenCalled();
    });
  });

  describe('emitErrorEvent', () => {
    it('should emit error event to errorEvents', () => {
      const listener = vi.fn();
      errorEvents.on('error', listener);

      const mockIo = {
        emit: vi.fn()
      };
      const error = new ServerError('Test error');

      emitErrorEvent(mockIo, error);

      // Listener receives (error, safeContext) — sensitive fields stripped so
      // socket.js subscribers can safely re-broadcast.
      expect(listener).toHaveBeenCalledWith(error, expect.any(Object));
      errorEvents.off('error', listener);
    });

    it('should pass sanitized context to errorEvents listeners', () => {
      const listener = vi.fn();
      errorEvents.on('error', listener);

      const mockIo = { emit: vi.fn() };
      const error = new ServerError('Test error', {
        context: { apiKey: 'secret-123', safe: 'visible' },
      });

      emitErrorEvent(mockIo, error);

      const safeContext = listener.mock.calls[0][1];
      expect(safeContext).toEqual({ safe: 'visible' });
      expect(safeContext.apiKey).toBeUndefined();
      errorEvents.off('error', listener);
    });
  });

  describe('createServiceErrorMapper', () => {
    const STATUS = { SVC_NOT_FOUND: 404, SVC_VALIDATION: 400 };

    it('maps a recognized code to a ServerError with the mapped status', () => {
      const map = createServiceErrorMapper(STATUS);
      const mapped = map(Object.assign(new Error('missing'), { code: 'SVC_NOT_FOUND' }));
      expect(mapped).toBeInstanceOf(ServerError);
      expect(mapped.status).toBe(404);
      expect(mapped.code).toBe('SVC_NOT_FOUND');
      expect(mapped.message).toBe('missing');
    });

    it('passes an unrecognized error through untouched', () => {
      const map = createServiceErrorMapper(STATUS);
      const original = Object.assign(new Error('boom'), { code: 'SOMETHING_ELSE' });
      expect(map(original)).toBe(original);
    });

    it('passes a code-less error through untouched', () => {
      const map = createServiceErrorMapper(STATUS);
      const original = new Error('plain');
      expect(map(original)).toBe(original);
    });

    it('attaches a non-empty buildContext result as context', () => {
      const map = createServiceErrorMapper(STATUS, (err) => ({ blockingSeries: err.blockingSeries }));
      const mapped = map(Object.assign(new Error('busy'), { code: 'SVC_VALIDATION', blockingSeries: ['s1'] }));
      expect(mapped.context).toEqual({ blockingSeries: ['s1'] });
    });

    it('omits context when buildContext returns undefined or an empty object', () => {
      const map = createServiceErrorMapper(STATUS, () => undefined);
      const mapped = map(Object.assign(new Error('x'), { code: 'SVC_VALIDATION' }));
      expect(mapped.context).toEqual({});

      const mapEmpty = createServiceErrorMapper(STATUS, () => ({}));
      const mappedEmpty = mapEmpty(Object.assign(new Error('y'), { code: 'SVC_VALIDATION' }));
      expect(mappedEmpty.context).toEqual({});
    });
  });

  describe('asyncHandler', () => {
    // `errorEvents` is a Node EventEmitter: emitting 'error' with zero listeners
    // re-throws the argument (the classic footgun). Production always has
    // subscribers (autoFixer / socket.js); keep a noop attached so emitErrorEvent
    // doesn't throw out of asyncHandler's catch during these tests.
    // Cleanup lives in afterEach (not test bodies) so a failing assertion can't
    // leak the noop listener, any test-registered listener, or the console.error
    // spy into sibling tests.
    let noopErrorListener;
    let errorSpy;
    let logSpy;
    let testListeners;
    // Register an errorEvents 'error' listener that this describe will remove.
    const trackListener = (fn) => { testListeners.push(fn); errorEvents.on('error', fn); };

    beforeEach(() => {
      testListeners = [];
      noopErrorListener = () => {};
      errorEvents.on('error', noopErrorListener);
      errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
      logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
    });
    afterEach(() => {
      errorEvents.off('error', noopErrorListener);
      for (const fn of testListeners) errorEvents.off('error', fn);
      errorSpy.mockRestore();
      logSpy.mockRestore();
    });

    it('catches a thrown ServerError, emits, and responds with status + body', async () => {
      const io = { emit: vi.fn() };
      const { req, res } = makeReqRes(io);
      const events = [];
      trackListener((err, ctx) => events.push({ err, ctx }));

      const handler = asyncHandler(async () => {
        throw new ServerError('nope', { status: 403, code: 'FORBIDDEN', context: { detail: 'x' } });
      });
      await handler(req, res, vi.fn());
      await flushMicrotasks();

      expect(res.status).toHaveBeenCalledWith(403);
      const body = res.json.mock.calls[0][0];
      expect(body.error).toBe('nope');
      expect(body.code).toBe('FORBIDDEN');
      expect(body.timestamp).toBeDefined();
      expect(body.context).toEqual({ detail: 'x' });
      // Both channels fire: the process-local errorEvents emitter and the io broadcast.
      expect(events).toHaveLength(1);
      expect(io.emit).toHaveBeenCalledWith(
        'error:occurred',
        expect.objectContaining({ code: 'FORBIDDEN', status: 403, message: 'nope' })
      );
    });

    it('normalizes a plain thrown Error to a 500 INTERNAL_ERROR response', async () => {
      const io = { emit: vi.fn() };
      const { req, res } = makeReqRes(io);

      const handler = asyncHandler(async () => {
        throw new Error('kaboom');
      });
      await handler(req, res, vi.fn());
      await flushMicrotasks();

      expect(res.status).toHaveBeenCalledWith(500);
      const body = res.json.mock.calls[0][0];
      expect(body.code).toBe('INTERNAL_ERROR');
      expect(body.error).toBe('kaboom');
    });

    // Mid-stream the envelope can't land, so the catch hands off to the error
    // chain WITHOUT reporting locally — errorMiddleware logs/emits it once and
    // then lets finalhandler destroy the socket.
    it('delegates to next() without reporting when the handler throws mid-stream', async () => {
      const io = { emit: vi.fn() };
      const { req, res } = makeReqRes(io);
      res.headersSent = true;
      const next = vi.fn();
      const boom = new ServerError('mid-stream', { status: 500 });

      await asyncHandler(async () => { throw boom; })(req, res, next);
      await flushMicrotasks();

      expect(res.json).not.toHaveBeenCalled();
      expect(io.emit).not.toHaveBeenCalled();
      expect(next).toHaveBeenCalledWith(boom);
    });

    // `throw null` must not reach next() as a falsy value — Express would read
    // that as "no error" and keep routing, hanging the request.
    it('normalizes a falsy throw before delegating mid-stream', async () => {
      const { req, res } = makeReqRes(null);
      res.headersSent = true;
      const next = vi.fn();

      await asyncHandler(async () => { throw null; })(req, res, next);
      await flushMicrotasks();

      expect(next).toHaveBeenCalledWith(expect.any(ServerError));
    });

    it('does not touch res when the wrapped handler resolves successfully', async () => {
      const { req, res } = makeReqRes({ emit: vi.fn() });

      const handler = asyncHandler(async () => 'ok');
      await handler(req, res, vi.fn());
      await flushMicrotasks();

      expect(res.status).not.toHaveBeenCalled();
      expect(res.json).not.toHaveBeenCalled();
    });

    it('still responds when no io is registered on the app', async () => {
      const { req, res } = makeReqRes(null);

      const handler = asyncHandler(async () => {
        throw new ServerError('missing', { status: 404 });
      });
      await handler(req, res, vi.fn());
      await flushMicrotasks();

      expect(res.status).toHaveBeenCalledWith(404);
      // status→code derivation still runs even without an io channel.
      expect(res.json.mock.calls[0][0].code).toBe('NOT_FOUND');
    });

    // `validateRequest` sets `context.details` to the full mapped Zod issue
    // array, so JSON.stringify-ing it emitted a multi-KB blob per 400 —
    // against the single-line logging convention. The log line must summarize;
    // the RESPONSE body must still carry every entry.
    it('summarizes a long details array into one line without stringifying it', async () => {
      const { req, res } = makeReqRes(null);
      const details = Array.from({ length: 12 }, (_, i) => ({
        path: `body.field${i}`,
        message: 'Required'
      }));

      await asyncHandler(async () => {
        throw new ServerError('Validation failed', {
          status: 400,
          code: 'VALIDATION_ERROR',
          context: { details }
        });
      })(req, res, vi.fn());
      await flushMicrotasks();

      expect(logSpy).toHaveBeenCalledTimes(1);
      const [line, ...extraArgs] = logSpy.mock.calls[0];
      expect(extraArgs).toEqual([]);
      expect(line).not.toContain('\n');
      expect(line).not.toContain('[{');
      expect(line).not.toContain('"path"');
      expect(line).toContain('body.field0: Required');
      expect(line).toContain('body.field4: Required');
      expect(line).not.toContain('body.field5');
      expect(line).toContain('(+7 more)');

      // Logging-only change: the envelope still carries the full array.
      expect(res.json.mock.calls[0][0].context.details).toEqual(details);
    });

    // dbAdmin puts raw pg_dump/pg_restore stderr in the same field.
    it('collapses a multi-line string details value to one truncated line', async () => {
      const { req, res } = makeReqRes(null);
      const details = `pg_dump: error: connection to server failed\n${'x'.repeat(500)}\ntrailing`;

      await asyncHandler(async () => {
        throw new ServerError('Export failed', { status: 400, context: { details } });
      })(req, res, vi.fn());
      await flushMicrotasks();

      const line = logSpy.mock.calls[0][0];
      expect(line).not.toContain('\n');
      expect(line).toContain('pg_dump: error: connection to server failed');
      expect(line).not.toContain('trailing');
      expect(line.endsWith('…')).toBe(true);
    });

    // `[]` and `{}` are truthy but summarize to nothing.
    it('omits the details segment entirely when it summarizes to nothing', async () => {
      const { req, res } = makeReqRes(null);

      await asyncHandler(async () => {
        throw new ServerError('Validation failed', { status: 400, context: { details: [] } });
      })(req, res, vi.fn());
      await flushMicrotasks();

      expect(logSpy.mock.calls[0][0]).toBe('🚫 Route refused [GET /api/thing] 400: Validation failed');
    });

    // stderr is reserved for faults worth investigating: a 4xx is the server
    // refusing a request (a guard's 409, validation, not-found), so it stays on
    // stdout unless the thrower marked it critical.
    it('routes a 4xx refusal to stdout and only 5xx/critical to stderr', async () => {
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        for (const status of [400, 404, 409]) {
          await asyncHandler(async () => { throw new ServerError('kept', { status }); })(makeReqRes(null).req, makeReqRes(null).res, vi.fn());
        }
        await flushMicrotasks();
        expect(errorSpy).not.toHaveBeenCalled();
        expect(warnSpy).not.toHaveBeenCalled();
        expect(logSpy.mock.calls.map(([line]) => line)).toEqual([
          '🚫 Route refused [GET /api/thing] 400: kept',
          '🚫 Route refused [GET /api/thing] 404: kept',
          '🚫 Route refused [GET /api/thing] 409: kept',
        ]);

        await asyncHandler(async () => { throw new ServerError('bad', { status: 409, severity: 'critical' }); })(makeReqRes(null).req, makeReqRes(null).res, vi.fn());
        await flushMicrotasks();
        expect(errorSpy).toHaveBeenCalledTimes(1);
        expect(errorSpy.mock.calls[0][0]).toBe('❌ Route error [GET /api/thing]: bad');
      } finally {
        warnSpy.mockRestore();
      }
    });

    // The 500 branch logs the stack, not `details` — it must stay untouched.
    it('leaves the 500 stack branch alone', async () => {
      const { req, res } = makeReqRes(null);
      const error = new ServerError('boom', { status: 500, context: { details: [{ path: 'a', message: 'b' }] } });

      await asyncHandler(async () => { throw error; })(req, res, vi.fn());
      await flushMicrotasks();

      expect(errorSpy).toHaveBeenCalledTimes(1);
      const [line, stack] = errorSpy.mock.calls[0];
      expect(line).not.toContain('a: b');
      expect(stack).toBe(error.stack);
    });

    // Regression: a plain Error thrown from a service function must log its
    // original stack location, not the normalizeError wrapper's stack. Use a
    // named synthetic throwing function so the location is stable and visible
    // in the stack trace.
    it('preserves the original Error stack when normalizing a 500 error through asyncHandler', async () => {
      const { req, res } = makeReqRes(null);

      // Define a named function that throws a plain Error (not a ServerError).
      function syntheticServiceFunction() {
        throw new Error('Service error from syntheticServiceFunction');
      }

      await asyncHandler(async () => {
        syntheticServiceFunction();
      })(req, res, vi.fn());
      await flushMicrotasks();

      expect(errorSpy).toHaveBeenCalledTimes(1);
      const [, stack] = errorSpy.mock.calls[0];

      // The logged stack must contain the original throwing function's name,
      // not normalizeError. This proves the originalStack field was captured
      // and used for logging.
      expect(stack).toContain('syntheticServiceFunction');
      expect(stack).not.toContain('normalizeError');
    });

    // --- regression tests for #12586: structured details must render as JSON ---
    it('renders nested object/array details as readable JSON, not [object Object]', async () => {
      const { req, res } = makeReqRes(null);
      const details = {
        ahead: [{ universe: 'core', version: 13 }],
        behind: [],
        senderPortosVersion: '12.4.1',
      };

      await asyncHandler(async () => {
        throw new ServerError('schema version conflict', {
          status: 409,
          code: 'CONFLICT',
          context: { details },
        });
      })(req, res, vi.fn());
      await flushMicrotasks();

      const line = logSpy.mock.calls[0][0];
      expect(line).not.toContain('[object Object]');
      expect(line).toContain('ahead=[{"universe":"core","version":13}]');
      expect(line).toContain('behind=[]');
      expect(line).toContain('senderPortosVersion=12.4.1');
    });

    it('renders a cyclic details value as a bounded placeholder without throwing', async () => {
      const { req, res } = makeReqRes(null);
      const cyclic = {};
      cyclic.self = cyclic;
      const details = { bad: cyclic };

      await asyncHandler(async () => {
        throw new ServerError('cyclic context', {
          status: 409,
          code: 'CONFLICT',
          context: { details },
        });
      })(req, res, vi.fn());
      await flushMicrotasks();

      expect(logSpy).toHaveBeenCalledTimes(1);
      const line = logSpy.mock.calls[0][0];
      expect(line).toContain('bad=[unserializable]');
    });
  });

  describe('sendErrorResponse', () => {
    const makeRes = (overrides = {}) => {
      const res = { headersSent: false, ...overrides };
      res.status = vi.fn(() => res);
      res.json = vi.fn(() => res);
      return res;
    };

    it('emits the standard envelope for callers outside a handler catch', () => {
      const res = makeRes();
      sendErrorResponse(res, new ServerError('Sample not found', { status: 404 }));

      expect(res.status).toHaveBeenCalledWith(404);
      const body = res.json.mock.calls[0][0];
      expect(body.error).toBe('Sample not found');
      expect(body.code).toBe('NOT_FOUND');
      expect(typeof body.timestamp).toBe('number');
    });

    it('normalizes a plain Error and returns the ServerError to the caller', () => {
      const res = makeRes();
      const error = sendErrorResponse(res, new Error('kaboom'));

      expect(error).toBeInstanceOf(ServerError);
      expect(res.status).toHaveBeenCalledWith(500);
      expect(res.json.mock.calls[0][0].code).toBe('INTERNAL_ERROR');
    });

    it('does not write once headers are already sent', () => {
      const res = makeRes({ headersSent: true });
      sendErrorResponse(res, new ServerError('too late', { status: 404 }));

      expect(res.status).not.toHaveBeenCalled();
      expect(res.json).not.toHaveBeenCalled();
    });

    it('emits the socket event with the sanitized context when io is supplied', () => {
      const res = makeRes();
      const io = { emit: vi.fn() };
      // `errorEvents` is an EventEmitter — an 'error' emit with no listener
      // re-throws, so subscribe for the duration of this assertion.
      const listener = vi.fn();
      errorEvents.on('error', listener);
      sendErrorResponse(
        res,
        new ServerError('boom for local peer', {
          status: 400,
          context: { modelId: 'm', apiKey: 'secret' },
          responseMessage: 'Request failed',
        }),
        { io }
      );

      const payload = io.emit.mock.calls.find(([event]) => event === 'error:occurred')[1];
      expect(payload.message).toBe('boom for local peer');
      expect(payload.context).toEqual({ modelId: 'm' });
      expect(res.json.mock.calls[0][0].error).toBe('Request failed');
      expect(res.json.mock.calls[0][0].context).toEqual({ modelId: 'm' });
      errorEvents.off('error', listener);
    });
  });

  describe('buildErrorEnvelope', () => {
    it('omits context when the sanitized context is empty', () => {
      const body = buildErrorEnvelope(new ServerError('nope', { status: 400 }), {});
      expect(body).toEqual({ error: 'nope', code: 'BAD_REQUEST', timestamp: expect.any(Number) });
    });

    it('can keep a detailed local message out of the HTTP response', () => {
      const error = new ServerError('Disabled for peer "Example Peer"', {
        status: 503,
        code: 'MEDIA_PROVIDER_DISABLED',
        responseMessage: 'Federated media provider is disabled',
      });

      expect(buildErrorEnvelope(error, {})).toEqual({
        error: 'Federated media provider is disabled',
        code: 'MEDIA_PROVIDER_DISABLED',
        timestamp: expect.any(Number),
      });
      expect(error.message).toContain('Example Peer');
    });
  });
});