first commit
This commit is contained in:
98
docs/api-stack/api/api-logger-worker-proxy/README.md
Normal file
98
docs/api-stack/api/api-logger-worker-proxy/README.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# @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
|
||||
|
||||
Reference in New Issue
Block a user