bunqueue-client 0.1.5__py3-none-any.whl

bunqueue/queue.py

@@ -0,0 +1,230 @@
+"""Queue: producer + control API over the bunqueue TCP protocol.
+
+Feature parity with the TypeScript client's Queue (TCP mode). Query and
+admin surfaces live in :mod:`queue_query` / :mod:`queue_admin` mixins.
+"""
+
+from __future__ import annotations
+
+import traceback
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from .connection import Connection, TlsOption, _compact
+from .errors import UnrecoverableError
+from .job import Job
+from .options import job_options, job_payload
+from .queue_admin import QueueAdminOps
+from .queue_query import QueueQueryOps
+from .worker_runtime import MAX_STACK_LINES
+from .telemetry import TelemetryHandler
+
+
+class Queue(QueueQueryOps, QueueAdminOps):
+    """Producer and management client for one named queue."""
+
+    def __init__(
+        self,
+        name: str,
+        host: str = "localhost",
+        port: int = 6789,
+        token: Optional[str] = None,
+        tls: TlsOption = None,
+        connection: Optional[Connection] = None,
+        command_timeout: float = 10.0,
+        prefix_key: str = "",
+        on_telemetry: Optional[TelemetryHandler] = None,
+    ) -> None:
+        self.name = prefix_key + name
+        self.connection = connection or Connection(
+            host=host,
+            port=port,
+            token=token,
+            tls=tls,
+            command_timeout=command_timeout,
+            on_telemetry=on_telemetry,
+        )
+        self._owns_connection = connection is None
+
+    # --------------------------------------------------------------- produce
+
+    def add(self, name: str, data: Any = None, **options: Any) -> Job:
+        """Add a job; returns a Job stub carrying the assigned id."""
+        payload = job_payload(name, data)
+        opts = job_options(**options)
+        response = self.connection.call({"cmd": "PUSH", "queue": self.name, "data": payload, **opts})
+        return Job({"id": response.get("id"), "queue": self.name, "data": payload, **opts}, self.connection)
+
+    def add_bulk(self, jobs: Sequence[Dict[str, Any]]) -> List[str]:
+        """Add many jobs in one round-trip.
+
+        Each entry: ``{"name": str, "data": Any, ...options}`` with the same
+        option names accepted by :meth:`add`.
+        """
+        inputs = []
+        for entry in jobs:
+            entry = dict(entry)
+            name = entry.pop("name")
+            data = entry.pop("data", None)
+            opts = job_options(**entry)
+            # PUSHB entries are typed JobInput, whose custom-id field is
+            # `customId` — unlike single PUSH which renames `jobId`->`customId`
+            # server-side. Without this rename the batch custom id is dropped
+            # (idempotency/getJobByCustomId broken).
+            if "jobId" in opts:
+                opts["customId"] = opts.pop("jobId")
+            inputs.append({"data": job_payload(name, data), **opts})
+        response = self.connection.call({"cmd": "PUSHB", "queue": self.name, "jobs": inputs})
+        return [str(job_id) for job_id in response.get("ids", [])]
+
+    # --------------------------------------------------------------- control
+
+    def pause(self) -> None:
+        self.connection.call({"cmd": "Pause", "queue": self.name})
+
+    def resume(self) -> None:
+        self.connection.call({"cmd": "Resume", "queue": self.name})
+
+    def is_paused(self) -> bool:
+        response = self.connection.call({"cmd": "IsPaused", "queue": self.name})
+        return bool(response.get("paused"))
+
+    def drain(self) -> int:
+        """Remove all waiting/delayed jobs; returns how many were dropped."""
+        response = self.connection.call({"cmd": "Drain", "queue": self.name})
+        return int(response.get("count", 0))
+
+    def obliterate(self) -> None:
+        self.connection.call({"cmd": "Obliterate", "queue": self.name})
+
+    def clean(self, grace_ms: int, limit: Optional[int] = None, state: Optional[str] = None) -> int:
+        response = self.connection.call(
+            _compact({"cmd": "Clean", "queue": self.name, "grace": grace_ms, "state": state, "limit": limit})
+        )
+        return int(response.get("count", 0))
+
+    def remove(self, job_id: str) -> None:
+        self.connection.call({"cmd": "Cancel", "id": job_id})
+
+    # `cancel` kept as an alias of remove (bunqueue-native name)
+    cancel = remove
+
+    def discard(self, job_id: str) -> None:
+        self.connection.call({"cmd": "Discard", "id": job_id})
+
+    def promote_job(self, job_id: str) -> None:
+        self.connection.call({"cmd": "Promote", "id": job_id})
+
+    def promote_jobs(self, count: Optional[int] = None) -> int:
+        response = self.connection.call(
+            _compact({"cmd": "PromoteJobs", "queue": self.name, "count": count})
+        )
+        return int(response.get("count", 0))
+
+    def retry_job(self, job_id: str) -> None:
+        """BullMQ contract: failed -> waiting (MoveToWait over TCP)."""
+        self.connection.call({"cmd": "MoveToWait", "id": job_id})
+
+    def retry_jobs(self, state: str = "failed", count: Optional[int] = None) -> int:
+        # `count` caps how many DLQ entries are retried (server >= 2.8.29);
+        # older servers ignore it and retry the whole DLQ (forward-compatible).
+        if state == "failed":
+            response = self.connection.call(
+                _compact({"cmd": "RetryDlq", "queue": self.name, "count": count})
+            )
+        elif state == "completed":
+            response = self.connection.call({"cmd": "RetryCompleted", "queue": self.name})
+        else:
+            raise ValueError("state must be 'failed' or 'completed'")
+        return int(response.get("count", 0))
+
+    def retry_completed(self, job_id: Optional[str] = None) -> int:
+        response = self.connection.call(
+            _compact({"cmd": "RetryCompleted", "queue": self.name, "id": job_id})
+        )
+        return int(response.get("count", 0))
+
+    # ----------------------------------------------------- job state changes
+
+    def update_job_progress(self, job_id: str, progress: int, message: Optional[str] = None) -> None:
+        self.connection.call(
+            _compact({"cmd": "Progress", "id": job_id, "progress": progress, "message": message})
+        )
+
+    def update_job_data(self, job_id: str, data: Any) -> None:
+        self.connection.call({"cmd": "Update", "id": job_id, "data": data})
+
+    def change_job_priority(self, job_id: str, priority: int, lifo: Optional[bool] = None) -> None:
+        self.connection.call(
+            _compact({"cmd": "ChangePriority", "id": job_id, "priority": priority, "lifo": lifo})
+        )
+
+    def change_job_delay(self, job_id: str, delay_ms: int) -> None:
+        self.connection.call({"cmd": "ChangeDelay", "id": job_id, "delay": delay_ms})
+
+    def move_job_to_wait(self, job_id: str) -> None:
+        self.connection.call({"cmd": "MoveToWait", "id": job_id})
+
+    def move_job_to_delayed(self, job_id: str, delay_ms: int) -> None:
+        self.connection.call({"cmd": "MoveToDelayed", "id": job_id, "delay": delay_ms})
+
+    def extend_job_lock(self, job_id: str, token: str, duration_ms: int) -> None:
+        self.connection.call(
+            {"cmd": "ExtendLock", "id": job_id, "token": token, "duration": duration_ms}
+        )
+
+    def move_job_to_completed(self, job_id: str, result: Any = None, token: Optional[str] = None) -> None:
+        self.connection.call(_compact({"cmd": "ACK", "id": job_id, "result": result, "token": token}))
+
+    def move_job_to_failed(
+        self, job_id: str, error: Union[BaseException, str], token: Optional[str] = None
+    ) -> None:
+        """Explicit failure path: mirrors the worker's FAIL wire.
+
+        Passing an exception persists its ``stack`` (traceback lines, bounded
+        like the worker path) and the UnrecoverableError "do not retry"
+        intent (#111 silent-loss class), not just the message. String errors
+        travel as before."""
+        if isinstance(error, BaseException):
+            message = str(error) or error.__class__.__name__
+            # Keep the LAST lines: a Python traceback ends with the raise site
+            # and the message (opposite of a JS stack, which leads with them).
+            stack = "".join(
+                traceback.format_exception(type(error), error, error.__traceback__)
+            ).splitlines()[-MAX_STACK_LINES:]
+            unrecoverable = True if isinstance(error, UnrecoverableError) else None
+        else:
+            message, stack, unrecoverable = error, None, None
+        self.connection.call(
+            _compact(
+                {
+                    "cmd": "FAIL",
+                    "id": job_id,
+                    "error": message,
+                    "stack": stack,
+                    "unrecoverable": unrecoverable,
+                    "token": token,
+                }
+            )
+        )
+
+    # ------------------------------------------------------------- lifecycle
+
+    def ping(self) -> bool:
+        return self.connection.ping()
+
+    def wait_until_ready(self) -> None:
+        self.connection.connect()
+
+    def close(self) -> None:
+        if self._owns_connection:
+            self.connection.close()
+
+    def disconnect(self) -> None:
+        """BullMQ-parity alias for :meth:`close`."""
+        self.close()
+
+    def __enter__(self) -> "Queue":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

