ankusa-sdk 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 99e44d64d5de0bc0b009a85ef6108009f93c42c90a4b28d39c8d39426421d588
+  data.tar.gz: 5084fce56a8a86cc4e1259c1b96a25c2fb1fa599b42e21cbc0248e7f179bd0b8
+SHA512:
+  metadata.gz: 25f553755bd7f33506aba3992f103c69a82e3e1fa11ffd81909f4a4e4df8fb5a649d0eaa658ec285dffac01dfb6f14b3d057257d8f55ec7b6d667c54b51856b6
+  data.tar.gz: bf270c6e0dcec34696106eaf96cb320004094126f8390e42ff84cd065d874c26b01fc653462aae47eb3960b4ab5a174f49d0e2bbae9fb7f339e4acf1f0956302

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to `ankusa-sdk` (the RubyGems gem) are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-10-01
+
+### Added
+
+- `Ankusa::ClaimCheckClient`: `redeem(ref, sha256)` parses a claim-check ref,
+  fetches its bytes from the gateway, and verifies them against the message's
+  sha256 before returning them; `health` for a liveness probe.
+- `Ankusa::RoutesClient`: the route-management client
+  (`routes.admin.port`) — `health`, `list_routes`, `create_route`, `get_route`,
+  `replace_route`, `update_route`, `delete_route`, `get_ip_rules`,
+  `put_ip_rules`, `test_route`.
+- `Ankusa::AdminClient`: the operator client (`admin.port`) — `health`,
+  `metrics`, `config`, `list_dead_letters`, `replay_dead_letters`,
+  `list_quarantined`.
+- `Ankusa::SourcesClient`, a client for `Ankusa.Admin.Router`: the tenant-scoped
+  source API's `server_version`, `list_sources`, `get_source`, `create_source`,
+  `update_source`, and `delete_source`, with `Ankusa::SourceSpec` (the writable
+  spec, `to_request_body` omits unset fields) and `Ankusa::Source` (a stored,
+  redacted source).
+- `Ankusa.parse_headers(headers)`, for receivers of Ankusa's HTTP sink: parses
+  `x-ankusa-id`/`x-ankusa-source`/`x-ankusa-tenant`/`content-type` into a
+  `HookHeaders` value, raising `MissingHookIdError` if `x-ankusa-id` is absent
+  or empty. `Ankusa.parse_claim_ref` is exported the same way.
+- `Ankusa::Transport`, the injectable transport hook (`Transport::Request` in,
+  `Transport::Response` out) with the default `Transport::NetHTTP`: one
+  connection per request, no redirects, no retries.
+- A `ClaimCheckError`/`RoutesError`/`AdminError`/`SourcesError` hierarchy under
+  `Ankusa::Error`, every class carrying a `retryable?` bit (except the sources
+  family, which carries `.status` and `.body` instead), so a consumer needs
+  exactly one bit to route a failure to dead-letter or retry.
+
+[Unreleased]: https://github.com/jamescarr/ankusa/compare/sdk-ruby-v0.3.0...HEAD
+[0.3.0]: https://github.com/jamescarr/ankusa/releases/tag/sdk-ruby-v0.3.0

