Skip to main content

psicose/
lib.rs

1//! # PSICOSE-1B
2//!
3//! A `no_std`, heapless **framework** for reliable byte links: wire protocol,
4//! pump, windowing, and **P2P sessions**. You compose the layers; nothing
5//! allocates. **Zero crate dependencies** — `use psicose::…` is only PSICOSE.
6//!
7//! P2P is **not** a separate crate. [`Node`], [`PeerId`], [`PeerTable`],
8//! [`PeerLink`], hello negotiation, and fragmentation live in this package
9//! on top of the same 4-byte frame. Examples call into this motor — they
10//! do not invent an external P2P and pass connections in.
11//!
12//! ## Framework layers
13//!
14//! ```text
15//! exemplos / application / boards/*
16//!        │
17//!        ▼
18//! psicose::Node                         ← motor entry
19//!        ├─ PeerLink / PeerTable / hello
20//!        ├─ Fragmenter / Defragmenter
21//!        ▼
22//! LinkFace / Wire::copy / Pump / WindowedPump
23//!        │  DATA 1 byte/frame + CRC-8 + ACK
24//!        ▼
25//! ByteTransport  (you implement on UART, or Wire harness)
26//! ```
27//!
28//! | Layer | Entry points |
29//! | --- | --- |
30//! | Wire frame / CRC / SEQ | [`Frame`], [`crc8`] |
31//! | Stop-and-wait / window | [`Pump`], [`WindowedPump`], [`Wire::copy`] |
32//! | Hardware demux | [`LinkFace`] |
33//! | P2P session + peers | [`Node`], [`PeerLink`], [`establish`] |
34//!
35//! ## Non-negotiable properties
36//!
37//! - **`#![no_std]`, `#![forbid(unsafe_code)]`, zero dependencies.**
38//!   No heap, no `Vec`, no third-party crates in the dependency graph.
39//! - **Constant memory regardless of transfer size.**
40//! - **The wire frame is fixed at [`protocol::FRAME_LEN`] = 4 bytes:**
41//!   `TYPE(1) | SEQ(1) | DATA(1) | CRC(1)`.
42//! - **Reliability is the protocol's job.** ACK, NACK, SEQ, CRC-8, retry.
43//!
44//! Start with [`prelude`]. Map: `docs/API.md`. Hardware: `docs/HARDWARE.md`.
45//! Spec: `docs/PROTOCOL.md`.
46//!
47//! ## What you import (`use psicose::…`)
48//!
49//! Prefer [`prelude`]. Everything below is a **psicose** type — no foreign
50//! crates appear in the public API.
51//!
52//! | Reach for | When |
53//! | --- | --- |
54//! | [`Node`] | P2P entry — identity, neighbors, `connect` / `accept` |
55//! | [`LinkFace`] | Hardware demux: one UART → Pump TX/RX ends |
56//! | [`Wire`] | In-memory A↔B harness (tests). Not the 4-byte frame. |
57//! | [`Wire::copy`] | Stop-and-wait copy through the motor |
58//! | [`establish`] / [`send_message`] | Cooperative P2P helpers |
59//! | [`PeerLink`] | Live link (prefer [`Node`]) |
60//! | [`SessionConfig`] | Hello offer — `DEFAULT`, `FORUM`, `SECURE` |
61//! | [`Pump`] / [`WindowedPump`] | Reliability over your [`ByteTransport`] |
62//! | [`Frame`] / [`crc8`] | Speak the 4-byte envelope yourself |
63//! | [`SliceSource`] / [`SliceSink`] | `&[u8]` / `&mut [u8]` as byte ends |
64//! | [`ByteTransport`] | **You** implement this for UART/SPI/radio |
65//!
66//! ## Minimal P2P example
67//!
68//! ```
69//! use psicose::prelude::*;
70//!
71//! let wire = Wire::new();
72//! let (pump_a, pump_b) = wire.link_pumps();
73//!
74//! let mut alice = Node::<4>::new(PeerId::from_label(b"alice"));
75//! let mut bob = Node::<4>::new(PeerId::from_label(b"bob"));
76//!
77//! let mut a = match alice.connect(pump_a) {
78//!     Ok(link) => link,
79//!     Err(_) => return,
80//! };
81//! let mut b = bob.accept(pump_b);
82//!
83//! assert!(establish(&mut a, &mut alice, &mut b, &mut bob));
84//! assert_eq!(alice.established(), 1);
85//! assert_eq!(bob.established(), 1);
86//! ```
87//!
88//! ## Threat model (short)
89//!
90//! CRC-8 detects accidental corruption. It does **not** authenticate.
91//! Confidentiality/authenticity are **outside** this crate — seal messages
92//! in your application before they enter the transport if needed.
93#![no_std]
94#![forbid(unsafe_code)]
95#![cfg_attr(docsrs, feature(doc_cfg))]
96#![warn(missing_docs)]
97
98pub mod actors;
99pub mod error;
100pub mod fault;
101pub mod p2p;
102pub mod prelude;
103pub mod protocol;
104pub mod pump;
105pub mod rx;
106pub mod stream;
107pub mod timeout;
108pub mod transport;
109pub mod tx;
110pub mod window;
111
112#[doc(inline)]
113pub use error::Error;
114#[doc(inline)]
115pub use p2p::{
116    establish, send_message, Capabilities, DefragError, Defragmenter, DuplexFull, DuplexPort,
117    DuplexWire, Fragmenter, HandshakeError, HeaderError, LinkError, LinkEvent, MessageHeader,
118    MessageId, Node, PeerEntry, PeerId, PeerLink, PeerSession, PeerTable, SessionConfig,
119    SessionState, StreamId, TableError, Wire, WireCopyError, HEADER_LEN, HELLO_LEN, MAX_PEERS,
120    PROTOCOL_VERSION,
121};
122#[doc(inline)]
123pub use protocol::{
124    crc8, Frame, FrameAssembler, FrameError, FrameType, Sequence, CRC8_POLY, FRAME_LEN, PAYLOAD_LEN,
125};
126#[doc(inline)]
127pub use pump::{Pump, PumpEvent, SessionStats, WindowedPump};
128#[doc(inline)]
129pub use rx::{PollOutcome, Receiver, RxState};
130#[doc(inline)]
131pub use stream::{
132    recv_all, recv_all_budgeted, recv_all_windowed, recv_all_windowed_budgeted, recv_bytes,
133    send_all, send_all_windowed, send_all_windowed_budgeted, send_bytes, SliceFull, SliceSink,
134    SliceSource, StreamError,
135};
136#[doc(inline)]
137pub use timeout::{IdleBudget, RetryPolicy};
138#[doc(inline)]
139pub use transport::{
140    ByteSink, ByteSource, ByteTransport, FaceError, FaceRx, FaceTx, HalfDuplex, LineDirection,
141    LinkFace, NopDirection, PageEvent, PageLink, Turn, TurnEvent, WindowTurn,
142};
143#[doc(inline)]
144pub use tx::{Sender, TxPoll, TxState};
145#[doc(inline)]
146pub use window::{W8Receiver, W8Sender, WindowedReceiver, WindowedSender, MAX_WINDOW};
147
148#[cfg(test)]
149mod test_support;