omniq 1.0.0__py3-none-any.whl

omniq/__init__.py

@@ -0,0 +1,3 @@
+from .client import OmniqClient
+from .consumer import consume
+from .types import JobCtx, PayloadT

omniq/_ops.py

@@ -0,0 +1,231 @@
+import json
+from dataclasses import dataclass
+from typing import Optional, Any
+
+from .clock import now_ms
+from .ids import new_ulid
+from .types import PayloadT, ReservePaused, ReserveJob, ReserveResult, AckFailResult
+from .transport import RedisLike
+from .scripts import OmniqScripts
+
+@dataclass
+class OmniqOps:
+    r: RedisLike
+    scripts: OmniqScripts
+
+    @staticmethod
+    def queue_base(queue_name: str) -> str:
+        if "{" in queue_name and "}" in queue_name:
+            return queue_name
+        return "{" + queue_name + "}"
+
+    def publish(
+        self,
+        *,
+        queue: str,
+        payload: Any,
+        job_id: Optional[str] = None,
+        max_attempts: int = 3,
+        timeout_ms: int = 30_000,
+        backoff_ms: int = 5_000,
+        due_ms: int = 0,
+        now_ms_override: int = 0,
+        gid: Optional[str] = None,
+        group_limit: int = 0,
+    ) -> str:
+        if not isinstance(payload, (dict, list)):
+            raise TypeError(
+                "publish(payload=...) must be a dict or list (structured JSON). "
+                "Wrap strings as {'text': '...'} or {'value': '...'}."
+            )
+
+        base = self.queue_base(queue)
+        nms = now_ms_override or now_ms()
+
+        jid = job_id or new_ulid()
+
+        payload_s = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
+
+        gid_s = (gid or "").strip()
+        glimit_s = str(int(group_limit)) if group_limit and group_limit > 0 else "0"
+
+        argv = [
+            base,
+            jid,
+            payload_s,
+            str(int(max_attempts)),
+            str(int(timeout_ms)),
+            str(int(backoff_ms)),
+            str(int(nms)),
+            str(int(due_ms)),
+            gid_s,
+            glimit_s,
+        ]
+
+        res = self.r.evalsha(self.scripts.enqueue_sha, 0, *argv)
+
+        if not isinstance(res, list) or len(res) < 2:
+            raise RuntimeError(f"Unexpected ENQUEUE response: {res}")
+
+        status = str(res[0])
+        out_id = str(res[1])
+
+        if status != "OK":
+            raise RuntimeError(f"ENQUEUE failed: {status}")
+
+        return out_id
+
+    def pause(self, *, queue: str) -> str:
+        base = self.queue_base(queue)
+        res = self.r.evalsha(self.scripts.pause_sha, 0, base)
+        return str(res)
+
+    def resume(self, *, queue: str) -> int:
+        base = self.queue_base(queue)
+        res = self.r.evalsha(self.scripts.resume_sha, 0, base)
+        try:
+            return int(res)
+        except Exception:
+            return 0
+
+    def is_paused(self, *, queue: str) -> bool:
+        base = self.queue_base(queue)
+        return self.r.exists(base + ":paused") == 1
+
+    def reserve(self, *, queue: str, now_ms_override: int = 0) -> ReserveResult:
+        base = self.queue_base(queue)
+        nms = now_ms_override or now_ms()
+
+        res = self.r.evalsha(self.scripts.reserve_sha, 0, base, str(int(nms)))
+
+        if not isinstance(res, list) or len(res) < 1:
+            raise RuntimeError(f"Unexpected RESERVE response: {res}")
+
+        if res[0] == "EMPTY":
+            return None
+
+        if res[0] == "PAUSED":
+            return ReservePaused()
+
+        if res[0] != "JOB" or len(res) < 7:
+            raise RuntimeError(f"Unexpected RESERVE response: {res}")
+
+        return ReserveJob(
+            status="JOB",
+            job_id=str(res[1]),
+            payload=str(res[2]),
+            lock_until_ms=int(res[3]),
+            attempt=int(res[4]),
+            gid=str(res[5] or ""),
+            lease_token=str(res[6] or ""),
+        )
+
+    def heartbeat(self, *, queue: str, job_id: str, lease_token: str, now_ms_override: int = 0) -> int:
+        base = self.queue_base(queue)
+        nms = now_ms_override or now_ms()
+
+        res = self.r.evalsha(self.scripts.heartbeat_sha, 0, base, job_id, str(int(nms)), lease_token)
+
+        if not isinstance(res, list) or len(res) < 1:
+            raise RuntimeError(f"Unexpected HEARTBEAT response: {res}")
+
+        if res[0] == "OK":
+            return int(res[1])
+
+        if res[0] == "ERR":
+            reason = str(res[1]) if len(res) > 1 else "UNKNOWN"
+            raise RuntimeError(f"HEARTBEAT failed: {reason}")
+
+        raise RuntimeError(f"Unexpected HEARTBEAT response: {res}")
+
+    def ack_success(self, *, queue: str, job_id: str, lease_token: str, now_ms_override: int = 0) -> None:
+        base = self.queue_base(queue)
+        nms = now_ms_override or now_ms()
+
+        res = self.r.evalsha(self.scripts.ack_success_sha, 0, base, job_id, str(int(nms)), lease_token)
+
+        if not isinstance(res, list) or len(res) < 1:
+            raise RuntimeError(f"Unexpected ACK_SUCCESS response: {res}")
+
+        if res[0] == "OK":
+            return
+
+        if res[0] == "ERR":
+            reason = str(res[1]) if len(res) > 1 else "UNKNOWN"
+            raise RuntimeError(f"ACK_SUCCESS failed: {reason}")
+
+        raise RuntimeError(f"Unexpected ACK_SUCCESS response: {res}")
+
+    def ack_fail(
+        self,
+        *,
+        queue: str,
+        job_id: str,
+        lease_token: str,
+        error: Optional[str] = None,
+        now_ms_override: int = 0,
+    ) -> AckFailResult:
+        base = self.queue_base(queue)
+        nms = now_ms_override or now_ms()
+
+        if error is None or str(error).strip() == "":
+            res = self.r.evalsha(self.scripts.ack_fail_sha, 0, base, job_id, str(int(nms)), lease_token)
+        else:
+            err_s = str(error)
+            res = self.r.evalsha(self.scripts.ack_fail_sha, 0, base, job_id, str(int(nms)), lease_token, err_s)
+
+        if not isinstance(res, list) or len(res) < 1:
+            raise RuntimeError(f"Unexpected ACK_FAIL response: {res}")
+
+        if res[0] == "RETRY":
+            return ("RETRY", int(res[1]))
+
+        if res[0] == "FAILED":
+            return ("FAILED", None)
+
+        if res[0] == "ERR":
+            reason = str(res[1]) if len(res) > 1 else "UNKNOWN"
+            raise RuntimeError(f"ACK_FAIL failed: {reason}")
+
+        raise RuntimeError(f"Unexpected ACK_FAIL response: {res}")
+
+    def promote_delayed(self, *, queue: str, max_promote: int = 1000, now_ms_override: int = 0) -> int:
+        base = self.queue_base(queue)
+        nms = now_ms_override or now_ms()
+
+        res = self.r.evalsha(self.scripts.promote_delayed_sha, 0, base, str(int(nms)), str(int(max_promote)))
+
+        if not isinstance(res, list) or len(res) < 2 or res[0] != "OK":
+            raise RuntimeError(f"Unexpected PROMOTE_DELAYED response: {res}")
+
+        return int(res[1])
+
+    def reap_expired(self, *, queue: str, max_reap: int = 1000, now_ms_override: int = 0) -> int:
+        base = self.queue_base(queue)
+        nms = now_ms_override or now_ms()
+
+        res = self.r.evalsha(self.scripts.reap_expired_sha, 0, base, str(int(nms)), str(int(max_reap)))
+
+        if not isinstance(res, list) or len(res) < 2 or res[0] != "OK":
+            raise RuntimeError(f"Unexpected REAP_EXPIRED response: {res}")
+
+        return int(res[1])
+
+    def job_timeout_ms(self, *, queue: str, job_id: str, default_ms: int = 60_000) -> int:
+        base = self.queue_base(queue)
+        k_job = base + ":job:" + job_id
+        v = self.r.hget(k_job, "timeout_ms")
+        try:
+            n = int(v) if v is not None and v != "" else 0
+        except Exception:
+            n = 0
+        return n if n > 0 else int(default_ms)
+
+    @staticmethod
+    def paused_backoff_s(poll_interval_s: float) -> float:
+        return max(0.25, float(poll_interval_s) * 10.0)
+
+    @staticmethod
+    def derive_heartbeat_interval_s(timeout_ms: int) -> float:
+        half = max(1.0, (float(timeout_ms) / 1000.0) / 2.0)
+        return max(1.0, min(10.0, half))

