99 lines
6.3 KiB
Markdown
99 lines
6.3 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [batching](./src/batching/batching.md) — Buffers outbound log records and flushes them in batches over a single MessagePort frame. Reducing one-frame-per-record…
|
|
- [batching](./src/batching/batching.md) — Buffers outbound log records and flushes them in batches over a single MessagePort frame. Reducing one-frame-per-record…
|
|
- [client](./src/client/client.md) — The worker-side proxy. Exposes a `LoggerLike` surface (`debug` / `info` / `warn` / `error`) that worker-isolated API pl…
|
|
- [client](./src/client/client.md) — The worker-side proxy. Exposes a `LoggerLike` surface (`debug` / `info` / `warn` / `error`) that worker-isolated API pl…
|
|
- [control-channel](./src/control-channel/control-channel.md) — Bidirectional control plane: the main process tells a worker-isolated plugin to stop or resume emitting log records. Th…
|
|
- [control-channel](./src/control-channel/control-channel.md) — Bidirectional control plane: the main process tells a worker-isolated plugin to stop or resume emitting log records. Th…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Stable identifier registry for failures originating in `@suaveplan/api-logger-worker-proxy`. Every public failure path…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Stable identifier registry for failures originating in `@suaveplan/api-logger-worker-proxy`. Every public failure path…
|
|
- [protocol](./src/protocol/protocol.md) — Defines the Zod-validated wire format for log frames travelling from a worker-isolated plugin to the main-process `@sua…
|
|
- [protocol](./src/protocol/protocol.md) — Defines the Zod-validated wire format for log frames travelling from a worker-isolated plugin to the main-process `@sua…
|
|
- [redaction-passthrough](./src/redaction-passthrough/redaction-passthrough.md) — Lets the main-side server apply the host logger's redaction policy to records arriving from worker-isolated plugins. Wo…
|
|
- [redaction-passthrough](./src/redaction-passthrough/redaction-passthrough.md) — Lets the main-side server apply the host logger's redaction policy to records arriving from worker-isolated plugins. Wo…
|
|
- [server](./src/server/server.md) — The main-side server. Consumes inbound `log-batch` frames from a worker-isolated plugin, applies redaction at the bound…
|
|
- [server](./src/server/server.md) — The main-side server. Consumes inbound `log-batch` frames from a worker-isolated plugin, applies redaction at the bound…
|
|
- [testing](./src/testing/testing.md) — In-process test fixtures for `@suaveplan/api-logger-worker-proxy`. Provides a `MessageChannel`-backed `PortLike` pair s…
|
|
- [conformance](./src/testing/conformance.md) — `runLoggerProxyConformance` builds an in-process harness that exercises the full client → port → server → main-logger p…
|
|
- [testing](./src/testing/testing.md) — In-process test fixtures for `@suaveplan/api-logger-worker-proxy`. Provides a `MessageChannel`-backed `PortLike` pair s…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/api-logger-worker-proxy
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
// 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" });
|
|
```
|
|
|
|
```ts
|
|
// 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`](src/server/server.md) — `createLoggerProxyServer` for the host.
|
|
- [`./worker-side`](src/client/client.md) — `createLoggerProxyClient` for the worker.
|
|
- [`./batching`](src/batching/batching.md) — size / idle / immediate-flush triggers + bounded backpressure.
|
|
- [`./control-channel`](src/control-channel/control-channel.md) — `disable` / `enable` channel.
|
|
- [`./redaction-passthrough`](src/redaction-passthrough/redaction-passthrough.md) — host-side redaction at the boundary.
|
|
- [`./protocol`](src/protocol/protocol.md) — wire format and Zod schemas.
|
|
- [`./error-codes`](src/error-codes/error-codes.md) — `LOGGER_PROXY.*` codes.
|
|
- [`./testing`](src/testing/testing.md) — 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
|
|
|