cadrumo.core.telemetry.http_sink module

The real network-transmitting TelemetrySink.

HttpTelemetrySink is the transport that was deliberately deferred until every earlier piece (the consent gate, the closed allowlisted TelemetryEventPayload, and LocalNoopTelemetrySink) proved the pipeline end-to-end without ever touching the network. This module adds the one sink that actually POSTs a payload off the operator’s host, and it is structurally inert by default: emit_telemetry_event() never constructs a sink on its own, so an HttpTelemetrySink only ever exists (and therefore only ever sends) when a call site both explicitly builds one AND already passed the four-way consent gate (telemetry_emit_permitted()).

Two additional invariants beyond the consent gate keep this sink safe:

1. No configured endpoint means no send, unconditionally. A sink built without cadrumo_telemetry_endpoint set (the documented default – None, scaffolded but read by no other transport) is a no-op, mirroring LocalNoopTelemetrySink’s inertness. This protects a deployment that flips cadrumo_telemetry_opt_in and a tier on without ever configuring where to send data.

2. A transport failure never escapes. Telemetry is best-effort diagnostic signal, never a load-bearing part of any command’s outcome; a connection refusal, timeout, or non-2xx response is logged at debug level and swallowed. The payload itself – already the allowlisted, non-sensitive TelemetryEventPayload shape – is never logged, so a failure cannot leak transmission content into local logs.

The HTTP transport reuses httpx, the project’s single outbound HTTP client dependency (the same library the GeminiAdapter and sibling LLM provider adapters use), rather than introducing a second HTTP client dependency.

See also

HttpTelemetrySink

The optional network sink defined here.

emit_telemetry_event()

Gate-then-dispatch function that accepts a sink but never constructs this transport by default.

telemetry_emit_permitted()

Consent gate callers must pass before any real send is attempted.

TelemetryEventPayload

Closed payload shape posted by this transport when configured.

class HttpTelemetrySink(endpoint, *, timeout_s=5.0)

Bases: object

Posts an allowlisted payload to a configured endpoint.

Variables:

endpoint – The remote telemetry collector URL, or None. When None (the default-off posture’s natural value for settings.cadrumo_telemetry_endpoint), send() is a pure no-op – the sink never dials out.

Parameters:

• endpoint (str | None)

• timeout_s (float)

property endpoint: str | None

The configured destination URL, or None when inert.

send(payload)

Best-effort POST of payload to the configured endpoint.

A no-op when endpoint is None (no transport configured). Any transport-level failure (connection error, timeout, non-2xx response) is caught, logged at debug level with no payload content, and swallowed – telemetry delivery failure must never surface to or affect the caller.

Parameters:

payload (TelemetryEventPayload) – The already-gated, already-allowlisted payload to transmit. Only TelemetryEventPayload’s own JSON representation is sent; no other data is attached to the request.

Return type:

None