index
Classes
| Class | Description |
|---|---|
| AssertionError | - |
| AssertionExpiredError | - |
| AssertionKeysConfigError | - |
| AssertionMalformedError | - |
| AssertionSignatureError | - |
| AssertionTtlExceededError | - |
| AssertionUnknownKeyError | - |
Interfaces
| Interface | Description |
|---|---|
| Auth | Auth object passed in with every authenticated request. |
| ErrorCollectorParam | Parameters provided to error collectors. |
| ErrorReportOptions | Subset of properties given to Sentry or similar error reporting services. https://docs.sentry.io/platforms/javascript/guides/node/apis/#captureException |
| IdentityAssertion | - |
| LoggerOptions | Context to give for a logger, which doesn't include properties that are global. |
| SafContext | Static, serializable context about what's currently going on. These should always be available in backend systems. |
| SafContextWithAuth | Convenience type for when the context needs to have auth. |
| SafReporters | Clients for reporting various sorts of telemetry. They're expected to be instantiated with a SafContext, so that context is included. |
Type Aliases
| Type Alias | Description |
|---|---|
| ErrorCollector | Collectors take errors reported to them and propagate them to telemetry services such as Sentry. |
| ErrorLevels | Taken from Sentry, excluding "log" which seems superfluous and vague |
| ErrorReporter | The function that application logic has access to for reporting errors. |
| LoggerContext | Context to give for a logger, which doesn't include properties that are global. |
| SubsystemName | List of allowed subsystem names to be used as context for logging and such. |
Variables
| Variable | Description |
|---|---|
| defaultErrorReporter | Default ErrorReporter; call addErrorCollector with this to use it. |
| HTTP_ACCESS_DURATION_WIDTH | Fixed 6-char duration ( 325ms / 72.2s). |
| HTTP_ACCESS_LARGE_BYTES | Response body at or above this size (bytes) is highlighted when ANSI styling is on. |
| HTTP_ACCESS_SIZE_WIDTH | Fixed 6-char response size; kb when > 1024 bytes. |
| HTTP_ACCESS_SLOW_MS | Access-log duration above this (ms) is highlighted when ANSI styling is on. |
| HTTP_CHANNEL_CLIENT_PLAIN | Browser/client traffic — heavy bar, arrow leans left (inbound from the edge). Unicode: BLACK LEFT-POINTING POINTER + HEAVY HORIZONTAL. |
| HTTP_CHANNEL_INTERNAL_PLAIN | Internal background traffic — light bar, arrow leans right (outbound dispatch). Unicode: LIGHT HORIZONTAL + RIGHT-POINTING SMALL TRIANGLE. |
| HTTP_CHANNEL_MARKER_WIDTH | Fixed visual width for the HTTP channel marker column. |
| metricHistogramDefaultBuckets | - |
| SAF_INTERNAL_ASSERTION_KEYS_NAME | - |
| safContextStorage | Storage for SafContext. |
| safReportersStorage | AsyncLocalStorage for SafReporters. |
| testContext | Context provided during testing. |
Functions
| Function | Description |
|---|---|
| addErrorCollector | Adds a callback for when errors are reported by the application. |
| addTransport | For production, when the application starts, it should add any transports using this function. Then all SAF-based applications will log to winston and they'll propagate to loggers such as Loki. |
| collectSystemMetrics | Call when the application starts. Calls prom-client's collectDefaultMetrics function under the hood. |
| configureInternalAssertionKeys | Loads HMAC assertion keys from the secret store when not set in env (prod). Dev sets SAF_INTERNAL_ASSERTION_KEYS in env; job tests stub env directly. Prod-local with INFISICAL_TOKEN=mock gets the placeholder "mock", which signAssertion / verifyAssertion accept as a fixed local key. |
| createLogger | Creates a child logger with the specified request ID. Any servers or processors should use this to create a unique logger for each request or job or what have you. However, if not "instantiating" the request, you should use the request ID provided by the caller, such as in the proto envelope, so that requests which span processes can be correlated. |
| createSilentLogger | Create a logger that doesn't print anything. |
| formatCompactTimestamp | Shared compact log timestamp: MM-DD HH:mm (UTC when TZ=UTC). |
| formatHttpAccessLine | - |
| formatHttpDurationMs | Fixed 6-char duration for access-log columns. Under 10s: 325ms. At/above 10s: 72.2s / 999s so long requests are never left-truncated (e.g. 72233ms must not become 2233ms). |
| formatHttpMethod | Fixed 5-char HTTP method so paths align (GET vs PATCH). |
| formatHttpResponseSize | Fixed 6-char response size; kb when > 1024 bytes. |
| formatHttpStatus | Fixed 3-char HTTP status for access-log alignment. |
| generateRequestId | Generates a request ID. Only necessary for "requests" which are not initiated by proxy servers, such as for cron or async jobs. |
| getErrorCollectors | - |
| getSafContext | Convenience function for getting SafContext store. Errors if not found, returns testContext if in test mode. |
| getSafContextWithAuth | Convenience function for getting SafContext store with auth. Errors if either the store is not found, or auth is not included. |
| getSafReporters | Convenience method for getting the SafReporters from the storage. Errors if not found. |
| getServiceName | Getter for service name. |
| httpAccessAnsiEnabled | - |
| httpChannelIndicator | - |
| makeSubsystemErrorReporter | During setup, subsystems should use this to create their own set of reporters. "Operation name" should be the name of the function. |
| makeSubsystemReporters | Creates a new SafReporters object for a given subsystem and operation. |
| runWithActingUser | Run fn with auth.userId set on the current SafContext. Use when a request is anonymous (webhooks, jobs) but should be attributed to the user who created the related resource for logging, analytics, and error reporting. |
| setServiceName | Sets the service name. Should be called as soon as the process starts. This is provided in SafContext and to instrumentation. |
| signAssertion | Signs an identity assertion. |
| verifyAssertion | Verifies an identity assertion token against any configured key. |
References
getGitHashes
Re-exports getGitHashes
GitHashes
Re-exports GitHashes
NodeEnvSchema
Re-exports NodeEnvSchema
typedEnv
Re-exports typedEnv