omniq/client.py

@@ -0,0 +1,136 @@
+from dataclasses import dataclass
+from typing import Callable, Optional, Any
+
+from ._ops import OmniqOps
+from .consumer import consume as consume_loop
+from .scripts import load_scripts, default_scripts_dir
+from .transport import RedisConnOpts, build_redis_client, RedisLike
+from .types import PayloadT, ReserveResult, AckFailResult
+
+@dataclass
+class OmniqClient:
+    _ops: OmniqOps
+
+    def __init__(
+        self,
+        *,
+        redis: Optional[RedisLike] = None,
+        redis_url: Optional[str] = None,
+        host: Optional[str] = None,
+        port: int = 6379,
+        db: int = 0,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        ssl: bool = False,
+        scripts_dir: Optional[str] = None,
+    ):
+        if redis is not None:
+            r = redis
+        else:
+            r = build_redis_client(
+                RedisConnOpts(
+                    redis_url=redis_url,
+                    host=host,
+                    port=port,
+                    db=db,
+                    username=username,
+                    password=password,
+                    ssl=ssl,
+                )
+            )
+
+        if scripts_dir is None:
+            scripts_dir = default_scripts_dir(__file__)
+        scripts = load_scripts(r, scripts_dir)
+
+        self._ops = OmniqOps(r=r, scripts=scripts)
+
+    @staticmethod
+    def queue_base(queue_name: str) -> str:
+        return OmniqOps.queue_base(queue_name)
+
+    def publish(
+        self,
+        *,
+        queue: str,
+        payload: Any,
+        job_id: Optional[str] = None,
+        max_attempts: int = 3,
+        timeout_ms: int = 60_000,
+        backoff_ms: int = 5_000,
+        due_ms: int = 0,
+        gid: Optional[str] = None,
+        group_limit: int = 0,
+    ) -> str:
+        return self._ops.publish(
+            queue=queue,
+            payload=payload,
+            job_id=job_id,
+            max_attempts=max_attempts,
+            timeout_ms=timeout_ms,
+            backoff_ms=backoff_ms,
+            due_ms=due_ms,
+            gid=gid,
+            group_limit=group_limit,
+        )
+
+    def reserve(self, *, queue: str, now_ms_override: int = 0) -> ReserveResult:
+        return self._ops.reserve(queue=queue, now_ms_override=now_ms_override)
+
+    def heartbeat(self, *, queue: str, job_id: str, lease_token: str, now_ms_override: int = 0) -> int:
+        return self._ops.heartbeat(queue=queue, job_id=job_id, lease_token=lease_token, now_ms_override=now_ms_override)
+
+    def ack_success(self, *, queue: str, job_id: str, lease_token: str, now_ms_override: int = 0) -> None:
+        return self._ops.ack_success(queue=queue, job_id=job_id, lease_token=lease_token, now_ms_override=now_ms_override)
+
+    def ack_fail(self, *, queue: str, job_id: str, lease_token: str, now_ms_override: int = 0) -> AckFailResult:
+        return self._ops.ack_fail(queue=queue, job_id=job_id, lease_token=lease_token, now_ms_override=now_ms_override)
+
+    def promote_delayed(self, *, queue: str, max_promote: int = 1000, now_ms_override: int = 0) -> int:
+        return self._ops.promote_delayed(queue=queue, max_promote=max_promote, now_ms_override=now_ms_override)
+
+    def reap_expired(self, *, queue: str, max_reap: int = 1000, now_ms_override: int = 0) -> int:
+        return self._ops.reap_expired(queue=queue, max_reap=max_reap, now_ms_override=now_ms_override)
+
+    def pause(self, *, queue: str) -> str:
+        return self._ops.pause(queue=queue)
+
+    def resume(self, *, queue: str) -> int:
+        return self._ops.resume(queue=queue)
+
+    def is_paused(self, *, queue: str) -> bool:
+        return self._ops.is_paused(queue=queue)
+
+    def consume(
+        self,
+        *,
+        queue: str,
+        handler: Callable[[Any], None],
+        poll_interval_s: float = 0.05,
+        promote_interval_s: float = 1.0,
+        promote_batch: int = 1000,
+        reap_interval_s: float = 1.0,
+        reap_batch: int = 1000,
+        heartbeat_interval_s: Optional[float] = None,
+        verbose: bool = False,
+        logger: Callable[[str], None] = print,
+        drain: bool = True,
+    ) -> None:
+        return consume_loop(
+            self._ops,
+            queue=queue,
+            handler=handler,
+            poll_interval_s=poll_interval_s,
+            promote_interval_s=promote_interval_s,
+            promote_batch=promote_batch,
+            reap_interval_s=reap_interval_s,
+            reap_batch=reap_batch,
+            heartbeat_interval_s=heartbeat_interval_s,
+            verbose=verbose,
+            logger=logger,
+            drain=drain,
+        )
+
+    @property
+    def ops(self) -> OmniqOps:
+        return self._ops

