@bajustone/fortress 1.0.0-rc.1

package/src/core/observability/listener-list.test.ts

@@ -0,0 +1,124 @@
+import type { FortressLogger } from './logger';
+import { describe, expect, it, vi } from 'vitest';
+import { createListenerList } from './listener-list';
+import { SILENT_LOGGER } from './logger';
+
+function mockLogger(): FortressLogger & { errorSpy: ReturnType<typeof vi.fn> } {
+  const errorSpy = vi.fn();
+  return {
+    ...SILENT_LOGGER,
+    error: errorSpy,
+    errorSpy,
+  };
+}
+
+describe('createListenerList (sync)', () => {
+  it('invokes listeners in registration order and returns an unsubscribe fn', () => {
+    const logger = mockLogger();
+    const list = createListenerList<number>({
+      kind: 'sync',
+      eventLabel: 'test',
+      logger: () => logger,
+    });
+
+    const calls: string[] = [];
+    const off1 = list.add((n) => {
+      calls.push(`a:${n}`);
+    });
+    const off2 = list.add((n) => {
+      calls.push(`b:${n}`);
+    });
+    expect(list.size()).toBe(2);
+
+    list.emit(1);
+    expect(calls).toEqual(['a:1', 'b:1']);
+
+    off1();
+    list.emit(2);
+    expect(calls).toEqual(['a:1', 'b:1', 'b:2']);
+
+    off2();
+    expect(list.size()).toBe(0);
+    list.emit(3);
+    expect(calls).toEqual(['a:1', 'b:1', 'b:2']);
+  });
+
+  it('catches thrown errors and routes them to the logger', () => {
+    const logger = mockLogger();
+    const list = createListenerList<{ id: string }>({
+      kind: 'sync',
+      eventLabel: 'boom',
+      logger: () => logger,
+    });
+
+    list.add(() => {
+      throw new Error('listener bug');
+    });
+    list.add(() => {
+      // healthy listener
+    });
+
+    // Emit should NOT throw — error is routed to logger.error.
+    expect(() => list.emit({ id: '1' })).not.toThrow();
+    expect(logger.errorSpy).toHaveBeenCalledTimes(1);
+    expect(logger.errorSpy.mock.calls[0][0]).toMatchObject({
+      event: 'boom',
+    });
+  });
+
+  it('remaining listeners still fire after one throws', () => {
+    const logger = mockLogger();
+    const list = createListenerList<number>({
+      kind: 'sync',
+      eventLabel: 'test',
+      logger: () => logger,
+    });
+    const after = vi.fn();
+    list.add(() => {
+      throw new Error('first listener');
+    });
+    list.add(after);
+    list.emit(42);
+    expect(after).toHaveBeenCalledWith(42);
+  });
+});
+
+describe('createListenerList (async)', () => {
+  it('fires listeners without awaiting their resolution', async () => {
+    const logger = mockLogger();
+    const list = createListenerList<string>({
+      kind: 'async',
+      eventLabel: 'async',
+      logger: () => logger,
+    });
+
+    let resolved = false;
+    list.add(async (v) => {
+      await new Promise(r => setTimeout(r, 10));
+      resolved = true;
+      expect(v).toBe('hello');
+    });
+
+    list.emit('hello');
+    // Listener hasn't finished yet — emit is non-blocking.
+    expect(resolved).toBe(false);
+    await new Promise(r => setTimeout(r, 30));
+    expect(resolved).toBe(true);
+  });
+
+  it('routes rejected promises to logger.error', async () => {
+    const logger = mockLogger();
+    const list = createListenerList<number>({
+      kind: 'async',
+      eventLabel: 'async',
+      logger: () => logger,
+    });
+    list.add(async () => {
+      throw new Error('async boom');
+    });
+
+    list.emit(1);
+    await new Promise(r => setTimeout(r, 10));
+    expect(logger.errorSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/core/observability/listener-list.ts

@@ -0,0 +1,73 @@
+import type { FortressLogger } from './logger';
+
+export type Unsubscribe = () => void;
+
+export interface ListenerList<E> {
+  emit: (event: E) => void;
+  add: (listener: (event: E) => void | Promise<void>) => Unsubscribe;
+  size: () => number;
+}
+
+/**
+ * Create a typed listener list with error routing and a sync/async contract.
+ *
+ * - `sync` kind: listeners return `void`. Used for hot-path observers
+ *   (permission checks) where the type signature discourages awaiting
+ *   expensive work inline.
+ * - `async` kind: listeners may return `void | Promise<void>`. Promises
+ *   returned by listeners are attached a `.catch` that routes failures to
+ *   the logger at `error` level — observer bugs never break the caller.
+ *
+ *   **Error-routing gotcha (async kind):** the safety net only engages
+ *   when the listener *returns* the promise. A listener that fires work
+ *   via `void asyncWork()` inside a sync body returns `undefined`, so the
+ *   listener list cannot observe a later rejection — it escapes to the
+ *   runtime's unhandled-rejection handler. If you want the safety net,
+ *   `return asyncWork()` or make the whole body `async`. `void asyncWork()`
+ *   is an explicit opt-out.
+ *
+ * The `logger` parameter is a thunk so the list can resolve the current
+ * logger lazily — allowing callers to construct the list before the final
+ * logger is available in the closure.
+ */
+export function createListenerList<E>(opts: {
+  kind: 'sync' | 'async';
+  eventLabel: string;
+  logger: () => FortressLogger;
+}): ListenerList<E> {
+  const listeners: Array<(event: E) => void | Promise<void>> = [];
+
+  return {
+    emit(event: E): void {
+      for (const listener of listeners) {
+        try {
+          const result = listener(event);
+          if (opts.kind === 'async' && result instanceof Promise) {
+            result.catch((err: unknown) => {
+              opts.logger().error(
+                { err, event: opts.eventLabel },
+                'fortress observer threw',
+              );
+            });
+          }
+        }
+        catch (err) {
+          opts.logger().error(
+            { err, event: opts.eventLabel },
+            'fortress observer threw',
+          );
+        }
+      }
+    },
+    add(listener): Unsubscribe {
+      listeners.push(listener);
+      return () => {
+        const i = listeners.indexOf(listener);
+        if (i >= 0) {
+          listeners.splice(i, 1);
+        }
+      };
+    },
+    size: () => listeners.length,
+  };
+}

package/src/core/observability/logger.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { SILENT_LOGGER } from './logger';
+
+describe('sILENT_LOGGER', () => {
+  it('is a no-op — every level callable with zero side effects', () => {
+    expect(SILENT_LOGGER.level).toBe('silent');
+    expect(() => SILENT_LOGGER.fatal('msg')).not.toThrow();
+    expect(() => SILENT_LOGGER.error('msg')).not.toThrow();
+    expect(() => SILENT_LOGGER.warn('msg')).not.toThrow();
+    expect(() => SILENT_LOGGER.info('msg')).not.toThrow();
+    expect(() => SILENT_LOGGER.debug('msg')).not.toThrow();
+    expect(() => SILENT_LOGGER.trace('msg')).not.toThrow();
+    expect(() => SILENT_LOGGER.silent('msg')).not.toThrow();
+  });
+
+  it('accepts the three pino-compatible argument shapes at every level', () => {
+    expect(() => SILENT_LOGGER.info('just a string')).not.toThrow();
+    expect(() => SILENT_LOGGER.info({ key: 'value' }, 'with object')).not.toThrow();
+    expect(() => SILENT_LOGGER.info('format %s', 'arg')).not.toThrow();
+  });
+
+  it('isLevelEnabled always returns false for the silent default', () => {
+    expect(SILENT_LOGGER.isLevelEnabled?.('debug')).toBe(false);
+    expect(SILENT_LOGGER.isLevelEnabled?.('error')).toBe(false);
+  });
+
+  it('is structurally compatible with a hand-rolled console logger', () => {
+    const calls: string[] = [];
+    const consoleLogger = {
+      level: 'info',
+      fatal: (...args: unknown[]): void => { calls.push(`fatal:${JSON.stringify(args)}`); },
+      error: (...args: unknown[]): void => { calls.push(`error:${JSON.stringify(args)}`); },
+      warn: (...args: unknown[]): void => { calls.push(`warn:${JSON.stringify(args)}`); },
+      info: (...args: unknown[]): void => { calls.push(`info:${JSON.stringify(args)}`); },
+      debug: (...args: unknown[]): void => { calls.push(`debug:${JSON.stringify(args)}`); },
+      trace: (...args: unknown[]): void => { calls.push(`trace:${JSON.stringify(args)}`); },
+      silent: (): void => {},
+    };
+    consoleLogger.warn({ plugin: 'test' }, 'warning');
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toContain('warn:');
+  });
+});

package/src/core/observability/logger.ts

@@ -0,0 +1,49 @@
+/**
+ * Structural logger contract. Shaped to be assignment-compatible with pino's
+ * `BaseLogger` and Fastify's `FastifyBaseLogger`, so consumers can drop a
+ * `pino()` instance or `fastify.log` in directly with zero adapter code.
+ *
+ * The default is {@link SILENT_LOGGER} — libraries that log to stderr by
+ * default are universally hated. Opt-in logging only.
+ */
+
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+export interface LogFn {
+  (msg: string): void;
+  (obj: Record<string, unknown>, msg?: string): void;
+  (msg: string, ...args: unknown[]): void;
+}
+
+export interface FortressLogger {
+  level: LogLevel | 'silent' | string;
+  fatal: LogFn;
+  error: LogFn;
+  warn: LogFn;
+  info: LogFn;
+  debug: LogFn;
+  trace: LogFn;
+  silent: LogFn;
+  /** Optional on pino/Fastify; Fortress calls it defensively. */
+  child?: (bindings: Record<string, unknown>) => FortressLogger;
+  /** Optional guard for lazy evaluation of expensive log metadata. */
+  isLevelEnabled?: (level: LogLevel) => boolean;
+}
+
+const NOOP: LogFn = () => {};
+
+/**
+ * No-op logger used when {@link FortressConfig.logger} is unset. Every method
+ * is a shared arrow function — zero allocation per call.
+ */
+export const SILENT_LOGGER: FortressLogger = {
+  level: 'silent',
+  fatal: NOOP,
+  error: NOOP,
+  warn: NOOP,
+  info: NOOP,
+  debug: NOOP,
+  trace: NOOP,
+  silent: NOOP,
+  isLevelEnabled: () => false,
+};

package/src/core/observability/spans.test.ts

@@ -0,0 +1,193 @@
+import type { Fortress } from '../fortress';
+import type { Attributes, AttributeValue, Span, TelemetryProvider } from './types';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+import { NO_OP_TELEMETRY } from './types';
+
+interface SpanRecord {
+  name: string;
+  attributes: Record<string, AttributeValue>;
+  ended: boolean;
+  status?: { code: 'ok' | 'error'; message?: string };
+  exception?: unknown;
+}
+
+/**
+ * Build a {@link TelemetryProvider} that records every span that gets
+ * started — used here instead of `@opentelemetry/sdk-trace-base` so we
+ * can assert on spans without adding another dev dep. The meter falls
+ * back to no-op because these tests only care about spans.
+ */
+function createSpyTelemetry(): { provider: TelemetryProvider; spans: SpanRecord[] } {
+  const spans: SpanRecord[] = [];
+  const startSpan = (name: string, attributes?: Attributes): Span => {
+    const record: SpanRecord = {
+      name,
+      attributes: { ...(attributes ?? {}) },
+      ended: false,
+    };
+    spans.push(record);
+    return {
+      setAttribute(key, value): void {
+        record.attributes[key] = value;
+      },
+      recordException(error): void {
+        record.exception = error;
+      },
+      setStatus(status): void {
+        record.status = status;
+      },
+      end(): void {
+        record.ended = true;
+      },
+    };
+  };
+  return {
+    provider: {
+      tracer: {
+        startSpan,
+        async startActiveSpan(name, attributes, callback) {
+          return callback(startSpan(name, attributes));
+        },
+      },
+      meter: NO_OP_TELEMETRY.meter,
+    },
+    spans,
+  };
+}
+
+const SECRET = 'span-test-secret-must-be-32-chars!';
+
+let fortress: Fortress;
+let spans: SpanRecord[];
+
+describe('handleRequest outer span', () => {
+  beforeEach(async () => {
+    const telemetry = createSpyTelemetry();
+    spans = telemetry.spans;
+    fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      observability: telemetry.provider,
+    });
+    await fortress.auth.createUser({
+      email: 'spans@example.com',
+      name: 'Span User',
+      password: 'password-123456',
+    });
+  });
+
+  it('falls back to startSpan for legacy custom telemetry providers', async () => {
+    const telemetry = createSpyTelemetry();
+    delete telemetry.provider.tracer.startActiveSpan;
+    const legacyFortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      observability: telemetry.provider,
+    });
+
+    const response = await legacyFortress.handleRequest(new Request('http://localhost/nope'));
+    expect(response.status).toBe(404);
+    expect(telemetry.spans.find(span => span.name === 'fortress.handleRequest')?.ended).toBe(true);
+  });
+
+  it('starts and ends a fortress.handleRequest span for every dispatched request', async () => {
+    const res = await fortress.handleRequest(
+      new Request('http://local/auth/login', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ identifier: 'spans@example.com', password: 'password-123456' }),
+      }),
+    );
+    expect(res.status).toBe(200);
+
+    const requestSpans = spans.filter(s => s.name === 'fortress.handleRequest');
+    expect(requestSpans.length).toBe(1);
+    const span = requestSpans[0]!;
+    expect(span.ended).toBe(true);
+    expect(span.attributes['http.method']).toBe('POST');
+    expect(span.attributes['http.route']).toBe('/auth/login');
+    expect(span.attributes['fortress.handler']).toBe('login');
+    expect(span.attributes['http.status_code']).toBe(200);
+    expect(span.status?.code).toBe('ok');
+  });
+
+  it('sets error status and records exception when dispatch throws', async () => {
+    const res = await fortress.handleRequest(
+      new Request('http://local/auth/login', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ identifier: 'spans@example.com', password: 'wrong' }),
+      }),
+    );
+    expect(res.status).toBe(401);
+
+    const requestSpan = spans.find(s => s.name === 'fortress.handleRequest');
+    expect(requestSpan).toBeDefined();
+    expect(requestSpan!.ended).toBe(true);
+    expect(requestSpan!.exception).toBeDefined();
+    expect(requestSpan!.status?.code).toBe('error');
+    expect(requestSpan!.attributes['http.status_code']).toBe(401);
+  });
+
+  it('sets error status on 4xx without a thrown exception', async () => {
+    // A request to an unknown route raises notFound — FortressError
+    // caught by the outer try.
+    const res = await fortress.handleRequest(
+      new Request('http://local/iam/roles/9999', { method: 'GET' }),
+    );
+    // iam/roles is owned by fortress — 401 because no bearer token,
+    // so we land in the exception branch. That's still "error" status.
+    // Use this assertion set to check the finally correctly marks 4xx.
+    expect([401, 403, 404]).toContain(res.status);
+
+    const span = spans.find(s => s.name === 'fortress.handleRequest');
+    expect(span?.ended).toBe(true);
+    expect(span?.status?.code).toBe('error');
+  });
+});
+
+describe('db-instrumentation spans', () => {
+  beforeEach(() => {
+    const telemetry = createSpyTelemetry();
+    spans = telemetry.spans;
+    fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      observability: telemetry.provider,
+    });
+  });
+
+  it('emits a span per DB operation with semantic-convention attributes', async () => {
+    await fortress.auth.createUser({
+      email: 'db-span@example.com',
+      name: 'DB Span User',
+      password: 'password-123456',
+    });
+
+    // Any span with a db.operation.name attribute is a DB span.
+    const dbSpans = spans.filter(s => typeof s.attributes['db.operation.name'] === 'string');
+    expect(dbSpans.length).toBeGreaterThan(0);
+
+    for (const span of dbSpans) {
+      expect(span.ended).toBe(true);
+      expect(span.attributes['db.system.name']).toBeDefined();
+    }
+
+    // Creating a user hits at least findOne(user), create(user), create(login_identifier).
+    const findOneUser = dbSpans.find(s =>
+      s.attributes['db.operation.name'] === 'findOne'
+      && s.attributes['db.collection.name'] === 'user',
+    );
+    expect(findOneUser).toBeDefined();
+    expect(findOneUser?.name).toBe('findOne user');
+
+    const createUser = dbSpans.find(s =>
+      s.attributes['db.operation.name'] === 'create'
+      && s.attributes['db.collection.name'] === 'user',
+    );
+    expect(createUser).toBeDefined();
+    expect(createUser?.name).toBe('create user');
+  });
+});

