cellos-sink-jsonl 0.5.1

JSON-Lines EventSink for CellOS — appends CloudEvents to a local JSONL file. Dev / audit-archive use.
Documentation

cellos-sink-jsonl

EventSink that appends each CloudEventV1 as one JSON object per line to a configured file. Dev mirror, CI artefact, audit archive.

What it is

Implements cellos_core::ports::EventSink. Each emit serializes the event and appends it (one line, trailing newline) to the path passed at construction. The file is opened lazily on the first emit.

Enabled in cellos-supervisor::composition::build_jsonl_sink when CELL_OS_JSONL_EVENTS=<path> is set. The JSONL sink runs in addition to the primary JetStream sink — it is a mirror, not a replacement. The cellos-supervisor wires it through the same DLQ(Sign(Redact(…))) composition as the primary sink.

What it does NOT do:

  • It does not rotate the file. Operators rotate / truncate / move it out of band.
  • It does not buffer events in memory; every emit is an async append.
  • It does not retry on failure — that is cellos-sink-dlq's job.
  • It will refuse to write an event larger than MAX_EVENT_BYTES (1 MiB) before any bytes touch disk, returning a typed CellosError::EventSink.

On ENOSPC (or io::ErrorKind::StorageFull), the error message starts with "sink full: " so log scrapers and supervisors can recognise the disk-full case without parsing the underlying io::Error.

Public API surface

Symbol Purpose
JsonlEventSink The sink.
JsonlEventSink::new(path) Construct; the file is opened on first emit.
MAX_EVENT_BYTES 1 MiB hard cap on a single serialized event.

Source: src/lib.rs.

Configuration

Env var Description
CELL_OS_JSONL_EVENTS Path to the append-only .jsonl file. When set, the supervisor mirrors every event here.

Examples

export CELL_OS_JSONL_EVENTS=/var/log/cellos/events.jsonl
cellos-supervisor --spec cell.yaml
tail -F /var/log/cellos/events.jsonl | jq .

Sink composition order in the supervisor (build_jsonl_sink):

DlqSink( Sign( Redact( JsonlEventSink ) ) )

Testing

cargo test -p cellos-sink-jsonl

Tests use tempfile to write to a scratch directory.

Related crates

  • cellos-sink-jetstream — production transport; this sink runs alongside it, not in place of it.
  • cellos-sink-redact — wraps this sink to strip secrets.
  • cellos-sink-dlq — wraps this sink to spill failures to disk.
  • cellos-supervisor — wires this sink in build_jsonl_sink.
  • cellos-core — defines EventSink and CloudEventV1.

ADRs

  • ADR-0011 — same sink composition is used by cellos-server.
  • FC-74 — 90-day audit retention floor; JSONL mirrors are one supported way to honour the floor.