omniq/clock.py

@@ -0,0 +1,4 @@
+import time
+
+def now_ms() -> int:
+    return int(time.time() * 1000)

omniq/consumer.py

@@ -0,0 +1,318 @@
+import json
+import threading
+import time
+import signal
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional
+
+from ._ops import OmniqOps
+from .types import JobCtx, ReserveJob
+
+@dataclass
+class StopController:
+    stop: bool = False
+
+@dataclass
+class HeartbeatHandle:
+    stop_evt: threading.Event
+    flags: Dict[str, bool]
+    thread: threading.Thread
+
+def _install_sigterm_handler(ctrl: StopController, logger, verbose: bool) -> None:
+    def on_sigterm(signum, _frame):
+        ctrl.stop = True
+        if verbose:
+            _safe_log(logger, f"[consume] SIGTERM received (stopping...)")
+
+    signal.signal(signal.SIGTERM, on_sigterm)
+
+def start_heartbeater(
+    ops: OmniqOps,
+    *,
+    queue: str,
+    job_id: str,
+    lease_token: str,
+    interval_s: float,
+) -> HeartbeatHandle:
+    stop_evt = threading.Event()
+    flags: Dict[str, bool] = {"lost": False}
+
+    def hb_loop():
+        try:
+            ops.heartbeat(queue=queue, job_id=job_id, lease_token=lease_token)
+        except Exception as e:
+            msg = str(e)
+            if "NOT_ACTIVE" in msg or "TOKEN_MISMATCH" in msg:
+                flags["lost"] = True
+                stop_evt.set()
+                return
+
+        while not stop_evt.wait(interval_s):
+            try:
+                ops.heartbeat(queue=queue, job_id=job_id, lease_token=lease_token)
+            except Exception as e:
+                msg = str(e)
+                if "NOT_ACTIVE" in msg or "TOKEN_MISMATCH" in msg:
+                    flags["lost"] = True
+                    stop_evt.set()
+                    return
+
+    t = threading.Thread(target=hb_loop, daemon=True)
+    t.start()
+    return HeartbeatHandle(stop_evt=stop_evt, flags=flags, thread=t)
+
+
+def _safe_log(logger: Callable[[str], None], msg: str) -> None:
+    try:
+        logger(msg)
+    except Exception:
+        pass
+
+
+def _payload_preview(payload: Any, max_len: int = 300) -> str:
+    try:
+        s = payload if isinstance(payload, str) else json.dumps(payload, ensure_ascii=False)
+    except Exception:
+        s = str(payload)
+    if len(s) > max_len:
+        return s[:max_len] + "…"
+    return s
+
+def consume(
+    ops: OmniqOps,
+    *,
+    queue: str,
+    handler: Callable[[JobCtx], None],
+    poll_interval_s: float = 0.05,
+    promote_interval_s: float = 1.0,
+    promote_batch: int = 1000,
+    reap_interval_s: float = 1.0,
+    reap_batch: int = 1000,
+    heartbeat_interval_s: Optional[float] = None,
+    verbose: bool = False,
+    logger: Callable[[str], None] = print,
+    stop_on_ctrl_c: bool = True,
+    drain: bool = True,
+) -> None:
+    """
+    Shutdown semantics:
+
+    - drain=True:
+        Ctrl+C (SIGINT) requests stop AFTER current job finishes.
+        We override SIGINT so it does NOT raise KeyboardInterrupt (graceful).
+        Second Ctrl+C => hard exit.
+
+    - drain=False:
+        Ctrl+C raises KeyboardInterrupt normally (fast stop).
+        We do NOT override SIGINT.
+        SIGTERM always requests stop; if drain=False we exit ASAP after reserve.
+
+    Notes:
+    - We cannot force-stop user code safely. drain=False relies on KeyboardInterrupt to interrupt sleep/py code.
+    """
+
+    last_promote = 0.0
+    last_reap = 0.0
+
+    # ensure StopController has sigint_count
+    if not hasattr(StopController, "__annotations__") or "sigint_count" not in getattr(StopController, "__annotations__", {}):
+        # fallback: still works without sigint_count, but no "double Ctrl+C" behavior
+        ctrl = StopController(stop=False)  # type: ignore
+        ctrl.sigint_count = 0  # type: ignore
+    else:
+        ctrl = StopController(stop=False, sigint_count=0)  # type: ignore
+
+    if stop_on_ctrl_c:
+        import signal
+
+        # Always handle SIGTERM (docker/k8s stop)
+        def on_sigterm(signum, _frame):
+            ctrl.stop = True
+            if verbose:
+                _safe_log(logger, f"[consume] SIGTERM received; stopping... queue={queue}")
+
+        signal.signal(signal.SIGTERM, on_sigterm)
+
+        if drain:
+            # drain=True: override SIGINT so handler is NOT interrupted.
+            # first Ctrl+C => request stop-after-job
+            # second Ctrl+C => hard exit (KeyboardInterrupt)
+            prev = signal.getsignal(signal.SIGINT)
+
+            def on_sigint(signum, frame):
+                ctrl.sigint_count += 1
+                if ctrl.sigint_count >= 2:
+                    if verbose:
+                        _safe_log(logger, f"[consume] SIGINT x2; hard exit now. queue={queue}")
+                    # restore default and re-raise via default behavior
+                    try:
+                        signal.signal(signal.SIGINT, prev if prev else signal.SIG_DFL)
+                    except Exception:
+                        signal.signal(signal.SIGINT, signal.SIG_DFL)
+                    raise KeyboardInterrupt
+
+                ctrl.stop = True
+                if verbose:
+                    _safe_log(logger, f"[consume] Ctrl+C received; draining current job then exiting. queue={queue}")
+
+            signal.signal(signal.SIGINT, on_sigint)
+        else:
+            # drain=False: do NOT override SIGINT
+            pass
+
+    try:
+        while True:
+            # if stop requested and idle, exit
+            if ctrl.stop:
+                if verbose:
+                    _safe_log(logger, f"[consume] stop requested; exiting (idle). queue={queue}")
+                return
+
+            now_s = time.time()
+
+            if now_s - last_promote >= promote_interval_s:
+                try:
+                    ops.promote_delayed(queue=queue, max_promote=promote_batch)
+                except Exception:
+                    pass
+                last_promote = now_s
+
+            if now_s - last_reap >= reap_interval_s:
+                try:
+                    ops.reap_expired(queue=queue, max_reap=reap_batch)
+                except Exception:
+                    pass
+                last_reap = now_s
+
+            try:
+                res = ops.reserve(queue=queue)
+            except Exception as e:
+                if verbose:
+                    _safe_log(logger, f"[consume] reserve error: {e}")
+                time.sleep(0.2)
+                continue
+
+            if res is None:
+                time.sleep(poll_interval_s)
+                continue
+
+            if getattr(res, "status", "") == "PAUSED":
+                time.sleep(ops.paused_backoff_s(poll_interval_s))
+                continue
+
+            assert isinstance(res, ReserveJob)
+            if not res.lease_token:
+                if verbose:
+                    _safe_log(logger, f"[consume] invalid reserve (missing lease_token) job_id={res.job_id}")
+                time.sleep(0.2)
+                continue
+
+            # if stop requested right after reserve:
+            # - drain=False => exit ASAP (no handler, no ack, stop heartbeats)
+            # - drain=True  => process this one job, then exit after ack
+            if ctrl.stop and not drain:
+                if verbose:
+                    _safe_log(logger, f"[consume] stop requested; fast-exit after reserve job_id={res.job_id}")
+                return
+
+            # payload is JSON (contract). keep defensive fallback.
+            try:
+                payload_obj: Any = json.loads(res.payload)
+            except Exception:
+                payload_obj = res.payload
+
+            ctx = JobCtx(
+                queue=queue,
+                job_id=res.job_id,
+                payload_raw=res.payload,
+                payload=payload_obj,
+                attempt=res.attempt,
+                lock_until_ms=res.lock_until_ms,
+                lease_token=res.lease_token,
+                gid=res.gid,
+            )
+
+            if verbose:
+                pv = _payload_preview(ctx.payload)
+                gid_s = ctx.gid or "-"
+                _safe_log(logger, f"[consume] received job_id={ctx.job_id} attempt={ctx.attempt} gid={gid_s} payload={pv}")
+
+            # heartbeat cadence
+            if heartbeat_interval_s is not None:
+                hb_s = float(heartbeat_interval_s)
+            else:
+                timeout_ms = ops.job_timeout_ms(queue=queue, job_id=res.job_id)
+                hb_s = ops.derive_heartbeat_interval_s(timeout_ms)
+
+            hb = start_heartbeater(
+                ops,
+                queue=queue,
+                job_id=res.job_id,
+                lease_token=res.lease_token,
+                interval_s=hb_s,
+            )
+
+            try:
+                handler(ctx)
+
+                hb.stop_evt.set()
+
+                if not hb.flags.get("lost", False):
+                    try:
+                        ops.ack_success(queue=queue, job_id=res.job_id, lease_token=res.lease_token)
+                        if verbose:
+                            _safe_log(logger, f"[consume] ack success job_id={ctx.job_id}")
+                    except Exception as e:
+                        if verbose:
+                            _safe_log(logger, f"[consume] ack success error job_id={ctx.job_id}: {e}")
+
+            except KeyboardInterrupt:
+                # This only happens in drain=False mode (SIGINT not overridden),
+                # or on double Ctrl+C in drain=True mode.
+                if verbose:
+                    _safe_log(logger, f"[consume] KeyboardInterrupt; exiting now. queue={queue}")
+                hb.stop_evt.set()
+                return
+
+            except Exception as e:
+                hb.stop_evt.set()
+
+                if not hb.flags.get("lost", False):
+                    try:
+                        err = f"{type(e).__name__}: {e}"
+                        result = ops.ack_fail(
+                            queue=queue,
+                            job_id=res.job_id,
+                            lease_token=res.lease_token,
+                            error=err,
+                        )
+                        if verbose:
+                            if result[0] == "RETRY":
+                                _safe_log(logger, f"[consume] ack fail job_id={ctx.job_id} => RETRY due_ms={result[1]}")
+                            else:
+                                _safe_log(logger, f"[consume] ack fail job_id={ctx.job_id} => FAILED")
+                            _safe_log(logger, f"[consume] error job_id={ctx.job_id} => {err}")
+                    except Exception as e2:
+                        if verbose:
+                            _safe_log(logger, f"[consume] ack fail error job_id={ctx.job_id}: {e2}")
+
+            finally:
+                try:
+                    hb.thread.join(timeout=0.1)
+                except Exception:
+                    pass
+
+            # drain=True: if stop requested (SIGTERM or Ctrl+C), exit after finishing this job
+            if ctrl.stop and drain:
+                if verbose:
+                    _safe_log(logger, f"[consume] stop requested; exiting after draining job_id={ctx.job_id}")
+                return
+
+    except KeyboardInterrupt:
+        # Ctrl+C while idle in drain=False mode, or double Ctrl+C in drain=True mode
+        if verbose:
+            _safe_log(logger, f"[consume] KeyboardInterrupt (outer); exiting now. queue={queue}")
+        return
+
+
+

