传输契约矩阵
这个矩阵把每个第一方 transport 固定到 public entry points、source files 和 contract tests。它的目的，是让可靠性声明可审计：raw wire transports 必须暴露投递失败；production-grade delivery 必须明确 wrappers 或 queues；lifecycle behavior 必须有命名 test path。
pnpm verify:transport-contracts 会把本页与 package exports 和仓库文件树核对。新增 transport source file 或 public transport subpath 时，必须在同一变更中更新本矩阵。
契约规则
- Raw HTTP/vendor transports 传播非 2xx responses 和 rejected
fetchcalls；除非被 wrapper 包住，否则不会静默 retry。 - Raw wire sinks 的生产投递需要
batchTransport()、retryTransport()、fallbackTransport()，或一个文档化了自身 queue/retry 行为的 transport。 - Runtime-dependent transports 必须记录它们依赖的平台表面，并测试 unavailable 或 failing dependencies。
- Durable paths 必须在测试中暴露
flush()或 persistence/replay 行为。 - Test-only 和 display-only transports 必须明确说明，不要暗示 delivery durability。
矩阵
| ID | Public entry | Export(s) | Source | Delivery contract | Failure and lifecycle contract | Contract tests |
|---|---|---|---|---|---|---|
core-batch | @loggerjs/core/transport-batch | batchTransport | packages/core/src/transports/batch.ts | 围绕任意 inner transport 提供 bounded queue、byte budget、timed flush、concurrency、retry、circuit breaker 和 drop accounting。 | Failed batches 会按策略 retry 或重新入队；flush() drain；close() 停止 timers 并 flush pending work。 | packages/core/test/batch-transport.test.ts packages/core/test/batch-coverage.test.ts |
core-retry | @loggerjs/core/transport-reliability | retryTransport, fallbackTransport | packages/core/src/transports/reliability.ts | 为已有 batching 或需要 per-call retry 的 transports 提供 immediate retry/fallback wrapper。 | Retries 使用 bounded backoff；circuit breaker 和 fallback behavior 可观测；flush()/close() delegate 到 wrapped transports。 | packages/core/test/reliability-transport.test.ts packages/core/test/reliability-coverage.test.ts |
core-console | @loggerjs/core/transport-console | consoleTransport | packages/core/src/transports/console.ts | Runtime-neutral local console sink。 | 使用 unpatched console functions 避免 capture recursion；默认过滤 console-origin events。 | packages/core/test/console-transport.test.ts |
core-memory | Root export | memoryTransport | packages/core/src/transports/memory.ts | 有界 in-memory diagnostics ring buffer；不 durable。 | 超过容量时丢弃最旧 entries；snapshots 同步且 process-local。 | packages/core/test/logger.test.ts packages/core/test/integration-api.test.ts |
core-test | @loggerjs/core/transport-test | testTransport | packages/core/src/transports/test.ts | Assertion-only in-memory sink，带 wait 和 snapshot helpers。 | Injectable failures 和 wait timeouts 属于测试契约；不是 production sink。 | packages/core/test/test-transport.test.ts |
browser-http | @loggerjs/browser/transport-http | browserHttpTransport | packages/browser/src/http-transport.ts | Browser fetch delivery，带 batching、retry options、可选 offline queue、payload transforms 和 page-exit beacon mode。 | 非 2xx 和 rejected fetch attempts 是 failures；page-exit beacon 是 best effort，受 size/runtime 影响。 | packages/browser/test/http-transport.test.ts tests/e2e/browser-production.spec.ts |
browser-indexeddb-queue | @loggerjs/browser/offline-indexeddb, @loggerjs/browser/transport-indexeddb | indexedDbBrowserHttpOfflineQueue, indexedDbTransport | packages/browser/src/indexeddb-offline-queue.ts packages/browser/src/indexeddb-transport.ts | Persistent browser queue/store，用于 reload-surviving replay 和 local export。 | IndexedDB unavailability、quota、private mode、blocked upgrades、TTL 和 pruning 都是 runtime-dependent 且有测试。 | packages/browser/test/indexeddb-offline-queue.test.ts packages/browser/test/indexeddb-transport.test.ts tests/e2e/browser-production.spec.ts |
browser-offline-first | @loggerjs/browser/offline-first-transport | offlineFirstTransport | packages/browser/src/offline-first-transport.ts | Remote-first delivery，在 offline 或 remote failure 后 queued replay。 | Remote rejection 会 queue payloads；storage 和 network 可用时 flush() replay queued records。 | packages/browser/test/offline-first-transport.test.ts |
browser-page-exit | @loggerjs/browser/transport-http, @loggerjs/browser/integration-page-lifecycle | browserHttpTransport page lifecycle flush | packages/browser/src/http-transport.ts packages/browser/src/page-lifecycle.ts | Browser HTTP 的 last-chance pagehide/visibilitychange delivery。 | sendBeacon 是 best effort；unsupported 或 failed beacon 会在可能时 fallback 到 configured HTTP behavior。 | packages/browser/test/http-transport.test.ts packages/browser/test/page-lifecycle.test.ts tests/e2e/browser-production.spec.ts |
browser-service-worker | @loggerjs/browser/transport-service-worker | browserServiceWorkerTransport | packages/browser/src/service-worker-transport.ts | Queue 到 configured 或 ready service worker controller 可用，再 post messages。 | Registration/controller availability 是 runtime-dependent；ready() 和 flush() 暴露 acceptance boundaries。 | packages/browser/test/service-worker-transport.test.ts tests/e2e/browser-production.spec.ts |
browser-websocket | @loggerjs/browser/transport-websocket | browserWebSocketTransport | packages/browser/src/websocket-transport.ts | Live WebSocket sink，connecting 或 closed 时有 bounded queue。 | Reconnection 由调用方拥有；queue bounds 和 close/error behavior 明确。 | packages/browser/test/websocket-transport.test.ts |
browser-broadcast | @loggerjs/browser/transport-broadcast-channel | browserBroadcastChannelTransport | packages/browser/src/broadcast-channel-transport.ts | 通过 BroadcastChannel 做 same-origin tab fan-out。 | Receiver presence 不保证；missing API 和 close semantics 有测试。 | packages/browser/test/broadcast-channel-transport.test.ts |
node-http | @loggerjs/node/transport-http | nodeHttpTransport | packages/node/src/http-transport.ts | Node fetch delivery，自包 batchTransport。 | 非 2xx/rejected fetch attempts 由 wrapper retry；flush() drain batched HTTP work。 | packages/node/test/http-transport.test.ts |
node-file | @loggerjs/node/transport-file, @loggerjs/node/transport-rotating-file | fileTransport, rotatingFileTransport | packages/node/src/file-transport.ts packages/node/src/rotating-file-transport.ts | Local NDJSON file durability，可选 synchronous writes、buffering 和 size rotation。 | flush() drain 正常 writes；支持时 flushSync() 是 crash-path contract；rotation 是 single-writer。 | packages/node/test/file-transport.test.ts packages/node/test/rotating-file-transport.test.ts |
node-stdout | @loggerjs/node/transport-stdout | stdoutTransport, stderrTransport | packages/node/src/stdout-transport.ts | stdout/stderr 的 NDJSON stream sink，带可选 buffering。 | Backpressure drain-aware；默认把 EPIPE 当 clean shutdown；flush() drain buffered writes。 | packages/node/test/stdout-transport.test.ts |
node-syslog | @loggerjs/node/transport-syslog | nodeSyslogTransport | packages/node/src/syslog-transport.ts | UDP 或 TCP 上 RFC-style syslog formatting。 | UDP lossy；TCP 依赖 socket lifecycle；format、send、close 和 error behavior 有测试。 | packages/node/test/syslog-transport.test.ts |
node-worker | @loggerjs/node/transport-worker | workerTransport | packages/node/src/worker-transport.ts | Worker-thread offload，带 codec transfer 和可选 ready/ack handshake。 | Startup、ack timeout、fallback、close 和 auto-end behavior 定义 acceptance boundary。 | packages/node/test/worker-transport.test.ts |
database | @loggerjs/database/transport, @loggerjs/database/sqlite, @loggerjs/database/postgres | databaseTransport, sqliteTransport, postgresTransport | packages/database/src/transport.ts packages/database/src/sqlite.ts packages/database/src/postgres.ts | Batched row mapping 到应用提供的 adapter、SQLite driver 或 Postgres client。 | Adapter/driver failures 通过 batch/retry 和 internal error reporting 暴露；transaction semantics 由 driver 拥有。 | packages/database/test/database-transport.test.ts |
datadog | @loggerjs/datadog/transport | datadogLogsTransport | packages/datadog/src/index.ts | Raw Datadog Logs HTTP payload sink。 | Missing fetch、非 2xx、rejected fetch 会让 raw transport 失败；生产 durability 需要 batchTransport() 或 retryTransport()。 | packages/datadog/test/datadog-transport.test.ts |
elastic | @loggerjs/elastic/transport | elasticTransport | packages/elastic/src/index.ts | Raw Elastic bulk HTTP payload sink。 | Missing fetch、非 2xx、rejected fetch 会让 raw transport 失败；生产 durability 需要 batchTransport() 或 retryTransport()。 | packages/elastic/test/elastic-transport.test.ts |
loki | @loggerjs/loki/transport | lokiTransport | packages/loki/src/index.ts | Raw Loki push HTTP payload sink。 | Missing fetch、非 2xx、rejected fetch 会让 raw transport 失败；生产 durability 需要 batchTransport() 或 retryTransport()。 | packages/loki/test/loki-transport.test.ts |
cloudwatch | @loggerjs/cloudwatch/transport | cloudWatchLogsTransport | packages/cloudwatch/src/index.ts | Raw CloudWatch Logs API payload sink。 | Missing fetch、非 2xx、rejected fetch 会让 raw transport 失败；sequence-token progression 仍依赖 caller/service。 | packages/cloudwatch/test/cloudwatch-transport.test.ts |
sentry | @loggerjs/sentry/transport | sentryTransport | packages/sentry/src/index.ts | Adapter 到应用提供的 Sentry SDK object。 | SDK throws 会让 raw transport 失败，并可被 wrappers 观察；capture-level mapping 和 disabled SDK methods 有测试。 | packages/sentry/test/sentry-transport.test.ts |
otel-otlp | @loggerjs/otel/transport-http, @loggerjs/otel/codec-otlp-json | otlpHttpTransport, otlpJsonCodec | packages/otel/src/transport.ts packages/otel/src/otlp-json.ts | OTLP/HTTP JSON delivery 自包 batchTransport；codec 把 LoggerJS events 映射为 OTLP logs。 | 非 2xx/rejected fetch attempts 由 wrapper retry；codec shape 和 metadata mapping 被固定。 | packages/otel/test/otlp-json.test.ts |
pretty-console | @loggerjs/pretty/transport-console | prettyConsoleTransport | packages/pretty/src/console-transport.ts | 人类可读 browser/console display sink。 | Display-only；避免 console capture loops，并为 DevTools 保留 raw arguments。 | packages/pretty/test/console-transport.test.ts |
pretty-stream | @loggerjs/pretty/transport-stream | prettyStreamTransport, prettyStdoutTransport, prettyStderrTransport | packages/pretty/src/stream-transport.ts | Node terminals 或 stream-like targets 的人类可读 stream sink。 | Backpressure 和 stream errors 可见；支持时 flush() 等待 drain。 | packages/pretty/test/stream-transport.test.ts |