package/src/core/observability/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Fortress-internal telemetry interfaces.
+ *
+ * Core code depends on these shapes, never on `@opentelemetry/api`. The OTel
+ * adapter in `src/otel/index.ts` is the only file in the repo that imports
+ * `@opentelemetry/api`; it returns a {@link TelemetryProvider} that satisfies
+ * these interfaces. This keeps `@opentelemetry/api` off the core critical
+ * path — runtimes like Cloudflare Workers and Deno never resolve it unless
+ * the user explicitly imports `@bajustone/fortress/otel`.
+ */
+
+export type AttributeValue = string | number | boolean;
+export type Attributes = Record<string, AttributeValue>;
+
+export interface Span {
+  setAttribute: (key: string, value: AttributeValue) => void;
+  recordException: (error: unknown) => void;
+  setStatus: (status: { code: 'ok' | 'error'; message?: string }) => void;
+  end: () => void;
+}
+
+export interface Tracer {
+  startSpan: (name: string, attributes?: Attributes) => Span;
+  /** Run a callback with this span as the active parent for nested spans. */
+  startActiveSpan?: <T>(
+    name: string,
+    attributes: Attributes | undefined,
+    callback: (span: Span) => T | Promise<T>,
+  ) => Promise<T>;
+}
+
+export interface Counter {
+  add: (value: number, attributes?: Attributes) => void;
+}
+
+export interface Histogram {
+  record: (value: number, attributes?: Attributes) => void;
+}
+
+export interface Meter {
+  createCounter: (
+    name: string,
+    options?: { description?: string; unit?: string },
+  ) => Counter;
+  createHistogram: (
+    name: string,
+    options?: { description?: string; unit?: string; boundaries?: number[] },
+  ) => Histogram;
+}
+
+export interface TelemetryProvider {
+  tracer: Tracer;
+  meter: Meter;
+}
+
+const NO_OP_SPAN: Span = {
+  setAttribute: () => {},
+  recordException: () => {},
+  setStatus: () => {},
+  end: () => {},
+};
+
+const NO_OP_COUNTER: Counter = { add: () => {} };
+const NO_OP_HISTOGRAM: Histogram = { record: () => {} };
+
+/**
+ * Default telemetry provider used when {@link FortressConfig.observability}
+ * is not set. Zero allocation per call — the instrument factories return
+ * shared no-op singletons and {@link Tracer.startSpan} returns a shared span.
+ */
+export const NO_OP_TELEMETRY: TelemetryProvider = {
+  tracer: {
+    startSpan: () => NO_OP_SPAN,
+    startActiveSpan: async (_name, _attributes, callback) => callback(NO_OP_SPAN),
+  },
+  meter: {
+    createCounter: () => NO_OP_COUNTER,
+    createHistogram: () => NO_OP_HISTOGRAM,
+  },
+};

