ankusa
Client SDK for Ankusa, the self-hosted webhook receiver: claim-check redemption, webhook header parsing, queue-message decoding, and clients for the route-management and operator APIs.
Async only, on Tokio: every call is an async fn you drive yourself, and every
request is bounded by tokio::time::timeout, so the runtime needs its timers (a
plain #[tokio::main] has them). The crate's own HTTP client is reqwest,
behind a Transport hook you can replace with anything that speaks
http::Request<Bytes>/http::Response<Bytes>.
Install
The crate is async: add tokio = { version = "1", features = ["macros", "rt-multi-thread"] } to your binary — or any other Tokio runtime, as long as
its time driver is enabled. TLS uses rustls by default;
default-features = false builds a plain-HTTP-only client.
Claim-check client
A queue worker that receives claim_ref in a job message calls redeem: it
parses the ref, fetches the bytes from the claim-check gateway, and verifies
them against the expected sha256 before handing them over.
#
# async
parse_claim_ref is exported standalone, for a consumer that wants the tenant
and claim id without a request:
use parse_claim_ref;
let parsed = parse_claim_ref?;
assert_eq!;
assert_eq!;
# Ok::
Every failure is a ClaimCheckError; is_retryable() distinguishes "try again
later" (the gateway was unavailable) from "give up or dead-letter" (the claim is
gone, the sha256 did not match, the gateway rejected the request):
#
# async
Webhook helper
For the receiving side of Ankusa's HTTP sink: parse_headers reads the
x-ankusa-* headers (plus content-type) out of a http::HeaderMap,
case-insensitively, and fails when x-ankusa-id is missing or empty.
use ;
use HeaderMap;
let mut headers = new;
headers.insert;
headers.insert;
assert_eq!;
# Ok::
HookHeaders also carries dedupe_key (from x-ankusa-dedupe-key),
replay_id (from x-ankusa-replay-id) and idempotency_key (from
x-ankusa-idempotency-key), each None when the header is absent or empty,
and its idempotency_key(include_replay) applies the same rule as Message
below.
Verifying signed deliveries
An HTTP sink with a secret signs every delivery the
Standard Webhooks way. Verify the raw
body before trusting it; answer 401 when it fails:
use HeaderMap;
use ;
let err = verify.unwrap_err;
assert_eq!;
Secrets are whsec_ + base64, or any other string used as its own bytes;
pass several during a rotation. VerifyOptions::tolerance_seconds (default
300) bounds the webhook-timestamp window. Signatures are compared in
constant time; a failure is an InvalidSignatureError with code and
field, never retryable.
Receiving a delivery (signed by default)
Ankusa's HTTP sink signs every delivery unless it is configured
allow_unsigned: true, so a receiver is closed by default. receive_delivery
is the one call that decides: with the sink's secrets it verifies as above;
with none, and no allow_unsigned, it refuses every delivery
(InvalidSignatureError, code invalid_secret) — otherwise any host that can
reach your URL could inject hooks. A configured secret is never weakened by
allow_unsigned. The signature is judged before the hook id, so a delivery
that fails it is a 401 even when it also lacks x-ankusa-id
(ReceiveError::MissingHookId, 400).
use HeaderMap;
use ;
let options = ReceiveOptions ;
let headers = new;
let err = receive_delivery.unwrap_err;
assert!;
hook.verification (also on parse_headers and decode_message results) is
an Option<Verification> saying how the node verified the hook at ingest,
None from a node older than the field. verification.flagged == true means
the node accepted a failed check (on_verify_failure: accept_flag) — treat it
as unverified. hook.is_trusted() (on Message, HookHeaders and
Verification) is that decision in one call: true only for status ok with
flagged false, so a flagged, failed or skipped hook, or one from a node
older than the field, is untrusted.
Consuming queue messages
The message's v is the wire format's major version: decode_message accepts
every v from MIN_SUPPORTED_VERSION to MAX_SUPPORTED_VERSION (1 and 2) into
the one Message, with v as the wire said it. A v: 2 message is a v: 1
message plus additive fields, so a consumer reads it the same way; any other
v is unsupported_version (permanent: dead-letter it). message.instance and
message.region are the Ankusa instance that published the message and the
region it is configured with (None for none). A message from the instance's
lifecycle sinks carries a CloudEvents event as its body:
decode_lifecycle(body) returns a LifecycleEvent.
An Ankusa sink delivers the v: 1 queue message as JSON: the body inline
(body_base64) or as a claim-check ref (claim), the body's sha256, the
provider's dedupe_key, the idempotency_key Ankusa computed for the hook,
and forwarded headers, and a replay_id when the
delivery is a replay. decode_message validates all of it and, on any
malformed input, returns an InvalidMessageError that is never retryable
(err.code is invalid_json, size_mismatch, integrity, …; err.field
names the offending key when the code is invalid_field).
Key a processed-ids table on idempotency_key: the key Ankusa shipped
(tenant:source_id:dedupe_key when the hook has a provider event key, else
id). For a message from a node that predates the field it computes the same
key itself, with tenant default when there is none. Pass
include_replay: true only if the consumer must reprocess replays — the
default drops replays of events it already processed.
use ;
use HashSet;
/// Returns `false` when the delivery was already processed.
Both body forms are supported: an inline message exposes the bytes as
message.body, while a claim-form message exposes the ref as message.claim
for a ClaimCheckClient::redeem call.
Routes client
RoutesClient drives the route-management listener (routes.admin.port): the
route table this node enforces, plus the global IP rules and a dry run that
shows which route a request would match.
#
# async
Route ids travel as one percent-encoded path segment, and an id that is empty,
. or .. is refused with RoutesError::InvalidRouteId before any request is
sent.
Admin client
AdminClient drives the operator listener (admin.port): health, Prometheus
metrics, the redacted config, the dead-letter queue, and quarantine.
#
# async
list_audit pages the audit trail (newest first), filtered by since,
until, actor, action and tenant; naming a tenant the credential
cannot see is AdminError::Rejected with scope tenant:*:
#
# async
Replay jobs are managed on the same listener. create_replay starts one (a
dlq job over dead-lettered rows, an archive job over a time window, or a
quarantine job that re-verifies held hooks and releases those that pass) and
returns the running job when the same spec is posted twice, so a proxy retry is
safe:
#
# async
Custom transport
ClientBuilder shares a base URL, headers, and a timeout across whichever
client you build, and Transport replaces the network entirely — useful for a
proxy, a fake in a test, or an HTTP stack you already have. A transport must
not follow redirects: a 3xx is reported as "unavailable". The timeout stays
Tokio's — every request is bounded by tokio::time::timeout, whatever the
transport — so a Tokio runtime with timers is still required.
use ;
use Bytes;
use ;
use Future;
;
#
# async
Develop
The conformance suite runs the language-neutral vectors in
conformance/
against this crate's public API, so ankusa passes the same conformance cases the
TypeScript and Python SDKs do.