zerodds_http2/lib.rs
1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 ZeroDDS Contributors
3
4//! Crate `zerodds-http2`. Safety classification: **STANDARD**.
5//!
6//! HTTP/2 (RFC 9113) wire codec — no_std framing + stream state
7//! machine + flow control + connection preface + settings.
8//! `forbid(unsafe_code)`. Implements the HTTP/2 wire layer
9//! without heap buffering or an async runtime: frames are
10//! encoded to / decoded from byte slices, and the state machine is
11//! callback-based.
12//!
13//! Note: RFC 9113 (HTTP/2) superseded RFC 7540, keeping the
14//! wire format and most § numbers while removing a few
15//! unused features (priority, hint directives). This crate
16//! follows RFC 9113.
17//!
18//! Spec: RFC 9113 §3 (connection preface) + §4 (frame layer) + §5
19//! (streams + multiplexing) + §6 (frame definitions) + §7 (error
20//! codes).
21//!
22//! ## Layer position
23//!
24//! Layer 5 — bridges. Substrate for:
25//!
26//! - [`zerodds-grpc-bridge`](../zerodds_grpc_bridge/index.html) —
27//! gRPC-over-HTTP/2 + gRPC-Web length-prefixed message codec
28//! (header block via [`zerodds-hpack`](../zerodds_hpack/index.html)).
29//!
30//! ## Public API (as of 1.0.0-rc.1)
31//!
32//! - [`Frame`] / [`FrameHeader`] / [`FrameType`] / [`Flags`] /
33//! [`encode_frame`] / [`decode_frame`] — frame-layer codec (§4 +
34//! §6).
35//! - [`CLIENT_PREFACE`] / [`check_preface`] — connection preface
36//! (§3.4).
37//! - [`Settings`] / [`Setting`] / [`SettingId`] — settings-frame
38//! codec + defaults (§6.5).
39//! - [`StreamId`] / [`StreamState`] — stream state machine (§5.1).
40//! - [`FlowControl`] — connection + stream flow control (§5.2).
41//! - [`ErrorCode`] / [`Http2Error`] — error codes (§7).
42//!
43//! ## Example
44//!
45//! ```rust
46//! use zerodds_http2::{FrameHeader, FrameType, Flags, encode_frame, decode_frame};
47//! use zerodds_http2::frame::DEFAULT_MAX_FRAME_SIZE;
48//!
49//! // PING frame (8-byte opaque payload, stream ID 0).
50//! let payload = [0u8; 8];
51//! let header = FrameHeader {
52//! length: 8,
53//! frame_type: FrameType::Ping,
54//! flags: Flags(0),
55//! stream_id: 0,
56//! };
57//!
58//! let mut buf = [0u8; 17]; // 9-byte header + 8-byte payload
59//! let written = encode_frame(&header, &payload, &mut buf, DEFAULT_MAX_FRAME_SIZE)
60//! .expect("encode");
61//! assert_eq!(written, 17);
62//!
63//! let (decoded, consumed) = decode_frame(&buf, DEFAULT_MAX_FRAME_SIZE).expect("decode");
64//! assert_eq!(consumed, 17);
65//! assert_eq!(decoded.header.frame_type, FrameType::Ping);
66//! ```
67
68#![no_std]
69#![forbid(unsafe_code)]
70#![warn(missing_docs)]
71
72extern crate alloc;
73
74#[cfg(feature = "std")]
75extern crate std;
76
77pub mod error;
78pub mod flow;
79pub mod frame;
80pub mod preface;
81pub mod settings;
82pub mod stream;
83
84pub use error::{ErrorCode, Http2Error};
85pub use flow::FlowControl;
86pub use frame::{Flags, Frame, FrameHeader, FrameType, decode_frame, encode_frame};
87pub use preface::{CLIENT_PREFACE, check_preface};
88pub use settings::{Setting, SettingId, Settings};
89pub use stream::{StreamId, StreamState};