package/src/core/openapi-drift.test.ts

@@ -0,0 +1,41 @@
+/**
+ * CI gate over fortress's emitted OpenAPI spec, using `@bajustone/fetcher`'s
+ * `lintSpec`. It surfaces keyword usages the runtime validator does not enforce
+ * (type-vs-runtime divergence).
+ *
+ * Two keywords are intentionally allowed: `format` (always annotation-only in
+ * JSON Schema — fortress pairs it with an enforcing `pattern` via `email()` /
+ * `uuid()` / … and keeps it for OpenAPI docs) and `additionalProperties`
+ * (records, and response-only schemas that are never request-validated). Any
+ * OTHER keyword fetcher's runtime can't enforce (`multipleOf`,
+ * `exclusiveMinimum`, `minItems`, `uniqueItems`, …) is a real gap — adding one
+ * to a fortress schema fails this gate so it's caught before it ships.
+ */
+import { lintSpec } from '@bajustone/fetcher/spec-tools';
+import { describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../testing';
+import { createFortress } from './fortress';
+import { toOpenAPI } from './openapi';
+
+interface SpecDriftIssue { pointer: string; keyword: string; severity: string; message: string }
+
+const KNOWN_UNENFORCED = new Set(['format', 'additionalProperties']);
+
+function coreSpec(): unknown {
+  const fortress = createFortress({ jwt: { key: 'x'.repeat(32) }, database: createTestAdapter() });
+  return toOpenAPI([...fortress.endpoints], { title: 'Fortress', version: '0.0.0' });
+}
+
+describe('openAPI spec drift (lintSpec gate)', () => {
+  it('emits no error-severity drift', () => {
+    const issues = lintSpec(coreSpec()) as SpecDriftIssue[];
+    expect(issues.filter(i => i.severity === 'error')).toEqual([]);
+  });
+
+  it('emits no unexpected unenforced keywords', () => {
+    const issues = lintSpec(coreSpec()) as SpecDriftIssue[];
+    const unexpected = issues.filter(i => !KNOWN_UNENFORCED.has(i.keyword));
+    // Rendered as readable strings so a failure points straight at the offending schema.
+    expect(unexpected.map(i => `${i.keyword} @ ${i.pointer}`)).toEqual([]);
+  });
+});

package/src/core/openapi.ts

@@ -0,0 +1,47 @@
+import type { OpenAPISpec, SpecBuilderOptions } from '../plugins/openapi/spec-builder';
+import type { ComponentSchemas, EndpointDefinition } from './endpoint';
+import { buildOpenAPISpec } from '../plugins/openapi/spec-builder';
+
+/** Options accepted by {@link toOpenAPI}. */
+export interface ToOpenAPIOptions extends Partial<SpecBuilderOptions> {
+  /** Additional reusable schemas to place under `components.schemas`. */
+  schemas?: ComponentSchemas;
+}
+
+/**
+ * Emit an OpenAPI 3.1 spec from a set of Fortress endpoint definitions.
+ *
+ * This is the env/DB-free helper for build scripts and codegen pipelines.
+ * If you already have a configured Fortress instance, prefer
+ * `fortress.toOpenAPI()` so the endpoint list defaults to everything that
+ * instance knows about.
+ *
+ * ```ts
+ * import { toOpenAPI } from '@bajustone/fortress';
+ * import { appEndpointList } from './routes/v1/endpoints';
+ *
+ * export const OPENAPI_SPEC = toOpenAPI(appEndpointList, {
+ *   title: 'My API',
+ *   version: '0.0.0',
+ *   servers: [{ url: 'http://localhost:3001' }],
+ *   tags: [{ name: 'Schools' }],
+ * });
+ * ```
+ *
+ * Defaults to endpoint `handler` values for `operationId`, matching host
+ * route-contract names. Pass `operationId: 'methodPath'` for Fortress's
+ * historical generated IDs.
+ */
+export function toOpenAPI(
+  endpoints: readonly EndpointDefinition[],
+  opts: ToOpenAPIOptions = {},
+): OpenAPISpec {
+  return buildOpenAPISpec([...endpoints], opts.schemas ?? {}, {
+    title: opts.title ?? 'Fortress API',
+    version: opts.version ?? '1.0.0',
+    description: opts.description,
+    servers: opts.servers,
+    tags: opts.tags,
+    operationId: opts.operationId ?? 'handler',
+  });
+}