@bajustone/fortress 1.0.0-rc.1

package/src/internal/changelog.ts

@@ -0,0 +1,56 @@
+const CHANGELOG_HEADER = '# Changelog';
+const UNRELEASED_HEADING = '## [Unreleased]';
+const SECTION_HEADING = /^### /;
+
+function parseGeneratedSections(value: string): Array<{ heading: string; body: string[] }> {
+  const lines = value.trim().split('\n');
+  const sections: Array<{ heading: string; body: string[] }> = [];
+  for (const line of lines) {
+    if (SECTION_HEADING.test(line))
+      sections.push({ heading: line, body: [] });
+    else if (sections.length > 0 && line.length > 0)
+      sections.at(-1)!.body.push(line);
+  }
+  return sections;
+}
+
+/** Promote the first, top-level Unreleased section without detaching its notes. */
+export function promoteUnreleased(
+  changelog: string,
+  version: string,
+  date: string,
+  generatedSection = '',
+): string {
+  const lines = changelog.split('\n');
+  if (lines[0] !== CHANGELOG_HEADER)
+    throw new Error('CHANGELOG.md must start with # Changelog');
+
+  const releaseStart = lines.findIndex((line, index) => index > 0 && line.startsWith('## '));
+  if (releaseStart < 0 || lines[releaseStart] !== UNRELEASED_HEADING)
+    throw new Error('CHANGELOG.md must have [Unreleased] as its first release section');
+
+  lines[releaseStart] = `## [${version}] - ${date}`;
+  let releaseEnd = lines.findIndex((line, index) => index > releaseStart && line.startsWith('## '));
+  if (releaseEnd < 0)
+    releaseEnd = lines.length;
+
+  for (const generated of parseGeneratedSections(generatedSection)) {
+    const existingHeading = lines.findIndex(
+      (line, index) => index > releaseStart && index < releaseEnd && line === generated.heading,
+    );
+    if (existingHeading >= 0) {
+      let insertion = lines.findIndex(
+        (line, index) => index > existingHeading && index < releaseEnd && SECTION_HEADING.test(line),
+      );
+      if (insertion < 0)
+        insertion = releaseEnd;
+      lines.splice(insertion, 0, ...generated.body, '');
+      releaseEnd += generated.body.length + 1;
+    }
+    else {
+      lines.splice(releaseStart + 1, 0, '', generated.heading, ...generated.body);
+      releaseEnd += generated.body.length + 2;
+    }
+  }
+  return lines.join('\n');
+}

package/src/otel/index.ts

