Skip to content

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 before send);
  • 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, an accept that 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 (a msgspec.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, as msgspec.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.

failed property

failed: int

Events the endpoint did not take, in the end.

missing property

missing: int

Events refused because accept read a key they did not carry.

sent property

sent: int

Events delivered so far.

accept

accept(view: EventView) -> bool

Whether this event is sent: by default, every kind or the configured ones.

body

body(items: Sequence[Any]) -> tuple[bytes, str]

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

flush() -> int

Send what is batched now — with an outbox, what is due —; how many events were taken. What is refused goes to refused, never raised.

health async

health() -> bool

Open, its timer alive.

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.

report async

report() -> DeliveryReport

Where this driver's items stand now.

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.

body_json

body_json(items: Sequence[Any]) -> tuple[bytes, str]

A batch as one JSON array.

body_ndjson

body_ndjson(items: Sequence[Any]) -> tuple[bytes, str]

A batch as one JSON value per line.