tachyon_i2p/

lib.rs

//! Safe async wrapper around `i2pd-sys`: a [`Destination`] (an I2P eepsite identity, reachable at
//! a `.b32.i2p` address) and an [`I2pStream`] implementing
//! [`AsyncRead`](tokio::io::AsyncRead)/[`AsyncWrite`](tokio::io::AsyncWrite), with no external
//! `i2pd` process or SAM bridge.
//!
//! Every `unsafe` call into libi2pd's C shim lives in this crate; the public API exposes no raw
//! pointers and no `pub unsafe fn`. That safety rests on this crate's reading of libi2pd's
//! threading and ownership contracts, documented at each `unsafe` block and in
//! `i2pd-sys/shim/shim.h`, not on anything the compiler checks.
//!
//! # Features
//!
//! `aws-lc` (default) and `fips` pick the `i2pd-sys` crypto backend; at least one must be
//! enabled, and `fips` wins if both are (Cargo features are additive, so a dependent crate can
//! pull `aws-lc` back in). `transit` (default) compiles in libi2pd's tunnel build-request path.
//!
//! # Basic usage
//!
//! ```rust,no_run
//! # async fn example() -> Result<(), tachyon_i2p::I2pError> {
//! use tachyon_i2p::{I2pRouter, SigType};
//!
//! let router = I2pRouter::start("my-eepsite").await?;
//! let mut dest = router
//!     // Empty slice: libi2pd's own hybrid encryption set. See `CryptoType` to narrow it down.
//!     .destination_from_keys_file("my-eepsite.keys", true, SigType::default(), &[])
//!     .await?;
//! println!("reachable at http://{}", dest.b32_address());
//!
//! loop {
//!     let _stream = dest.accept().await?; // implements AsyncRead + AsyncWrite
//!     // ... spawn a task to serve it ...
//! }
//! # }
//! ```
//!
//! Only one [`I2pRouter`] may run per process at a time: libi2pd keeps its router context as a
//! process-wide global. Starting a new one after the previous router has been dropped works.
//!
//! # Network participation
//!
//! This crate runs a real I2P router, so it has a position in the network beyond hosting your own
//! destinations. By default it carries transit tunnels (other users' traffic) at up to 256 KB/s
//! router-wide, and does not act as a floodfill. Transit defaults to on because a router that
//! relays nothing gives an observer no cover traffic: every byte crossing the link is then yours.
//! [`RouterConfig`] is the only way to change any of it -- libi2pd reads these settings as the
//! router comes up, and never parses an `i2pd.conf` when embedded as a library.

#[cfg(not(any(feature = "aws-lc", feature = "fips")))]
compile_error!(
    "no crypto backend selected -- enable exactly one of the `aws-lc` (default) or `fips` \
     features."
);

/// Compiles the `README.md` usage example as a doctest so it can't drift from the real API.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeExample;

mod destination;
mod error;
mod router;
mod stream;

pub use destination::Destination;
pub use error::I2pError;
pub use router::{CryptoType, I2pRouter, RouterConfig, SigType};
pub use stream::I2pStream;