Skip to main content

Crate base_http

Crate base_http 

Source
Expand description

§base-http

A runtime-independent HTTP semantic layer for Base, porting Socketry’s protocol-http model to Rust. It defines requests, responses, fields and bodies without performing I/O, while sibling packages implement HTTP/1, pooled clients and servers over Base scheduler sockets.

§Usage

Add base-http for the semantic types:

cargo add base-http

Add base-http-client or base-http-server for the HTTP/1 client and server, and enable the rustls feature of either for TLS.

Messages carry public metadata and an arbitrary body owner, and body mapping preserves the metadata:

use base_http::{Method, Request, Response, Status, body::BufferedBody};

let request = Request::new(Method::POST, "/submit", b"hello".to_vec())
    .map_body(BufferedBody::from);
let (metadata, body) = request.into_parts();
let mut response = Response::new(Status::OK, body);
response.fields.add("Content-Type", "text/plain")?;
assert_eq!(metadata.method, Method::POST);

The pooled client/server example sends POST requests through one endpoint pool to a local echo server. Run it with cargo run --locked --manifest-path crates/client/Cargo.toml --example client_server, adding --features rustls and -- --https for TLS. The low-level example demonstrates direct ownership of the HTTP/1 lanes.

§Releasing

Prepare a release with cargo bake cargo:version:patch (or minor, major, or bump --version X.Y.Z), commit it with a Release: vVERSION trailer, then run cargo bake cargo:release and open a pull request. After review and merge, GitHub Actions publishes the release when the configured crates-io environment approves it, then creates or updates the matching GitHub Release from releases.md. Follow the shared Releasing skill for the standard process.

§Releases

See releases.md for the full release history.

§v0.2.0

  • base-http-client and base-http-server disable Nagle’s algorithm (TCP_NODELAY) on each TCP connection they establish or accept, so small writes such as streamed frames on long-lived duplex exchanges are not delayed by Nagle’s algorithm interacting with delayed acknowledgements. Set the new Options::tcp_nodelay to false to leave the socket options unchanged. Setting the option is best effort and does not fail a connection. This is a breaking change: Options in both crates gains the public tcp_nodelay field, so struct literals need it or ..Default::default(), and Client::new, serve and serve_tls now require the scheduler to implement SocketSetOption<TcpNoDelay>, which every Base scheduler backend provides. serve_connection leaves the options of a caller-accepted socket unchanged.
  • base-http1 incoming body reads are cancellation safe. Dropping a pending read, or cancelling its wait, loses no input, so a later read resumes at the same position. Previously any later read failed with “previous body read failed or was abandoned”. A read that fails for another reason still fails every later read, now with “previous body read failed”.

§v0.1.0

  • First release of base-http, base-http1, base-http-protocol, base-http-client and base-http-server. base-http defines runtime-independent HTTP semantics: requests and responses, methods, statuses, versions, request targets, ordered fields with header interpretation and combination policies, interim responses, and buffered and streaming bodies. Constructing messages and mapping bodies performs no I/O.
  • base-http1 implements native HTTP/1.0 and HTTP/1.1 framing over Base scheduler streams. It parses heads with a hand-written parser and handles fixed-length, chunked and close-delimited bodies, trailers and interim responses. The server side also manages 101 upgrades and CONNECT. base-http-protocol selects the protocol for a connection, including through ALPN.
  • base-http-client provides a cloneable client with an explicit driver that pools HTTP/1 connections through base-pool, over plain TCP or, with the rustls feature, TLS. base-http-server serves connections and listeners with a connection limit, over plain TCP or, with the rustls feature, TLS.
  • Errors report each cause once: an error either describes its cause in its message or returns it from source. A connection that fails to open is base_http_client::Error::Connect, which carries the endpoint address.
  • Requires Rust 1.87, base-scheduler 0.3, base-pool 0.3 and base-endpoint 0.1.

§See Also

§Contributing

Please open an issue or pull request on GitHub.

Re-exports§

pub use fields::Field;
pub use fields::FieldError;
pub use fields::Fields;
pub use headers::HttpHeaders;
pub use interim::InterimError;
pub use interim::InterimHandler;
pub use interim::InterimResponses;
pub use method::Method;
pub use protocol::Protocol;
pub use request::Request;
pub use request::RequestMetadata;
pub use response::Response;
pub use response::ResponseMetadata;
pub use status::Status;
pub use target::Authority;
pub use target::Path;
pub use target::Scheme;
pub use version::Version;

Modules§

body
Native HTTP bodies, following Protocol::HTTP::Body.
fields
Ordered pairs of token names and opaque byte values, without interpretation or section state. Protocol drivers decide which value bytes each protocol can carry: HTTP/2 and HTTP/3 extensions can negotiate binary values, so the semantic model does not restrict them.
headers
Explicit HTTP interpretation of raw fields. Other application protocols can interpret Fields independently or configure their own combination policy.
interim
Per-exchange interim-response hooks, independent of message heads and bodies.
method
protocol
request
response
status
target
Request target components. Schemes and HTTP hosts are case-insensitive, so schemes and authorities are stored in lowercase (RFC 3986, sections 3.1 and 6.2.2.1; RFC 9110, section 4.2.3); paths are preserved as supplied. Percent-encoded authority bytes are lowercased too, which is equivalent though RFC 3986 prefers uppercase hexadecimal digits. Drivers validate target combinations and wire syntax before transmission.
version