ankusa 0.2.4__tar.gz

ankusa-0.2.4/.gitignore

@@ -0,0 +1,48 @@
+# The directory Mix will write compiled artifacts to. Recursive: this repo
+# is a mono-repo of multiple Mix projects (packages/*, examples/*/*), each
+# with its own _build/.
+**/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+**/cover/
+
+# The directory Mix downloads your dependencies sources to.
+**/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+**/doc/
+
+# Temporary files, for example, from tests.
+/tmp/
+packages/*/tmp/
+
+# Local WAL, segments, quarantine, and DLQ written by the framework at runtime.
+packages/*/data/
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez
+
+# Ignore package tarballs (built via "mix hex.build").
+packages/*/*.tar
+
+# Node (examples/*/worker).
+**/node_modules/
+
+# TypeScript / Python SDK build output (built via "npm run build" /
+# "npm pack" / "uv build").
+packages/sdk-typescript/dist/
+packages/sdk-python/dist/
+
+# Python (packages/sdk-python, examples/quickstart).
+**/.venv/
+**/__pycache__/
+**/*.egg-info/
+**/.pytest_cache/
+**/.mypy_cache/
+*.tgz
+
+# Load-generator output from examples/oban-consumer/run.sh (CSVs + JSON reports).
+examples/oban-consumer/.e2e-out/