@@ -0,0 +1,158 @@
+/**
+ * OpenTelemetry adapter for Fortress.
+ *
+ * This is the **only file in the repository that imports `@opentelemetry/api`**.
+ * Core Fortress code depends on the internal {@link TelemetryProvider}
+ * interface in `src/core/observability/types.ts`; this sub-path exists so
+ * runtimes that never opt in (Cloudflare Workers, Deno without OTel, etc.)
+ * never resolve `@opentelemetry/api` at all.
+ *
+ * The import is dynamic (`await import(...)`) as a belt-and-suspenders
+ * guarantee: even if a bundler or package resolver attempts to evaluate
+ * this module, `@opentelemetry/api` is not referenced until
+ * {@link createOtelTelemetry} is actually called.
+ *
+ * Usage:
+ * ```ts
+ * import { createFortress } from '@bajustone/fortress';
+ * import { createOtelTelemetry } from '@bajustone/fortress/otel';
+ * import pino from 'pino';
+ *
+ * const observability = await createOtelTelemetry({ name: 'my-app-auth' });
+ * const fortress = createFortress({
+ *   // ...config
+ *   logger: pino(),
+ *   observability,
+ * });
+ * ```
+ *
+ * The returned provider satisfies Fortress's internal
+ * {@link TelemetryProvider} interface and can be wired into any
+ * `FortressConfig.observability` slot. Because Fortress's metric catalog
+ * uses the stable OTel semantic convention for database operations
+ * (`db.client.operation.duration`), Grafana/Prometheus dashboards that
+ * know about that name will automatically pick up Fortress's DB queries.
+ */
+
+import type { Span, TelemetryProvider } from '../core/observability/types';
+
+export type { AuthEvent, AuthEventListener } from '../core/auth/auth-service';
+export type {
+  IamEvent,
+  IamEventListener,
+  PermissionCheckEvent,
+  PermissionCheckListener,
+} from '../core/iam/iam-service';
+export type { Unsubscribe } from '../core/observability/listener-list';
+export type { FortressLogger } from '../core/observability/logger';
+export type {
+  Attributes,
+  AttributeValue,
+  Counter,
+  Histogram,
+  Meter,
+  Span,
+  TelemetryProvider,
+  Tracer,
+} from '../core/observability/types';
+
+export interface OtelTelemetryOptions {
+  /** Instrumentation scope name. Defaults to `'fortress'`. */
+  name?: string;
+  /** Instrumentation scope version. Defaults to `'0.0.x'`. */
+  version?: string;
+}
+
+/**
+ * Create a Fortress {@link TelemetryProvider} backed by OpenTelemetry's
+ * global tracer and meter providers.
+ *
+ * If `@opentelemetry/api` is not installed, this function throws with a
+ * clear error message pointing at the missing peer dependency. The
+ * dynamic import ensures the failure mode is a controlled throw at call
+ * time — not a module-load crash.
+ *
+ * When no OTel SDK is registered globally, the returned provider's spans
+ * and metric instruments will resolve to OTel's own no-op implementations
+ * and impose no measurable overhead.
+ */
+export async function createOtelTelemetry(
+  options: OtelTelemetryOptions = {},
+): Promise<TelemetryProvider> {
+  let api: typeof import('@opentelemetry/api');
+  try {
+    api = await import('@opentelemetry/api');
+  }
+  catch (cause) {
+    throw new Error(
+      '@opentelemetry/api is not installed. Add it to your dependencies to use createOtelTelemetry().',
+      { cause },
+    );
+  }
+
+  const name = options.name ?? 'fortress';
+  const version = options.version ?? '0.0.x';
+  const otelTracer = api.trace.getTracer(name, version);
+  const otelMeter = api.metrics.getMeter(name, version);
+  const { SpanStatusCode } = api;
+  const wrapSpan = (span: import('@opentelemetry/api').Span): Span => ({
+    setAttribute: (k, v): void => {
+      span.setAttribute(k, v);
+    },
+    recordException: (err): void => {
+      span.recordException(err as Error);
+    },
+    setStatus: (s): void => {
+      span.setStatus({
+        code: s.code === 'ok' ? SpanStatusCode.OK : SpanStatusCode.ERROR,
+        message: s.message,
+      });
+    },
+    end: (): void => {
+      span.end();
+    },
+  });
+
+  return {
+    tracer: {
+      startSpan(spanName, attrs): Span {
+        return wrapSpan(otelTracer.startSpan(spanName, { attributes: attrs }));
+      },
+      startActiveSpan<T>(
+        spanName: string,
+        attrs: import('../core/observability/types').Attributes | undefined,
+        callback: (span: Span) => T | Promise<T>,
+      ): Promise<T> {
+        return otelTracer.startActiveSpan(
+          spanName,
+          { attributes: attrs },
+          async span => callback(wrapSpan(span)),
+        );
+      },
+    },
+    meter: {
+      createCounter(metricName, opts): import('../core/observability/types').Counter {
+        const c = otelMeter.createCounter(metricName, opts);
+        return {
+          add: (v, a): void => {
+            c.add(v, a);
+          },
+        };
+      },
+      createHistogram(metricName, opts): import('../core/observability/types').Histogram {
+        const h = otelMeter.createHistogram(metricName, {
+          description: opts?.description,
+          unit: opts?.unit,
+          advice: opts?.boundaries
+            ? { explicitBucketBoundaries: opts.boundaries }
+            : undefined,
+        });
+        return {
+          record: (v, a): void => {
+            h.record(v, a);
+          },
+        };
+      },
+    },
+  };
+}

