hyperdb_api_core/protocol/mod.rs
1// Copyright (c) 2026, Salesforce, Inc. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3
4#![allow(
5 missing_docs,
6 reason = "internal crate; not published to crates.io. Docs are contributor-facing, covered in DEVELOPMENT.md."
7)]
8
9//! Wire protocol implementation for Hyper database.
10//!
11//! This module implements the `PostgreSQL` wire protocol with Hyper-specific
12//! extensions for `LittleEndian` binary format (`HyperBinary`). It sits between
13//! the sibling `types` module (type system) and `client` module (connection management).
14//!
15//! # Two-Layer Byte Order Design
16//!
17//! The Hyper wire protocol has two layers with *different* byte orders:
18//!
19//! | Layer | Byte Order | Modules | Rationale |
20//! |---|---|---|---|
21//! | Message framing | **`BigEndian`** | [`message`] | `PostgreSQL` specification compatibility |
22//! | Data encoding | **`LittleEndian`** | [`copy`], [`types`] | Hyper's native format, optimized for x86/x64 |
23//!
24//! All message headers, lengths, and column counts use `BigEndian` (network byte
25//! order), exactly like standard `PostgreSQL`. Actual data values inside those
26//! messages use `LittleEndian`, which is Hyper's native format. This lets Hyper
27//! stay compatible with `PostgreSQL` client libraries while avoiding byte-swapping
28//! on the dominant deployment architectures.
29//!
30//! # Modules
31//!
32//! - [`message`] -- Frontend (client-to-server) and backend (server-to-client)
33//! message framing, parsing, and construction. All lengths are `BigEndian`.
34//! - [`copy`] -- `HyperBinary` COPY format: header, row encoding, and read helpers.
35//! All data values are `LittleEndian`.
36//! - [`types`] -- Conversion between Rust types and `HyperBinary` format
37//! (`LittleEndian` encoding/decoding).
38//! - [`escape`] -- SQL identifier and literal escaping via zero-cost newtype
39//! wrappers with [`std::fmt::Display`] implementations.
40
41#![warn(missing_docs, rust_2018_idioms, clippy::all)]
42
43pub mod copy;
44pub mod escape;
45pub mod message;
46#[cfg(kani)]
47mod proofs;
48pub mod types;
49
50pub use crate::types::Oid;
51pub use types::ParseError;