bunqueue/queue_admin.py

@@ -0,0 +1,201 @@
+"""Admin operations mixin for Queue: DLQ, configs, rate limits, schedulers,
+webhooks, monitoring. Mirrors the TS client's management surface (TCP mode)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .connection import _compact
+from .errors import CommandError
+from .options import build_cron_job_options
+
+
+class QueueAdminOps:
+    """Mixin: requires ``self.name`` and ``self.connection``."""
+
+    # ------------------------------------------------------------------- dlq
+
+    def get_dlq(self, count: Optional[int] = None) -> List[Dict[str, Any]]:
+        response = self.connection.call(_compact({"cmd": "Dlq", "queue": self.name, "count": count}))
+        return list(response.get("jobs") or response.get("data") or [])
+
+    def retry_dlq(self, job_id: Optional[str] = None, count: Optional[int] = None) -> int:
+        # `count` caps how many DLQ entries are retried when no `job_id` is
+        # given (server >= 2.8.29); older servers ignore it (forward-compatible).
+        response = self.connection.call(
+            _compact({"cmd": "RetryDlq", "queue": self.name, "jobId": job_id, "count": count})
+        )
+        return int(response.get("count", 0))
+
+    def purge_dlq(self) -> int:
+        response = self.connection.call({"cmd": "PurgeDlq", "queue": self.name})
+        return int(response.get("count", 0))
+
+    def set_dlq_config(self, config: Dict[str, Any]) -> None:
+        self.connection.call({"cmd": "SetDlqConfig", "queue": self.name, "config": config})
+
+    def get_dlq_config(self) -> Dict[str, Any]:
+        response = self.connection.call({"cmd": "GetDlqConfig", "queue": self.name})
+        return dict(response.get("config") or response.get("data") or {})
+
+    # ----------------------------------------------------------------- stall
+
+    def set_stall_config(self, config: Dict[str, Any]) -> None:
+        self.connection.call({"cmd": "SetStallConfig", "queue": self.name, "config": config})
+
+    def get_stall_config(self) -> Dict[str, Any]:
+        response = self.connection.call({"cmd": "GetStallConfig", "queue": self.name})
+        return dict(response.get("config") or response.get("data") or {})
+
+    # ------------------------------------------------- rate limit/concurrency
+
+    def set_global_rate_limit(self, max_jobs: int, duration_ms: Optional[int] = None) -> None:
+        """`duration_ms` accepted for TS-signature parity; the wire carries only `limit`."""
+        del duration_ms
+        self.connection.call({"cmd": "RateLimit", "queue": self.name, "limit": max_jobs})
+
+    def remove_global_rate_limit(self) -> None:
+        self.connection.call({"cmd": "RateLimitClear", "queue": self.name})
+
+    def set_global_concurrency(self, concurrency: int) -> None:
+        self.connection.call({"cmd": "SetConcurrency", "queue": self.name, "limit": concurrency})
+
+    def remove_global_concurrency(self) -> None:
+        self.connection.call({"cmd": "ClearConcurrency", "queue": self.name})
+
+    # -------------------------------------------------------------- scheduler
+
+    def upsert_job_scheduler(
+        self,
+        scheduler_id: str,
+        repeat: Dict[str, Any],
+        template: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """BullMQ-style scheduler.
+
+        ``repeat``: {"pattern": cron, "every": ms, "tz": timezone,
+        "immediately": bool, "limit": n}. ``template``: {"name", "data", "opts"}.
+        """
+        template = template or {}
+        opts = template.get("opts") or {}
+        data: Dict[str, Any] = {"name": template.get("name", scheduler_id)}
+        tdata = template.get("data")
+        if isinstance(tdata, dict):
+            data.update(tdata)
+        elif tdata is not None:
+            data["payload"] = tdata
+        # Priority and deduplication of spawned jobs travel as TOP-LEVEL Cron
+        # fields (the handler reads cmd.priority/uniqueKey/dedup); inside
+        # jobOptions the server's CronJobOptions silently ignores them (#111).
+        dedup = opts.get("deduplication") or {}
+        dedup_fields = _compact(
+            {"ttl": dedup.get("ttl"), "extend": dedup.get("extend"), "replace": dedup.get("replace")}
+        )
+        command = _compact(
+            {
+                "cmd": "Cron",
+                "name": scheduler_id,
+                "queue": self.name,
+                "data": data,
+                "schedule": repeat.get("pattern"),
+                "repeatEvery": repeat.get("every"),
+                "priority": opts.get("priority"),
+                "timezone": repeat.get("tz"),
+                "immediately": repeat.get("immediately"),
+                "maxLimit": repeat.get("limit"),
+                "uniqueKey": opts.get("unique_key") or dedup.get("id"),
+                "dedup": dedup_fields if dedup_fields else None,
+                "skipIfNoWorker": repeat.get("skip_if_no_worker"),
+                "skipMissedOnRestart": repeat.get("skip_missed_on_restart"),
+                "preventOverlap": repeat.get("prevent_overlap"),
+                # Map Pythonic template opts (attempts, remove_on_complete, ...)
+                # to the wire CronJobOptions, else the server silently drops
+                # them and cron-spawned jobs fall back to JOB_DEFAULTS.
+                "jobOptions": build_cron_job_options(opts),
+            }
+        )
+        self.connection.call(command)
+
+    def remove_job_scheduler(self, scheduler_id: str) -> None:
+        self.connection.call({"cmd": "CronDelete", "name": scheduler_id})
+
+    def get_job_scheduler(self, scheduler_id: str) -> Optional[Dict[str, Any]]:
+        try:
+            response = self.connection.call({"cmd": "CronGet", "name": scheduler_id})
+        except CommandError as exc:
+            if "not found" in str(exc).lower():
+                return None
+            raise
+        cron = response.get("cron") or response.get("data")
+        return dict(cron) if cron else None
+
+    def get_job_schedulers(self) -> List[Dict[str, Any]]:
+        response = self.connection.call({"cmd": "CronList"})
+        crons = response.get("crons", [])
+        return [dict(c) for c in crons if c.get("queue") == self.name]
+
+    def get_job_schedulers_count(self) -> int:
+        return len(self.get_job_schedulers())
+
+    def add_cron(self, name: str, schedule: str, data: Any = None, **repeat: Any) -> None:
+        """Shorthand: cron-pattern scheduler (mirrors Bunqueue.cron)."""
+        self.upsert_job_scheduler(name, {"pattern": schedule, **repeat}, {"name": name, "data": data})
+
+    def every(self, name: str, interval_ms: int, data: Any = None, **repeat: Any) -> None:
+        """Shorthand: fixed-interval scheduler (mirrors Bunqueue.every)."""
+        self.upsert_job_scheduler(name, {"every": interval_ms, **repeat}, {"name": name, "data": data})
+
+    # --------------------------------------------------------------- webhooks
+
+    def add_webhook(
+        self,
+        url: str,
+        events: List[str],
+        queue: Optional[str] = None,
+        secret: Optional[str] = None,
+    ) -> Optional[str]:
+        response = self.connection.call(
+            _compact({"cmd": "AddWebhook", "url": url, "events": events, "queue": queue, "secret": secret})
+        )
+        data = response.get("data") if isinstance(response.get("data"), dict) else response
+        webhook_id = data.get("webhookId") or data.get("id")
+        return str(webhook_id) if webhook_id else None
+
+    def remove_webhook(self, webhook_id: str) -> None:
+        self.connection.call({"cmd": "RemoveWebhook", "webhookId": webhook_id})
+
+    def list_webhooks(self) -> List[Dict[str, Any]]:
+        response = self.connection.call({"cmd": "ListWebhooks"})
+        data = response.get("data")
+        if isinstance(data, dict):
+            return list(data.get("webhooks") or [])
+        return list(response.get("webhooks") or [])
+
+    def set_webhook_enabled(self, webhook_id: str, enabled: bool) -> None:
+        # wire field is `id` (SetWebhookEnabledCommand), unlike RemoveWebhook's `webhookId`
+        self.connection.call({"cmd": "SetWebhookEnabled", "id": webhook_id, "enabled": enabled})
+
+    # ------------------------------------------------------------- monitoring
+
+    def get_workers(self) -> List[Dict[str, Any]]:
+        response = self.connection.call({"cmd": "ListWorkers"})
+        data = response.get("data")
+        if isinstance(data, dict):
+            return list(data.get("workers") or [])
+        return list(response.get("workers") or [])
+
+    def get_workers_count(self) -> int:
+        return len(self.get_workers())
+
+    def get_stats(self) -> Dict[str, Any]:
+        response = self.connection.call({"cmd": "Stats"})
+        return dict(response.get("stats", {}))
+
+    def get_metrics(self) -> Dict[str, Any]:
+        response = self.connection.call({"cmd": "Metrics"})
+        return dict(response.get("metrics", {}))
+
+    def list_queues(self) -> List[Any]:
+        """Returns the server's queue list (names or info dicts)."""
+        response = self.connection.call({"cmd": "ListQueues"})
+        return list(response.get("queues") or response.get("data") or [])

