ankusa.sdk.admin — io.github.jamescarr/ankusa-clj 0.1.0

The admin listener (admin.port, default 4002): health, metrics, the effective configuration, the dead-letter queue, the quarantine, and replay jobs that re-deliver from either (or from the archive).

Responses are decoded JSON with keyword keys (metrics returns the Prometheus text). Failures carry :retryable:

Error	:retryable	Cause
RoleNotEnabledError	false	409 role_not_enabled: ask another node (:role names it)
AdminRejectedError	false	any other 4xx (:status, :code, :scope)
AdminUnavailableError	true	5xx, a redirect, a non-JSON body, or unreachable

Every call is one request: no retry, no followed redirect.

client clj

(client base-url)

(client base-url opts)

Build a client for the listener at base-url (an absolute http(s) URL).

opts may hold:

• :headers: a map of header name (string or keyword) to string value, sent on every request.
• :timeout-ms: a positive integer, default 10000. It bounds the whole call, from connecting through the last body byte.
• :transport: a function that performs one request, to replace the JDK HTTP client (a different HTTP library, an in-process fake). It receives {:method "GET" :url "http://host/path?q" :headers {"name" "value"} :body <byte[] or nil> :timeout-ms 10000} and returns {:status 200 :headers {...} :body <byte[] or nil>}. Throwing any Exception is a transport failure. It must not follow redirects.

Bad input throws IllegalArgumentException.

config clj

(config client)

The effective, redacted configuration: GET /v1/config.

create-replay clj

(create-replay client spec)

Create a replay job: POST /v1/replays with spec as the JSON body.

spec names the job: {"kind" "dlq"}, {"kind" "archive"} or {"kind" "quarantine"}, plus the kind's filter (source_id/id/since/ until for dlq and quarantine, from/to/sinks for archive) and the optional rate and max_lag_ms. The response is the full Replay object; a retry of the same spec answers the existing running or paused job instead of creating a second.

get-replay clj

(get-replay client id)

One replay job by id: GET /v1/replays/{id}. A 404 is an AdminRejectedError with :code "replay_not_found".

health clj

(health client)

Liveness probe: GET /health -> {:status :instance :roles}.

list-audit clj

(list-audit client)

(list-audit client params)

The audit trail, newest first: GET /v1/audit.

params may carry :cursor, :limit, :since, :until, :actor, :action and :tenant (a map, or a seq of [k v] pairs when the order must be exact); nil values are left out of the query string rather than sent as =.

list-dead-letters clj

(list-dead-letters client)

(list-dead-letters client params)

A page of dead-lettered hooks, newest first: GET /v1/dlq.

params may carry :source_id, :since and :limit (a map, or a seq of [k v] pairs when the order must be exact); nil values are left out of the query string rather than sent as =.

list-quarantined clj

(list-quarantined client)

(list-quarantined client params)

Recent quarantined hooks, newest first: GET /v1/quarantine.

params may carry :limit; nil values are left out of the query string.

list-replays clj

(list-replays client)

Every replay job, newest first: GET /v1/replays -> {:replays [...]}.

metrics clj

(metrics client)

The Prometheus text exposition body: GET /metrics, as a string.

update-replay clj

(update-replay client id patch)

Change a replay job: PATCH /v1/replays/{id} with patch as the JSON body.

patch may set state ("running", "paused", "cancelled"), rate, and max_lag_ms. A job that already finished (done, cancelled, failed) is a replay_finished rejection.