localqueue 1.0.0__cp312-cp312-win_amd64.whl

localqueue/__init__.py

@@ -0,0 +1,16 @@
+"""localqueue: fila persistente local em SQLite com ACK, lease e retry."""
+
+from localqueue.core import JsonSerializer, SimpleQueue
+from localqueue.exceptions import Empty, LeaseExpired, LocalQueueError
+from localqueue.job import Job
+from localqueue.worker import Worker
+
+__all__ = [
+    "Empty",
+    "Job",
+    "JsonSerializer",
+    "LeaseExpired",
+    "LocalQueueError",
+    "SimpleQueue",
+    "Worker",
+]

localqueue/core.py

@@ -0,0 +1,272 @@
+"""Facade Python para a fila persistente localqueue."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time as _time
+from pathlib import Path
+from typing import Any, Optional, Protocol
+
+from localqueue import localqueue as _native
+from localqueue.exceptions import Empty, LeaseExpired, LocalQueueError
+from localqueue.job import Job
+
+log = logging.getLogger(__name__)
+
+
+class Serializer(Protocol):
+    """Protocolo para serializadores compatíveis."""
+
+    def dumps(self, obj: Any) -> bytes: ...
+
+    def loads(self, data: bytes) -> Any: ...
+
+
+class JsonSerializer:
+    """Serializador JSON padrão."""
+
+    def dumps(self, obj: Any) -> bytes:
+        return json.dumps(obj).encode("utf-8")
+
+    def loads(self, data: bytes) -> Any:
+        return json.loads(data.decode("utf-8"))
+
+
+class SimpleQueue:
+    """Fila persistente baseada em SQLite com ACK/NACK, lease e retry.
+
+    O motor transacional é implementado em Rust (extensão nativa), garantindo
+    atomicidade mesmo com múltiplos processos/threads.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        name: str = "default",
+        *,
+        lease_seconds: float = 60.0,
+        max_retries: int = 3,
+        fsync: bool = False,
+        serializer: Optional[Serializer] = None,
+    ) -> None:
+        """Inicializa a fila.
+
+        :param path: diretório onde o banco SQLite será armazenado.
+        :param name: nome da fila.
+        :param lease_seconds: tempo de lease para cada job retirado.
+        :param max_retries: número máximo de tentativas antes de dead-letter.
+        :param fsync: quando ``True`` usa ``PRAGMA synchronous=FULL``.
+        :param serializer: serializador com métodos ``dumps`` e ``loads``.
+        """
+        if not lease_seconds > 0:
+            raise ValueError("'lease_seconds' deve ser positivo")
+        if max_retries < 0:
+            raise ValueError("'max_retries' deve ser não negativo")
+
+        self.path = Path(path)
+        self.name = name
+        self.lease_seconds = lease_seconds
+        self.max_retries = max_retries
+        self.serializer = serializer or JsonSerializer()
+
+        self.path.mkdir(parents=True, exist_ok=True)
+        db_path = self.path / "localqueue.db"
+
+        self._native: Optional[_native.NativeQueue] = _native.NativeQueue(
+            str(db_path),
+            name,
+            max_attempts=max_retries + 1,
+            fsync=fsync,
+        )
+
+    def _get_native(self) -> "_native.NativeQueue":
+        native = self._native
+        if native is None:
+            raise LocalQueueError("fila fechada")
+        return native
+
+    def put(self, data: Any, job_id: Optional[str] = None) -> int:
+        """Adiciona um item à fila.
+
+        :param data: payload a ser enfileirado.
+        :param job_id: identificador único opcional para deduplicação.
+        :return: id interno do item na fila.
+        """
+        payload = self.serializer.dumps(data)
+        return self._get_native().put(payload, job_id)
+
+    def get(
+        self, block: bool = True, timeout: Optional[float] = None
+    ) -> Job:
+        """Retira um item da fila com lease.
+
+        :param block: se ``True``, bloqueia até haver um item disponível.
+        :param timeout: tempo máximo de espera em segundos.
+        :return: instância de :class:`Job`.
+        :raises Empty: se ``block=False`` e a fila estiver vazia, ou se
+            ``block=True`` e ``timeout`` expirar.
+        """
+        lease_ms = int(self.lease_seconds * 1000)
+
+        if not block:
+            lease = self._get_native().get(lease_ms)
+            if lease is None:
+                raise Empty("fila vazia")
+            return self._to_job(lease)
+
+        if timeout is not None and timeout < 0:
+            raise ValueError("'timeout' deve ser não negativo")
+
+        start = _time.monotonic()
+        sleep = 0.01
+        max_sleep = 0.25
+        while True:
+            lease = self._get_native().get(lease_ms)
+            if lease is not None:
+                return self._to_job(lease)
+
+            if timeout is not None:
+                elapsed = _time.monotonic() - start
+                if elapsed >= timeout:
+                    raise Empty("fila vazia")
+
+            _time.sleep(sleep)
+            sleep = min(sleep * 1.5, max_sleep)
+
+    def get_nowait(self) -> Job:
+        """Variação não bloqueante de :meth:`get`."""
+        return self.get(block=False)
+
+    def ack(self, job: Job) -> None:
+        """Confirma o processamento bem-sucedido de um job."""
+        self._get_native().ack(job.id, job.receipt)
+
+    def nack(
+        self,
+        job: Job,
+        *,
+        delay: float = 0.0,
+        last_error: Optional[str] = None,
+    ) -> None:
+        """Devolve o job à fila (erro transitório).
+
+        Se o job já atingiu ``max_retries``, ele é movido para dead-letter.
+        """
+        delay_ms = int(delay * 1000)
+        self._get_native().nack(job.id, job.receipt, delay_ms, last_error)
+
+    def fail(self, job: Job, last_error: Optional[str] = None) -> None:
+        """Marca o job como falha definitiva (dead-letter)."""
+        self._get_native().fail(job.id, job.receipt, last_error)
+
+    def extend_lease(self, job: Job, seconds: float) -> None:
+        """Estende o lease de um job.
+
+        Levanta :class:`LeaseExpired` se o lease já tiver expirado.
+        """
+        extend_ms = int(seconds * 1000)
+        new_expiration = self._get_native().extend_lease(
+            job.id, job.receipt, extend_ms
+        )
+        job.lease_expires_at = new_expiration / 1000.0
+
+    def reclaim_expired_leases(self) -> int:
+        """Recupera jobs cujo lease expirou.
+
+        :return: número de leases recuperados.
+        """
+        return self._get_native().reclaim_expired(None)
+
+    def stats(self) -> dict[str, int]:
+        """Retorna estatísticas da fila."""
+        stats = self._get_native().stats()
+        return {
+            "ready": stats.ready,
+            "processing": stats.processing,
+            "acked": stats.acked,
+            "failed": stats.failed,
+        }
+
+    def _to_job(self, lease: "_native.Lease") -> Job:
+        data = self.serializer.loads(lease.payload)
+        return Job(
+            id=lease.id,
+            data=data,
+            attempts=max(0, lease.attempts - 1),
+            receipt=lease.receipt,
+            lease_expires_at=lease.lease_until / 1000.0,
+            queue=self,
+        )
+
+    def purge(self, older_than: float, *, include_failed: bool = False) -> int:
+        """Remove mensagens antigas da fila.
+
+        :param older_than: idade máxima em segundos. Mensagens mais antigas
+            serão removidas.
+        :param include_failed: quando ``True``, também remove mensagens
+            ``failed``. Por padrão apenas ``acked`` são removidas.
+        :return: número de mensagens removidas.
+        """
+        if older_than < 0:
+            raise ValueError("'older_than' deve ser não negativo")
+
+        older_than_ms = int(older_than * 1000)
+        removed = 0
+        removed += self._get_native().purge(older_than_ms, 2)  # acked
+        if include_failed:
+            removed += self._get_native().purge(older_than_ms, 3)  # failed
+        return removed
+
+    def list_failed(
+        self, limit: int = 100, offset: int = 0
+    ) -> list[dict[str, Any]]:
+        """Lista mensagens na dead-letter.
+
+        :param limit: número máximo de mensagens.
+        :param offset: deslocamento para paginação.
+        :return: lista de dicionários com informações das mensagens.
+        """
+        if limit < 0:
+            raise ValueError("'limit' deve ser não negativo")
+        if offset < 0:
+            raise ValueError("'offset' deve ser não negativo")
+
+        failed = self._get_native().list_failed(limit, offset)
+        return [
+            {
+                "id": msg.id,
+                "data": self.serializer.loads(msg.payload),
+                "attempts": msg.attempts,
+                "last_error": msg.last_error,
+                "created_at": msg.created_at / 1000.0,
+                "updated_at": msg.updated_at / 1000.0,
+            }
+            for msg in failed
+        ]
+
+    def retry_failed(self, message_id: int) -> None:
+        """Move uma mensagem da dead-letter de volta para a fila.
+
+        :param message_id: id da mensagem a ser retentada.
+        """
+        self._get_native().retry_failed(message_id)
+
+    def vacuum(self) -> None:
+        """Compacta todo o ``localqueue.db`` compartilhado pelas filas.
+
+        A operação pode disputar o lock do SQLite com workers ativos.
+        """
+        self._get_native().vacuum()
+
+    def close(self) -> None:
+        """Fecha a conexão com o banco."""
+        if self._native is not None:
+            self._native.close()
+            self._native = None
+
+    def __enter__(self) -> SimpleQueue:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