data/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 The Ankusa Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,256 @@
+# ankusa-sdk
+
+The Ruby client SDK for [Ankusa](https://github.com/jamescarr/ankusa)
+deployments: one gem meant to bundle everything a non-Elixir consumer needs to
+talk to an Ankusa deployment. Today that's the
+[claim-check gateway](https://github.com/jamescarr/ankusa/blob/main/docs/claim-check.md)
+client, the route-management and operator (admin) clients, the
+source-management client, and a webhook-receiving header helper; more clients
+(ingest) land here as they're built.
+
+## Install
+
+```sh
+gem install ankusa-sdk
+```
+
+or in a `Gemfile`:
+
+```ruby
+gem "ankusa-sdk"
+```
+
+then, in code:
+
+```ruby
+require "ankusa/sdk"
+```
+
+Before the first RubyGems release, depend on it as a path gem the same way the
+Elixir packages in this monorepo depend on `ankusa` core before their first Hex
+release:
+
+```ruby
+gem "ankusa-sdk", path: "packages/sdk-ruby"
+```
+
+Everything the SDK exposes lives under `Ankusa::`.
+
+## Claim-check client
+
+Redeem a claim-check ref, verify the bytes it returns against the message's
+`sha256`, and classify failures into dead-letter vs. retry, without holding any
+object-store credentials. Conforms to the framework's own contract,
+[`priv/openapi/claim_check.v1.yaml`](../ankusa/priv/openapi/claim_check.v1.yaml):
+the spec is the source of truth, this package conforms to it, not the reverse.
+
+```ruby
+require "ankusa/sdk"
+
+CLAIM_CHECK = Ankusa::ClaimCheckClient.new(ENV.fetch("CLAIM_CHECK_URL", "http://localhost:4001"))
+
+# A queue message that carries a claim also carries its sha256:
+#   "claim":  "urn:ankusa:claim:v1:<tenant>:<claim_id>"  (claim_id: uppercase ULID)
+#   "sha256": 64-char lowercase hex of the claim's bytes
+def resolve_body(message)
+  CLAIM_CHECK.redeem(message["claim"], message["sha256"])
+rescue Ankusa::ClaimCheckError => e
+  # bad ref/sha256, 404, or an integrity mismatch: dead-letter, don't requeue
+  raise unless e.retryable?
+
+  # gateway unreachable or 5xx: safe to retry
+  raise
+end
+```
+
+`redeem` does three things `GET /v1/claims/...` alone doesn't:
+
+1. Parses the ref into its tenant id, claim id, and gateway path
+   (`GET /v1/claims/{tenant_id}/{claim_id}`) (`Ankusa.parse_claim_ref`, also
+   exported standalone).
+2. Fetches the bytes.
+3. Verifies them against the message's `sha256` (the gateway itself does not
+   check this, see "Redeem a claim" in
+   [`docs/claim-check.md`](https://github.com/jamescarr/ankusa/blob/main/docs/claim-check.md))
+   before ever returning them to you.
+
+Every failure is a `ClaimCheckError` subclass with a `retryable?` method, so a
+consumer needs exactly one bit to decide dead-letter vs. retry:
+
+| Class | `retryable?` | Cause |
+| --- | --- | --- |
+| `InvalidClaimRefError` | `false` | `ref` isn't a well-formed claim-check URN, or `sha256` isn't 64-char lowercase hex |
+| `ClaimNotFoundError` | `false` | gateway `404`: expired by retention, or never written |
+| `ClaimRejectedError` | `false` | gateway `4xx` other than `404` (`.status`, `.body`) |
+| `ClaimIntegrityError` | `false` | sha256 of the returned bytes doesn't match |
+| `ClaimCheckUnavailableError` | `true` | gateway `5xx`/`503`, or unreachable |
+
+`health` hits `GET /health` for a liveness probe. There's no `close`: the
+default transport opens one connection per request.
+
+## Webhook receiver helper
+
+Every receiver of Ankusa's HTTP sink needs the same handful of headers off each
+request; `Ankusa.parse_headers` replaces the hand-rolled
+`env["HTTP_X_ANKUSA_ID"]` lookups with one call and a typed result. Names are
+matched case-insensitively, so it takes anything from a lowercased header hash
+to a Rack env mapped once:
+
+```ruby
+require "ankusa/sdk"
+
+# Rack carries these as HTTP_X_ANKUSA_* (content-type as CONTENT_TYPE):
+# parse_headers downcases what it is given, but it does not strip Rack's
+# HTTP_ prefix or its underscores.
+def header_map(env)
+  headers = env.filter_map do |key, value|
+    [key.delete_prefix("HTTP_").tr("_", "-"), value] if key.start_with?("HTTP_")
+  end.to_h
+  headers["content-type"] = env["CONTENT_TYPE"] if env["CONTENT_TYPE"]
+  headers
+end
+
+def call(env)
+  hook =
+    begin
+      Ankusa.parse_headers(header_map(env))
+    rescue Ankusa::MissingHookIdError
+      return [400, {}, []]
+    end
+
+  body = env["rack.input"].read
+  # hook.id, hook.source, hook.tenant, hook.content_type
+  [200, {}, []]
+end
+```
+
+`HookHeaders#id` is what a receiver dedupes on: delivery is at-least-once (see
+"HTTP handoff" in
+[`docs/integrations.md`](https://github.com/jamescarr/ankusa/blob/main/docs/integrations.md)),
+so the same hook can arrive twice after a retry. Header lookup is always
+case-insensitive, regardless of whether the mapping passed in already is.
+
+## Routes client
+
+Manage route definitions and the global IP rules on the route-management
+listener (`routes.admin.port`, default 4003) — the `routes` tag of
+[`priv/openapi/admin.v1.yaml`](../ankusa/priv/openapi/admin.v1.yaml).
+
+```ruby
+require "ankusa/sdk"
+
+routes = Ankusa::RoutesClient.new(ENV.fetch("ROUTES_URL", "http://localhost:4003"))
+
+routes.create_route({"id" => "stripe", "path" => "/webhooks/stripe"})
+routes.get_ip_rules   # {"default" => "allow", "rules" => []}
+routes.test_route({"method" => "POST", "path" => "/webhooks/stripe", "ip" => "203.0.113.7"})
+```
+
+Methods: `health`, `list_routes`, `create_route`, `get_route`, `replace_route`,
+`update_route`, `delete_route`, `get_ip_rules`, `put_ip_rules`, `test_route`.
+Route ids are percent-encoded as one path segment, so `/`, `?`, `#`, `%` and a
+space in an id can't reshape the URL.
+
+Failures are `RoutesError` subclasses: `InvalidRouteIdError` (an id that isn't a
+string, is empty, or is `.`/`..` — raised before any request, because a URL
+parser would otherwise normalize it into the collection endpoint and hand back
+the list page as if it were a route), `RouteNotFoundError` (404),
+`RoutesRejectedError` (any other 4xx, carrying `code`, `field`, `message`,
+`conflicting_id`, `max_routes`), and `RoutesUnavailableError` (5xx, an
+unfollowed redirect, a non-JSON success body, or unreachable; retryable).
+
+## Admin client
+
+The operator API on `admin.port` (default 4002): health, Prometheus metrics, the
+redacted config, the DLQ, and the quarantine list — the `operations`, `dlq`, and
+`quarantine` tags of `admin.v1.yaml`.
+
+```ruby
+require "ankusa/sdk"
+
+admin = Ankusa::AdminClient.new(ENV.fetch("ADMIN_URL", "http://localhost:4002"))
+
+admin.health                          # {"status" => "ok", "instance" => ..., "roles" => [...]}
+admin.list_dead_letters({"limit" => 10})  # {"total" => ..., "entries" => [...]}
+admin.replay_dead_letters({"source_id" => "demo"})
+admin.list_quarantined
+```
+
+Methods: `health`, `metrics` (Prometheus text), `config`, `list_dead_letters`,
+`replay_dead_letters`, `list_quarantined`. Failures are `AdminError` subclasses:
+`RoleNotEnabledError` (409 `role_not_enabled`, carrying `role`),
+`AdminRejectedError` (any other 4xx, carrying `code`), and
+`AdminUnavailableError` (5xx, an unfollowed redirect, or unreachable;
+retryable).
+
+## Sources client
+
+Ankusa's ingest sources are tenant-scoped: a source is addressed as
+`<tenant>.<name>`, and `Ankusa.Admin.Router` serves their CRUD API on the same
+`admin.port` as the operator API. `SourcesClient` speaks in those terms and
+builds the paths for you.
+
+```ruby
+require "ankusa/sdk"
+
+sources = Ankusa::SourcesClient.new(ENV.fetch("ADMIN_URL", "http://localhost:4002"))
+
+sources.list_sources("acme")                                   # [Source, ...]
+sources.get_source("acme", "billing")                          # Source
+sources.create_source("acme", "billing", Ankusa::SourceSpec.new(sinks: [{"type" => "log"}]))
+sources.update_source(
+  "acme",
+  "billing",
+  Ankusa::SourceSpec.new(sinks: [{"type" => "log"}], on_verify_failure: "reject")
+)
+sources.delete_source("acme", "billing")
+```
+
+Methods: `server_version`, `list_sources`, `get_source`, `create_source`,
+`update_source`, `delete_source`. A write takes the whole spec (`SourceSpec`,
+whose `to_request_body` omits unset fields); a read returns a `Source`, which is
+always redacted — resending a read-back `verify` map is not the same as
+resending the stored secret, so supply secrets through `SourceSpec`.
+
+`expected_version: "0.3.0"` is an optional latch: the first API call fetches
+`GET /health`, compares its `"version"` field, and raises
+`VersionMismatchError` on a mismatch (the version is cached afterwards, so no
+further request checks it). Failures are `SourcesError` subclasses, each
+carrying `.status` and `.body`: `SourceNotFoundError` (404),
+`SourceConflictError` (409), `SourceStoreReadOnlyError` (409 — the deployment's
+source store is a static seed), `SourceInvalidError` (400, or an invalid
+tenant/name caught before any request), `VersionMismatchError`, and
+`SourcesUnavailableError` (unreachable, timed out, or 5xx).
+
+Tenants and source names must match `[A-Za-z0-9_-]{1,64}`; anything else raises
+`SourceInvalidError` before a path is built.
+
+## Layout
+
+```
+lib/ankusa/
+  sdk.rb                # entry point: require "ankusa/sdk"
+  sdk/version.rb
+  error.rb              # Ankusa::Error, the root of every SDK error
+  transport.rb          # the injectable transport hook + the default Net::HTTP one
+  connection.rb         # shared URL/query/body/JSON rules (@api private)
+  webhook.rb            # x-ankusa-* header parsing for HTTP-sink receivers
+  claim_check.rb        # the claim-check gateway client
+  routes.rb             # the route-management client (routes.admin.port)
+  admin.rb              # the operator client (admin.port)
+  sources.rb            # the tenant-scoped source-management client (admin.port)
+test/
+  test_helper.rb
+  test_conformance.rb     # runs the language-neutral vectors in conformance/
+  test_routes.rb
+  test_admin.rb
+  test_sources.rb
+```
+
+## Develop
+
+```sh
+bundle install
+bundle exec rake              # tests + standard
+bundle exec rake conformance  # just the conformance vectors
+```

data/lib/ankusa/admin.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Ankusa
+  # Every failure the admin client can raise.
+  #
+  # `retryable?` is the whole point of this hierarchy, exactly as in the
+  # claim-check client: a caller (an operator script, a dashboard) needs one bit
+  # -- retry, or surface the rejection -- and nothing here requires it to know
+  # the operator API's status codes to get that right.
+  #
+  # Non-retryable: the listener said 409 role_not_enabled (ask another node) or
+  # another 4xx (a rejected filter). Retryable: the listener said 5xx, or the
+  # request never completed (network error, timeout).
+  class AdminError < Error
+    def retryable? = false
+  end
+
+  # The listener is unreachable, or answered 5xx. Safe to retry.
+  class AdminUnavailableError < AdminError
+    def retryable? = true
+  end
+
+  # The listener returned 409 role_not_enabled: this node does not run the role
+  # the operation needs. Ask another node; `role` names it.
+  class RoleNotEnabledError < AdminError
+    attr_reader :role
+
+    def initialize(message, role:)
+      super(message)
+      @role = role
+    end
+  end
+
+  # The listener rejected the request (any other 4xx).
+  #
+  # `status` is the HTTP status; `code` is the body's `error` field
+  # (`invalid_filter`, ...).
+  class AdminRejectedError < AdminError
+    attr_reader :status, :code
+
+    def initialize(message, status:, code:)
+      super(message)
+      @status = status
+      @code = code
+    end
+  end
+
+  # Operate against the operator API (`admin.port`, default 4002): health,
+  # Prometheus metrics, the redacted config, the dead-letter queue, and the
+  # quarantine list. Responses are node-local by design, so a fleet operator
+  # scrapes every node's admin port.
+  #
+  # Like the claim-check client, the listener itself performs no authentication
+  # -- `headers` is for whatever a deployer's own boundary (service mesh, an API
+  # gateway) expects in front of it.
+  class AdminClient
+    def initialize(base_url, headers: nil, timeout: 10.0, transport: nil)
+      @connection = Connection.new(base_url, headers: headers, timeout: timeout, transport: transport)
+    end
+
+    # Liveness probe: GET /health -> {status, instance, roles}.
+    def health
+      json(request("GET", "/health"))
+    end
+
+    # GET /metrics -> the Prometheus text exposition body.
+    def metrics
+      request("GET", "/metrics").body.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    # GET /v1/config -> the effective, redacted configuration.
+    def config
+      json(request("GET", "/v1/config"))
+    end
+
+    # GET /v1/dlq -> a page of dead-lettered hooks, newest first.
+    #
+    # `params` may carry `source_id`, `since` and `limit`; absent keys are
+    # omitted from the query string rather than sent as `=`.
+    def list_dead_letters(params = nil)
+      json(request("GET", "/v1/dlq", query: params))
+    end
+
+    # POST /v1/dlq/replay -> {replayed}.
+    #
+    # `filter` is a filter, not a payload; omitted or empty (`{}`) replays
+    # everything.
+    def replay_dead_letters(filter = nil)
+      json(request("POST", "/v1/dlq/replay", json: filter || {}))
+    end
+
+    # GET /v1/quarantine -> recent quarantined hooks, newest first.
+    #
+    # `params` may carry `limit`; absent keys are omitted from the query string
+    # rather than sent as `=`.
+    def list_quarantined(params = nil)
+      json(request("GET", "/v1/quarantine", query: params))
+    end
+
+    private
+
+    def request(http_method, path, query: nil, json: nil)
+      response = @connection.request(http_method, path, query: query, json: json)
+      raise_for_status(response)
+      response
+    rescue Transport::Error => e
+      raise AdminUnavailableError, "admin listener unreachable: #{e.message}"
+    end
+
+    def json(response)
+      Connection.parse_json(response.body)
+    rescue JSON::ParserError
+      raise AdminUnavailableError, "admin listener returned a non-JSON body (#{response.status})"
+    end
+
+    def raise_for_status(response)
+      status = response.status
+      return if status >= 200 && status < 300
+
+      body = Connection.error_body(response)
+      code = body.is_a?(Hash) ? body["error"] : nil
+
+      if status == 409 && code == "role_not_enabled"
+        role = body.is_a?(Hash) ? body["role"] : nil
+        raise RoleNotEnabledError.new("role not enabled on this node: #{role.inspect}", role: role)
+      end
+
+      if status >= 400 && status < 500
+        raise AdminRejectedError.new(
+          "admin listener rejected the request (#{status}): #{body.inspect}",
+          status: status,
+          code: code
+        )
+      end
+
+      # Everything else that isn't 2xx is retryable: 1xx, an unfollowed 3xx
+      # redirect, and 5xx.
+      raise AdminUnavailableError, "admin listener error (#{status}): #{body.inspect}"
+    end
+  end
+end