bunqueue/queue_query.py

@@ -0,0 +1,204 @@
+"""Query operations mixin for Queue (jobs, states, counts, logs, children)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from .connection import _compact
+from .errors import CommandError, CommandTimeoutError
+from .job import Job
+
+
+def _values_payload(response: Dict[str, Any]) -> Dict[str, Any]:
+    """Unwrap {data: {values: {...}}} (server) or top-level values."""
+    data = response.get("data")
+    if isinstance(data, dict) and "values" in data:
+        return dict(data.get("values") or {})
+    return dict(response.get("values") or {})
+
+
+class QueueQueryOps:
+    """Mixin: requires ``self.name`` and ``self.connection``."""
+
+    # ------------------------------------------------------------------ jobs
+
+    def get_job(self, job_id: str) -> Optional[Job]:
+        try:
+            response = self.connection.call({"cmd": "GetJob", "id": job_id})
+        except CommandError as exc:
+            if "not found" in str(exc).lower():
+                return None
+            raise
+        raw = response.get("job")
+        return Job(raw, self.connection) if raw else None
+
+    def get_job_by_custom_id(self, custom_id: str) -> Optional[Job]:
+        try:
+            response = self.connection.call({"cmd": "GetJobByCustomId", "customId": custom_id})
+        except CommandError as exc:
+            if "not found" in str(exc).lower():
+                return None
+            raise
+        raw = response.get("job")
+        return Job(raw, self.connection) if raw else None
+
+    def get_jobs(
+        self,
+        state: Optional[Union[str, Sequence[str]]] = None,
+        start: int = 0,
+        end: int = 1000,
+    ) -> List[Job]:
+        """Mirror TS getJobsAsync: offset=start, limit=end-start."""
+        command = _compact(
+            {
+                "cmd": "GetJobs",
+                "queue": self.name,
+                "state": list(state) if isinstance(state, (list, tuple)) else state,
+                "offset": start,
+                "limit": max(end - start, 0),
+            }
+        )
+        response = self.connection.call(command)
+        return [Job(raw, self.connection) for raw in response.get("jobs", [])]
+
+    def get_waiting(self, start: int = 0, end: int = 1000) -> List[Job]:
+        return self.get_jobs("waiting", start, end)
+
+    def get_delayed(self, start: int = 0, end: int = 1000) -> List[Job]:
+        return self.get_jobs("delayed", start, end)
+
+    def get_active(self, start: int = 0, end: int = 1000) -> List[Job]:
+        return self.get_jobs("active", start, end)
+
+    def get_completed(self, start: int = 0, end: int = 1000) -> List[Job]:
+        return self.get_jobs("completed", start, end)
+
+    def get_failed(self, start: int = 0, end: int = 1000) -> List[Job]:
+        return self.get_jobs("failed", start, end)
+
+    def get_prioritized(self, start: int = 0, end: int = 1000) -> List[Job]:
+        return self.get_jobs("prioritized", start, end)
+
+    def get_waiting_children(self, start: int = 0, end: int = 1000) -> List[Job]:
+        return self.get_jobs("waiting-children", start, end)
+
+    # ----------------------------------------------------------------- state
+
+    def get_state(self, job_id: str) -> str:
+        response = self.connection.call({"cmd": "GetState", "id": job_id})
+        return str(response.get("state"))
+
+    def get_result(self, job_id: str) -> Any:
+        response = self.connection.call({"cmd": "GetResult", "id": job_id})
+        return response.get("result")
+
+    def get_progress(self, job_id: str) -> Dict[str, Any]:
+        response = self.connection.call({"cmd": "GetProgress", "id": job_id})
+        return {"progress": response.get("progress"), "message": response.get("message")}
+
+    def wait_for_job(self, job_id: str, timeout_ms: int = 30000) -> Any:
+        """Block until the job completes; returns its result.
+
+        The server's ``WaitJob`` waiter resolves only on completion, answering
+        ``{ok:true, completed:false}`` (no result) otherwise — so returning
+        ``None`` would be indistinguishable from a genuine ``None`` result. On
+        non-completion we probe the job state: a ``failed`` job raises
+        :class:`CommandError` (it will not complete), everything else raises
+        :class:`CommandTimeoutError`."""
+        # The server validates 0 <= timeout <= 600000: clamp instead of erroring.
+        timeout_ms = max(0, min(timeout_ms, 600_000))
+        response = self.connection.call(
+            {"cmd": "WaitJob", "id": job_id, "timeout": timeout_ms},
+            timeout=timeout_ms / 1000 + 5,
+        )
+        if not response.get("completed"):
+            try:
+                state = self.get_state(job_id)
+            except CommandError:
+                state = None
+            if state == "failed":
+                raise CommandError(f"job {job_id} failed before completion")
+            raise CommandTimeoutError(f"waitUntilFinished timed out after {timeout_ms}ms")
+        return response.get("result")
+
+    def wait_job_until_finished(
+        self, job_id: str, queue_events: Any = None, ttl_ms: Optional[int] = None
+    ) -> Any:
+        """BullMQ-parity alias for :meth:`wait_for_job` (`queue_events` unused over TCP)."""
+        del queue_events
+        return self.wait_for_job(job_id, ttl_ms if ttl_ms is not None else 30000)
+
+    # -------------------------------------------------------------- children
+
+    def get_children_values(self, job_id: str) -> Dict[str, Any]:
+        response = self.connection.call({"cmd": "GetChildrenValues", "id": job_id})
+        return _values_payload(response)
+
+    def get_failed_children_values(self, job_id: str) -> Dict[str, Any]:
+        response = self.connection.call({"cmd": "GetFailedChildrenValues", "id": job_id})
+        return _values_payload(response)
+
+    def get_ignored_children_failures(self, job_id: str) -> Dict[str, Any]:
+        response = self.connection.call({"cmd": "GetIgnoredChildrenFailures", "id": job_id})
+        return _values_payload(response)
+
+    def remove_child_dependency(self, job_id: str) -> None:
+        self.connection.call({"cmd": "RemoveChildDependency", "id": job_id})
+
+    def remove_unprocessed_children(self, job_id: str) -> None:
+        self.connection.call({"cmd": "RemoveUnprocessedChildren", "id": job_id})
+
+    def get_deduplication_job_id(self, deduplication_id: str) -> Optional[str]:
+        """Id of the job currently holding this deduplication key (customId)."""
+        job = self.get_job_by_custom_id(deduplication_id)
+        return job.id if job else None
+
+    # ---------------------------------------------------------------- counts
+
+    def get_job_counts(self) -> Dict[str, int]:
+        response = self.connection.call({"cmd": "GetJobCounts", "queue": self.name})
+        return dict(response.get("counts", {}))
+
+    def get_waiting_count(self) -> int:
+        return self.get_job_counts().get("waiting", 0)
+
+    def get_active_count(self) -> int:
+        return self.get_job_counts().get("active", 0)
+
+    def get_completed_count(self) -> int:
+        return self.get_job_counts().get("completed", 0)
+
+    def get_failed_count(self) -> int:
+        return self.get_job_counts().get("failed", 0)
+
+    def get_delayed_count(self) -> int:
+        return self.get_job_counts().get("delayed", 0)
+
+    def get_prioritized_count(self) -> int:
+        return self.get_job_counts().get("prioritized", 0)
+
+    def get_waiting_children_count(self) -> int:
+        return self.get_job_counts().get("waiting-children", 0)
+
+    def count(self) -> int:
+        response = self.connection.call({"cmd": "Count", "queue": self.name})
+        return int(response.get("count", 0))
+
+    def get_counts_per_priority(self) -> Dict[str, int]:
+        response = self.connection.call({"cmd": "GetCountsPerPriority", "queue": self.name})
+        return dict(response.get("counts") or response.get("data") or {})
+
+    # ------------------------------------------------------------------ logs
+
+    def add_job_log(self, job_id: str, message: str, level: Optional[str] = None) -> None:
+        self.connection.call(_compact({"cmd": "AddLog", "id": job_id, "message": message, "level": level}))
+
+    def get_job_logs(self, job_id: str, start: Optional[int] = None, end: Optional[int] = None) -> List[Any]:
+        response = self.connection.call(_compact({"cmd": "GetLogs", "id": job_id, "start": start, "end": end}))
+        data = response.get("data")
+        if isinstance(data, dict):
+            return list(data.get("logs") or [])
+        return list(response.get("logs") or [])
+
+    def clear_job_logs(self, job_id: str, keep_logs: Optional[int] = None) -> None:
+        self.connection.call(_compact({"cmd": "ClearLogs", "id": job_id, "keepLogs": keep_logs}))

bunqueue/simple/__init__.py

@@ -0,0 +1,16 @@
+"""Simple Mode: Queue + Worker in a single object (1:1 with the official
+`Bunqueue` class in src/client/bunqueue.ts, TCP mode only)."""
+
+from .app import Bunqueue
+from .cancellation import CancelSignal, CancellationManager
+from .circuit_breaker import WorkerCircuitBreaker
+from .retry import calculate_backoff, execute_with_retry
+
+__all__ = [
+    "Bunqueue",
+    "CancelSignal",
+    "CancellationManager",
+    "WorkerCircuitBreaker",
+    "calculate_backoff",
+    "execute_with_retry",
+]