http_streams_core/
lib.rs

1#![forbid(unsafe_code)]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3
4//! Framework-neutral building blocks for streaming HTTP bodies as sequences of items.
5//!
6//! This crate holds the parts that are the same whichever HTTP library is in use: the wire
7//! formats (encoding *and* decoding), the error type, and the progress/observability state
8//! machine. It knows nothing about any specific client or server.
9//!
10//! You are unlikely to depend on it directly. It backs:
11//!
12//! - [axum-streams](https://github.com/abdolence/axum-streams-rs): server side
13//! - [reqwest-streams](https://github.com/abdolence/reqwest-streams-rs): client side
14//!
15//! Both re-export the types they expose, so downstream code names them through those crates
16//! rather than here.
17//!
18//! # Why this crate exists
19//!
20//! It was extracted from those two, which had grown up as a pair: one encoding response bodies
21//! on the server, the other decoding them on the client. Adding streaming *request* bodies
22//! meant each needed what the other already had, and the two had by then also grown
23//! near-identical progress and error handling independently. The shared parts moved here so a
24//! body encoded by one is decoded by the same code in the other.
25//!
26//! # Features
27//!
28//! **Note:** the `default` features do not include any formats.
29//!
30//! - `json`: JSON array and JSON Lines (JSONL)
31//! - `csv`: CSV
32//! - `protobuf`: length-prefixed Protobuf
33//! - `arrow`: Apache Arrow IPC
34//! - `text`: raw UTF-8 text (encode only, see below)
35//! - `tracing`: report progress and errors through [tracing]
36//!
37//! # Directionality
38//!
39//! Every format can encode. All but `text` can decode: text framing writes raw bytes with no
40//! delimiter, so `["ab", "c"]` and `["a", "bc"]` are byte-identical on the wire and splitting
41//! them back into items is not merely unimplemented but impossible.
42//!
43//! [tracing]: https://docs.rs/tracing
44
45#[macro_use]
46mod macros;
47
48pub mod buffer;
49pub mod content_type;
50pub mod envelope;
51pub mod error;
52pub mod format;
53pub mod progress;
54pub mod stream;
55
56cfg_arrow! {
57    pub use arrow_format::{ArrowIpcEncoder, ArrowRecordBatchIpcStreamFormat};
58    pub use arrow_ipc_codec::ArrowIpcCodec;
59    mod arrow_format;
60    mod arrow_ipc_codec;
61}
62
63cfg_protobuf! {
64    pub use protobuf_format::{ProtobufEncoder, ProtobufStreamFormat};
65    pub use protobuf_len_codec::ProtobufLenPrefixCodec;
66    mod protobuf_format;
67    mod protobuf_len_codec;
68}
69
70cfg_text! {
71    pub use text_format::{TextEncoder, TextStreamFormat};
72    mod text_format;
73}
74
75cfg_csv! {
76    pub use csv_format::{CsvEncoder, CsvParser, CsvStreamFormat};
77    pub use csv_record_codec::{CsvFrameConfig, CsvRecordCodec};
78    /// Re-exported so callers can configure [`CsvStreamFormat`] without depending on `csv`.
79    pub use csv::{QuoteStyle, Terminator};
80    mod csv_format;
81    mod csv_record_codec;
82}
83
84cfg_json! {
85    pub use json_formats::{
86        JsonArrayEncoder, JsonArrayStreamFormat, JsonNewLineEncoder, JsonNewLineStreamFormat,
87    };
88    pub use json_array_codec::JsonArrayCodec;
89    pub use json_nl_codec::JsonNewLineCodec;
90    mod json_array_codec;
91    mod json_formats;
92    mod json_nl_codec;
93}
94
95pub use buffer::{buffer_bytes, buffer_ready_items};
96pub use content_type::ContentType;
97pub use envelope::StreamFormatEnvelope;
98pub use error::{StreamError, StreamErrorKind};
99pub use format::{
100    DecodeOptions, DefaultFormat, FrameParser, IdentityParser, ItemEncoder, StreamFormat,
101    StreamFormatDecode, StreamFormatEncode, DEFAULT_BUF_CAPACITY,
102};
103pub use progress::{
104    count_bytes, count_items, instrument, Counting, Direction, ErrorInfo, Progress, ProgressItem,
105    ProgressOptions, Side, StreamContext, StreamErrorHandler, StreamOutcome, StreamProgress,
106    StreamProgressHandler, DEFAULT_PROGRESS_INTERVAL,
107};
108pub use stream::{decode_stream, encode_stream};
109
110/// Alias for the [`Result`] type produced by streaming a body in either direction.
111pub type StreamResult<T> = std::result::Result<T, StreamError>;
http_streams_core/lib.rs

http_streams_core/
lib.rs
