rust-py-audit 0.2.4__tar.gz → 0.3.1__tar.gz

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/Cargo.lock

@@ -1597,7 +1597,7 @@ dependencies = [
 
 [[package]]
 name = "rust_py_audit"
-version = "0.2.4"
+version = "0.3.1"
 dependencies = [
  "httpmock",
  "pyo3",

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rust_py_audit"
-version = "0.2.4"
+version = "0.3.1"
 edition = "2021"
 description = "Auditoria de eventos com cadeia de hashes (SHA-256) para apps Python, core em Rust via PyO3."
 license = "MIT"

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rust-py-audit
-Version: 0.2.4
+Version: 0.3.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -198,7 +198,7 @@ See the full example in [`examples/django_example/`](examples/django_example/).
 |---|---|---|---|
 | `"local"` (default) | ✅ | ❌ | The library's original behavior, no external dependency |
 | `"remote"` | ❌ (except for pending entries, see below) | ✅ | ImmutableLog is the single source of truth; a delivery failure raises an exception |
-| `"hybrid"` | ✅ | ✅ | Local chain + remote receipt; a delivery failure NEVER raises — it becomes `delivery_status="pending"` |
+| `"hybrid"` | ✅ | ✅ | Local chain + remote receipt; a delivery failure NEVER raises — a transient (retryable) failure becomes `status="pending"` (queued for `flush_pending()`), a permanent one becomes `status="failed"` (not queued) |
 
 `mode="local"` is the default — existing code calling `AuditLogger(app_name, file_path)` keeps working unchanged.
 
@@ -228,11 +228,12 @@ event = audit.log(
 
 print(event["immutablelog"])
 # {"status": "delivered", "tx_id": "tx_...", "payload_hash": "...", ...}
-# or {"status": "pending", "tx_id": None, ...} if delivery failed (hybrid mode)
+# or {"status": "pending", "tx_id": None, ...} on a transient failure (hybrid mode)
+# or {"status": "failed", "tx_id": None, ...} on a permanent failure (hybrid mode)
 
 # Retries delivery of every event still marked "pending":
 print(audit.flush_pending())
-# {"flushed": 1, "still_pending": 0, "total": 1}
+# {"flushed": 1, "failed": 0, "still_pending": 0, "total": 1}
 ```
 
 ### Environment variables
@@ -319,7 +320,11 @@ Same behavior as FastAPI: `severity` computed from `status_code`, and delivery f
 - **Retryable**: `5xx` and timeouts.
 - **Permanent** (never retried): `400`, `401`, `403`, `429`, and any other client error.
 - In `mode="remote"`, exhausting retries (or a permanent error) raises `RuntimeError`.
-- In `mode="hybrid"`, the same scenario marks the event as `delivery_status="pending"`, writes it to `audit.pending.jsonl`, and never raises — call `audit.flush_pending()` (manually, or from a cron/worker) to retry later.
+- In `mode="hybrid"`, delivery never raises:
+  - a **retryable** failure (5xx/timeout) marks the event `status="pending"` and queues it in `audit.pending.jsonl` — call `audit.flush_pending()` (manually, or from a cron/worker) to retry later;
+  - a **permanent** failure (4xx) marks the event `status="failed"` and does **not** queue it (retrying would never succeed, so it stays out of the queue instead of getting stuck there forever). The event is still recorded locally and the chain stays valid — `"failed"` is just operational metadata.
+
+In `mode="hybrid"`, the event is appended to the local JSONL **once**, already carrying its final receipt (an O(1) append per event, not a full-file rewrite). A network failure still records the event locally (as `pending`/`failed`), so it is never lost to a failed delivery; the only loss window is the process being killed mid-request, and even then a delivery that did reach ImmutableLog is preserved in the remote store.
 
 ### Integrity guarantee
 
@@ -371,7 +376,7 @@ Records an event and returns the full event (already with `id`, `timestamp`, `ha
 | `hash` | `str` | SHA-256 (64 hex chars) of the event + `previous_hash` |
 | `severity` | `str \| absent` | Only present if passed to `log()`. Becomes `meta.type` on ImmutableLog |
 | `immutable_trail` | `str \| absent` | Only present if passed to `log()` (and not empty after sanitization). Becomes `meta.immutable_trail` |
-| `immutablelog` | `dict \| absent` | Only present in `mode="remote"`/`"hybrid"`. `status` is `"delivered"` or `"pending"`; other fields (`tx_id`, `payload_hash`, `duplicate`, `request_id`, ...) come from the ImmutableLog response |
+| `immutablelog` | `dict \| absent` | Only present in `mode="remote"`/`"hybrid"`. `status` is `"delivered"`, `"pending"` (transient failure, queued), or `"failed"` (permanent failure, not queued); other fields (`tx_id`, `payload_hash`, `duplicate`, `request_id`, ...) come from the ImmutableLog response |
 
 In `mode="remote"`, a permanent failure or exhausted retries raise `RuntimeError` instead of returning the dict.
 
@@ -394,10 +399,23 @@ Hash of the last recorded event (in-memory cache, O(1)) — `None` if no event h
 Attempts to redeliver to ImmutableLog every event marked as `pending` (recorded in `audit.pending.jsonl`, derived from `file_path`). Only relevant in `mode="hybrid"` — other modes never populate this queue.
 
 ```python
-{"flushed": 1, "still_pending": 0, "total": 1}
+{"flushed": 1, "failed": 0, "still_pending": 0, "total": 1}
 ```
 
-On success, updates `event["immutablelog"]` in `audit.jsonl` (without changing `hash`) and removes the event from the queue. Events that fail again stay in the queue for the next call.
+For each queued event:
+- **delivered** → updates `event["immutablelog"]` in `audit.jsonl` to `"delivered"` (without changing `hash`) and removes it from the queue (counts toward `flushed`);
+- **permanent failure** → marks it `"failed"` in `audit.jsonl` and removes it from the queue, so it doesn't stay stuck forever (counts toward `failed`);
+- **retryable failure** → left in the queue for the next call (counts toward `still_pending`).
+
+---
+
+## Roadmap
+
+`rust-py-audit` is mature (v0.3.0): the SHA-256 hash chain, JSONL storage,
+FastAPI/Django middlewares, and the ImmutableLog `local`/`remote`/`hybrid`
+integration are shipped and stable. Directional ideas under consideration (log
+rotation, incremental verification, more delivery backends, an async client, a
+Flask middleware) are tracked in [ROADMAP.md](./ROADMAP.md).
 
 ---
 

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/README.md

@@ -161,7 +161,7 @@ See the full example in [`examples/django_example/`](examples/django_example/).
 |---|---|---|---|
 | `"local"` (default) | ✅ | ❌ | The library's original behavior, no external dependency |
 | `"remote"` | ❌ (except for pending entries, see below) | ✅ | ImmutableLog is the single source of truth; a delivery failure raises an exception |
-| `"hybrid"` | ✅ | ✅ | Local chain + remote receipt; a delivery failure NEVER raises — it becomes `delivery_status="pending"` |
+| `"hybrid"` | ✅ | ✅ | Local chain + remote receipt; a delivery failure NEVER raises — a transient (retryable) failure becomes `status="pending"` (queued for `flush_pending()`), a permanent one becomes `status="failed"` (not queued) |
 
 `mode="local"` is the default — existing code calling `AuditLogger(app_name, file_path)` keeps working unchanged.
 
@@ -191,11 +191,12 @@ event = audit.log(
 
 print(event["immutablelog"])
 # {"status": "delivered", "tx_id": "tx_...", "payload_hash": "...", ...}
-# or {"status": "pending", "tx_id": None, ...} if delivery failed (hybrid mode)
+# or {"status": "pending", "tx_id": None, ...} on a transient failure (hybrid mode)
+# or {"status": "failed", "tx_id": None, ...} on a permanent failure (hybrid mode)
 
 # Retries delivery of every event still marked "pending":
 print(audit.flush_pending())
-# {"flushed": 1, "still_pending": 0, "total": 1}
+# {"flushed": 1, "failed": 0, "still_pending": 0, "total": 1}
 ```
 
 ### Environment variables
@@ -282,7 +283,11 @@ Same behavior as FastAPI: `severity` computed from `status_code`, and delivery f
 - **Retryable**: `5xx` and timeouts.
 - **Permanent** (never retried): `400`, `401`, `403`, `429`, and any other client error.
 - In `mode="remote"`, exhausting retries (or a permanent error) raises `RuntimeError`.
-- In `mode="hybrid"`, the same scenario marks the event as `delivery_status="pending"`, writes it to `audit.pending.jsonl`, and never raises — call `audit.flush_pending()` (manually, or from a cron/worker) to retry later.
+- In `mode="hybrid"`, delivery never raises:
+  - a **retryable** failure (5xx/timeout) marks the event `status="pending"` and queues it in `audit.pending.jsonl` — call `audit.flush_pending()` (manually, or from a cron/worker) to retry later;
+  - a **permanent** failure (4xx) marks the event `status="failed"` and does **not** queue it (retrying would never succeed, so it stays out of the queue instead of getting stuck there forever). The event is still recorded locally and the chain stays valid — `"failed"` is just operational metadata.
+
+In `mode="hybrid"`, the event is appended to the local JSONL **once**, already carrying its final receipt (an O(1) append per event, not a full-file rewrite). A network failure still records the event locally (as `pending`/`failed`), so it is never lost to a failed delivery; the only loss window is the process being killed mid-request, and even then a delivery that did reach ImmutableLog is preserved in the remote store.
 
 ### Integrity guarantee
 
@@ -334,7 +339,7 @@ Records an event and returns the full event (already with `id`, `timestamp`, `ha
 | `hash` | `str` | SHA-256 (64 hex chars) of the event + `previous_hash` |
 | `severity` | `str \| absent` | Only present if passed to `log()`. Becomes `meta.type` on ImmutableLog |
 | `immutable_trail` | `str \| absent` | Only present if passed to `log()` (and not empty after sanitization). Becomes `meta.immutable_trail` |
-| `immutablelog` | `dict \| absent` | Only present in `mode="remote"`/`"hybrid"`. `status` is `"delivered"` or `"pending"`; other fields (`tx_id`, `payload_hash`, `duplicate`, `request_id`, ...) come from the ImmutableLog response |
+| `immutablelog` | `dict \| absent` | Only present in `mode="remote"`/`"hybrid"`. `status` is `"delivered"`, `"pending"` (transient failure, queued), or `"failed"` (permanent failure, not queued); other fields (`tx_id`, `payload_hash`, `duplicate`, `request_id`, ...) come from the ImmutableLog response |
 
 In `mode="remote"`, a permanent failure or exhausted retries raise `RuntimeError` instead of returning the dict.
 
@@ -357,10 +362,23 @@ Hash of the last recorded event (in-memory cache, O(1)) — `None` if no event h
 Attempts to redeliver to ImmutableLog every event marked as `pending` (recorded in `audit.pending.jsonl`, derived from `file_path`). Only relevant in `mode="hybrid"` — other modes never populate this queue.
 
 ```python
-{"flushed": 1, "still_pending": 0, "total": 1}
+{"flushed": 1, "failed": 0, "still_pending": 0, "total": 1}
 ```
 
-On success, updates `event["immutablelog"]` in `audit.jsonl` (without changing `hash`) and removes the event from the queue. Events that fail again stay in the queue for the next call.
+For each queued event:
+- **delivered** → updates `event["immutablelog"]` in `audit.jsonl` to `"delivered"` (without changing `hash`) and removes it from the queue (counts toward `flushed`);
+- **permanent failure** → marks it `"failed"` in `audit.jsonl` and removes it from the queue, so it doesn't stay stuck forever (counts toward `failed`);
+- **retryable failure** → left in the queue for the next call (counts toward `still_pending`).
+
+---
+
+## Roadmap
+
+`rust-py-audit` is mature (v0.3.0): the SHA-256 hash chain, JSONL storage,
+FastAPI/Django middlewares, and the ImmutableLog `local`/`remote`/`hybrid`
+integration are shipped and stable. Directional ideas under consideration (log
+rotation, incremental verification, more delivery backends, an async client, a
+Flask middleware) are tracked in [ROADMAP.md](./ROADMAP.md).
 
 ---
 

rust_py_audit-0.3.1/ROADMAP.md

@@ -0,0 +1,68 @@
+# Roadmap — rust-py-audit
+
+Direction for `rust-py-audit`: a tamper-evident audit log for Python with a Rust
+core (PyO3 + maturin). The library is already mature (v0.3.0) — the SHA-256 hash
+chain, JSONL storage, FastAPI/Django middlewares, and the ImmutableLog
+`local`/`remote`/`hybrid` integration are shipped and stable. This document tracks
+what is done and the **directional** ideas under consideration.
+
+> Status legend: ✅ shipped · 🔜 planned (next) · 💡 idea (no version yet) · ⚠️ note
+
+> ⚠️ Beyond "shipped", items below are **inferred directions, not commitments**.
+> Confirm priorities with the maintainer before planning a release around them.
+
+---
+
+## Shipped — up to v0.3.0
+
+- ✅ `AuditLogger` with `log(...)`, `verify()`, `last_hash()`.
+- ✅ **SHA-256 hash chain** — each event embeds the previous event's hash; any
+  edit, deletion, or reordering is detected by `verify()` (re-read from disk,
+  never trusts an in-memory cache).
+- ✅ Append-only **JSONL** storage — one event per line, no database.
+- ✅ Thread-safe — the chain stays linear under concurrency.
+- ✅ Free-form JSON-serializable `metadata`.
+- ✅ FastAPI and Django middlewares (log state-changing requests:
+  POST/PUT/PATCH/DELETE).
+- ✅ **ImmutableLog integration** — `local`/`remote`/`hybrid` modes, automatic
+  retry with idempotency key, pending queue (`audit.pending.jsonl`),
+  `flush_pending()`, and transient (`pending`) vs permanent (`failed`) failure
+  handling that never takes down the application response.
+- ✅ `severity`, `immutable_trail`, and `env` delivery metadata (never enter the
+  hash, so `verify()` stays valid after `flush_pending()`).
+- ✅ ImmutableLog HTTP client runs in the Rust core (PyO3 + reqwest).
+
+---
+
+## Directional ideas (no version assigned — confirm before planning)
+
+- 💡 **Log rotation / segmentation** — roll the JSONL by size or date while
+  preserving chain continuity across segments (carry the last hash forward).
+- 💡 **Incremental verification** — verify only events appended since the last
+  known-good hash, instead of re-reading the whole file every time.
+- 💡 **More delivery backends** — additional sinks alongside ImmutableLog (e.g.
+  S3/object storage, syslog, a generic webhook), reusing the retry/pending logic.
+- 💡 **Async client** — non-blocking delivery path for high-throughput async apps.
+- 💡 **Flask middleware** — parity with the FastAPI/Django adapters.
+- 💡 **Query/read helpers** — iterate or filter recorded events (by actor, action,
+  resource, time range) without hand-parsing the JSONL.
+- 💡 **Benchmarks suite** — hashing + append throughput under concurrency.
+
+---
+
+## Known limitations (by design, for now)
+
+- Local JSONL is single-file and append-only (no built-in rotation yet).
+- `verify()` re-reads the entire file (O(n)); fine for typical logs, see the
+  incremental-verification idea above for very large files.
+- ImmutableLog delivery is synchronous on the `log()` path (bounded by
+  `timeout_ms` + retries); `hybrid` mode never raises, queuing transient failures.
+
+---
+
+## Contributing to the roadmap
+
+Versions and ordering are indicative and may shift. Bump the version in **both**
+`Cargo.toml` and `pyproject.toml` (kept in sync) plus `__version__`, ship tests
+(`cargo test --no-default-features` + `pytest`), then tag `vX.Y.Z` to trigger the
+release workflow (Trusted Publishing / OIDC to PyPI).

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "rust-py-audit"
-version = "0.2.4"
+version = "0.3.1"
 description = "Fast, tamper-evident event auditing (hash chain) for Python apps, with a Rust core."
 readme = "README.md"
 license = "MIT"

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/python/rust_py_audit/__init__.py

@@ -8,5 +8,5 @@ que existe um módulo nativo por trás.
 
 from ._rust_py_audit import AuditLogger, hello
 
-__version__ = "0.2.4"
+__version__ = "0.3.1"
 __all__ = ["AuditLogger", "hello"]

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/src/audit_logger.rs

@@ -354,38 +354,54 @@ impl AuditLogger {
 
         // Igual a `log()`: tudo que trava o `Mutex` ou faz rede roda com
         // o GIL liberado (REGRA CRÍTICA na doc da struct).
-        let (flushed, still_pending) = py.allow_threads(|| -> Result<(usize, usize), crate::errors::AuditError> {
-            // Primeiro a parte cara/lenta (rede), SEM segurar o lock:
-            // acumulamos os receipts entregues e os ids a remover da fila.
-            let mut delivered: HashMap<String, ImmutableLogReceipt> = HashMap::new();
-            let mut flushed_ids: HashSet<String> = HashSet::new();
-
-            for event in &pending_events {
-                let severity = resolve_severity(event.severity.as_deref())
-                    .map_err(crate::errors::AuditError::Config)?;
-                if let Ok(receipt) = self.deliver(event, severity, event.immutable_trail.as_deref())
-                {
-                    delivered.insert(event.id.clone(), receipt);
-                    flushed_ids.insert(event.id.clone());
+        let (flushed, failed, still_pending) =
+            py.allow_threads(|| -> Result<(usize, usize, usize), crate::errors::AuditError> {
+                // Primeiro a parte cara/lenta (rede), SEM segurar o lock:
+                // acumulamos os receipts a gravar e os ids a remover da fila.
+                // `receipts` junta entregues e permanentes-falhados (ambos
+                // saem da fila); `handled` é o conjunto de ids a remover.
+                let mut receipts: HashMap<String, ImmutableLogReceipt> = HashMap::new();
+                let mut handled: HashSet<String> = HashSet::new();
+                let mut flushed = 0usize;
+                let mut failed = 0usize;
+
+                for event in &pending_events {
+                    let severity = resolve_severity(event.severity.as_deref())
+                        .map_err(crate::errors::AuditError::Config)?;
+                    match self.deliver(event, severity, event.immutable_trail.as_deref()) {
+                        Ok(receipt) => {
+                            receipts.insert(event.id.clone(), receipt);
+                            handled.insert(event.id.clone());
+                            flushed += 1;
+                        }
+                        Err(err) if err.is_retryable() => {
+                            // Transitório: continua na fila para a próxima
+                            // chamada de `flush_pending()` tentar de novo.
+                        }
+                        Err(_) => {
+                            // Permanente: marca `failed` e tira da fila —
+                            // retentar não muda o resultado (#8).
+                            receipts.insert(event.id.clone(), ImmutableLogReceipt::failed());
+                            handled.insert(event.id.clone());
+                            failed += 1;
+                        }
+                    }
                 }
-                // Em falha o evento simplesmente continua na fila para a
-                // próxima chamada de `flush_pending()` tentar de novo.
-            }
 
-            // Só agora travamos, para a parte que mexe nos arquivos —
-            // serializando contra um `log()` concorrente. As funções em
-            // lote releem os arquivos aqui dentro, então eventos
-            // acrescentados nesse meio-tempo são preservados.
-            let _guard = self.lock_last_hash();
-            storage::update_event_receipts(&self.file_path, &delivered)?;
-            storage::remove_events(&pending_path, &flushed_ids)?;
+                // Só agora travamos, para a parte que mexe nos arquivos —
+                // serializando contra um `log()` concorrente. As funções em
+                // lote releem os arquivos aqui dentro, então eventos
+                // acrescentados nesse meio-tempo são preservados.
+                let _guard = self.lock_last_hash();
+                storage::update_event_receipts(&self.file_path, &receipts)?;
+                storage::remove_events(&pending_path, &handled)?;
 
-            let flushed = flushed_ids.len();
-            Ok((flushed, total - flushed))
-        })?;
+                Ok((flushed, failed, total - flushed - failed))
+            })?;
 
         let dict = PyDict::new_bound(py);
         dict.set_item("flushed", flushed)?;
+        dict.set_item("failed", failed)?;
         dict.set_item("still_pending", still_pending)?;
         dict.set_item("total", total)?;
         Ok(dict.into())
@@ -499,29 +515,47 @@ impl AuditLogger {
                 *guard = Some(event.hash.clone());
             }
             AuditMode::Hybrid => {
-                // Salva local PRIMEIRO: mesmo que o processo morra antes
-                // do envio terminar, o evento já está persistido (sem
-                // receipt) — nunca perdemos o registro local por uma
-                // falha de rede.
-                storage::append_event(&self.file_path, &event)?;
-                *guard = Some(event.hash.clone());
+                // Entrega ANTES de gravar, para anexar o evento ao JSONL
+                // local UMA única vez (append O(1)) já com o receipt
+                // final — em vez de gravar e depois reescrever o arquivo
+                // inteiro (O(n)) só para anexar o receipt. Falha em hybrid
+                // NUNCA é exceção Python.
+                //
+                // Isso preserva a garantia "uma falha de REDE nunca perde
+                // o registro local": uma falha de rede (timeout, conexão
+                // recusada, 5xx) cai num dos ramos `Err` abaixo, que grava
+                // o evento localmente do mesmo jeito. O único cenário novo
+                // de perda é o processo ser MORTO no meio da chamada de
+                // rede (janela limitada por `timeout_ms`) — e, mesmo aí, se
+                // a entrega chegou ao ImmutableLog o registro existe no
+                // destino remoto (a fonte de verdade no modo hybrid).
+                let (receipt, queue_for_retry) =
+                    match self.deliver(&event, resolved_severity, event.immutable_trail.as_deref()) {
+                        Ok(receipt) => (receipt, false),
+                        Err(err) if err.is_retryable() => {
+                            // Transitório: vira `pending` e entra na fila
+                            // para `flush_pending()` tentar de novo depois.
+                            (ImmutableLogReceipt::pending(), true)
+                        }
+                        Err(_) => {
+                            // Permanente (400/401/403/429/...): retentar não
+                            // muda nada, então `failed` e NÃO enfileira.
+                            (ImmutableLogReceipt::failed(), false)
+                        }
+                    };
 
-                match self.deliver(&event, resolved_severity, event.immutable_trail.as_deref()) {
-                    Ok(receipt) => {
-                        event.immutablelog = Some(receipt.clone());
-                        storage::update_event_receipt(&self.file_path, &event.id, &receipt)?;
-                    }
-                    Err(_) => {
-                        // Falha em hybrid NÃO é exceção Python: o evento
-                        // já está seguro localmente, então devolvemos
-                        // status "pending" e deixamos `flush_pending()`
-                        // tentar de novo depois.
-                        let pending_receipt = ImmutableLogReceipt::pending();
-                        event.immutablelog = Some(pending_receipt.clone());
-                        storage::update_event_receipt(&self.file_path, &event.id, &pending_receipt)?;
-                        storage::append_event(&storage::pending_path_for(&self.file_path), &event)?;
-                    }
+                event.immutablelog = Some(receipt);
+
+                // Enfileira ANTES de gravar no arquivo principal: se o
+                // processo morrer entre os dois appends, o evento ainda
+                // está na fila e `flush_pending()` o reentrega — preferível
+                // a ficar gravado como `pending` no arquivo principal sem
+                // estar na fila (preso sem reenvio).
+                if queue_for_retry {
+                    storage::append_event(&storage::pending_path_for(&self.file_path), &event)?;
                 }
+                storage::append_event(&self.file_path, &event)?;
+                *guard = Some(event.hash.clone());
             }
         }
 

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/src/immutablelog_receipt.rs

@@ -39,4 +39,16 @@ impl ImmutableLogReceipt {
             ..Default::default()
         }
     }
+
+    /// Entrega abandonada por erro PERMANENTE (400/401/403/429/...):
+    /// diferente de `pending`, um evento `failed` NÃO entra na fila de
+    /// reenvio — retentar não mudaria o resultado, então deixá-lo
+    /// pendente só o prenderia para sempre numa fila que
+    /// `flush_pending()` nunca conseguiria esvaziar.
+    pub fn failed() -> Self {
+        ImmutableLogReceipt {
+            status: "failed".to_string(),
+            ..Default::default()
+        }
+    }
 }

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/tests/test_flush_pending.py

@@ -14,7 +14,7 @@ def test_flush_pending_on_empty_queue_is_a_no_op(tmp_path, immutablelog_server):
 
     result = audit.flush_pending()
 
-    assert result == {"flushed": 0, "still_pending": 0, "total": 0}
+    assert result == {"flushed": 0, "failed": 0, "still_pending": 0, "total": 0}
 
 
 def test_flush_pending_retries_and_updates_receipt_on_recovery(tmp_path, immutablelog_server):
@@ -32,7 +32,7 @@ def test_flush_pending_retries_and_updates_receipt_on_recovery(tmp_path, immutab
     assert event["immutablelog"]["status"] == "pending"
 
     still_failing = audit.flush_pending()
-    assert still_failing == {"flushed": 0, "still_pending": 1, "total": 1}
+    assert still_failing == {"flushed": 0, "failed": 0, "still_pending": 1, "total": 1}
 
     immutablelog_server.set_default_response(202, {
         "ok": True,
@@ -43,7 +43,7 @@ def test_flush_pending_retries_and_updates_receipt_on_recovery(tmp_path, immutab
         "request_id": "req_flushed",
     })
     recovered = audit.flush_pending()
-    assert recovered == {"flushed": 1, "still_pending": 0, "total": 1}
+    assert recovered == {"flushed": 1, "failed": 0, "still_pending": 0, "total": 1}
 
     pending_path = tmp_path / "audit.pending.jsonl"
     assert pending_path.read_text().strip() == ""
@@ -123,4 +123,37 @@ def test_flush_pending_without_pending_file_is_a_no_op(tmp_path):
 
     result = audit.flush_pending()
 
-    assert result == {"flushed": 0, "still_pending": 0, "total": 0}
+    assert result == {"flushed": 0, "failed": 0, "still_pending": 0, "total": 0}
+
+
+def test_flush_pending_gives_up_on_permanent_error_and_dequeues(tmp_path, immutablelog_server):
+    # Um evento que ficou "pending" por uma falha transitória (500), mas
+    # cuja causa virou PERMANENTE (401) na hora do flush, precisa sair da
+    # fila marcado como "failed" — em vez de ficar preso para sempre (#8).
+    immutablelog_server.set_default_response(500, {"ok": False, "reason": "internal_error"})
+    audit = AuditLogger(
+        app_name="billing-api",
+        file_path=str(tmp_path / "audit.jsonl"),
+        mode="hybrid",
+        immutablelog_url=immutablelog_server.url,
+        immutablelog_api_key="iml_live_ok",
+        retry_enabled=False,
+    )
+
+    event = audit.log(actor_id="user_1", action="DELETE_INVOICE", resource="invoice", resource_id="inv_1")
+    assert event["immutablelog"]["status"] == "pending"
+
+    immutablelog_server.set_default_response(401, {"ok": False, "reason": "invalid_api_key"})
+    result = audit.flush_pending()
+    assert result == {"flushed": 0, "failed": 1, "still_pending": 0, "total": 1}
+
+    # Saiu da fila e ficou marcado como "failed" no arquivo principal.
+    pending_path = tmp_path / "audit.pending.jsonl"
+    assert pending_path.read_text().strip() == ""
+
+    persisted = json.loads((tmp_path / "audit.jsonl").read_text().strip())
+    assert persisted["immutablelog"]["status"] == "failed"
+    assert persisted["hash"] == event["hash"]
+
+    # Uma nova chamada não tem mais nada para tentar.
+    assert audit.flush_pending() == {"flushed": 0, "failed": 0, "still_pending": 0, "total": 0}

{rust_py_audit-0.2.4 → rust_py_audit-0.3.1}/tests/test_immutablelog_hybrid.py

@@ -39,9 +39,10 @@ def test_hybrid_does_not_raise_on_remote_failure(tmp_path, immutablelog_server):
     assert event["immutablelog"]["status"] == "pending"
 
 
-def test_hybrid_failure_keeps_local_event_and_queues_pending_file(tmp_path, immutablelog_server):
-    immutablelog_server.set_default_response(401, {"ok": False, "reason": "invalid_api_key"})
-    audit = _audit_logger(tmp_path, immutablelog_server)
+def test_hybrid_retryable_failure_keeps_local_event_and_queues_pending_file(tmp_path, immutablelog_server):
+    # 500 é RETRYABLE: vira "pending" e entra na fila para reenvio.
+    immutablelog_server.set_default_response(500, {"ok": False, "reason": "internal_error"})
+    audit = _audit_logger(tmp_path, immutablelog_server, retry_enabled=False)
 
     event = audit.log(actor_id="user_1", action="DELETE_INVOICE", resource="invoice", resource_id="inv_1")
 
@@ -58,6 +59,30 @@ def test_hybrid_failure_keeps_local_event_and_queues_pending_file(tmp_path, immu
     assert json.loads(pending_lines[0])["id"] == event["id"]
 
 
+def test_hybrid_permanent_failure_marks_failed_and_does_not_queue(tmp_path, immutablelog_server):
+    # 401 é PERMANENTE (#8): vira "failed" e NÃO entra na fila — retentar
+    # não mudaria o resultado, então não fica preso para sempre.
+    immutablelog_server.set_default_response(401, {"ok": False, "reason": "invalid_api_key"})
+    audit = _audit_logger(tmp_path, immutablelog_server)
+
+    event = audit.log(actor_id="user_1", action="DELETE_INVOICE", resource="invoice", resource_id="inv_1")
+
+    assert event["immutablelog"]["status"] == "failed"
+
+    audit_lines = (tmp_path / "audit.jsonl").read_text().strip().splitlines()
+    assert len(audit_lines) == 1
+    persisted = json.loads(audit_lines[0])
+    assert persisted["hash"] == event["hash"]
+    assert persisted["immutablelog"]["status"] == "failed"
+
+    # Erro permanente não cria/popula a fila de pendências.
+    pending_path = tmp_path / "audit.pending.jsonl"
+    assert not pending_path.exists() or pending_path.read_text().strip() == ""
+
+    # E a cadeia local continua válida (o "failed" é só metadado).
+    assert audit.verify()["valid"] is True
+
+
 def test_hybrid_local_chain_stays_valid_after_failure(tmp_path, immutablelog_server):
     immutablelog_server.set_default_response(500, {"ok": False, "reason": "internal_error"})
     audit = _audit_logger(tmp_path, immutablelog_server, retry_enabled=False)