George Lambert
b4150c8250
Compose-ready workspace: packages/zappier (rate card, portal, Stripe), packages/verae-zapier-middleware (timestamp + NATS), packages/verae-zapier (CLI app), vendor/zapier-platform, and research/zapier vendor corpus. Gate 0 structure checks pass. Product code and research are not yet wired.
103 lines
2.5 KiB
Markdown
103 lines
2.5 KiB
Markdown
# Module: `debug`
|
|
|
|
**Path:** `verae-zapier-middleware/src/debug/`
|
|
**Phase:** 1
|
|
**Purpose:** Runtime-toggleable failure tracing with secret redaction and correlation IDs.
|
|
|
|
## Files
|
|
|
|
| File | Role |
|
|
|------|------|
|
|
| `config.js` | Parse env into enable/namespaces/level |
|
|
| `redact.js` | Strip secrets from log metadata |
|
|
| `logger.js` | Namespaced `createDebugger` |
|
|
| `trace-context.js` | ALS store (no logger import) |
|
|
| `trace.js` | `withTrace`, Express middleware |
|
|
| `index.js` | Public barrel export |
|
|
|
|
---
|
|
|
|
## `parseDebugVeraeEnv(raw)`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **For** | Interpret `DEBUG_VERAE` env string |
|
|
| **Input** | `raw: string \| undefined` |
|
|
| **Output** | `{ enabled: boolean, namespaces: Set<string>\|null }` |
|
|
| **Notes** | `1`/`*` → all namespaces; `"auth,nats"` → allow-list |
|
|
|
|
## `loadDebugConfig(env?)`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **For** | Build full debug config from environment |
|
|
| **Input** | `env?: NodeJS.ProcessEnv` (default `process.env`) |
|
|
| **Output** | `DebugConfig` `{ enabled, namespaces, level, filePath }` |
|
|
|
|
## `shouldLog(config, namespace, messageLevel)`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **For** | Decide if a line should emit |
|
|
| **Input** | config, namespace string, level |
|
|
| **Output** | `boolean` |
|
|
|
|
## `redact(input)`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **For** | Deep-redact secrets for safe logging |
|
|
| **Input** | any JSON-like value |
|
|
| **Output** | redacted clone |
|
|
|
|
## `createDebugger(namespace)`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **For** | Get `{ debug, info, warn, error }` logger for a namespace |
|
|
| **Input** | `namespace: string` |
|
|
| **Output** | `Debugger` |
|
|
| **Side effects** | Writes to stderr (or test sink) when enabled |
|
|
|
|
### `Debugger.debug|info|warn|error(message, meta?)`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **Input** | `message: string`, `meta?: Record<string, unknown>` |
|
|
| **Output** | `void` |
|
|
|
|
## `withTrace(options, fn)`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **For** | Run work under a correlation id |
|
|
| **Input** | `{ traceId?, span? }`, `fn: () => T\|Promise<T>` |
|
|
| **Output** | `T\|Promise<T>` |
|
|
|
|
## `getTraceId()`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **For** | Read active correlation id |
|
|
| **Output** | `string\|null` |
|
|
|
|
## `traceMiddleware(req, res, next)`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **For** | Per-request Express trace context |
|
|
| **Input** | Express `(req, res, next)` |
|
|
| **Output** | `void` |
|
|
| **Sets** | `req.traceId`, response header `X-Trace-Id` |
|
|
|
|
## `setDebugTestSink(sink)`
|
|
|
|
| | |
|
|
|--|--|
|
|
| **For** | Capture log lines in unit tests |
|
|
| **Input** | `((line: string) => void) \| null` |
|
|
| **Output** | `void` |
|
|
|
|
## Env reference
|
|
|
|
See [../debugging.md](../debugging.md).
|