localqueue/exceptions.py

@@ -0,0 +1,5 @@
+"""Exceções usadas pelo localqueue."""
+
+from localqueue.localqueue import Empty, LeaseExpired, LocalQueueError
+
+__all__ = ["Empty", "LeaseExpired", "LocalQueueError"]

localqueue/job.py

@@ -0,0 +1,25 @@
+"""Modelo de job retornado pela fila."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class Job:
+    """Representa um item retirado da fila para processamento."""
+
+    id: int
+    data: Any
+    attempts: int
+    receipt: str
+    lease_expires_at: float
+    queue: "SimpleQueue"  # type: ignore[name-defined]  # noqa: F821
+
+    def extend_lease(self, seconds: float) -> None:
+        """Estende o lease do job.
+
+        Levanta :class:`LeaseExpired` se o lease já tiver expirado.
+        """
+        self.queue.extend_lease(self, seconds)

localqueue/localqueue.pyi

@@ -0,0 +1,58 @@
+"""Type stubs para o módulo nativo localqueue.localqueue."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+class Lease:
+    id: int
+    payload: bytes
+    attempts: int
+    receipt: str
+    lease_until: int
+
+class Stats:
+    ready: int
+    processing: int
+    acked: int
+    failed: int
+
+class FailedMessage:
+    id: int
+    payload: bytes
+    attempts: int
+    last_error: Optional[str]
+    created_at: int
+    updated_at: int
+
+class NativeQueue:
+    def __init__(
+        self,
+        path: str,
+        queue: str,
+        max_attempts: int = 3,
+        fsync: bool = False,
+    ) -> None: ...
+    def put(self, payload: bytes, job_id: Optional[str] = None) -> int: ...
+    def get(self, lease_ms: int) -> Optional[Lease]: ...
+    def ack(self, id: int, receipt: str) -> None: ...
+    def nack(
+        self,
+        id: int,
+        receipt: str,
+        delay_ms: int = 0,
+        last_error: Optional[str] = None,
+    ) -> None: ...
+    def fail(self, id: int, receipt: str, last_error: Optional[str] = None) -> None: ...
+    def extend_lease(self, id: int, receipt: str, extend_ms: int) -> int: ...
+    def reclaim_expired(self, now: Optional[int] = None) -> int: ...
+    def stats(self) -> Stats: ...
+    def purge(self, older_than_ms: int, status: Optional[int] = None) -> int: ...
+    def list_failed(self, limit: int = 100, offset: int = 0) -> list[FailedMessage]: ...
+    def retry_failed(self, id: int) -> None: ...
+    def vacuum(self) -> None: ...
+    def close(self) -> None: ...
+
+class LocalQueueError(Exception): ...
+class Empty(LocalQueueError): ...
+class LeaseExpired(LocalQueueError): ...