package/src/otel/otel-types.test.ts

@@ -0,0 +1,35 @@
+import type {
+  AuthEvent,
+  AuthEventListener,
+  FortressLogger,
+  IamEvent,
+  IamEventListener,
+  PermissionCheckEvent,
+  PermissionCheckListener,
+  TelemetryProvider,
+  Unsubscribe,
+} from '../index';
+import type {
+  AuthEvent as OtelAuthEvent,
+  AuthEventListener as OtelAuthEventListener,
+  FortressLogger as OtelFortressLogger,
+  IamEvent as OtelIamEvent,
+  IamEventListener as OtelIamEventListener,
+  PermissionCheckEvent as OtelPermissionCheckEvent,
+  PermissionCheckListener as OtelPermissionCheckListener,
+  TelemetryProvider as OtelTelemetryProvider,
+  Unsubscribe as OtelUnsubscribe,
+} from './index';
+import { expectTypeOf, it } from 'vitest';
+
+it('exports public observability contracts from root and /otel', () => {
+  expectTypeOf<OtelFortressLogger>().toEqualTypeOf<FortressLogger>();
+  expectTypeOf<OtelTelemetryProvider>().toEqualTypeOf<TelemetryProvider>();
+  expectTypeOf<OtelAuthEvent>().toEqualTypeOf<AuthEvent>();
+  expectTypeOf<OtelAuthEventListener>().toEqualTypeOf<AuthEventListener>();
+  expectTypeOf<OtelIamEvent>().toEqualTypeOf<IamEvent>();
+  expectTypeOf<OtelIamEventListener>().toEqualTypeOf<IamEventListener>();
+  expectTypeOf<OtelPermissionCheckEvent>().toEqualTypeOf<PermissionCheckEvent>();
+  expectTypeOf<OtelPermissionCheckListener>().toEqualTypeOf<PermissionCheckListener>();
+  expectTypeOf<OtelUnsubscribe>().toEqualTypeOf<Unsubscribe>();
+});

package/src/otel/otel.test.ts

