1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
// SPDX-FileCopyrightText: Copyright (C) 2026 David Stainton
// SPDX-License-Identifier: AGPL-3.0-only
//! High-level Pigeonhole API with database persistence.
//!
//! This module provides a simplified API for the Pigeonhole protocol,
//! automatically managing state (capabilities, indices) via SQLite.
//!
//! # Overview
//!
//! The low-level pigeonhole API in [`crate::pigeonhole`] requires manual
//! management of write/read capabilities and message box indices. This
//! module wraps that API with automatic state persistence, making it
//! much easier to build applications.
//!
//! # Features
//!
//! - **Automatic index management**: Write and read indices are automatically
//! persisted and incremented after each operation.
//! - **Channel persistence**: Channels (with their capabilities) are stored in
//! SQLite and can be recovered after application restart.
//! - **Tombstone support**: Delete messages by overwriting them with zeros.
//! - **Copy command support**: Send large payloads that span multiple boxes
//! using the Copy command with automatic chunking.
//! - **Message history**: Received messages are stored for later retrieval.
//!
//! # Example
//!
//! ```rust,ignore
//! use katzenpost_thin_client::persistent::{PigeonholeClient, Database};
//!
//! // Open database and create client
//! let db = Database::open("pigeonhole.db")?;
//! let pigeonhole = PigeonholeClient::new(thin_client, db);
//!
//! // Generate a fresh capability pair via the thin client
//! let mut seed = [0u8; 32];
//! rand::thread_rng().fill_bytes(&mut seed);
//! let kp = thin_client.new_keypair(&seed).await?;
//!
//! // Sender loads a write channel
//! let mut writer = pigeonhole
//! .load_write_channel("alice-to-bob", &kp.write_cap, &kp.first_message_index)?;
//! writer.send(b"Hello, world!").await?;
//!
//! // Receiver (possibly on another machine, with their own PigeonholeClient)
//! let mut reader = pigeonhole
//! .load_read_channel("from-alice", &kp.read_cap, &kp.first_message_index)?;
//! let message = reader.receive().await?;
//! ```
//!
//! # Plaintext Size Constraints
//!
//! Single messages sent via [`WriteChannel::send`] must not exceed
//! `PigeonholeGeometry.max_plaintext_payload_length` bytes.
//!
//! # Database Schema
//!
//! The module creates four tables:
//! - `write_channels`: write capabilities and write-side `next_index`
//! - `read_channels`: read capabilities and read-side `next_index`
//! - `pending_messages`: messages waiting to be sent or acknowledged
//! - `received_messages`: messages received from read channels
pub use ;
pub use Database;
pub use ;
pub use ;