omniq/ids.py

@@ -0,0 +1,4 @@
+import ulid
+
+def new_ulid() -> str:
+    return str(ulid.new())

omniq/monitor.py

@@ -0,0 +1,138 @@
+from dataclasses import dataclass
+from typing import List
+
+@dataclass(frozen=True)
+class QueueCounts:
+    paused: bool
+    waiting: int
+    active: int
+    delayed: int
+    completed: int
+    failed: int
+
+
+@dataclass(frozen=True)
+class GroupStatus:
+    gid: str
+    inflight: int
+    limit: int
+
+
+@dataclass(frozen=True)
+class ActiveSample:
+    job_id: str
+    gid: str
+    lock_until_ms: int
+    attempt: int
+
+
+@dataclass(frozen=True)
+class DelayedSample:
+    job_id: str
+    gid: str
+    due_ms: int
+    attempt: int
+
+
+class QueueMonitor:
+    def __init__(self, uq):
+        self._uq = uq
+        self._r = getattr(uq, "r", None) or getattr(getattr(uq, "ops", None), "r", None) or getattr(getattr(uq, "_ops", None), "r", None)
+        if self._r is None:
+            raise ValueError("QueueMonitor needs redis access (inject from server, do not expose to UI callers).")
+
+    def _base(self, queue: str) -> str:
+        return self._uq.queue_base(queue)
+
+    def counts(self, queue: str) -> QueueCounts:
+        base = self._base(queue)
+        r = self._r
+
+        paused = r.exists(f"{base}:paused") == 1
+
+        waiting = int(r.llen(f"{base}:wait") or 0)
+        active = int(r.zcard(f"{base}:active") or 0)
+        delayed = int(r.zcard(f"{base}:delayed") or 0)
+        completed = int(r.llen(f"{base}:completed") or 0)
+        failed = int(r.llen(f"{base}:failed") or 0)
+
+        return QueueCounts(
+            paused=paused,
+            waiting=waiting,
+            active=active,
+            delayed=delayed,
+            completed=completed,
+            failed=failed,
+        )
+
+    def groups_ready(self, queue: str, limit: int = 200) -> List[str]:
+        base = self._base(queue)
+        r = self._r
+        limit = max(1, min(int(limit), 2000))
+        try:
+            gids = r.zrange(f"{base}:groups:ready", 0, limit - 1)
+            return [g for g in gids if g]
+        except Exception:
+            return []
+
+    def group_status(self, queue: str, gids: List[str], default_limit: int = 1) -> List[GroupStatus]:
+        base = self._base(queue)
+        r = self._r
+
+        out: List[GroupStatus] = []
+        for gid in gids:
+            inflight = int(r.get(f"{base}:g:{gid}:inflight") or "0")
+
+            raw = r.get(f"{base}:g:{gid}:limit")
+            try:
+                gl = int(raw) if raw else 0
+            except Exception:
+                gl = 0
+            limit = gl if gl > 0 else int(default_limit)
+
+            out.append(GroupStatus(gid=str(gid), inflight=inflight, limit=limit))
+        return out
+
+    def sample_active(self, queue: str, limit: int = 50) -> List[ActiveSample]:
+        base = self._base(queue)
+        r = self._r
+        limit = max(1, min(int(limit), 500))
+
+        job_ids = r.zrange(f"{base}:active", 0, limit - 1)
+        out: List[ActiveSample] = []
+
+        for jid in job_ids:
+            k_job = f"{base}:job:{jid}"
+            gid, attempt = r.hmget(k_job, "gid", "attempt")
+            score = r.zscore(f"{base}:active", jid) or 0
+            out.append(
+                ActiveSample(
+                    job_id=str(jid),
+                    gid=str(gid or ""),
+                    lock_until_ms=int(score),
+                    attempt=int(attempt or 0),
+                )
+            )
+        return out
+
+    def sample_delayed(self, queue: str, limit: int = 50) -> List[DelayedSample]:
+        base = self._base(queue)
+        r = self._r
+        limit = max(1, min(int(limit), 500))
+
+        job_ids = r.zrange(f"{base}:delayed", 0, limit - 1)
+        out: List[DelayedSample] = []
+
+        for jid in job_ids:
+            k_job = f"{base}:job:{jid}"
+            gid, attempt = r.hmget(k_job, "gid", "attempt")
+            due = r.zscore(f"{base}:delayed", jid) or 0
+            out.append(
+                DelayedSample(
+                    job_id=str(jid),
+                    gid=str(gid or ""),
+                    due_ms=int(due),
+                    attempt=int(attempt or 0),
+                )
+            )
+        return out