@@ -0,0 +1,235 @@
+import type { MetricData, ResourceMetrics } from '@opentelemetry/sdk-metrics';
+import type { Fortress } from '../core/fortress';
+import { context, metrics, trace } from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import {
+  AggregationTemporality,
+  InMemoryMetricExporter,
+  MeterProvider,
+  PeriodicExportingMetricReader,
+} from '@opentelemetry/sdk-metrics';
+import {
+  BasicTracerProvider,
+  InMemorySpanExporter,
+  SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createFortress } from '../core/fortress';
+import { assertSuccess } from '../core/types';
+import { createTestAdapter } from '../testing';
+import { createOtelTelemetry } from './index';
+
+const SECRET = 'otel-integration-test-secret-32!!';
+
+let fortress: Fortress;
+let exporter: InMemoryMetricExporter;
+let reader: PeriodicExportingMetricReader;
+let provider: MeterProvider;
+let traceProvider: BasicTracerProvider;
+let spanExporter: InMemorySpanExporter;
+let contextManager: AsyncLocalStorageContextManager;
+
+async function collectMetrics(): Promise<MetricData[]> {
+  await reader.forceFlush();
+  const snapshots: ResourceMetrics[] = exporter.getMetrics();
+  const all: MetricData[] = [];
+  for (const snapshot of snapshots) {
+    for (const scope of snapshot.scopeMetrics) {
+      all.push(...scope.metrics);
+    }
+  }
+  return all;
+}
+
+function findMetric(list: MetricData[], name: string): MetricData | undefined {
+  return list.find(m => m.descriptor.name === name);
+}
+
+describe('createOtelTelemetry', () => {
+  beforeEach(async () => {
+    exporter = new InMemoryMetricExporter(AggregationTemporality.CUMULATIVE);
+    reader = new PeriodicExportingMetricReader({
+      exporter,
+      exportIntervalMillis: 60_000,
+    });
+    provider = new MeterProvider({ readers: [reader] });
+    metrics.setGlobalMeterProvider(provider);
+    spanExporter = new InMemorySpanExporter();
+    traceProvider = new BasicTracerProvider({
+      spanProcessors: [new SimpleSpanProcessor(spanExporter)],
+    });
+    trace.setGlobalTracerProvider(traceProvider);
+    contextManager = new AsyncLocalStorageContextManager().enable();
+    context.setGlobalContextManager(contextManager);
+
+    const telemetry = await createOtelTelemetry({ name: 'fortress-test' });
+    fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      rbac: { cache: { ttlSeconds: 30, maxEntries: 100 } },
+      observability: telemetry,
+    });
+
+    await fortress.auth.createUser({
+      email: 'otel@example.com',
+      name: 'OTel User',
+      password: 'password-123456',
+    });
+  });
+
+  afterEach(async () => {
+    await provider.shutdown();
+    await traceProvider.shutdown();
+    metrics.disable();
+    trace.disable();
+    context.disable();
+    contextManager.disable();
+  });
+
+  it('emits fortress.auth.events.total on successful login', async () => {
+    await fortress.auth.login('otel@example.com', 'password-123456');
+    const all = await collectMetrics();
+
+    const authEvents = findMetric(all, 'fortress.auth.events.total');
+    expect(authEvents).toBeDefined();
+    // There should be at least one data point with LOGIN_SUCCESS + password.
+    const points = authEvents!.dataPoints;
+    const success = points.find((p) => {
+      const attrs = p.attributes as Record<string, string>;
+      return attrs.event === 'LOGIN_SUCCESS' && attrs.outcome === 'success';
+    });
+    expect(success).toBeDefined();
+  });
+
+  it('emits fortress.auth.events.total with outcome=failure on bad credentials', async () => {
+    await expect(
+      fortress.auth.login('otel@example.com', 'wrong'),
+    ).rejects.toThrow();
+    const all = await collectMetrics();
+
+    const authEvents = findMetric(all, 'fortress.auth.events.total');
+    expect(authEvents).toBeDefined();
+    const failure = authEvents!.dataPoints.find((p) => {
+      const attrs = p.attributes as Record<string, string>;
+      return attrs.event === 'LOGIN_FAILURE' && attrs.outcome === 'failure';
+    });
+    expect(failure).toBeDefined();
+  });
+
+  it('emits fortress.iam.permission_check.duration histogram + cache hit/miss counters', async () => {
+    // Set up permissions.
+    const user = await fortress.auth.createUser({
+      email: 'perm-otel@example.com',
+      name: 'Perm User',
+      password: 'password-123456',
+    });
+    const role = await fortress.iam.createRole('reader', [
+      { resource: 'post', action: 'read' },
+    ]);
+    await fortress.iam.bindRoleToUser(user.id, role.id);
+
+    // Two checks: miss + hit.
+    await fortress.iam.checkPermission({ type: 'USER', id: user.id }, 'post', 'read');
+    await fortress.iam.checkPermission({ type: 'USER', id: user.id }, 'post', 'read');
+
+    const all = await collectMetrics();
+
+    const duration = findMetric(all, 'fortress.iam.permission_check.duration');
+    expect(duration).toBeDefined();
+    expect(duration!.dataPoints.length).toBeGreaterThan(0);
+
+    const hits = findMetric(all, 'fortress.iam.permission_check.cache.hits');
+    const misses = findMetric(all, 'fortress.iam.permission_check.cache.misses');
+    expect(hits).toBeDefined();
+    expect(misses).toBeDefined();
+
+    // Sum the counters — there must be at least one hit and one miss.
+    function sumCounter(m: MetricData | undefined): number {
+      if (!m)
+        return 0;
+      return m.dataPoints.reduce((acc, p) => acc + Number(p.value), 0);
+    }
+    expect(sumCounter(misses)).toBeGreaterThanOrEqual(1);
+    expect(sumCounter(hits)).toBeGreaterThanOrEqual(1);
+  });
+
+  it('emits the standard db.client.operation.duration histogram for Fortress DB calls', async () => {
+    // Any DB operation will do — the register in beforeEach is enough.
+    await fortress.auth.login('otel@example.com', 'password-123456');
+    const all = await collectMetrics();
+
+    const dbDuration = findMetric(all, 'db.client.operation.duration');
+    expect(dbDuration).toBeDefined();
+    expect(dbDuration!.dataPoints.length).toBeGreaterThan(0);
+
+    // At least one data point should carry the standard semantic-convention
+    // attributes: db.system.name and db.operation.name.
+    const hasDbAttrs = dbDuration!.dataPoints.some((p) => {
+      const attrs = p.attributes as Record<string, string>;
+      return 'db.system.name' in attrs && 'db.operation.name' in attrs;
+    });
+    expect(hasDbAttrs).toBe(true);
+  });
+
+  it('parents nested database spans under the active request span', async () => {
+    const response = await fortress.handleRequest(new Request('http://localhost/auth/login', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ identifier: 'otel@example.com', password: 'password-123456' }),
+    }));
+    expect(response.status).toBe(200);
+    await traceProvider.forceFlush();
+
+    const spans = spanExporter.getFinishedSpans();
+    const requestSpan = spans.find(span => span.name === 'fortress.handleRequest');
+    const databaseSpans = spans.filter(span => span.attributes['db.operation.name'] !== undefined);
+    expect(requestSpan).toBeDefined();
+    expect(databaseSpans.length).toBeGreaterThan(0);
+    expect(databaseSpans.some(
+      span => span.parentSpanContext?.spanId === requestSpan?.spanContext().spanId,
+    )).toBe(true);
+  });
+
+  it('emits fortress.auth.token_verify.duration on verifyToken calls', async () => {
+    const login = await fortress.auth.login('otel@example.com', 'password-123456');
+    assertSuccess(login);
+    expect(login.accessToken).toBeTruthy();
+    // Successful verify
+    await fortress.auth.verifyToken(login.accessToken as string);
+    // Failed verify
+    await expect(fortress.auth.verifyToken('not.a.jwt')).rejects.toThrow();
+
+    const all = await collectMetrics();
+    const verify = findMetric(all, 'fortress.auth.token_verify.duration');
+    expect(verify).toBeDefined();
+
+    const ok = verify!.dataPoints.find((p) => {
+      const attrs = p.attributes as Record<string, string>;
+      return attrs.result === 'ok';
+    });
+    const invalid = verify!.dataPoints.find((p) => {
+      const attrs = p.attributes as Record<string, string>;
+      return attrs.result === 'invalid';
+    });
+    expect(ok).toBeDefined();
+    expect(invalid).toBeDefined();
+  });
+
+  it('createOtelTelemetry returns a zero-overhead provider when no SDK is registered', async () => {
+    // Shut down the SDK so there's no global provider.
+    await provider.shutdown();
+    metrics.disable();
+
+    const fresh = await createOtelTelemetry({ name: 'fortress-no-sdk' });
+    // Methods should exist and be callable without throwing.
+    const counter = fresh.meter.createCounter('foo');
+    expect(() => counter.add(1, { attr: 'x' })).not.toThrow();
+    const histogram = fresh.meter.createHistogram('bar');
+    expect(() => histogram.record(0.5)).not.toThrow();
+    const span = fresh.tracer.startSpan('baz');
+    expect(() => {
+      span.setAttribute('k', 'v');
+      span.end();
+    }).not.toThrow();
+  });
+});