localqueue 1.0.0__tar.gz → 1.0.1__tar.gz

{localqueue-1.0.0 → localqueue-1.0.1}/.github/workflows/ci.yml

@@ -81,14 +81,18 @@ jobs:
           python-version: ${{ matrix.python }}
           cache: pip
 
-      - name: Install test dependencies
-        run: python -m pip install --upgrade "maturin>=1.14,<2" "pytest>=8,<10"
-
-      - name: Build the extension in the test environment
-        run: maturin develop --release --locked
-
-      - name: Run tests
-        run: pytest -ra
+      - name: Build extension and run tests in a virtual environment
+        shell: bash
+        run: |
+          python -m venv .venv
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            source .venv/Scripts/activate
+          else
+            source .venv/bin/activate
+          fi
+          python -m pip install --upgrade "maturin>=1.14,<2" "pytest>=8,<10"
+          maturin develop --release --locked
+          pytest -ra
 
   wheel-smoke:
     name: Build and smoke-test wheel

{localqueue-1.0.0 → localqueue-1.0.1}/Cargo.lock

@@ -97,7 +97,7 @@ dependencies = [
 
 [[package]]
 name = "localqueue"
-version = "1.0.0"
+version = "1.0.1"
 dependencies = [
  "pyo3",
  "rusqlite",

{localqueue-1.0.0 → localqueue-1.0.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "localqueue"
-version = "1.0.0"
+version = "1.0.1"
 edition = "2021"
 rust-version = "1.83"
 readme = "README.md"

localqueue-1.0.1/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: localqueue
+Version: 1.0.1
+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: A persistent, multiprocess-safe local queue for Python, backed by SQLite and Rust.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/brunoportis/localqueue
+Project-URL: Issues, https://github.com/brunoportis/localqueue/issues
+Project-URL: Repository, https://github.com/brunoportis/localqueue
+
+# localqueue
+
+[![PyPI](https://img.shields.io/pypi/v/localqueue.svg)](https://pypi.org/project/localqueue/)
+[![Python](https://img.shields.io/pypi/pyversions/localqueue.svg)](https://pypi.org/project/localqueue/)
+[![CI](https://github.com/brunoportis/localqueue/actions/workflows/ci.yml/badge.svg)](https://github.com/brunoportis/localqueue/actions/workflows/ci.yml)
+
+A persistent, multiprocess-safe local queue for Python, backed by SQLite and Rust.
+
+`localqueue` gives scripts and workers durable jobs with ACK/NACK, leases,
+bounded retries, and dead-letter handling—without a server, daemon, or external
+service.
+
+- **Durable:** jobs survive process restarts in a local SQLite database.
+- **Safe under concurrency:** multiple Python threads and processes can share a
+  queue on the same machine.
+- **Failure-aware:** expired leases and transient failures are retried; exhausted
+  jobs move to a dead-letter state.
+- **Fenced:** every delivery has a unique receipt, so stale workers cannot
+  acknowledge a newer delivery.
+- **Flexible:** use multiple named queues, optional job deduplication, automatic
+  worker heartbeats, and custom serializers.
+
+[Installation](#installation) · [Quick start](#quick-start) ·
+[Worker](#worker) · [Guarantees](#delivery-guarantees) ·
+[API](#api-overview) · [Development](#development)
+
+## Installation
+
+Using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add localqueue
+```
+
+Using pip:
+
+```bash
+python -m pip install localqueue
+```
+
+`localqueue` requires Python 3.10 or newer.
+
+## Quick start
+
+```python
+from localqueue import SimpleQueue
+
+with SimpleQueue("./data", lease_seconds=30, max_retries=3) as queue:
+    queue.put(
+        {"task": "send-email", "to": "hello@example.com"},
+        job_id="welcome-email-42",
+    )
+
+    job = queue.get()
+
+    try:
+        send_email(job.data)
+    except Exception as error:
+        queue.nack(job, last_error=str(error))
+    else:
+        queue.ack(job)
+```
+
+The path passed to `SimpleQueue` is a directory. The queue creates and manages
+`localqueue.db` inside it. Payloads are JSON-serialized by default.
+
+## Worker
+
+`Worker` handles the ACK/NACK lifecycle for you. A successful handler is
+acknowledged, an unexpected exception is retried, and an exception listed in
+`permanent_errors` is sent directly to the dead-letter state.
+
+```python
+from localqueue import SimpleQueue, Worker
+
+
+class InvalidDeployment(Exception):
+    pass
+
+
+def deploy(job):
+    print(f"Deploying {job.data['app']}@{job.data['revision']}")
+
+
+with SimpleQueue("./data", lease_seconds=30, max_retries=3) as queue:
+    worker = Worker(
+        queue,
+        deploy,
+        permanent_errors=(InvalidDeployment,),
+        heartbeat_interval=10,
+    )
+    worker.run()
+```
+
+For long-running handlers, `heartbeat_interval` renews the lease in the
+background. A handler can also renew it explicitly with
+`job.extend_lease(seconds)`.
+
+## Delivery guarantees
+
+> [!IMPORTANT]
+> `localqueue` provides **at-least-once** delivery, not exactly-once delivery.
+> A worker can finish an external side effect and crash before `ack()`, causing
+> the job to be delivered again. Make handlers idempotent when duplicate effects
+> matter.
+
+```text
+put() ──> ready ──> leased ──> acked
+                     │
+                     ├── nack() or expired lease ──> ready
+                     │
+                     └── fail() or retry limit ────> failed
+                                                        │
+                                           retry_failed() ──> ready
+```
+
+| Behavior | Guarantee |
+| --- | --- |
+| Successful `put()` | The job was committed to SQLite and has an internal ID. |
+| Worker crash | An unacknowledged job becomes available after its lease expires. |
+| Stale worker | `ack()`, `nack()`, `fail()`, and lease extension require the current receipt. |
+| Retries | `max_retries` allows that many retries after the initial delivery; exhaustion moves the job to `failed`. |
+| Deduplication | A `job_id` is unique within a named queue while its record exists. |
+| Ordering | Ready jobs are claimed by insertion ID, but completion order is best effort under concurrency. |
+
+By default, SQLite uses `synchronous=NORMAL`, which protects against normal
+process crashes but may lose recent transactions after an operating-system or
+power failure. Pass `fsync=True` to use `synchronous=FULL` for stronger
+durability.
+
+See [Delivery guarantees](https://github.com/brunoportis/localqueue/blob/main/docs/guarantees.md)
+for the complete durability, lease, retry, fencing, and deduplication contract.
+
+## Configuration
+
+```python
+queue = SimpleQueue(
+    "./data",
+    name="emails",
+    lease_seconds=60,
+    max_retries=3,
+    fsync=False,
+    serializer=None,
+)
+```
+
+| Option | Default | Description |
+| --- | ---: | --- |
+| `path` | required | Directory containing the shared `localqueue.db` file. |
+| `name` | `"default"` | Logical queue name; several queues can share one database. |
+| `lease_seconds` | `60.0` | Time a worker owns a delivery before it can be reclaimed. |
+| `max_retries` | `3` | Retries allowed after the first delivery. |
+| `fsync` | `False` | Use SQLite `synchronous=FULL` when enabled. |
+| `serializer` | JSON | Object implementing `dumps(obj) -> bytes` and `loads(bytes) -> obj`. |
+
+## API overview
+
+| Method | Purpose |
+| --- | --- |
+| `put(data, job_id=None)` | Enqueue a payload, with optional deduplication. |
+| `get(block=True, timeout=None)` | Claim a job and start its lease. |
+| `get_nowait()` | Claim immediately or raise `Empty`. |
+| `ack(job)` | Confirm successful processing. |
+| `nack(job, delay=0, last_error=None)` | Return a transient failure to the queue, optionally with a delay. |
+| `fail(job, last_error=None)` | Move a permanent failure to the dead-letter state. |
+| `extend_lease(job, seconds)` | Renew the current delivery lease. |
+| `reclaim_expired_leases()` | Reclaim expired leases explicitly; `get()` also does this automatically. |
+| `stats()` | Return `ready`, `processing`, `acked`, and `failed` counts. |
+| `list_failed(limit=100, offset=0)` | Inspect dead-letter jobs. |
+| `retry_failed(message_id)` | Move a dead-letter job back to `ready`. |
+| `purge(older_than, include_failed=False)` | Delete old terminal records. |
+| `vacuum()` | Compact the shared SQLite database. Run during a maintenance window. |
+
+## Architecture
+
+The public API is a small Python facade over a native
+[PyO3](https://pyo3.rs/) extension. Rust owns the transactional state machine,
+while SQLite WAL mode provides local persistence and coordinates competing
+writers.
+
+```text
+Python application
+       │
+       ▼
+SimpleQueue / Worker       Python API and serialization
+       │
+       ▼
+Rust native extension      leases, receipts, retries, transactions
+       │
+       ▼
+localqueue.db              SQLite WAL, one machine
+```
+
+All queue state lives in one SQLite table. Claims and multi-step transitions
+use immediate transactions so concurrent processes cannot reserve the same
+delivery. This is local infrastructure for a shared database on one machine,
+not a distributed message broker.
+
+## Development
+
+Build the extension in a local virtual environment and run the test suite:
+
+```bash
+uv sync --extra dev
+uv run maturin develop
+uv run pytest
+```
+
+Rust quality checks:
+
+```bash
+cargo fmt --all --check
+cargo clippy --locked --all-targets --all-features -- -D warnings
+```
+
+Build a release wheel:
+
+```bash
+uv run maturin build --release --locked
+```
+

localqueue-1.0.1/README.md

@@ -0,0 +1,220 @@
+# localqueue
+
+[![PyPI](https://img.shields.io/pypi/v/localqueue.svg)](https://pypi.org/project/localqueue/)
+[![Python](https://img.shields.io/pypi/pyversions/localqueue.svg)](https://pypi.org/project/localqueue/)
+[![CI](https://github.com/brunoportis/localqueue/actions/workflows/ci.yml/badge.svg)](https://github.com/brunoportis/localqueue/actions/workflows/ci.yml)
+
+A persistent, multiprocess-safe local queue for Python, backed by SQLite and Rust.
+
+`localqueue` gives scripts and workers durable jobs with ACK/NACK, leases,
+bounded retries, and dead-letter handling—without a server, daemon, or external
+service.
+
+- **Durable:** jobs survive process restarts in a local SQLite database.
+- **Safe under concurrency:** multiple Python threads and processes can share a
+  queue on the same machine.
+- **Failure-aware:** expired leases and transient failures are retried; exhausted
+  jobs move to a dead-letter state.
+- **Fenced:** every delivery has a unique receipt, so stale workers cannot
+  acknowledge a newer delivery.
+- **Flexible:** use multiple named queues, optional job deduplication, automatic
+  worker heartbeats, and custom serializers.
+
+[Installation](#installation) · [Quick start](#quick-start) ·
+[Worker](#worker) · [Guarantees](#delivery-guarantees) ·
+[API](#api-overview) · [Development](#development)
+
+## Installation
+
+Using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add localqueue
+```
+
+Using pip:
+
+```bash
+python -m pip install localqueue
+```
+
+`localqueue` requires Python 3.10 or newer.
+
+## Quick start
+
+```python
+from localqueue import SimpleQueue
+
+with SimpleQueue("./data", lease_seconds=30, max_retries=3) as queue:
+    queue.put(
+        {"task": "send-email", "to": "hello@example.com"},
+        job_id="welcome-email-42",
+    )
+
+    job = queue.get()
+
+    try:
+        send_email(job.data)
+    except Exception as error:
+        queue.nack(job, last_error=str(error))
+    else:
+        queue.ack(job)
+```
+
+The path passed to `SimpleQueue` is a directory. The queue creates and manages
+`localqueue.db` inside it. Payloads are JSON-serialized by default.
+
+## Worker
+
+`Worker` handles the ACK/NACK lifecycle for you. A successful handler is
+acknowledged, an unexpected exception is retried, and an exception listed in
+`permanent_errors` is sent directly to the dead-letter state.
+
+```python
+from localqueue import SimpleQueue, Worker
+
+
+class InvalidDeployment(Exception):
+    pass
+
+
+def deploy(job):
+    print(f"Deploying {job.data['app']}@{job.data['revision']}")
+
+
+with SimpleQueue("./data", lease_seconds=30, max_retries=3) as queue:
+    worker = Worker(
+        queue,
+        deploy,
+        permanent_errors=(InvalidDeployment,),
+        heartbeat_interval=10,
+    )
+    worker.run()
+```
+
+For long-running handlers, `heartbeat_interval` renews the lease in the
+background. A handler can also renew it explicitly with
+`job.extend_lease(seconds)`.
+
+## Delivery guarantees
+
+> [!IMPORTANT]
+> `localqueue` provides **at-least-once** delivery, not exactly-once delivery.
+> A worker can finish an external side effect and crash before `ack()`, causing
+> the job to be delivered again. Make handlers idempotent when duplicate effects
+> matter.
+
+```text
+put() ──> ready ──> leased ──> acked
+                     │
+                     ├── nack() or expired lease ──> ready
+                     │
+                     └── fail() or retry limit ────> failed
+                                                        │
+                                           retry_failed() ──> ready
+```
+
+| Behavior | Guarantee |
+| --- | --- |
+| Successful `put()` | The job was committed to SQLite and has an internal ID. |
+| Worker crash | An unacknowledged job becomes available after its lease expires. |
+| Stale worker | `ack()`, `nack()`, `fail()`, and lease extension require the current receipt. |
+| Retries | `max_retries` allows that many retries after the initial delivery; exhaustion moves the job to `failed`. |
+| Deduplication | A `job_id` is unique within a named queue while its record exists. |
+| Ordering | Ready jobs are claimed by insertion ID, but completion order is best effort under concurrency. |
+
+By default, SQLite uses `synchronous=NORMAL`, which protects against normal
+process crashes but may lose recent transactions after an operating-system or
+power failure. Pass `fsync=True` to use `synchronous=FULL` for stronger
+durability.
+
+See [Delivery guarantees](https://github.com/brunoportis/localqueue/blob/main/docs/guarantees.md)
+for the complete durability, lease, retry, fencing, and deduplication contract.
+
+## Configuration
+
+```python
+queue = SimpleQueue(
+    "./data",
+    name="emails",
+    lease_seconds=60,
+    max_retries=3,
+    fsync=False,
+    serializer=None,
+)
+```
+
+| Option | Default | Description |
+| --- | ---: | --- |
+| `path` | required | Directory containing the shared `localqueue.db` file. |
+| `name` | `"default"` | Logical queue name; several queues can share one database. |
+| `lease_seconds` | `60.0` | Time a worker owns a delivery before it can be reclaimed. |
+| `max_retries` | `3` | Retries allowed after the first delivery. |
+| `fsync` | `False` | Use SQLite `synchronous=FULL` when enabled. |
+| `serializer` | JSON | Object implementing `dumps(obj) -> bytes` and `loads(bytes) -> obj`. |
+
+## API overview
+
+| Method | Purpose |
+| --- | --- |
+| `put(data, job_id=None)` | Enqueue a payload, with optional deduplication. |
+| `get(block=True, timeout=None)` | Claim a job and start its lease. |
+| `get_nowait()` | Claim immediately or raise `Empty`. |
+| `ack(job)` | Confirm successful processing. |
+| `nack(job, delay=0, last_error=None)` | Return a transient failure to the queue, optionally with a delay. |
+| `fail(job, last_error=None)` | Move a permanent failure to the dead-letter state. |
+| `extend_lease(job, seconds)` | Renew the current delivery lease. |
+| `reclaim_expired_leases()` | Reclaim expired leases explicitly; `get()` also does this automatically. |
+| `stats()` | Return `ready`, `processing`, `acked`, and `failed` counts. |
+| `list_failed(limit=100, offset=0)` | Inspect dead-letter jobs. |
+| `retry_failed(message_id)` | Move a dead-letter job back to `ready`. |
+| `purge(older_than, include_failed=False)` | Delete old terminal records. |
+| `vacuum()` | Compact the shared SQLite database. Run during a maintenance window. |
+
+## Architecture
+
+The public API is a small Python facade over a native
+[PyO3](https://pyo3.rs/) extension. Rust owns the transactional state machine,
+while SQLite WAL mode provides local persistence and coordinates competing
+writers.
+
+```text
+Python application
+       │
+       ▼
+SimpleQueue / Worker       Python API and serialization
+       │
+       ▼
+Rust native extension      leases, receipts, retries, transactions
+       │
+       ▼
+localqueue.db              SQLite WAL, one machine
+```
+
+All queue state lives in one SQLite table. Claims and multi-step transitions
+use immediate transactions so concurrent processes cannot reserve the same
+delivery. This is local infrastructure for a shared database on one machine,
+not a distributed message broker.
+
+## Development
+
+Build the extension in a local virtual environment and run the test suite:
+
+```bash
+uv sync --extra dev
+uv run maturin develop
+uv run pytest
+```
+
+Rust quality checks:
+
+```bash
+cargo fmt --all --check
+cargo clippy --locked --all-targets --all-features -- -D warnings
+```
+
+Build a release wheel:
+
+```bash
+uv run maturin build --release --locked
+```

{localqueue-1.0.0 → localqueue-1.0.1}/pyproject.toml

@@ -1,11 +1,16 @@
 [project]
 name = "localqueue"
-version = "1.0.0"
-description = "Fila persistente local em SQLite com ACK, lease e retry."
+version = "1.0.1"
+description = "A persistent, multiprocess-safe local queue for Python, backed by SQLite and Rust."
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = []
 
+[project.urls]
+Homepage = "https://github.com/brunoportis/localqueue"
+Repository = "https://github.com/brunoportis/localqueue"
+Issues = "https://github.com/brunoportis/localqueue/issues"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0",

{localqueue-1.0.0 → localqueue-1.0.1}/src/storage.rs

@@ -1,6 +1,7 @@
-use rusqlite::{Connection, OpenFlags};
+use rusqlite::{Connection, ErrorCode, OpenFlags};
 use std::sync::Mutex;
-use std::time::{SystemTime, UNIX_EPOCH};
+use std::thread;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use crate::error::{QueueError, Result};
 use crate::schema::SCHEMA_SQL;
@@ -18,10 +19,10 @@ impl Storage {
                 | OpenFlags::SQLITE_OPEN_URI,
         )?;
 
-        conn.pragma_update(None, "journal_mode", "WAL")?;
+        conn.pragma_update(None, "busy_timeout", 5000)?;
+        enable_wal(&conn)?;
         conn.pragma_update(None, "synchronous", if fsync { "FULL" } else { "NORMAL" })?;
         conn.pragma_update(None, "foreign_keys", "ON")?;
-        conn.pragma_update(None, "busy_timeout", 5000)?;
 
         conn.execute_batch(SCHEMA_SQL)?;
 
@@ -43,6 +44,26 @@ impl Storage {
     }
 }
 
+fn enable_wal(conn: &Connection) -> Result<()> {
+    let deadline = Instant::now() + Duration::from_secs(5);
+
+    loop {
+        match conn.pragma_update(None, "journal_mode", "WAL") {
+            Ok(()) => return Ok(()),
+            Err(error)
+                if matches!(
+                    error,
+                    rusqlite::Error::SqliteFailure(ref failure, _)
+                        if matches!(failure.code, ErrorCode::DatabaseBusy | ErrorCode::DatabaseLocked)
+                ) && Instant::now() < deadline =>
+            {
+                thread::sleep(Duration::from_millis(25));
+            }
+            Err(error) => return Err(error.into()),
+        }
+    }
+}
+
 pub fn now_ms() -> i64 {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)

{localqueue-1.0.0 → localqueue-1.0.1}/tests/test_contract.py

@@ -11,6 +11,13 @@ import pytest
 from localqueue import Empty, Job, LeaseExpired, LocalQueueError, SimpleQueue
 
 
+def _put_job_with_same_id(path: str, result_queue) -> None:
+    q = SimpleQueue(path, lease_seconds=5.0)
+    job_id = q.put({"task": "x"}, job_id="job-123")
+    result_queue.put(job_id)
+    q.close()
+
+
 class TestContract:
     def test_two_queues_same_db(self, tmp_path):
         """Duas filas com nomes diferentes no mesmo banco."""
@@ -205,15 +212,12 @@ os._exit(1)
 
         path = tmp_path / "dedup"
 
-        def put_job(result_queue):
-            q = SimpleQueue(str(path), lease_seconds=5.0)
-            job_id = q.put({"task": "x"}, job_id="job-123")
-            result_queue.put(job_id)
-            q.close()
-
         result_queue = multiprocessing.Queue()
         processes = [
-            multiprocessing.Process(target=put_job, args=(result_queue,))
+            multiprocessing.Process(
+                target=_put_job_with_same_id,
+                args=(str(path), result_queue),
+            )
             for _ in range(2)
         ]
         for p in processes:

localqueue-1.0.0/PKG-INFO

@@ -1,131 +0,0 @@
-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/README.md

@@ -1,118 +0,0 @@
-# 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
-```