omniq/scripts.py

@@ -0,0 +1,40 @@
+import os
+from dataclasses import dataclass
+from typing import Protocol
+
+class ScriptLoader(Protocol):
+    def script_load(self, script: str) -> str: ...
+
+@dataclass(frozen=True)
+class OmniqScripts:
+    enqueue_sha: str
+    reserve_sha: str
+    ack_success_sha: str
+    ack_fail_sha: str
+    promote_delayed_sha: str
+    reap_expired_sha: str
+    heartbeat_sha: str
+    pause_sha: str
+    resume_sha: str
+
+def default_scripts_dir(current_file: str) -> str:
+    here = os.path.dirname(os.path.abspath(current_file))
+    return os.path.abspath(os.path.join(here, "..", "..", "scripts", "scripts"))
+
+def load_scripts(r: ScriptLoader, scripts_dir: str) -> OmniqScripts:
+    def load_one(name: str) -> str:
+        path = os.path.join(scripts_dir, name)
+        with open(path, "r", encoding="utf-8") as f:
+            return r.script_load(f.read())
+
+    return OmniqScripts(
+        enqueue_sha=load_one("enqueue.lua"),
+        reserve_sha=load_one("reserve.lua"),
+        ack_success_sha=load_one("ack_success.lua"),
+        ack_fail_sha=load_one("ack_fail.lua"),
+        promote_delayed_sha=load_one("promote_delayed.lua"),
+        reap_expired_sha=load_one("reap_expired.lua"),
+        heartbeat_sha=load_one("heartbeat.lua"),
+        pause_sha=load_one("pause.lua"),
+        resume_sha=load_one("resume.lua"),
+    )

