@suaveplan/api-logger-worker-proxy - Worker → main proxy for @suaveplan/logger. Marshals LoggerLike calls across a MessagePort with plugin pre-tagging, batched send, bounded backpressure (drops rather than throws), main-side redaction passthrough, and a control channel for disable/enable during shutdown.

Stage-3 worker → main proxy for @suaveplan/logger. Lets a worker-isolated API plugin call a normal LoggerLike surface while the records cross a MessagePort to the host's main-side logger. Pre-tags every record with the plugin's { name, version }, batches outbound traffic, drops under backpressure (no thrown exceptions on log calls), applies redaction at the boundary, and exposes a control channel so the main host can disable worker emit during shutdown.

Universal: depends only on a structural PortLike shape that matches both Node/Bun's worker_threads MessagePort and the Web platform's MessagePort. No platform globals at module load.

Documentation tree

batching — Buffers outbound log records and flushes them in batches over a single MessagePort frame. Reducing one-frame-per-record…
- batching — Buffers outbound log records and flushes them in batches over a single MessagePort frame. Reducing one-frame-per-record…
client — The worker-side proxy. Exposes a LoggerLike surface (debug / info / warn / error) that worker-isolated API pl…
- client — The worker-side proxy. Exposes a LoggerLike surface (debug / info / warn / error) that worker-isolated API pl…
control-channel — Bidirectional control plane: the main process tells a worker-isolated plugin to stop or resume emitting log records. Th…
- control-channel — Bidirectional control plane: the main process tells a worker-isolated plugin to stop or resume emitting log records. Th…
error-codes — Stable identifier registry for failures originating in @suaveplan/api-logger-worker-proxy. Every public failure path…
- error-codes — Stable identifier registry for failures originating in @suaveplan/api-logger-worker-proxy. Every public failure path…
protocol — Defines the Zod-validated wire format for log frames travelling from a worker-isolated plugin to the main-process `@sua…
- protocol — Defines the Zod-validated wire format for log frames travelling from a worker-isolated plugin to the main-process `@sua…
redaction-passthrough — Lets the main-side server apply the host logger's redaction policy to records arriving from worker-isolated plugins. Wo…
- redaction-passthrough — Lets the main-side server apply the host logger's redaction policy to records arriving from worker-isolated plugins. Wo…
server — The main-side server. Consumes inbound log-batch frames from a worker-isolated plugin, applies redaction at the bound…
- server — The main-side server. Consumes inbound log-batch frames from a worker-isolated plugin, applies redaction at the bound…
testing — In-process test fixtures for @suaveplan/api-logger-worker-proxy. Provides a MessageChannel-backed PortLike pair s…
- conformance — runLoggerProxyConformance builds an in-process harness that exercises the full client → port → server → main-logger p…
- testing — In-process test fixtures for @suaveplan/api-logger-worker-proxy. Provides a MessageChannel-backed PortLike pair s…

Install

bun add @suaveplan/api-logger-worker-proxy

Quick start

// Worker side
import { createLoggerProxyClient } from "@suaveplan/api-logger-worker-proxy/worker-side";

const log = createLoggerProxyClient(workerPort, {
    name: "my-plugin",
    version: "0.1.0",
});
log.info("hello", { route: "/health" });
log.error("upstream failed", { code: "ECONNRESET" });

// Main side
import { createLoggerProxyServer } from "@suaveplan/api-logger-worker-proxy/main-side";
import { createConsoleLogger } from "@suaveplan/logger/console";

const server = createLoggerProxyServer(mainPort, createConsoleLogger());
// ... later, during shutdown:
import { createControlChannelSender } from "@suaveplan/api-logger-worker-proxy/control-channel";
createControlChannelSender(mainPort).disable();
server.close();

Subpath exports

./main-side — createLoggerProxyServer for the host.
./worker-side — createLoggerProxyClient for the worker.
./batching — size / idle / immediate-flush triggers + bounded backpressure.
./control-channel — disable / enable channel.
./redaction-passthrough — host-side redaction at the boundary.
./protocol — wire format and Zod schemas.
./error-codes — LOGGER_PROXY.* codes.
./testing — in-process harness and conformance helpers.

Design notes

Best-effort logging. log.info(...) and friends NEVER throw on a full queue or a closed port. Dropped records bump a counter that consumers may surface via OTel; an application MUST NOT break because the log sink is slow.
Plugin pre-tagging. Workers attach { name, version } to each batch; the main-side server routes through logger.child(plugin) when the host logger supports it, otherwise merges into context.
Disposal order. During plugin shutdown the main host calls disable() BEFORE tearing down its sink. The worker stops emitting, the sink is disposed, then the worker is terminated.
No mocks. The conformance harness wires real production objects through a real MessageChannel — see src/testing/conformance.md.

License

MIT

6.3 KiB Raw Blame History