Overview

@saflib/node provides shared runtime infrastructure for Node.js processes in SAF applications — request context, logging, metrics, error reporting, and internal identity assertions. HTTP servers, gRPC services, cron/job runners, CLIs, and tests all use the same AsyncLocalStorage stores and reporter helpers defined here.

Subsystem libraries (@saflib/express, @saflib/grpc, cron, jobs, …) wire context and reporters at operation boundaries. This package holds the core types, stores, and bootstrap helpers they share.

This library does not provide any tools developer would tend to use day-to-day. This logic is mostly used for development of core SAF features.

What this package provides

• Context — SafContext in safContextStorage; getSafContext and getSafContextWithAuth for handlers and jobs
• Reporters — Winston logging and error collectors via SafReporters and getSafReporters
• Service bootstrap — setServiceName, addTransport, addErrorCollector, collectSystemMetrics
• Subsystem helpers — createLogger, makeSubsystemReporters, generateRequestId
• Internal auth — signAssertion / verifyAssertion with configureInternalAssertionKeys
• Subpath exports — @saflib/node/env (package env vars), @saflib/node/git-hashes (build metadata), @saflib/node/cli-context (re-exports @saflib/commander setupContext)

See Instrumentation for how context, reporters, and metrics fit together in applications and subsystem libraries. API details: code reference.

Subsystems

Any request-scoped or long-running Node process should provide context and reporters at operation boundaries:

Subsystem	Typical provider
HTTP	@saflib/express middleware
gRPC	@saflib/grpc interceptors
Cron / jobs	@saflib/cron, @saflib/jobs runners
CLI	@saflib/commander setupContext (also @saflib/node/cli-context)
Tests	stubs when NODE_ENV=test (see instrumentation doc)

Product {service}-common packages hold service-specific dependencies (database clients, vendor SDKs) and pass them into each subsystem bootstrap. See monorepo service layout.

Application startup

Call bootstrap functions once at process start, before initializing servers or workers:

1. setServiceName — must match the service package name (without org prefix) and Docker service name
2. addTransport / addErrorCollector — wire Winston and error reporting (e.g. Loki, Sentry)
3. collectSystemMetrics — opt into Prometheus default metrics via prom-client

Handlers, jobs, and CLI commands then use getSafContext, getSafReporters, and related helpers — not raw console.log or ad hoc loggers.