localqueue/worker.py

@@ -0,0 +1,156 @@
+"""Worker genérico para processar jobs do localqueue."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional
+
+from localqueue.core import SimpleQueue
+from localqueue.exceptions import Empty, LeaseExpired
+from localqueue.job import Job
+
+log = logging.getLogger(__name__)
+
+
+class Worker:
+    """Worker simples que consome jobs de uma :class:`SimpleQueue`.
+
+    O handler recebe o ``Job`` completo. Ele pode levantar exceções para
+    sinalizar erro:
+
+    * Qualquer exceção não listada em ``permanent_errors``: o job volta para
+      a fila (ou dead-letter se atingir ``max_retries``).
+    * Exceção em ``permanent_errors``: o job vai para dead-letter.
+    """
+
+    def __init__(
+        self,
+        queue: SimpleQueue,
+        handler: Callable[[Job], Any],
+        *,
+        permanent_errors: Optional[tuple[type[BaseException], ...]] = None,
+        poll_interval: float = 1.0,
+        heartbeat_interval: Optional[float] = None,
+    ) -> None:
+        """Inicializa o worker.
+
+        :param queue: fila a ser consumida.
+        :param handler: função que processa o job.
+        :param permanent_errors: tupla de exceções que devem mover o job para
+            dead-letter.
+        :param poll_interval: intervalo entre tentativas quando a fila está
+            vazia.
+        :param heartbeat_interval: se definido, renova o lease
+            automaticamente durante o processamento.
+        """
+        if not poll_interval > 0:
+            raise ValueError("'poll_interval' deve ser positivo")
+        if heartbeat_interval is not None and not heartbeat_interval > 0:
+            raise ValueError("'heartbeat_interval' deve ser positivo")
+
+        self.queue = queue
+        self.handler = handler
+        self.permanent_errors = permanent_errors or ()
+        self.poll_interval = poll_interval
+        self.heartbeat_interval = heartbeat_interval
+        self._stop = False
+
+    def run(self) -> None:
+        """Inicia o loop de consumo."""
+        while not self._stop:
+            try:
+                job = self.queue.get(block=True, timeout=self.poll_interval)
+            except Empty:
+                continue
+
+            self._process(job)
+
+    def run_once(self) -> bool:
+        """Processa no máximo um job.
+
+        :return: ``True`` se um job foi processado, ``False`` se a fila estava
+            vazia.
+        """
+        try:
+            job = self.queue.get(block=False)
+        except Empty:
+            return False
+        self._process(job)
+        return True
+
+    def _process(self, job: Job) -> None:
+        log.info("Processando job %s (tentativa %d)", job.id, job.attempts)
+        try:
+            if self.heartbeat_interval is not None:
+                result = self._run_with_heartbeat(job)
+            else:
+                result = self.handler(job)
+        except LeaseExpired:
+            log.warning(
+                "Lease do job %s foi perdido; resultado será descartado",
+                job.id,
+            )
+            return
+        except self.permanent_errors:
+            log.exception("Erro permanente no job %s", job.id)
+            self._transition(self.queue.fail, job)
+        except Exception:
+            log.exception("Erro transitório no job %s; devolvendo à fila", job.id)
+            self._transition(self.queue.nack, job)
+        else:
+            log.debug("Job %s processado com sucesso: %s", job.id, result)
+            self._transition(self.queue.ack, job)
+
+    def _transition(
+        self, operation: Callable[[Job], None], job: Job
+    ) -> None:
+        try:
+            operation(job)
+        except LeaseExpired:
+            log.warning(
+                "Lease do job %s foi perdido antes da transição; "
+                "resultado será descartado",
+                job.id,
+            )
+
+    def _run_with_heartbeat(self, job: Job) -> Any:
+        """Executa o handler renovando o lease periodicamente."""
+        import threading
+
+        result: list[Any] = []
+        error: list[BaseException] = []
+        done = threading.Event()
+        lease_lost = False
+
+        def target() -> None:
+            try:
+                result.append(self.handler(job))
+            except BaseException as exc:  # noqa: BLE001
+                error.append(exc)
+            finally:
+                done.set()
+
+        thread = threading.Thread(target=target, daemon=True)
+        thread.start()
+
+        while not done.wait(self.heartbeat_interval):
+            try:
+                job.extend_lease(self.queue.lease_seconds)
+            except Exception:
+                log.warning("Perdeu o lease do job %s", job.id)
+                lease_lost = True
+                break
+
+        # Espera o handler terminar, mesmo se o lease foi perdido.
+        done.wait()
+
+        if lease_lost:
+            raise LeaseExpired(f"job {job.id} perdeu o lease durante o processamento")
+
+        if error:
+            raise error[0]
+        return result[0] if result else None
+
+    def stop(self) -> None:
+        """Sinaliza para o worker parar no próximo ciclo."""
+        self._stop = True

localqueue-1.0.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: localqueue
+Version: 1.0.0
+Requires-Dist: persist-queue==1.1.0 ; extra == 'benchmark'
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: maturin>=1.14 ; extra == 'dev'
+Provides-Extra: benchmark
+Provides-Extra: dev
+Summary: Fila persistente local em SQLite com ACK, lease e retry.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# localqueue
+
+Fila persistente local em SQLite com ACK, lease e retry.
+
+O motor transacional é implementado em **Rust** (extensão nativa via pyo3/maturin),
+garantindo atomicidade mesmo com múltiplos processos e threads. A facade em
+**Python** mantém uma API simples e agradável.
+
+## Características
+
+- Persistência em disco via SQLite (sobrevive a reinícios).
+- Semântica de ACK/NACK/falha com **receipt/fencing token**.
+- Lease/timeout: jobs não confirmados dentro do prazo voltam para a fila.
+- Retry com limite máximo; após isso vão para dead-letter.
+- Deduplicação opcional por `job_id`.
+- Extensão de lease (`job.extend_lease(...)`) e heartbeat no worker.
+- Estatísticas consistentes mesmo em multiprocessos.
+- Serialização JSON por padrão (legível e interoperável).
+- Suporte a múltiplas filas no mesmo banco (`name="foo"`, `name="bar"`).
+
+## Arquitetura
+
+```text
+localqueue/
+├── src/               # Rust: schema, storage, queue, error, lib (pyo3)
+├── python/localqueue/    # Python: SimpleQueue, Job, Worker, exceções
+├── Cargo.toml
+└── pyproject.toml     # build via maturin
+```
+
+Toda a máquina de estados vive em uma única tabela SQLite (`messages`), com
+transações `BEGIN IMMEDIATE` para atomicidade. Não há camadas auxiliares de
+estado: cada operação (`put`, `get`, `ack`, `nack`, `fail`) é uma única
+transação.
+
+## Uso rápido
+
+```python
+from localqueue import SimpleQueue
+
+with SimpleQueue("./data", lease_seconds=30, max_retries=3) as q:
+    q.put({"type": "deploy", "app": "jarvis", "revision": "abc123"})
+
+    job = q.get()
+    try:
+        process(job.data)
+    except Exception:
+        q.nack(job)
+    else:
+        q.ack(job)
+```
+
+## Worker
+
+```python
+from localqueue import SimpleQueue, Worker
+
+def deploy(job):
+    print(f"Deploying {job.data['app']}@{job.data['revision']}")
+    # Opcional: renova lease para jobs longos
+    job.extend_lease(60)
+
+q = SimpleQueue("./data")
+worker = Worker(q, deploy, heartbeat_interval=10)
+worker.run()
+```
+
+## Multithreading / multiprocessos
+
+A fila é segura para uso com múltiplas threads e processos. O SQLite (em WAL)
+serializa escritas, mas `BEGIN IMMEDIATE` e `busy_timeout` garantem que
+operações concorrentes não corrompam o estado.
+
+## Idempotência
+
+Mesmo com fencing token, um job pode ser entregue mais de uma vez (por
+exemplo, se o worker concluir um efeito externo e morrer antes de executar
+`ack`). A fila oferece semântica at-least-once, não exactly-once.
+Recomenda-se que os handlers sejam idempotentes — use `job_id` para
+deduplicação quando necessário.
+
+As garantias completas de durabilidade, leases, retries e fencing estão em
+[`docs/guarantees.md`](docs/guarantees.md).
+
+## API resumida
+
+* ``put(data, job_id=None)`` – enfileira um item.
+* ``get(block=True, timeout=None)`` – retira um item com lease.
+* ``get_nowait()`` – variação não bloqueante.
+* ``ack(job)`` – confirma processamento.
+* ``nack(job, delay=0, last_error=None)`` – devolve à fila (erro transitório).
+* ``fail(job, last_error=None)`` – envia para dead-letter.
+* ``extend_lease(job, seconds)`` – renova o lease de um job.
+* ``reclaim_expired_leases()`` – recupera leases expirados manualmente.
+* ``stats()`` – retorna contagens de ready, processing, acked e failed.
+
+## Manutenção
+
+* ``purge(older_than, include_failed=False)`` – remove mensagens antigas.
+* ``list_failed(limit=100, offset=0)`` – lista mensagens na dead-letter.
+* ``retry_failed(message_id)`` – move mensagem failed de volta para ready.
+* ``vacuum()`` – compacta todo o arquivo compartilhado ``localqueue.db``. Pode
+  disputar o lock do SQLite com workers ativos, portanto prefira executá-lo em
+  uma janela de manutenção.
+
+## Desenvolvimento
+
+```bash
+uv sync --extra dev
+maturin develop
+pytest
+```
+
+## Build para distribuição
+
+```bash
+maturin build --release
+```
+

localqueue-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+localqueue/__init__.py,sha256=t4A3Jck_OlW_tPU_TEx0Jd9-hXhgyGDpbI6-1U3b3FU,424
+localqueue/core.py,sha256=3v2SgWab_EwYtjAdQ4v1zM1KqZ3xOFIZy-2FV4CAm0g,9206
+localqueue/exceptions.py,sha256=6QLLFOaNDTGUW7sEXd1geLgeub_Dcpma3pJvf77J93Y,174
+localqueue/job.py,sha256=3hPuysli4MMVMp0TrHGgCk3ZF8CBMZae4ElGvg0OB-E,626
+localqueue/localqueue.cp312-win_amd64.pyd,sha256=Oc3-clPGdjm6f90wOMpBRoRI9Ec984fyCquB5P9RqqM,2016256
+localqueue/localqueue.pyi,sha256=Sk8LiP68YKOaDhX0_mwViw44vshRakK-koQg5xeyAhE,1690
+localqueue/worker.py,sha256=Lo9teBb8CAuMsQECKV4_kVo1M_fAfiOEAMoHDu9JWdI,5274
+localqueue-1.0.0.dist-info/METADATA,sha256=SPAz2jtddAlJLzI69HcYlbvsmx53c2oJIsuHb8lw7-8,4415
+localqueue-1.0.0.dist-info/WHEEL,sha256=SN7W5s0Ji01-9u_6QL7cEnscsXvljOVQDFMt-2tILwI,97
+localqueue-1.0.0.dist-info/sboms/localqueue.cyclonedx.json,sha256=68KV1N48gKG3FVCOIRkp8YUZY6cGLZKueEtFT0X7DeQ,36852
+localqueue-1.0.0.dist-info/RECORD,,

localqueue-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.14.1)
+Root-Is-Purelib: false
+Tag: cp312-cp312-win_amd64