ankusa-0.2.4/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to `ankusa` (the PyPI package) 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.2.4] - 2026-09-28
+
+### Added
+
+- `RoutesClient(base_url, headers=None, timeout=10.0)`: 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` — with a `RoutesError` hierarchy
+  (`RouteNotFoundError`, `RoutesRejectedError`, `RoutesUnavailableError`).
+- `AdminClient(base_url, headers=None, timeout=10.0)`: the operator client
+  (`admin.port`) — `health`, `metrics`, `config`, `list_dead_letters`,
+  `replay_dead_letters`, `list_quarantined` — with an `AdminError` hierarchy
+  (`RoleNotEnabledError`, `AdminRejectedError`, `AdminUnavailableError`).
+
+### Fixed
+
+- `parse_headers` no longer raises `ValueError` for an `x-ankusa-seq` value
+  that `str.isdigit()` accepts but `int()` rejects (e.g. `²`); a sequence
+  number now requires all-ASCII digits and is `None` otherwise.
+
+## [0.2.1] - 2026-09-28
+
+### Changed
+
+- Claim-check refs are now `urn:ankusa:claim:v1:<tenant>:<claim_id>`, where
+  `claim_id` is a canonical uppercase ULID; `parse_claim_ref` returns
+  `ParsedClaimRef(tenant_id, claim_id, path)` and `redeem` fetches
+  `GET /v1/claims/{tenant_id}/{claim_id}`.
+- `ClaimCheckClient.redeem(ref, sha256)` takes the expected sha256 (the queue
+  message's `sha256` field) and verifies the returned bytes against it. A
+  malformed `sha256` raises `InvalidClaimRefError` before any request.
+
+## [0.1.0] - 2026-09-27
+
+### Added
+
+- `ClaimCheckClient(base_url, headers=None, timeout=10.0)`, the first client
+  this package bundles: `.redeem(ref)` parses a claim-check ref, fetches its
+  bytes from the gateway, and verifies them against the ref's own declared
+  size and sha256 before returning them. `.health()` for a liveness probe.
+  Built on [`httpx`](https://www.python-httpx.org/) against the contract in
+  `priv/openapi/claim_check.v1.yaml`.
+- `parse_claim_ref`, exported standalone.
+- A `ClaimCheckError` hierarchy (`InvalidClaimRefError`,
+  `ClaimNotFoundError`, `ClaimRejectedError`, `ClaimIntegrityError`,
+  `ClaimCheckUnavailableError`), each carrying a `retryable` boolean, so a
+  consumer needs exactly one bit to route a failure to dead-letter or retry.
+- `parse_headers(headers)`, for receivers of Ankusa's HTTP sink: parses
+  `x-ankusa-id`/`x-ankusa-source`/`x-ankusa-seq`/`x-ankusa-tenant`/
+  `content-type` into a `HookHeaders` dataclass, raising
+  `MissingHookIdError` if `x-ankusa-id` is absent.
+
+[Unreleased]: https://github.com/jamescarr/ankusa/compare/sdk-python-v0.2.4...HEAD
+[0.2.4]: https://github.com/jamescarr/ankusa/compare/sdk-python-v0.2.1...sdk-python-v0.2.4
+[0.2.1]: https://github.com/jamescarr/ankusa/releases/tag/sdk-python-v0.2.1
+[0.1.0]: https://github.com/jamescarr/ankusa/releases/tag/sdk-python-v0.1.0

ankusa-0.2.4/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.

ankusa-0.2.4/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.5
+Name: ankusa
+Version: 0.2.4
+Summary: Client SDK for Ankusa deployments. Bundles the claim-check gateway client, the route-management and operator (admin) clients, and a webhook-receiving header helper; more clients (ingest) land here as they're built.
+Project-URL: Repository, https://github.com/jamescarr/ankusa
+Project-URL: Homepage, https://github.com/jamescarr/ankusa/tree/main/packages/sdk-python
+Project-URL: Issues, https://github.com/jamescarr/ankusa/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: admin,ankusa,claim-check,routes,webhook
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# ankusa
+
+The client SDK for [Ankusa](https://github.com/jamescarr/ankusa) deployments:
+one PyPI package 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 and a webhook-receiving header helper; more clients (ingest, admin)
+land here as they're built.
+
+## Install
+
+Not published yet. Until the first release, depend on it as a local path,
+the same way the Elixir packages in this monorepo depend on `ankusa` core
+before their first Hex release, and `packages/sdk-typescript` depends on
+itself via `file:`.
+
+With [`uv`](https://docs.astral.sh/uv/):
+
+```toml
+[project]
+dependencies = ["ankusa"]
+
+[tool.uv.sources]
+ankusa = { path = "../../packages/sdk-python" }
+```
+
+Or with plain `pip`:
+
+```sh
+pip install -e ../../packages/sdk-python
+```
+
+## 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.
+
+```python
+import os
+
+from ankusa import ClaimCheckClient, ClaimCheckError
+
+claim_check = ClaimCheckClient(os.environ.get("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: dict) -> bytes:
+    try:
+        return claim_check.redeem(message["claim"], message["sha256"])
+    except ClaimCheckError as err:
+        if not err.retryable:
+            # bad ref/sha256, 404, or an integrity mismatch: dead-letter, don't requeue
+            raise
+        # gateway unreachable or 5xx: safe to retry
+        raise
+```
+
+`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}`) (`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` attribute,
+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.
+
+`ClaimCheckClient` owns an `httpx.Client`; use it as a context manager
+(`with ClaimCheckClient(...) as claim_check:`) or call `.close()` yourself
+when done.
+
+## Webhook receiver helper
+
+Every receiver of Ankusa's HTTP sink needs the same handful of headers off
+each request; `parse_headers` replaces the hand-rolled `self.headers.get(...)`
+calls with one call and a typed result:
+
+```python
+from ankusa import MissingHookIdError, parse_headers
+
+def do_POST(self):
+    try:
+        hook = parse_headers(self.headers)
+    except MissingHookIdError:
+        self.send_response(400)
+        self.end_headers()
+        return
+
+    body = self.rfile.read(int(self.headers.get("content-length", "0")))
+    # hook.id, hook.source, hook.seq, hook.tenant, hook.content_type
+    ...
+```
+
+`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.
+
+[`examples/quickstart/worker.py`](https://github.com/jamescarr/ankusa/tree/main/examples/quickstart/worker.py)
+uses this.
+
+## 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).
+
+```python
+import os
+
+from ankusa import RoutesClient
+
+routes = RoutesClient(os.environ.get("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()`. Failures are `RoutesError` subclasses with a
+`retryable` attribute: `RouteNotFoundError` (404), `RoutesRejectedError`
+(400/409, carrying `code`, `field`, `message`, `conflicting_id`,
+`max_routes`), and `RoutesUnavailableError` (5xx/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`.
+
+```python
+import os
+
+from ankusa import AdminClient
+
+admin = AdminClient(os.environ.get("ADMIN_URL", "http://localhost:4002"))
+
+admin.health()                          # {"status": "ok", "instance": ..., "roles": [...]}
+admin.list_dead_letters(limit=10)
+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, carrying `role`),
+`AdminRejectedError` (400, carrying `code`), and `AdminUnavailableError`
+(5xx/unreachable, retryable).
+
+## Layout
+
+```
+src/ankusa/
+  __init__.py           # umbrella barrel: re-exports every client this package bundles
+  py.typed
+  webhook.py             # x-ankusa-* header parsing for HTTP-sink receivers
+  claim_check/           # the claim-check gateway client
+    __init__.py          # barrel for this client
+    client.py
+    ref.py
+    errors.py
+  routes/                # the route-management client (routes.admin.port)
+    __init__.py
+    client.py
+    errors.py
+  admin/                 # the operator client (admin.port)
+    __init__.py
+    client.py
+    errors.py
+tests/
+  test_client.py
+  test_ref.py
+  test_webhook.py
+  test_routes.py
+  test_admin.py
+```
+
+A future client (say, an ingest helper) gets its own `src/ankusa/<name>/`
+directory with the same shape, re-exported from `src/ankusa/__init__.py`.
+
+## Develop
+
+```sh
+uv sync
+uv run pytest
+uv run mypy
+```