bunqueue-client 0.1.5__tar.gz

bunqueue_client-0.1.5/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/

bunqueue_client-0.1.5/CHANGELOG.md

@@ -0,0 +1,183 @@
+# Changelog
+
+All notable changes to `bunqueue-client` (Python SDK) are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.5] - 2026-07-20
+
+First version published on PyPI: `pip install bunqueue-client`.
+
+### Fixed
+
+- Reject MessagePack payloads larger than the protocol's 64 MiB frame cap
+  locally with `SerializationError`, before registering a pending request or
+  writing to the socket.
+- Recursively validate commands before writing: cyclic containers, non-string
+  map keys, and integers beyond float64 range now raise `SerializationError`
+  without leaking pending requests. Shared containers remain valid; binary
+  values and list/tuple arrays keep their wire representation.
+
+### Added
+
+- Dependency-free structured transport telemetry through the optional
+  `on_telemetry` callback, with lifecycle, auth, command latency, timeout,
+  reconnect, and error events. Consumer exceptions are isolated.
+- Focused real-server telemetry tests. Connection lifecycle and frame helpers
+  were split into single-responsibility modules below the 300-line source cap.
+- Add independent-thread idempotency and single-lease races, fixed-seed
+  generated payload invariants, malformed mutation fuzzing, and an opt-in
+  sustained producer profile.
+
+## [0.1.4] - 2026-07-14
+
+Conformance-suite driven: the SDK is now certified by the cross-language
+conformance kit (`sdk/conformance`, 17/17) against the formal wire spec
+(`docs/protocol.md`).
+
+### Fixed
+
+- **`drain()` now returns the number of removed jobs** (was `None`,
+  silently discarding the wire `count`).
+
+## [0.1.3] - 2026-07-14
+
+Spec-alignment audit against the core protocol. Every fix ships with a repro
+test in `tests/e2e_spec_align.py`.
+
+### Fixed
+
+- **`heartbeat_interval_s=0` now disables heartbeats.** Previously
+  `Event.wait(0)` made the heartbeat loop busy-spin, flooding the server with
+  `Heartbeat` commands. `0` (or negative) now matches the official client's
+  "0 = disabled" semantics.
+- **`batch_size` is clamped to the server maximum (1000).** The server
+  rejects `PULLB` with `count > 1000`; an unclamped `batch_size` combined
+  with `concurrency > 1000` wedged the poll loop in a permanent error cycle.
+- **FAIL stack truncation no longer loses the raise site.** The worker sent
+  the last 20 traceback lines but the server persists only the FIRST
+  `stackTraceLimit` lines (default 10), so long tracebacks kept a middle
+  window without the raise site. The worker now sends at most as many
+  trailing lines as the server keeps, honoring a per-job `stackTraceLimit`.
+- **Simple Mode `cron()`/`every()` forward the execution `limit=`.** The
+  option was silently dropped (the "client drops a wire-supported field"
+  class, #111); it now reaches the scheduler as wire `maxLimit`.
+- **`wait_for_job()` clamps `timeout_ms` to the server cap (600000).**
+  Larger values were rejected by the server with "timeout must be at most
+  600000" instead of waiting.
+- **`PROTOCOL_VERSION` bumped to 2**, matching the version the server
+  advertises in `Hello`.
+
+## [0.1.2] - 2026-07-10
+
+Second audit pass: packaging, connection failure paths, worker lifecycle
+edges. New fixes ship with repro tests in `tests/e2e_audit_fixes.py` and
+`tests/e2e_worker.py`.
+
+### Added
+
+- **Opt-in ACKB batching for the Worker** (TS SDK parity):
+  `Worker(..., ack_batch={"max_size": 50, "max_delay_ms": 5})` buffers
+  successful ACKs and flushes them as a single `ACKB` round-trip on size,
+  delay, or close. A job stays active (lock renewed) until its batch settles;
+  on a failed batch each job gets an `error` event and `completed` is NOT
+  emitted. (H2)
+- **PEP 561**: the package now ships `bunqueue/py.typed`, so type checkers
+  consume the inline hints; `Typing :: Typed` classifier added. (H1)
+- **Logging**: a `logging.getLogger("bunqueue")` logger (NullHandler attached
+  in `__init__`) now surfaces the previously silent failure points at warning
+  level: `_safe_call` swallowed errors, raising event listeners, failed worker
+  registrations, priority-aging ticks, ACKB settle-callback errors. (H2)
+- `Worker` is now a context manager (`with Worker(...) as w:`), matching
+  `Queue` and `FlowProducer`. (M3)
+- `SerializationError` (subclass of `BunqueueError`), raised when a command
+  payload cannot be msgpack-serialized; the original error is chained. (M1)
+
+### Fixed
+
+- **Pending-future leak on serialization failure.** `Connection._send`
+  registered the reqId future before `msgpack.packb`; an unserializable
+  payload (e.g. a `datetime` in job data) leaked the entry forever and
+  surfaced as a raw `TypeError`. Payloads now serialize first and failures
+  raise `SerializationError`. (M1)
+- **TLS handshake failures** now close the raw socket (no fd leak), count into
+  the same reconnect backoff as plain connect failures, and raise
+  `ConnectionClosedError` with the `ssl` error chained, instead of leaking a
+  raw `ssl.SSLError`. (M2)
+- **Worker close edges**: `close()` with `autorun=False` and `run()` never
+  called now marks the worker closed and closes its connection; an expired
+  `close(timeout)` returns `False` and keeps the live thread reference (state
+  stays honest, a later `close()` joins again) instead of nulling it. (M3)
+- **Register false-success.** A failed `RegisterWorker` no longer marks the
+  generation as registered, so the next poll iteration retries; previously the
+  server could stay unaware of the worker until the next reconnect
+  (Discussion #103 class). (M5)
+- **Scheduler template priority/deduplication** (#111 class, TS SDK parity):
+  `upsert_job_scheduler` now sends the template's `priority` and
+  `deduplication` (`uniqueKey`/`dedup`) as top-level `Cron` fields, where the
+  server actually reads them; inside `jobOptions` they were silently ignored
+  and spawned jobs fell back to defaults.
+- **move_job_to_failed with an exception** (#111 class, TS SDK parity): when
+  passed an `Exception`, the FAIL command now carries `stack` (bounded
+  traceback lines, last-lines like the worker path) and the `unrecoverable`
+  flag for `UnrecoverableError`, so the failure intent and stacktrace persist
+  server-side. String errors travel unchanged.
+
+### Verified
+
+- Not-found narrowing: `get_job`, `get_job_by_custom_id`, `get_job_scheduler`
+  and `get_flow` already catch only `CommandError` with a "not found" message
+  (mapping it to `None`) and rethrow everything else; connection/timeout
+  failures never masquerade as a missing job. Regression test added.
+
+### Packaging
+
+- `LICENSE` (MIT) now ships with the sdist/wheel; pyproject uses the SPDX
+  `license = "MIT"` expression with `license-files` (hatchling >= 1.27).
+- Classifiers for Python 3.9 through 3.13; `Repository` and `Changelog`
+  project URLs. (M4)
+
+## [0.1.1] - 2026-07-08
+
+Protocol-coherence audit against the bunqueue server. Every fix ships with a
+RED→GREEN repro in `tests/e2e_audit_fixes.py`.
+
+### Fixed
+
+- **add_bulk dropped the custom job id.** PUSHB entries are `JobInput`
+  (`customId`), not the single-PUSH `jobId` the server renames — the batch
+  path now renames `jobId`→`customId`, so `get_job_by_custom_id` and idempotent
+  bulk ingest work. (H1)
+- **Half-open link wedge.** Enable `SO_KEEPALIVE` (~15s idle) and tear down the
+  socket after 3 consecutive command timeouts so the next call reconnects,
+  instead of wedging until the OS abandons the writes. The teardown is
+  generation-guarded so a stale-connection timeout can't abort a fresh
+  reconnect. (H2)
+- **Auth race on reconnect.** `_conn_lock` is now reentrant and Auth is sent
+  while holding it, flipping `_connected` only after Auth completes — a
+  concurrent thread can no longer send a command ahead of the Auth frame
+  (server would reject it `Not authenticated`). (H3)
+- **get_flow crashed on a missing job.** A missing root/child now yields `None`
+  and is skipped (partial tree) instead of raising; the catch is narrowed to
+  `'not found'` so real server errors still surface, and a `visited` set guards
+  against cycles now that `depth` defaults to unlimited. (H4)
+- **wait_for_job returned `None` on timeout.** It now raises on non-completion:
+  a `failed` job raises `CommandError`, otherwise `CommandTimeoutError` — the
+  `completed` flag is no longer ignored. (M1)
+
+### Changed
+
+- Simple Mode cron (`Bunqueue.cron`/`every`, `upsert_job_scheduler`) now maps
+  Pythonic job options snake_case→camelCase via `build_cron_job_options`
+  (`attempts`→`maxAttempts`, `remove_on_complete`→`removeOnComplete`, …) so
+  cron-spawned jobs honor the requested retry/cleanup policy instead of falling
+  back to server defaults; also forwards `skip_missed_on_restart`. (M3)
+- `retry_dlq` / `retry_jobs`: the dead `count` field is no longer sent on the
+  wire (the server has no partial RetryDlq; `count` is accepted only for
+  signature parity).
+
+## [0.1.0] - initial published release
+
+- TCP client (msgpack wire protocol): `Queue`, `Worker`, `FlowProducer`,
+  `Bunqueue` Simple Mode, TLS, auth, reqId pipelining.

bunqueue_client-0.1.5/CLAUDE.md

@@ -0,0 +1,89 @@
+# bunqueue Python SDK — development guide
+
+Python client SDK for the bunqueue server. Speaks ONLY the native TCP
+protocol (msgpack). Parity reference: the official TypeScript client in
+`../../src/client/` (TCP mode — embedded/sandboxed/QueueEvents are excluded
+by design: they require the in-process Bun runtime).
+
+## Non-negotiable rules
+
+1. **Never touch the bunqueue core** (`../../src/`): this SDK lives here only.
+2. **Max 250 lines per file** — split into modules/mixins, don't compress.
+3. **Single runtime dependency: `msgpack`** — nothing else.
+4. **Protocol source of truth**: `../../src/domain/types/command.ts`
+   (commands), `../../src/domain/types/response.ts` (responses),
+   `../../src/infrastructure/server/handlers/` (actual shapes). When in
+   doubt, read the handler — never guess.
+5. Every new method → matching e2e test in `tests/e2e_*.py`.
+6. All docs, comments, and identifiers in English.
+
+## Module map
+
+| File | Role |
+|---|---|
+| `wire.py` | Wire helpers: `_compact` (drop None), `_js_safe` (int→float64), TLS context |
+| `connection.py` | Socket + reader thread, reqId→Future pipelining, auth, lazy reconnect |
+| `errors.py` | Hierarchy: `BunqueueError` → Connection/Timeout/Command/Auth + `UnrecoverableError` |
+| `events.py` | Thread-safe EventEmitter (on/once/off/emit) |
+| `options.py` | Pythonic kwargs → PUSH wire fields (`attempts`→`maxAttempts`, etc.) |
+| `job.py` | Job wrapper: properties + per-id operations (progress, log, lock, retry…) |
+| `queue.py` | Queue core: produce + control; composes the mixins |
+| `queue_query.py` | Query mixin: getJob(s), states, counts, logs, children values |
+| `queue_admin.py` | Admin mixin: DLQ, configs, rate limit, schedulers/cron, webhooks, monitoring |
+| `worker.py` | Worker lifecycle: start/run/pause/close, events |
+| `worker_runtime.py` | Worker runtime mixin: poll loop, job execution, heartbeats, registry |
+| `flow.py` | FlowProducer: tree/chain/fan-in, UpdateParent, rollback |
+| `simple/app.py` + `simple/app_api.py` | `Bunqueue` Simple Mode: constructor + processing pipeline, API mixin |
+| `simple/{retry,circuit_breaker,batch,triggers,aging,cancellation,ttl,dedup_debounce}.py` | Simple Mode subsystems, 1:1 with `src/client/bunqueue/` |
+
+## Wire protocol (VITAL gotchas)
+
+- Frame = 4-byte big-endian u32 length + standard msgpack map. Request
+  `{cmd, reqId, ...}`; response `{ok, reqId, ...}`; `ok:false` → `error` field.
+- Auth = first command `{cmd:'Auth', token}`. `Hello` for version negotiation.
+- **BigInt killer**: Python ints outside the int32 range travel as
+  int64/uint64 msgpack → the server (msgpackr) decodes them as `BigInt` →
+  arithmetic crash (e.g. `ListWorkers`). `_js_safe()` converts them to
+  float64 (exact ≤ 2^53). NEVER remove this conversion.
+- The **job name travels inside `data`**: `data = {"name": ..., **user}`.
+- Responses **wrapped in `data`**: `GetLogs→data.logs`,
+  `ListWorkers→data.workers`, `GetChildrenValues→data.values`,
+  `AddWebhook→data.webhookId`, `ListWebhooks→data.webhooks`, `Ping→data.pong`.
+- Responses **top-level**: `IsPaused→paused`, `CronGet→cron`,
+  `GetProgress→progress/message`, `PULL→job+token`, `PULLB→jobs+tokens`,
+  `PUSH→id`, `PUSHB→ids`, `Count/Clean→count`.
+- `Progress` only works on **active** jobs (errors on waiting).
+- `lifo` orders only among jobs that are **both** lifo; mixed → FIFO by runAt.
+- `GetJobs`/`PromoteJobs` read from SQLite: the write buffer flushes every
+  ~10ms → in tests wait with `wait_until`, never assert right after a push.
+- Not-found (`GetJob`, `GetJobByCustomId`, `CronGet`) → the server answers a
+  "not found" error: the SDK maps it to `None`; don't leak the exception.
+- Webhooks: localhost/private URLs rejected (SSRF guard); valid events look
+  like `job.completed`.
+- `retry_job` over TCP = `MoveToWait`; `retry_jobs("failed")` = `RetryDlq`;
+  `retry_jobs("completed")` = `RetryCompleted`.
+- `FAIL` supports `unrecoverable: true` (skip retries → DLQ) and
+  `stack: string[]` (persisted, capped at `stackTraceLimit`).
+
+## Tests
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install msgpack   # once
+.venv/bin/python tests/test_integration.py   # smoke (8) — also pytest-compatible
+.venv/bin/python tests/run_e2e.py            # full e2e (112)
+BUNQUEUE_SDK_SOAK_SECONDS=3600 .venv/bin/python tests/soak.py
+```
+
+Both spawn a real server (`bun src/main.ts` from the repo root, random port,
+temp DB). `tests/harness.py` = server fixture + `@test` registry +
+`wait_until`. The auth suite uses a dedicated server with `AUTH_TOKENS`.
+
+## New-method checklist
+
+1. Find the command in `command.ts` and the response shape in its handler.
+2. Add the method in the right mixin (query/admin/core) — snake_case mirror
+   of the TS name (`getJobCounts` → `get_job_counts`).
+3. `_compact()` the payload; unwrap the response correctly (see gotchas).
+4. Add an e2e test in the matching `tests/e2e_<area>.py`.
+5. `run_e2e.py` + `test_integration.py` green. Update the README if the
+   public surface changed.

bunqueue_client-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Egeo Minotti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bunqueue_client-0.1.5/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: bunqueue-client
+Version: 0.1.5
+Summary: Python client SDK for bunqueue — high-performance job queue server (TCP mode)
+Project-URL: Homepage, https://github.com/egeominotti/bunqueue
+Project-URL: Documentation, https://bunqueue.dev
+Project-URL: Repository, https://github.com/egeominotti/bunqueue
+Project-URL: Changelog, https://github.com/egeominotti/bunqueue/blob/main/sdk/python/CHANGELOG.md
+Author: Egeo Minotti
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bunqueue,jobs,queue,task-queue,worker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: msgpack>=1.0.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<a href="https://bunqueue.dev">
+  <img src="https://raw.githubusercontent.com/egeominotti/bunqueue/main/.github/logo.png" alt="bunqueue logo" width="110" />
+</a>
+
+# bunqueue-client (Python)
+
+**The official Python client for [bunqueue](https://bunqueue.dev), the high performance job queue server.**
+
+Native TCP protocol (msgpack, pipelined), one runtime dependency (`msgpack`), sync plus thread based workers.
+
+[![license](https://img.shields.io/badge/license-MIT-1a1a2e)](https://github.com/egeominotti/bunqueue/blob/main/sdk/python/LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-2ea44f)](https://github.com/egeominotti/bunqueue/tree/main/sdk/python)
+[![conformance](https://img.shields.io/badge/protocol-conformant%2017%2F17-d3156d)](https://github.com/egeominotti/bunqueue/tree/main/sdk/conformance)
+
+[Documentation](https://bunqueue.dev/guide/sdks/) · [Protocol spec](https://github.com/egeominotti/bunqueue/blob/main/docs/protocol.md) · [Server](https://github.com/egeominotti/bunqueue) · [Changelog](https://github.com/egeominotti/bunqueue/blob/main/sdk/python/CHANGELOG.md)
+
+</div>
+
+---
+
+Python client for [bunqueue](https://github.com/egeominotti/bunqueue), the
+high-performance job queue server for Bun. Talks the native TCP protocol
+(msgpack, pipelined) with the same core API as the TypeScript SDK, including
+opt-in ACK batching and dependency-free structured transport telemetry.
+Connection pooling remains TypeScript-only for now.
+
+The bunqueue **server** runs on Bun (or as a compiled binary / Docker). This
+SDK lets any Python service produce and consume jobs on it: *one queue, any
+language*.
+
+## Install
+
+```bash
+# PyPI release coming soon; install from the repo today:
+pip install "git+https://github.com/egeominotti/bunqueue.git#subdirectory=sdk/python"
+# dependency: msgpack; import name: bunqueue
+```
+
+Requires Python ≥ 3.9 and a running bunqueue server (`bunx bunqueue start`).
+
+## Quick start
+
+```python
+from bunqueue import Queue, Worker
+
+# Producer
+queue = Queue("emails", host="localhost", port=6789)
+job = queue.add("send", {"to": "user@example.com"}, priority=5, attempts=3)
+print(job.id)
+
+# Consumer
+def process(job):
+    job.update_progress(50)
+    return {"sent": True}
+
+worker = Worker("emails", process, concurrency=10)
+worker.on("completed", lambda job, result: print(job.id, result))
+worker.run()  # blocking; or worker.start() for a background thread
+```
+
+All queue semantics (retry, backoff, DLQ, priorities, stall detection, cron)
+run **server-side** — the worker only pulls, heartbeats, and acks.
+
+## Feature surface
+
+- **Queue**: `add`, `add_bulk`, full job options (priority, delay, attempts,
+  backoff, ttl, timeout, job_id, deduplication, depends_on, tags, group_id,
+  lifo, remove_on_complete/fail, durable, repeat, debounce, …)
+- **Query**: `get_job`, `get_job_by_custom_id`, `get_jobs` (+ per-state
+  helpers), `get_state`, `get_result`, `get_progress`, `wait_for_job`
+  (raises `CommandTimeoutError` on timeout, BullMQ contract),
+  counts (+ per-priority), children values, job logs
+- **Control**: pause/resume/drain/obliterate/clean, remove, discard,
+  promote (single/bulk), retry_job / retry_jobs, move to wait/delayed,
+  change priority/delay, update data, extend lock
+- **DLQ**: `get_dlq`, `retry_dlq`, `purge_dlq`, DLQ config
+- **Schedulers**: `upsert_job_scheduler` (cron pattern or interval),
+  `add_cron` / `every` shorthands, get/list/remove
+- **Admin**: rate limit, global concurrency, stall config, webhooks,
+  stats/metrics/list_queues/get_workers
+- **Worker**: events (`ready`, `active`, `completed`, `failed`, `progress`,
+  `drained`, `error`, `closed`), pause/resume, graceful `close()` (also a
+  context manager), automatic lock heartbeats (jobs longer than the lock TTL
+  survive), `UnrecoverableError` to skip retries, opt-in ACK batching
+  (`ack_batch={"max_size": 50, "max_delay_ms": 5}`: successful ACKs flush as
+  one `ACKB` on size/delay/close; a job stays active until its batch settles)
+- **FlowProducer**: `add` (parent/child trees), `add_bulk`, `add_chain`
+  (sequential), `add_bulk_then` (fan-in), `get_flow`, atomic rollback
+- **Simple Mode** (`Bunqueue`): Queue + Worker in one object — routes,
+  onion middleware, in-process retry (fixed/exponential/jitter/fibonacci/
+  custom + `retry_if`), circuit breaker, batch accumulation, event triggers,
+  job TTL, priority aging, cooperative cancellation (`get_signal`),
+  dedup/debounce defaults, cron shorthands — 1:1 with the official client
+  (TCP mode; `embedded` raises)
+- **Connection**: auth token, TLS (`tls=True`, `{"ca_file": ...}`,
+  `{"verify": False}`), pipelining, lazy reconnect, structured telemetry
+
+Not applicable outside Bun (by design): embedded mode, sandboxed workers,
+`QueueEvents` (in-process subscription; use webhooks or SSE/WS on the HTTP
+port instead).
+
+## Errors
+
+```python
+from bunqueue import (
+    BunqueueError,        # base
+    ConnectionClosedError,
+    CommandTimeoutError,
+    CommandError,         # server answered ok=false
+    AuthError,
+    SerializationError,   # payload not msgpack-serializable (e.g. datetime)
+    UnrecoverableError,   # raise in a processor: fail terminally, no retries
+)
+```
+
+The SDK logs its otherwise-silent failure points (swallowed command errors,
+raising listeners, failed registrations) at warning level on the `bunqueue`
+logger; attach a handler to see them.
+
+### Structured telemetry
+
+Pass `on_telemetry` to `Connection` or `Queue` to bridge transport metrics to
+OpenTelemetry, Prometheus, or your logger without adding an SDK dependency:
+
+```python
+queue = Queue("emails", on_telemetry=lambda event: metrics.record(event))
+```
+
+Events cover `connect`, `disconnect`, `reconnect_scheduled`, `auth`, `command`,
+`command_timeout`, and `error`. Command events contain the command name,
+request id, outcome, and monotonic duration. Payloads and authentication tokens
+are never included. A telemetry callback that raises is isolated from the
+transport and cannot fail a queue operation.
+
+## Protocol notes
+
+- Wire: 4-byte big-endian length prefix + standard msgpack map per message;
+  requests carry a `reqId` echoed by the server (pipelining).
+- Integers outside int32 are sent as float64 (exact ≤ 2^53): the server's
+  msgpack decoder turns int64 into `BigInt`, which its arithmetic rejects.
+  The SDK handles this automatically. Consequence: integers larger than 2^53
+  (e.g. 64-bit snowflake IDs) lose precision — pass them as **strings**.
+- Command maps require string keys at every nesting level. Cyclic containers
+  and integers outside the float64 range raise `SerializationError` locally,
+  before a pending request is registered or any bytes are written. Binary
+  values and array-like lists/tuples are preserved by the wire normalizer.
+
+## Tests
+
+```bash
+python -m venv .venv && .venv/bin/pip install msgpack
+.venv/bin/python tests/test_integration.py   # basic (8)
+.venv/bin/python tests/run_e2e.py            # full e2e vs real server (112)
+BUNQUEUE_SDK_SOAK_SECONDS=3600 .venv/bin/python tests/soak.py
+```
+
+Both spawn a real bunqueue server (`bun src/main.ts` from the repo root). The
+E2E runner emits a monotonic duration for each case so the isolated SDK gate
+can rank slow tests without relying on timing assertions. Hardening covers
+independent-connection idempotency and single-lease contention, fixed-seed
+generated payloads, malformed mutation corpora, 1000-job bursts, and
+crash/restart recovery. The opt-in soak keeps one connection alive; set
+`BUNQUEUE_SDK_SOAK_BATCH` to increase load.
+
+## License
+
+MIT. See the [LICENSE](https://github.com/egeominotti/bunqueue/blob/main/sdk/python/LICENSE) file.
+Documentation: [bunqueue.dev/guide/sdks](https://bunqueue.dev/guide/sdks/).
+Issues and feature requests: [GitHub issues](https://github.com/egeominotti/bunqueue/issues).

bunqueue_client-0.1.5/README.md

@@ -0,0 +1,171 @@
+<div align="center">
+
+<a href="https://bunqueue.dev">
+  <img src="https://raw.githubusercontent.com/egeominotti/bunqueue/main/.github/logo.png" alt="bunqueue logo" width="110" />
+</a>
+
+# bunqueue-client (Python)
+
+**The official Python client for [bunqueue](https://bunqueue.dev), the high performance job queue server.**
+
+Native TCP protocol (msgpack, pipelined), one runtime dependency (`msgpack`), sync plus thread based workers.
+
+[![license](https://img.shields.io/badge/license-MIT-1a1a2e)](https://github.com/egeominotti/bunqueue/blob/main/sdk/python/LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-2ea44f)](https://github.com/egeominotti/bunqueue/tree/main/sdk/python)
+[![conformance](https://img.shields.io/badge/protocol-conformant%2017%2F17-d3156d)](https://github.com/egeominotti/bunqueue/tree/main/sdk/conformance)
+
+[Documentation](https://bunqueue.dev/guide/sdks/) · [Protocol spec](https://github.com/egeominotti/bunqueue/blob/main/docs/protocol.md) · [Server](https://github.com/egeominotti/bunqueue) · [Changelog](https://github.com/egeominotti/bunqueue/blob/main/sdk/python/CHANGELOG.md)
+
+</div>
+
+---
+
+Python client for [bunqueue](https://github.com/egeominotti/bunqueue), the
+high-performance job queue server for Bun. Talks the native TCP protocol
+(msgpack, pipelined) with the same core API as the TypeScript SDK, including
+opt-in ACK batching and dependency-free structured transport telemetry.
+Connection pooling remains TypeScript-only for now.
+
+The bunqueue **server** runs on Bun (or as a compiled binary / Docker). This
+SDK lets any Python service produce and consume jobs on it: *one queue, any
+language*.
+
+## Install
+
+```bash
+# PyPI release coming soon; install from the repo today:
+pip install "git+https://github.com/egeominotti/bunqueue.git#subdirectory=sdk/python"
+# dependency: msgpack; import name: bunqueue
+```
+
+Requires Python ≥ 3.9 and a running bunqueue server (`bunx bunqueue start`).
+
+## Quick start
+
+```python
+from bunqueue import Queue, Worker
+
+# Producer
+queue = Queue("emails", host="localhost", port=6789)
+job = queue.add("send", {"to": "user@example.com"}, priority=5, attempts=3)
+print(job.id)
+
+# Consumer
+def process(job):
+    job.update_progress(50)
+    return {"sent": True}
+
+worker = Worker("emails", process, concurrency=10)
+worker.on("completed", lambda job, result: print(job.id, result))
+worker.run()  # blocking; or worker.start() for a background thread
+```
+
+All queue semantics (retry, backoff, DLQ, priorities, stall detection, cron)
+run **server-side** — the worker only pulls, heartbeats, and acks.
+
+## Feature surface
+
+- **Queue**: `add`, `add_bulk`, full job options (priority, delay, attempts,
+  backoff, ttl, timeout, job_id, deduplication, depends_on, tags, group_id,
+  lifo, remove_on_complete/fail, durable, repeat, debounce, …)
+- **Query**: `get_job`, `get_job_by_custom_id`, `get_jobs` (+ per-state
+  helpers), `get_state`, `get_result`, `get_progress`, `wait_for_job`
+  (raises `CommandTimeoutError` on timeout, BullMQ contract),
+  counts (+ per-priority), children values, job logs
+- **Control**: pause/resume/drain/obliterate/clean, remove, discard,
+  promote (single/bulk), retry_job / retry_jobs, move to wait/delayed,
+  change priority/delay, update data, extend lock
+- **DLQ**: `get_dlq`, `retry_dlq`, `purge_dlq`, DLQ config
+- **Schedulers**: `upsert_job_scheduler` (cron pattern or interval),
+  `add_cron` / `every` shorthands, get/list/remove
+- **Admin**: rate limit, global concurrency, stall config, webhooks,
+  stats/metrics/list_queues/get_workers
+- **Worker**: events (`ready`, `active`, `completed`, `failed`, `progress`,
+  `drained`, `error`, `closed`), pause/resume, graceful `close()` (also a
+  context manager), automatic lock heartbeats (jobs longer than the lock TTL
+  survive), `UnrecoverableError` to skip retries, opt-in ACK batching
+  (`ack_batch={"max_size": 50, "max_delay_ms": 5}`: successful ACKs flush as
+  one `ACKB` on size/delay/close; a job stays active until its batch settles)
+- **FlowProducer**: `add` (parent/child trees), `add_bulk`, `add_chain`
+  (sequential), `add_bulk_then` (fan-in), `get_flow`, atomic rollback
+- **Simple Mode** (`Bunqueue`): Queue + Worker in one object — routes,
+  onion middleware, in-process retry (fixed/exponential/jitter/fibonacci/
+  custom + `retry_if`), circuit breaker, batch accumulation, event triggers,
+  job TTL, priority aging, cooperative cancellation (`get_signal`),
+  dedup/debounce defaults, cron shorthands — 1:1 with the official client
+  (TCP mode; `embedded` raises)
+- **Connection**: auth token, TLS (`tls=True`, `{"ca_file": ...}`,
+  `{"verify": False}`), pipelining, lazy reconnect, structured telemetry
+
+Not applicable outside Bun (by design): embedded mode, sandboxed workers,
+`QueueEvents` (in-process subscription; use webhooks or SSE/WS on the HTTP
+port instead).
+
+## Errors
+
+```python
+from bunqueue import (
+    BunqueueError,        # base
+    ConnectionClosedError,
+    CommandTimeoutError,
+    CommandError,         # server answered ok=false
+    AuthError,
+    SerializationError,   # payload not msgpack-serializable (e.g. datetime)
+    UnrecoverableError,   # raise in a processor: fail terminally, no retries
+)
+```
+
+The SDK logs its otherwise-silent failure points (swallowed command errors,
+raising listeners, failed registrations) at warning level on the `bunqueue`
+logger; attach a handler to see them.
+
+### Structured telemetry
+
+Pass `on_telemetry` to `Connection` or `Queue` to bridge transport metrics to
+OpenTelemetry, Prometheus, or your logger without adding an SDK dependency:
+
+```python
+queue = Queue("emails", on_telemetry=lambda event: metrics.record(event))
+```
+
+Events cover `connect`, `disconnect`, `reconnect_scheduled`, `auth`, `command`,
+`command_timeout`, and `error`. Command events contain the command name,
+request id, outcome, and monotonic duration. Payloads and authentication tokens
+are never included. A telemetry callback that raises is isolated from the
+transport and cannot fail a queue operation.
+
+## Protocol notes
+
+- Wire: 4-byte big-endian length prefix + standard msgpack map per message;
+  requests carry a `reqId` echoed by the server (pipelining).
+- Integers outside int32 are sent as float64 (exact ≤ 2^53): the server's
+  msgpack decoder turns int64 into `BigInt`, which its arithmetic rejects.
+  The SDK handles this automatically. Consequence: integers larger than 2^53
+  (e.g. 64-bit snowflake IDs) lose precision — pass them as **strings**.
+- Command maps require string keys at every nesting level. Cyclic containers
+  and integers outside the float64 range raise `SerializationError` locally,
+  before a pending request is registered or any bytes are written. Binary
+  values and array-like lists/tuples are preserved by the wire normalizer.
+
+## Tests
+
+```bash
+python -m venv .venv && .venv/bin/pip install msgpack
+.venv/bin/python tests/test_integration.py   # basic (8)
+.venv/bin/python tests/run_e2e.py            # full e2e vs real server (112)
+BUNQUEUE_SDK_SOAK_SECONDS=3600 .venv/bin/python tests/soak.py
+```
+
+Both spawn a real bunqueue server (`bun src/main.ts` from the repo root). The
+E2E runner emits a monotonic duration for each case so the isolated SDK gate
+can rank slow tests without relying on timing assertions. Hardening covers
+independent-connection idempotency and single-lease contention, fixed-seed
+generated payloads, malformed mutation corpora, 1000-job bursts, and
+crash/restart recovery. The opt-in soak keeps one connection alive; set
+`BUNQUEUE_SDK_SOAK_BATCH` to increase load.
+
+## License
+
+MIT. See the [LICENSE](https://github.com/egeominotti/bunqueue/blob/main/sdk/python/LICENSE) file.
+Documentation: [bunqueue.dev/guide/sdks](https://bunqueue.dev/guide/sdks/).
+Issues and feature requests: [GitHub issues](https://github.com/egeominotti/bunqueue/issues).