Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,104 @@
/**
* Sentry bootstrap for the BullMQ worker process.
*
* Exposes {@link initWorkerSentry} (called from `index.ts` as the very first
* statement) and {@link workerErrorReporter} (an `ErrorReporter` facade that
* `startWorkerRuntime` and any other code-path can use to forward unhandled
* errors to Sentry).
*
* When `SENTRY_DSN_WORKER` is empty or unset every export becomes a no-op
* so local development and Sentry-less staging environments keep working
* unchanged.
*
* @see docs/improvement-plan/02-observability/sentry-wiring-api-worker.md
*/
import { createNoopErrorReporter, createSentryErrorReporter, type ErrorReporter } from "@toolctrl/error-reporter";
export interface WorkerSentryConfig {
dsn: string | undefined;
environment: string | undefined;
release: string | undefined;
tracesSampleRate: number;
profilesSampleRate: number;
}
const DEFAULT_TRACES_SAMPLE_RATE_PROD = 0.1;
const DEFAULT_TRACES_SAMPLE_RATE_DEV = 1.0;
const DEFAULT_PROFILES_SAMPLE_RATE = 0.0;
export function parseSampleRate(raw: string | undefined, fallback: number): number {
if (raw === undefined || raw === null || raw === "") return fallback;
const parsed = Number(raw);
if (!Number.isFinite(parsed)) return fallback;
if (parsed < 0) return 0;
if (parsed > 1) return 1;
return parsed;
}
export function readWorkerSentryConfig(env: NodeJS.ProcessEnv = process.env): WorkerSentryConfig {
const nodeEnv = env.NODE_ENV || "development";
const tracesDefault = nodeEnv === "production" ? DEFAULT_TRACES_SAMPLE_RATE_PROD : DEFAULT_TRACES_SAMPLE_RATE_DEV;
return {
dsn: env.SENTRY_DSN_WORKER || undefined,
environment: env.SENTRY_ENVIRONMENT || nodeEnv || undefined,
release: env.SENTRY_RELEASE || undefined,
tracesSampleRate: parseSampleRate(env.SENTRY_TRACES_SAMPLE_RATE, tracesDefault),
profilesSampleRate: parseSampleRate(env.SENTRY_PROFILES_SAMPLE_RATE, DEFAULT_PROFILES_SAMPLE_RATE),
};
}
let cachedReporter: ErrorReporter | undefined;
let cachedConfig: WorkerSentryConfig | undefined;
/**
* Idempotent. The first call builds the Sentry-backed reporter (or the
* no-op reporter when `SENTRY_DSN_WORKER` is empty); subsequent calls
* return the cached instance. The Sentry SDK is loaded lazily through
* the adapter in `@toolctrl/error-reporter`, so unit tests that do not
* import this module never touch `@sentry/node` at all.
*/
export function initWorkerSentry(config: WorkerSentryConfig = readWorkerSentryConfig()): ErrorReporter {
if (cachedReporter) {
return cachedReporter;
}
cachedConfig = config;
if (!config.dsn) {
cachedReporter = createNoopErrorReporter();
return cachedReporter;
}
cachedReporter = createSentryErrorReporter({
dsn: config.dsn,
environment: config.environment,
release: config.release,
tracesSampleRate: config.tracesSampleRate,
profilesSampleRate: config.profilesSampleRate,
maxBreadcrumbs: 50,
});
return cachedReporter;
}
/**
* Reporter facade. Lazy on first access so `apps/worker/src/index.ts`
* controls when initialisation happens.
*/
export const workerErrorReporter: ErrorReporter = {
report(event) {
const reporter = cachedReporter ?? initWorkerSentry();
return reporter.report(event);
},
};
/** Test-only: reset the cached reporter/config so multiple test cases can call init. */
export function __resetWorkerSentryForTests(): void {
cachedReporter = undefined;
cachedConfig = undefined;
}
/** Test-only: read the cached config (or undefined if not initialised). */
export function __getWorkerSentryConfigForTests(): WorkerSentryConfig | undefined {
return cachedConfig;
}