Skip to main content

iroh_http_core/
lib.rs

1//! `iroh-http-core` — Iroh QUIC endpoint, HTTP/1.1 via hyper, fetch and serve.
2//!
3//! This crate owns the Iroh endpoint and wires HTTP/1.1 framing to QUIC
4//! streams via hyper.  Nothing in here knows about JavaScript.
5//!
6//! Per epic #182 the crate is split into two top-level modules with a
7//! one-way dependency:
8//!
9//! - [`http`] — pure-Rust HTTP-over-iroh primitives. No `u64` handles,
10//!   no callbacks. A pure-Rust application can call [`http::client::fetch_request`]
11//!   and [`http::server::serve`] without touching any FFI type.
12//! - [`ffi`] — FFI bridge: handle store, callback-shaped serve, flat
13//!   fetch. Wraps [`http`]; never imported in the reverse direction
14//!   (enforced by `tests/architecture.rs`).
15#![deny(unsafe_code)]
16
17pub mod endpoint;
18
19pub(crate) mod ffi;
20pub(crate) mod http;
21
22// Cross-cutting utility modules (extracted from lib.rs, see #198).
23mod addr;
24mod crypto;
25mod encoding;
26mod error;
27
28// Thin re-export modules preserving external API paths.
29pub mod events {
30    pub use crate::http::events::*;
31}
32pub mod registry {
33    pub use crate::ffi::registry::*;
34}
35
36// ── Pure-Rust HTTP API surface (`mod http`) ───────────────────────────────────
37pub use http::body::{Body, BoxError};
38pub use http::client::{fetch_request, FetchError};
39pub use http::server::{
40    serve, serve_connection, serve_with_events, ConnectionServeEnd, ConnectionServeError,
41    ConnectionServeOptions, ConnectionServeResult, ConnectionServeRuntime, RemoteEndpointId,
42    RemoteNodeId, ServeHandle, ServeOptions, DEFAULT_MAX_REQUEST_BODY_BYTES,
43    DEFAULT_MAX_RESPONSE_BODY_BYTES,
44};
45
46// ── FFI bridge surface (`mod ffi`) ────────────────────────────────
47pub use ffi::dispatcher::{ffi_serve, ffi_serve_with_callback, respond};
48pub use ffi::fetch::fetch;
49#[allow(clippy::disallowed_types)] // FFI re-exports at crate root
50pub use ffi::handles::{
51    make_body_channel, BodyReader, HandleStore, ResponseHeadEntry, StoreConfig,
52};
53pub use ffi::session::{CloseInfo, Session};
54#[allow(clippy::disallowed_types)] // FFI re-exports at crate root
55pub use ffi::types::{FfiDuplexStream, FfiResponse, RequestPayload};
56
57// ── Other re-exports kept at crate root ───────────────────────────────────────
58pub use endpoint::{
59    parse_direct_addrs, AddressLookupRemoval, AddressLookupSource, AddressLookupUpsert,
60    AddressLookupUpsertError, ConnectionEvent, DiscoveryOptions, EndpointStats, IrohEndpoint,
61    NetworkingOptions, NodeAddrInfo, NodeOptions, PathInfo, PeerStats, PoolOptions,
62    SourceScopedAddressLookup, StreamingOptions,
63};
64pub use events::TransportEvent;
65pub use http::server::stack::{CompressionOptions, StackConfig};
66pub use registry::{get_endpoint, insert_endpoint, remove_endpoint};
67
68// ── Structured error types ────────────────────────────────────────────────────
69pub use error::{CoreError, ErrorCode};
70
71// ── ALPN protocol identifiers ─────────────────────────────────────────────────
72
73/// ALPN for the HTTP/1.1-over-QUIC protocol (version 2 wire format).
74pub const ALPN: &[u8] = b"iroh-http/2";
75/// ALPN for base + bidirectional streaming sessions.
76pub const ALPN_DUPLEX: &[u8] = b"iroh-http/2-duplex";
77
78/// String form of [`ALPN`], for use in [`NodeOptions::capabilities`].
79pub const ALPN_STR: &str = "iroh-http/2";
80/// String form of [`ALPN_DUPLEX`], for use in [`NodeOptions::capabilities`].
81pub const ALPN_DUPLEX_STR: &str = "iroh-http/2-duplex";
82
83/// All recognised ALPN capability strings.
84pub const KNOWN_ALPNS: &[&str] = &[ALPN_STR, ALPN_DUPLEX_STR];
85
86// ── Key operations ───────────────────────────────────────────────────────────
87pub use crypto::{generate_secret_key, public_key_verify, secret_key_sign};
88
89// ── Encoding utilities ────────────────────────────────────────────────────────
90pub(crate) use encoding::base32_decode;
91pub use encoding::base32_encode;
92
93// ── Node address parsing ──────────────────────────────────────────────────────
94pub use addr::{node_ticket, parse_node_addr, ParsedNodeAddr};