ankusa.sdk.impl.http — io.github.jamescarr/ankusa-clj 0.1.0

The one place the SDK issues requests.

Conventions every caller relies on, because the conformance vectors count requests and bound latency:

• One request per call. There is no retry.
• A redirect is never followed: a 3xx is classified as unavailable.
• A non-2xx status is a value each client maps to its own error, never an exception.
• Bodies stay bytes; the caller decides whether they are claim bytes, JSON, or Prometheus text.

client clj

(client base-url opts extra-keys)

Build the Client record every public client wraps.

opts is nil or a map with :headers, :timeout-ms (default 10000), :transport (default the JDK HTTP client), plus any of extra-keys. Anything else throws IllegalArgumentException, as does a base URL that is not an absolute http(s) URL.

decode-json clj

(decode-json bytes)

Parse the response bytes as JSON with keyword keys, or return ::invalid.

error-body clj

(error-body bytes)

The body as JSON (keyword keys) when it parses, else its text ("" when empty).

failure-text clj

(failure-text e)

A one-line description of a transport failure: its class, then its message when it has one.

invalid? clj

(invalid? v)

True when v is what parse-json returns for text that is not JSON.

parse-json clj

(parse-json s key-fn)

Parse s as exactly one JSON value (only whitespace may follow it), with object keys passed through key-fn. Returns ::invalid when s is not JSON, so a literal JSON null (which is nil) stays distinguishable.

path-segment clj

(path-segment s)

Percent-encode s as exactly one path segment: every UTF-8 byte outside RFC 3986 unreserved becomes %XX, so /, ?, # and % cannot reshape the URL (and a space is %20, not +).

request clj

(request client method path {:keys [query] :as opts})

Issue one request and return {:status int :body bytes}, or {:error e} when the transport threw (an unreachable server, a timeout, a refused connection).

method is an upper-case string and path starts with /. opts may hold :query (nil, a map, or a seq of [k v] pairs; nil values are dropped and input order is kept) and :json (encoded as the request body).

The transport is called with {:method :url :headers {name value} :body <bytes or nil> :timeout-ms} and must return {:status int :headers {...} :body <bytes or nil>} without following redirects.

utf8-string clj

(utf8-string bytes)

Strictly decode bytes as UTF-8, or return nil when they are not.