# @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