Module buffer 

The on-disk ring buffer, the tombstone, and the wipe.

Everything lives under $CODEWHALE_HOME/telemetry/, created 0700, with every file 0600:

file	role
buffer.jsonl	one JSON event per line, awaiting a flush
buffer.jsonl.lock	a sibling lock file; never the data file
dryrun.jsonl	the sink when the endpoint resolves empty, same ring policy
state.json	last version seen and last flush attempt
install_id.json	the random install id
disabled	the tombstone: present ⇒ nothing is appended, drained, or sent

Appends, compaction, delivery, identity/state writes, startup arming, and wipe share one sibling lock. Runtime and exit paths take it with try_write(): on contention the event or batch is dropped. Only startup arming and the user-requested wipe may wait. That keeps the panic hook and SIGINT path non-blocking while also making opt-out an ordering boundary — after wipe returns, no pre-wipe writer or sender can still publish data.

Appenders re-open per append, so a compaction rewrite cannot leave anyone writing to a stale inode.

Constants

MAX_BYTES

Byte ceiling for either sink.

MAX_EVENTS

Newest events retained in either sink.

MAX_LINE_BYTES

A single append must fit in one atomic write(2).

Functions

append

Append one serialized event or batch to path.

append_locked

Append a line that is too large for one atomic write(2), serialising against other writers with the compaction lock instead.

buffer_path

buffer.jsonl — the pending-event sink.

drain

Take every buffered line and truncate the buffer, under the compaction lock.

dryrun_path

dryrun.jsonl — where batches go when the endpoint resolves to None.

ensure_dir

Create the telemetry directory 0700, if it is missing.

install_id_path

install_id.json.

lock_path

buffer.jsonl.lock — the sibling lock file. Never the data file, and never unlinked: replacing it would leave appenders and compactors holding different inodes and serialising against nothing.

read_lines

Read every intact line from path, dropping a torn trailing line.

state_path

state.json.

tombstone_path

disabled — the tombstone.

tombstone_present

Whether the tombstone is present.

truncate

Truncate a file to zero length, leaving the inode in place. A missing file is not an error.

try_with_lock

Run operation holding the exclusive compaction lock if it is free.

wipe

Wipe every trace of collection, leaving a permanent tombstone.

with_lock

Run operation holding the exclusive compaction lock, blocking.