client-query-cache 0.8.1__tar.gz → 0.9.1__tar.gz

client_query_cache-0.9.1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: client-query-cache
+Version: 0.9.1
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: annotated-types>=0.8.0
+Requires-Dist: pymongo>=4.18.1
+Requires-Dist: opentelemetry-api>=1.45.0 ; extra == 'otel'
+Provides-Extra: otel
+License-File: LICENSE
+Summary: Sync and asyncio PyMongo query caching with change-stream invalidation and Rust-backed sharing across workers.
+Author-email: Alessio Locatelli <<software.development@secure.mailbox.org>>
+License-Expression: Apache-2.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://alessio-locatelli.github.io/client-query-cache/
+Project-URL: Repository, https://github.com/alessio-locatelli/client-query-cache
+
+# Client-side query caching for PyMongo
+
+[![PyPI](https://img.shields.io/pypi/v/client-query-cache?color=lightgrey)](https://pypi.org/project/client-query-cache/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/client-query-cache)](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/alessio-locatelli/client-query-cache/actions/workflows/test.yml)
+[![Typing](https://img.shields.io/pypi/types/client-query-cache)](https://pypi.org/project/client-query-cache/)
+
+**Speed up read-heavy, high-throughput Python applications.** `client-query-cache` serves eligible repeated PyMongo reads from memory, reducing read latency and avoiding MongoDB round trips on cache hits.
+
+Add caching through an explicit [cached collection view](https://alessio-locatelli.github.io/client-query-cache/usage/cached-reads/). Keep your existing MongoDB queries and use PyMongo for writes.
+
+- **[Synchronous](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) and [asyncio](https://alessio-locatelli.github.io/client-query-cache/getting-started/asyncio/) APIs** for long-lived Python applications.
+- **[MongoDB change streams](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/)** invalidate affected results, including writes from other applications.
+- **[Shared caching across application workers](https://alessio-locatelli.github.io/client-query-cache/operations/shared-cache/)** on one [supported Linux host](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements) reduces duplicate cached documents and uses one change stream per active database.
+- **[A Rust-backed shared cache](https://alessio-locatelli.github.io/client-query-cache/benchmarks/shared-cache/)** serves eligible warm reads from native shared memory without a MongoDB round trip.
+
+Choose `CacheManager` for caching within one process, or `SharedCacheManager` to reuse eligible collection reads across trusted same-host workers. Both support sync and asyncio. See [which manager to choose](https://alessio-locatelli.github.io/client-query-cache/getting-started/choose-a-manager/).
+
+With shared caching, workers look up the same cache and use their own PyMongo clients for misses and bypasses:
+
+```mermaid
+flowchart TB
+    subgraph Application["Python application"]
+        Worker1["Python worker 1"] -->|"Cache lookup"| Cache["Rust-backed<br/>shared cache"]
+        Worker2["Python worker 2"] -->|"Cache lookup"| Cache
+    end
+    Worker1 -->|"Miss / bypass"| DB[("MongoDB")]
+    Worker2 -->|"Miss / bypass"| DB
+    DB -.->|"Change streams<br/>Async invalidation"| Cache
+```
+
+[Benchmarks](https://alessio-locatelli.github.io/client-query-cache/benchmarks/shared-cache/) compare direct reads, independent caches and shared caching. Sharing avoids duplicated values and streams, but its owner process and cache misses have costs. Rust does not guarantee a faster application or lower total memory for every workload.
+
+![Illustrative process-local read latency on a logarithmic scale: direct local MongoDB read, about 120 microseconds; direct Atlas M0 read, 79.4 milliseconds; cached reads in either deployment, about 61 microseconds.](docs/user/assets/benchmark-latency-light.svg)
+
+The graphic shows [process-local measurements from local MongoDB and Atlas deployments](https://alessio-locatelli.github.io/client-query-cache/benchmarks/#illustrative-read-latency); it is separate from the shared-cache comparison above.
+
+## Quick start
+
+```bash
+uv add client-query-cache
+```
+
+Or use `pip install client-query-cache`.
+
+Start a MongoDB server before running this example. For local development, follow the [single-member replica-set setup](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#local-mongodb).
+
+```python
+from pymongo import MongoClient
+
+from client_query_cache import CacheManager
+
+with (
+    MongoClient("mongodb://localhost:27017") as client,
+    CacheManager(client) as cache_manager,
+):
+    collection = client["client_query_cache_tutorial"]["items"]
+    cached_collection = cache_manager.get_cached_collection(collection)
+    collection.replace_one(
+        {"_id": "example"}, {"_id": "example", "value": 42}, upsert=True
+    )
+    cached_collection.find_one({"_id": "example"})
+    cached_collection.find_one({"_id": "example"})  # Repeated reads can hit the cache.
+```
+
+Check the [platform and MongoDB requirements](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements) before installing. [Read eligibility](https://alessio-locatelli.github.io/client-query-cache/reference/api/#bypass-conditions) determines which requests can use the cache.
+
+Invalidation is asynchronous: cached reads can briefly return a preceding value after a write. Use direct PyMongo reads with suitable consistency controls for read-after-write and current authorization; see [consistency](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/).
+
+## Run an application
+
+Start with the [synchronous](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) or [asyncio](https://alessio-locatelli.github.io/client-query-cache/getting-started/asyncio/) tutorial. The [shared FastAPI example](https://alessio-locatelli.github.io/client-query-cache/examples/fastapi-shared/) runs real Granian workers and verifies cross-process hits, invalidation and graceful shutdown. The [compact FastAPI example](https://alessio-locatelli.github.io/client-query-cache/examples/fastapi-minimal/) demonstrates process-local caching.
+
+[Deployment](https://alessio-locatelli.github.io/client-query-cache/operations/) · [API reference](https://alessio-locatelli.github.io/client-query-cache/reference/api/) · [Examples](https://alessio-locatelli.github.io/client-query-cache/examples/)
+
+The library is tested against real MongoDB replica sets, including [concurrency stress tests](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/concurrency-stress-tests.md). Separate checks guard against [performance](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/performance-regression-guard.md) and [memory](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/memory-regression-tests.md) regressions.
+
+---
+
+> MongoDB is a registered trademark of MongoDB, Inc. This project is independent and is not affiliated with or endorsed by MongoDB, Inc.
+

client_query_cache-0.9.1/README.md

@@ -0,0 +1,80 @@
+# Client-side query caching for PyMongo
+
+[![PyPI](https://img.shields.io/pypi/v/client-query-cache?color=lightgrey)](https://pypi.org/project/client-query-cache/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/client-query-cache)](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/alessio-locatelli/client-query-cache/actions/workflows/test.yml)
+[![Typing](https://img.shields.io/pypi/types/client-query-cache)](https://pypi.org/project/client-query-cache/)
+
+**Speed up read-heavy, high-throughput Python applications.** `client-query-cache` serves eligible repeated PyMongo reads from memory, reducing read latency and avoiding MongoDB round trips on cache hits.
+
+Add caching through an explicit [cached collection view](https://alessio-locatelli.github.io/client-query-cache/usage/cached-reads/). Keep your existing MongoDB queries and use PyMongo for writes.
+
+- **[Synchronous](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) and [asyncio](https://alessio-locatelli.github.io/client-query-cache/getting-started/asyncio/) APIs** for long-lived Python applications.
+- **[MongoDB change streams](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/)** invalidate affected results, including writes from other applications.
+- **[Shared caching across application workers](https://alessio-locatelli.github.io/client-query-cache/operations/shared-cache/)** on one [supported Linux host](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements) reduces duplicate cached documents and uses one change stream per active database.
+- **[A Rust-backed shared cache](https://alessio-locatelli.github.io/client-query-cache/benchmarks/shared-cache/)** serves eligible warm reads from native shared memory without a MongoDB round trip.
+
+Choose `CacheManager` for caching within one process, or `SharedCacheManager` to reuse eligible collection reads across trusted same-host workers. Both support sync and asyncio. See [which manager to choose](https://alessio-locatelli.github.io/client-query-cache/getting-started/choose-a-manager/).
+
+With shared caching, workers look up the same cache and use their own PyMongo clients for misses and bypasses:
+
+```mermaid
+flowchart TB
+    subgraph Application["Python application"]
+        Worker1["Python worker 1"] -->|"Cache lookup"| Cache["Rust-backed<br/>shared cache"]
+        Worker2["Python worker 2"] -->|"Cache lookup"| Cache
+    end
+    Worker1 -->|"Miss / bypass"| DB[("MongoDB")]
+    Worker2 -->|"Miss / bypass"| DB
+    DB -.->|"Change streams<br/>Async invalidation"| Cache
+```
+
+[Benchmarks](https://alessio-locatelli.github.io/client-query-cache/benchmarks/shared-cache/) compare direct reads, independent caches and shared caching. Sharing avoids duplicated values and streams, but its owner process and cache misses have costs. Rust does not guarantee a faster application or lower total memory for every workload.
+
+![Illustrative process-local read latency on a logarithmic scale: direct local MongoDB read, about 120 microseconds; direct Atlas M0 read, 79.4 milliseconds; cached reads in either deployment, about 61 microseconds.](docs/user/assets/benchmark-latency-light.svg)
+
+The graphic shows [process-local measurements from local MongoDB and Atlas deployments](https://alessio-locatelli.github.io/client-query-cache/benchmarks/#illustrative-read-latency); it is separate from the shared-cache comparison above.
+
+## Quick start
+
+```bash
+uv add client-query-cache
+```
+
+Or use `pip install client-query-cache`.
+
+Start a MongoDB server before running this example. For local development, follow the [single-member replica-set setup](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#local-mongodb).
+
+```python
+from pymongo import MongoClient
+
+from client_query_cache import CacheManager
+
+with (
+    MongoClient("mongodb://localhost:27017") as client,
+    CacheManager(client) as cache_manager,
+):
+    collection = client["client_query_cache_tutorial"]["items"]
+    cached_collection = cache_manager.get_cached_collection(collection)
+    collection.replace_one(
+        {"_id": "example"}, {"_id": "example", "value": 42}, upsert=True
+    )
+    cached_collection.find_one({"_id": "example"})
+    cached_collection.find_one({"_id": "example"})  # Repeated reads can hit the cache.
+```
+
+Check the [platform and MongoDB requirements](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements) before installing. [Read eligibility](https://alessio-locatelli.github.io/client-query-cache/reference/api/#bypass-conditions) determines which requests can use the cache.
+
+Invalidation is asynchronous: cached reads can briefly return a preceding value after a write. Use direct PyMongo reads with suitable consistency controls for read-after-write and current authorization; see [consistency](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/).
+
+## Run an application
+
+Start with the [synchronous](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) or [asyncio](https://alessio-locatelli.github.io/client-query-cache/getting-started/asyncio/) tutorial. The [shared FastAPI example](https://alessio-locatelli.github.io/client-query-cache/examples/fastapi-shared/) runs real Granian workers and verifies cross-process hits, invalidation and graceful shutdown. The [compact FastAPI example](https://alessio-locatelli.github.io/client-query-cache/examples/fastapi-minimal/) demonstrates process-local caching.
+
+[Deployment](https://alessio-locatelli.github.io/client-query-cache/operations/) · [API reference](https://alessio-locatelli.github.io/client-query-cache/reference/api/) · [Examples](https://alessio-locatelli.github.io/client-query-cache/examples/)
+
+The library is tested against real MongoDB replica sets, including [concurrency stress tests](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/concurrency-stress-tests.md). Separate checks guard against [performance](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/performance-regression-guard.md) and [memory](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/memory-regression-tests.md) regressions.
+
+---
+
+> MongoDB is a registered trademark of MongoDB, Inc. This project is independent and is not affiliated with or endorsed by MongoDB, Inc.

{client_query_cache-0.8.1 → client_query_cache-0.9.1}/native/shared-index/Cargo.lock

@@ -147,9 +147,9 @@ dependencies = [
 
 [[package]]
 name = "pyo3"
-version = "0.29.3"
+version = "0.30.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
+checksum = "229ca13b8a15bb0d1487b81ab975bfcd97513416499a8312011b6036e42e0de4"
 dependencies = [
  "libc",
  "once_cell",
@@ -161,18 +161,18 @@ dependencies = [
 
 [[package]]
 name = "pyo3-build-config"
-version = "0.29.3"
+version = "0.30.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
+checksum = "70130e2b6dd1ee589a8788026a429561ca5c40fa7a2fa7914c2282eddae24700"
 dependencies = [
  "target-lexicon",
 ]
 
 [[package]]
 name = "pyo3-ffi"
-version = "0.29.3"
+version = "0.30.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
+checksum = "5e7ff73c555c286d212d4ce7e5fbda845a973c4f61bd5f160f5f2c3c2a04d1c4"
 dependencies = [
  "libc",
  "pyo3-build-config",
@@ -180,9 +180,9 @@ dependencies = [
 
 [[package]]
 name = "pyo3-macros"
-version = "0.29.3"
+version = "0.30.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
+checksum = "c46d2e5862c7bb8207e3b639f713dda3c499933444784154c11d013c5a691b60"
 dependencies = [
  "proc-macro2",
  "pyo3-macros-backend",
@@ -192,9 +192,9 @@ dependencies = [
 
 [[package]]
 name = "pyo3-macros-backend"
-version = "0.29.3"
+version = "0.30.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
+checksum = "38b89f066f2ae72a2aef52d1537ca2fcd104440ebfadee06e97aa90738a25b9b"
 dependencies = [
  "heck",
  "proc-macro2",
@@ -263,9 +263,9 @@ checksum = "5b3dc8af474f516a851ff4bd12db780f948b9250ad37211e4eec0bccea54e01b"
 
 [[package]]
 name = "syn"
-version = "2.0.119"
+version = "3.0.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
 dependencies = [
  "proc-macro2",
  "quote",

{client_query_cache-0.8.1 → client_query_cache-0.9.1}/native/shared-index/Cargo.toml

@@ -20,7 +20,7 @@ python = ["dep:pyo3"]
 
 [dependencies]
 libc = "0.2.190"
-pyo3 = { version = "0.29.3", features = ["abi3-py314"], optional = true }
+pyo3 = { version = "0.30.1", features = ["abi3-py314"], optional = true }
 
 [target.'cfg(loom)'.dependencies]
 loom = "0.7.2"

client_query_cache-0.9.1/native/shared-index/deny.toml

@@ -0,0 +1,16 @@
+# cargo-deny 0.19.9: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html
+# The default license allowlist is empty. We override it because these permissive
+# licenses cover the resolved native dependency graph and permit distribution.
+[licenses]
+allow = ["Apache-2.0", "Apache-2.0 WITH LLVM-exception", "MIT", "Unicode-3.0"]
+
+[bans]
+# The default is warn. We override it because duplicate versions must be resolved.
+multiple-versions = "deny"
+# The default is allow. We override it because unbounded dependencies hinder review.
+wildcards = "deny"
+
+[sources]
+# Both defaults are warn. We override them because only crates.io is approved.
+unknown-registry = "deny"
+unknown-git = "deny"

client_query_cache-0.9.1/native/shared-index/src/echo/tests.rs

@@ -0,0 +1,303 @@
+use std::sync::Arc;
+
+use super::*;
+use crate::index::{Layout, Writer};
+use crate::memory::zeroed;
+use crate::sync::AtomicU64;
+
+const EPOCH: u64 = 3;
+
+fn published() -> Index<Arc<[AtomicU64]>> {
+    let layout = Layout::new(8, 64, 1, 1).unwrap();
+    let index = Index::create(zeroed(layout.words()), layout, 5, u64::MAX).unwrap();
+    assert!(index.set_available(0, true) && index.set_progress(0, 1) && index.set_epoch(0, EPOCH));
+    let query = Query {
+        database: 0,
+        namespace: 0,
+        epoch: EPOCH,
+        identity: b"present",
+        shape: b"shape",
+    };
+    let mut writer = Writer::new(index.clone());
+    let payload = writer.store(b"payload").unwrap();
+    writer.publish(&query, payload).unwrap();
+    index
+}
+
+fn selection(identity: &[u8]) -> Vec<u8> {
+    let mut bytes = Vec::new();
+    bytes.extend_from_slice(&0_u32.to_le_bytes());
+    bytes.extend_from_slice(&0_u32.to_le_bytes());
+    bytes.extend_from_slice(&EPOCH.to_le_bytes());
+    bytes.extend_from_slice(&(identity.len() as u32).to_le_bytes());
+    bytes.extend_from_slice(&5_u32.to_le_bytes());
+    bytes.extend_from_slice(identity);
+    bytes.extend_from_slice(b"shape");
+    bytes
+}
+
+fn request(request_id: u32, identities: &[&[u8]]) -> Vec<u8> {
+    let mut body = Vec::new();
+    body.extend_from_slice(&request_id.to_le_bytes());
+    body.extend_from_slice(&(identities.len() as u32).to_le_bytes());
+    for identity in identities {
+        body.extend_from_slice(&selection(identity));
+    }
+    let mut frame = (body.len() as u32).to_le_bytes().to_vec();
+    frame.extend_from_slice(&body);
+    frame
+}
+
+fn expected_reply(request_id: u32) -> Vec<u8> {
+    let mut body = Vec::new();
+    body.extend_from_slice(&request_id.to_le_bytes());
+    body.extend_from_slice(&2_u32.to_le_bytes());
+    body.extend_from_slice(&7_u32.to_le_bytes());
+    body.extend_from_slice(b"payload");
+    body.extend_from_slice(&MISS.to_le_bytes());
+    let mut frame = (body.len() as u32).to_le_bytes().to_vec();
+    frame.extend_from_slice(&body);
+    frame
+}
+
+#[test]
+fn answers_each_selection_in_order() {
+    let index = published();
+    let mut out = Vec::new();
+    let frame = request(9, &[b"present", b"absent"]);
+    answer_frame(&index, 5, &frame[LENGTH_BYTES..], 1, &mut out).unwrap();
+    assert_eq!(out, expected_reply(9));
+}
+
+#[test]
+fn rejects_malformed_frames() {
+    let index = published();
+    let frame = request(9, &[b"present"]);
+    let body = &frame[LENGTH_BYTES..];
+    let mut overstated = body.to_vec();
+    overstated[4] = 2;
+    let mut trailing = body.to_vec();
+    trailing.push(0);
+    for malformed in [
+        &body[..body.len() - 1],
+        &body[..6],
+        &overstated[..],
+        &trailing[..],
+    ] {
+        assert!(answer_frame(&index, 5, malformed, 1, &mut Vec::new()).is_err());
+    }
+}
+
+fn connection() -> (Connection, UnixStream) {
+    let (stream, peer) = UnixStream::pair().unwrap();
+    stream.set_nonblocking(true).unwrap();
+    let connection = Connection {
+        stream,
+        inbox: Vec::new(),
+        outbox: Vec::new(),
+        sent: 0,
+        writable: false,
+    };
+    (connection, peer)
+}
+
+#[test]
+fn rejects_more_selections_than_one_frame_may_carry() {
+    let index = published();
+    let identities = vec![&b"present"[..]; SELECTION_LIMIT as usize + 1];
+    let frame = request(9, &identities);
+    assert!(answer_frame(&index, 5, &frame[LENGTH_BYTES..], 1, &mut Vec::new()).is_err());
+    let frame = request(9, &identities[1..]);
+    assert!(answer_frame(&index, 5, &frame[LENGTH_BYTES..], 1, &mut Vec::new()).is_ok());
+}
+
+#[test]
+fn rejects_replies_larger_than_a_frame() {
+    let payload = vec![7_u8; REPLY_LIMIT / 9];
+    let layout = Layout::new(8, payload.len(), 1, 1).unwrap();
+    let index = Index::create(zeroed(layout.words()), layout, 5, u64::MAX).unwrap();
+    assert!(index.set_available(0, true) && index.set_progress(0, 1) && index.set_epoch(0, EPOCH));
+    let mut writer = Writer::new(index.clone());
+    let stored = writer.store(&payload).unwrap();
+    let query = Query {
+        database: 0,
+        namespace: 0,
+        epoch: EPOCH,
+        identity: b"present",
+        shape: b"shape",
+    };
+    writer.publish(&query, stored).unwrap();
+    let fits = request(9, &[&b"present"[..]; 8]);
+    assert!(answer_frame(&index, 5, &fits[LENGTH_BYTES..], 1, &mut Vec::new()).is_ok());
+    let oversized = request(9, &[&b"present"[..]; 9]);
+    assert!(answer_frame(&index, 5, &oversized[LENGTH_BYTES..], 1, &mut Vec::new()).is_err());
+}
+
+#[test]
+fn closes_a_connection_whose_replies_are_not_read() {
+    let index = published();
+    let (mut connection, _peer) = connection();
+    connection.outbox = vec![0; QUEUE_LIMIT];
+    connection.inbox = request(9, &[b"present"]);
+    assert!(connection.answer(&index, 5).is_err());
+    connection
+        .outbox
+        .truncate(QUEUE_LIMIT - expected_reply(9).len());
+    connection.inbox = request(9, &[b"present", b"absent"]);
+    assert!(connection.answer(&index, 5).is_ok());
+}
+
+#[test]
+fn buffers_at_most_one_frame_of_unanswered_input() {
+    let (mut connection, mut peer) = connection();
+    let writer = std::thread::spawn(move || {
+        let _ = peer.write_all(&vec![0xff; 2 * INBOX_LIMIT]);
+    });
+    let mut scratch = vec![0_u8; RECEIVE_BYTES];
+    while connection.inbox.len() < INBOX_LIMIT {
+        assert!(connection.receive(&mut scratch));
+    }
+    assert!(connection.receive(&mut scratch));
+    assert_eq!(connection.inbox.len(), INBOX_LIMIT);
+    drop(connection);
+    writer.join().unwrap();
+}
+
+struct EchoSocket {
+    echo: Echo,
+    directory: std::path::PathBuf,
+}
+
+impl Drop for EchoSocket {
+    fn drop(&mut self) {
+        self.echo.stop();
+        std::fs::remove_dir_all(&self.directory).unwrap();
+    }
+}
+
+fn echo_socket() -> (EchoSocket, UnixStream) {
+    let directory = std::env::temp_dir().join("agents").join(format!(
+        "shared-index-echo-{}-{}",
+        std::process::id(),
+        monotonic_ns()
+    ));
+    std::fs::create_dir_all(&directory).unwrap();
+    let path = directory.join("echo.sock");
+    let echo = Echo::start(published(), UnixListener::bind(&path).unwrap()).unwrap();
+    let client = UnixStream::connect(&path).unwrap();
+    (EchoSocket { echo, directory }, client)
+}
+
+#[test]
+fn serves_frames_split_across_reads_over_a_socket() {
+    let (_server, mut client) = echo_socket();
+    let mut frames = request(1, &[b"present", b"absent"]);
+    frames.extend_from_slice(&request(2, &[b"present", b"absent"]));
+    let (first, second) = frames.split_at(10);
+    client.write_all(first).unwrap();
+    std::thread::sleep(std::time::Duration::from_millis(20));
+    client.write_all(second).unwrap();
+    let mut expected = expected_reply(1);
+    expected.extend_from_slice(&expected_reply(2));
+    let mut reply = vec![0; expected.len()];
+    client.read_exact(&mut reply).unwrap();
+    assert_eq!(reply, expected);
+}
+
+#[test]
+fn backpressure_preserves_unsent_reply_bytes() {
+    let (mut connection, mut peer) = connection();
+    let poller = Poller::new().unwrap();
+    poller
+        .control(
+            libc::EPOLL_CTL_ADD,
+            connection.stream.as_raw_fd(),
+            FIRST_CONNECTION,
+            libc::EPOLLIN,
+        )
+        .unwrap();
+    let expected = vec![b'r'; 2 * FRAME_LIMIT];
+    connection.outbox.clone_from(&expected);
+    let mut received = Vec::new();
+    assert!(connection.flush(&poller, FIRST_CONNECTION));
+    assert!(connection.writable);
+    assert!(connection.sent > 0 && connection.sent < expected.len());
+    while !connection.outbox.is_empty() {
+        let sent = connection.sent;
+        let start = received.len();
+        received.resize(sent, 0);
+        peer.read_exact(&mut received[start..]).unwrap();
+        assert!(connection.flush(&poller, FIRST_CONNECTION));
+    }
+    let start = received.len();
+    received.resize(expected.len(), 0);
+    peer.read_exact(&mut received[start..]).unwrap();
+    assert_eq!(received, expected);
+    assert!(!connection.writable);
+    assert_eq!(connection.sent, 0);
+}
+
+#[test]
+fn closed_peer_rejects_pending_replies() {
+    let (mut connection, peer) = connection();
+    drop(peer);
+    connection.outbox.extend_from_slice(b"reply");
+    assert!(!connection.flush(&Poller::new().unwrap(), FIRST_CONNECTION));
+}
+
+#[test]
+fn peer_reset_closes_the_connection() {
+    let (mut connection, peer) = connection();
+    connection.stream.write_all(b"unread reply").unwrap();
+    drop(peer);
+    assert!(!connection.receive(&mut [0; 64]));
+}
+
+struct IgnoredUserSignal(libc::sigaction);
+
+extern "C" fn ignore_user_signal(_signal: libc::c_int) {}
+
+impl IgnoredUserSignal {
+    fn install() -> Self {
+        let mut action = unsafe { std::mem::zeroed::<libc::sigaction>() };
+        action.sa_sigaction = ignore_user_signal as *const () as usize;
+        assert_eq!(unsafe { libc::sigemptyset(&raw mut action.sa_mask) }, 0);
+        let mut previous = unsafe { std::mem::zeroed::<libc::sigaction>() };
+        assert_eq!(
+            unsafe { libc::sigaction(libc::SIGUSR1, &raw const action, &raw mut previous) },
+            0
+        );
+        Self(previous)
+    }
+}
+
+impl Drop for IgnoredUserSignal {
+    fn drop(&mut self) {
+        assert_eq!(
+            unsafe { libc::sigaction(libc::SIGUSR1, &raw const self.0, std::ptr::null_mut()) },
+            0
+        );
+    }
+}
+
+#[test]
+fn signals_do_not_stop_the_echo_server() {
+    use std::os::unix::thread::JoinHandleExt;
+    use std::time::Duration;
+
+    let _handler = IgnoredUserSignal::install();
+    let (server, mut client) = echo_socket();
+    client
+        .set_read_timeout(Some(Duration::from_secs(3)))
+        .unwrap();
+    let thread = server.echo.thread.as_ref().unwrap().as_pthread_t();
+    for request_id in 0..8 {
+        std::thread::sleep(Duration::from_millis(1));
+        assert_eq!(unsafe { libc::pthread_kill(thread, libc::SIGUSR1) }, 0);
+        let frame = request(request_id, &[]);
+        client.write_all(&frame).unwrap();
+        let mut reply = vec![0; frame.len()];
+        client.read_exact(&mut reply).unwrap();
+        assert_eq!(reply, frame);
+    }
+}