omniq/transport.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional, Protocol
+
+import redis
+
+class RedisLike(Protocol):
+    def evalsha(self, sha: str, numkeys: int, *args: str) -> Any: ...
+    def script_load(self, script: str) -> str: ...
+    def exists(self, key: str) -> int: ...
+    def hget(self, key: str, field: str) -> Optional[str]: ...
+
+
+@dataclass(frozen=True)
+class RedisConnOpts:
+    redis_url: Optional[str] = None
+    host: Optional[str] = None
+    port: int = 6379
+    db: int = 0
+    username: Optional[str] = None
+    password: Optional[str] = None
+    ssl: bool = False
+    socket_timeout: Optional[float] = None
+    socket_connect_timeout: Optional[float] = None
+
+
+def build_redis_client(opts: RedisConnOpts) -> redis.Redis:
+    if opts.redis_url:
+        return redis.Redis.from_url(opts.redis_url, decode_responses=True)
+
+    if not opts.host:
+        raise ValueError("RedisConnOpts requires host (or redis_url)")
+
+    return redis.Redis(
+        host=opts.host,
+        port=int(opts.port),
+        db=int(opts.db),
+        username=opts.username,
+        password=opts.password,
+        ssl=bool(opts.ssl),
+        socket_timeout=opts.socket_timeout,
+        socket_connect_timeout=opts.socket_connect_timeout,
+        decode_responses=True,
+    )

