reqwest_streams/lib.rs
1#![allow(unused_parens, clippy::new_without_default)]
2#![forbid(unsafe_code)]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4
5//! Streaming responses support for reqwest for different formats:
6//! - JSON array stream format
7//! - JSON Lines (NL/NewLines) format
8//! - CSV stream format
9//! - [Protobuf] len-prefixed stream format
10//! - [Apache Arrow IPC] stream format
11//!
12//! This type of responses are useful when you are reading huge stream of objects from some source (such as database, file, etc)
13//! and want to avoid huge memory allocations to store on the server side.
14//!
15//! # Features
16//!
17//! **Note:** The `default` features do not include any formats.
18//!
19//! - `json`: JSON array and JSON Lines (JSONL) stream formats
20//! - `csv`: CSV stream format
21//! - `protobuf`: [Protobuf] len-prefixed stream format
22//! - `arrow`: [Apache Arrow IPC] stream format
23//!
24//! # Example
25//!
26//! ```rust,no_run
27//! use futures::stream::BoxStream as _;
28//! use reqwest_streams::JsonStreamResponse as _;
29//! use serde::Deserialize;
30//!
31//! #[derive(Debug, Clone, Deserialize)]
32//! struct MyTestStructure {
33//! some_test_field: String
34//! }
35//!
36//!#[tokio::main]
37//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
38//!
39//! let _stream = reqwest::get("http://localhost:8080/json-array")
40//! .await?
41//! .json_array_stream::<MyTestStructure>(1024);
42//!
43//! Ok(())
44//! }
45//! ```
46//!
47//! More and complete examples available on the github in the examples directory.
48//!
49//! ## Need server support?
50//! There is the same functionality:
51//! - [axum-streams](https://github.com/abdolence/axum-streams-rs).
52//!
53//!
54//! [Apache Arrow IPC]: https://arrow.apache.org/docs/format/Columnar.html#serialization-and-interprocess-communication-ipc
55//! [Protobuf]: https://protobuf.dev/programming-guides/encoding/
56
57#[macro_use]
58mod macros;
59
60cfg_json! {
61 pub use json_stream::JsonStreamResponse;
62 mod json_stream;
63 mod json_array_codec;
64}
65
66cfg_csv! {
67 pub use csv_stream::CsvStreamResponse;
68 mod csv_stream;
69}
70
71use crate::error::StreamBodyError;
72
73cfg_protobuf! {
74 pub use protobuf_stream::ProtobufStreamResponse;
75 mod protobuf_stream;
76 mod protobuf_len_codec;
77}
78
79cfg_arrow! {
80 pub use arrow_ipc_stream::ArrowIpcStreamResponse;
81 mod arrow_ipc_stream;
82 mod arrow_ipc_len_codec;
83}
84
85pub mod error;
86
87/// Alias for the [`Result`] type returned by streaming responses.
88pub type StreamBodyResult<T> = std::result::Result<T, StreamBodyError>;
89
90#[cfg(test)]
91mod test_client;