http
etrack.providers.drivers.sink.http
providers/drivers/sink/http: HttpDriver — events batched to any HTTP endpoint; the base a custom driver is built on.
The bus already gives every sink its own worker, a bounded queue and a select: this driver adds what a remote system
needs. Events gather in a batch that leaves when it is full or when the oldest has waited flush; a request that
meets a network error, a 408, 425, 429 or a 5xx is retried with a doubling backoff, any other refusal is final; a batch
refused for good is sent again item by item, so one bad item costs one item. What is refused in the end is handed to
refused with the server's reason — never raised in the bus's way. Every request is signed by the configured Auth, or
by the host's own SignerPort. Leaving the driver sends what is left.
Handed an OutboxPort, the driver guarantees delivery: send stores each item under its key before any network
call, and a relay delivers what is due — a refusal worth another attempt waits the next step of schedule (the last
repeats), an item still undelivered past deadline is dead, a final refusal is dead at once, each with its reason, and
requeue on the outbox sends a dead item again. Delivery is at least once; the receiver deduplicates by key. The
guarantee begins when the item is stored: what a run held in memory before it ended is the host's to reconcile.
Subscribe such a driver with Delivery.GUARANTEED, so the bus never drops what it has not stored yet.
A custom driver subclasses it and overrides what it must, nothing else:
view— the fields it reads (the bus narrows every event onto it beforesend);phases— the phases it wants (the bus skips the rest before queueing);accept(view)— whether this event is sent at all — the project's gate: it fails closed, anacceptthat reads a key the event does not carry (view.attributes["app.owner"]) refuses the event and counts it (missing), so a missing fact never passes as a default;encode(view)— the item the event becomes (amsgspec.Struct, a dict, anything msgspec encodes);body(items)— the request body and its content type, when the endpoint wants a shape of its own (with an outbox, the items it receives are the stored ones, asmsgspec.Raw);key(view, content)— with an outbox, the key an item is stored and deduplicated by: by default, its content's hash;refused(items, refusal)— what to do with items the endpoint did not take: by default, a warning.
DeliveryReport
Bases: Struct
Where a driver's items stand: delivered, refused in the end, refused by the gate for a missing key, and — with an outbox — still pending and dead.
HttpDriver
HttpDriver(
*,
signer: SignerPort | None = None,
outbox: OutboxPort | None = None,
**given: Unpack[HttpConfig],
)
A batching, retrying, signed HTTP sink — use it as it is, or subclass it for a system of your own.
Keyword arguments as HttpConfig names them; what is not given, ETRACK_HTTP_* fills (infra/defaults).
signer, when given, signs every request instead of the configured auth; outbox, when given, stores every
item before it is sent and guarantees its delivery.
accept
accept(view: EventView) -> bool
Whether this event is sent: by default, every kind or the configured ones.
body
The request body and its content type: by default, the configured encoding.
encode
encode(view: EventView) -> Any
What the event becomes in the batch: by default, the view itself.
flush
async
Send what is batched now — with an outbox, what is due —; how many events were taken. What is refused goes to
refused, never raised.
key
key(view: EventView, content: bytes) -> str
With an outbox, the key an item is stored and deduplicated by: by default, the hash of what it encodes to.
refused
refused(items: Sequence[Any], refusal: Refusal) -> None
Items the endpoint did not take, and why: by default, a warning with the server's reason.
send
async
send(view: EventView) -> None
Add the event to the batch — a full batch leaves at once —, or, with an outbox, store it for the relay.