omniq/types.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple, Union, Literal
+
+PayloadT = Union[Dict[str, Any], list]
+
+@dataclass(frozen=True)
+class JobCtx:
+    queue: str
+    job_id: str
+    payload_raw: str
+    payload: PayloadT
+    attempt: int
+    lock_until_ms: int
+    lease_token: str
+    gid: str = ""
+
+ReserveEmpty = None
+
+@dataclass(frozen=True)
+class ReservePaused:
+    status: Literal["PAUSED"] = "PAUSED"
+
+@dataclass(frozen=True)
+class ReserveJob:
+    status: Literal["JOB"]
+    job_id: str
+    payload: str
+    lock_until_ms: int
+    attempt: int
+    gid: str
+    lease_token: str
+
+ReserveResult = Union[ReserveEmpty, ReservePaused, ReserveJob]
+
+AckFailResult = Tuple[Literal["RETRY", "FAILED"], Optional[int]]

omniq-1.0.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: omniq
+Version: 1.0.0
+Summary: OmniQ v1 - Redis+Lua queue Python SDK
+Requires-Python: >=3.9
+Requires-Dist: redis>=5.0.0
+Requires-Dist: ulid-py>=1.1.0

omniq-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+omniq/__init__.py,sha256=PoDH4HY02Q_8tshE6OgRkPSWnGpJDvAovNWlV-NeCw0,98
+omniq/_ops.py,sha256=oSy3o1-0PRj_B1V8Ga7n7y83NpUYoxF872SDxsLpNZY,7656
+omniq/client.py,sha256=qqG3nsfgTjGtap8hKsLJd_9vd0Iui_8aMJdJQhQCdmk,4643
+omniq/clock.py,sha256=YTpVrkx1hyop4GU9DuGXfu23n5KPsgGb_1DINiiV0FU,69
+omniq/consumer.py,sha256=z-yFYRIDX6HTD5hf4Xls7EYp5_zRw9Jc_B6RQO8o4Ws,11140
+omniq/ids.py,sha256=bGkDDZfYaZvFEnUD02TylWA05UpDYztQwndIscxFjm8,63
+omniq/monitor.py,sha256=N0qbGUJfqwUubHLvgMbemswhcQLamwsc4_5OYgqFyr0,4008
+omniq/scripts.py,sha256=E5fhtc5m6qhEwCvIz__nwSWrH0L3xGkJXRO29ajY6kI,1316
+omniq/transport.py,sha256=4Nj-RoyZG0L0aEbCleNCF1bWQHW7J4yVgPGmebWxGPE,1309
+omniq/types.py,sha256=KXj-Z-uPV7lO3fmmyK6QYL8pJiPoYYei8UcPf0v1YUU,743
+omniq-1.0.0.dist-info/METADATA,sha256=G-imH3HvAVfNKvBhNR9jwq4wFDZEWrZgfoH_8zD4q8M,177
+omniq-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+omniq-1.0.0.dist-info/top_level.txt,sha256=SMvOWui1e7OpLJn5BC_QsiZQIqsjhNfURCd7Ru9CuRE,6
+omniq-1.0.0.dist-info/RECORD,,

omniq-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

omniq-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+omniq