git_packetline/
lib.rs

1//! Read and write the git packet line wire format without copying it.
2//!
3//! For reading the packet line format use the [`StreamingPeekableIter`], and for writing the [`Writer`].
4//! ## Feature Flags
5#![cfg_attr(
6    feature = "document-features",
7    cfg_attr(doc, doc = ::document_features::document_features!())
8)]
9#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
10#![deny(missing_docs, rust_2018_idioms, unsafe_code)]
11
12const U16_HEX_BYTES: usize = 4;
13const MAX_DATA_LEN: usize = 65516;
14const MAX_LINE_LEN: usize = MAX_DATA_LEN + U16_HEX_BYTES;
15const FLUSH_LINE: &[u8] = b"0000";
16const DELIMITER_LINE: &[u8] = b"0001";
17const RESPONSE_END_LINE: &[u8] = b"0002";
18const ERR_PREFIX: &[u8] = b"ERR ";
19
20/// One of three side-band types allowing to multiplex information over a single connection.
21#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
22#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
23pub enum Channel {
24    /// The usable data itself in any format.
25    Data = 1,
26    /// Progress information in a user-readable format.
27    Progress = 2,
28    /// Error information in a user readable format. Receiving it usually terminates the connection.
29    Error = 3,
30}
31
32mod line;
33///
34pub mod read;
35
36///
37#[cfg(any(feature = "async-io", feature = "blocking-io"))]
38mod write;
39#[cfg(all(not(feature = "blocking-io"), feature = "async-io"))]
40pub use write::async_io::Writer;
41#[cfg(feature = "blocking-io")]
42pub use write::blocking_io::Writer;
43
44/// A borrowed packet line as it refers to a slice of data by reference.
45#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
46#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
47pub enum PacketLineRef<'a> {
48    /// A chunk of raw data.
49    Data(&'a [u8]),
50    /// A flush packet.
51    Flush,
52    /// A delimiter packet.
53    Delimiter,
54    /// The end of the response.
55    ResponseEnd,
56}
57
58/// A packet line representing an Error in a side-band channel.
59#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
60#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
61pub struct ErrorRef<'a>(pub &'a [u8]);
62
63/// A packet line representing text, which may include a trailing newline.
64#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
65#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
66pub struct TextRef<'a>(pub &'a [u8]);
67
68/// A band in a side-band channel.
69#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
70#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
71pub enum BandRef<'a> {
72    /// A band carrying data.
73    Data(&'a [u8]),
74    /// A band carrying user readable progress information.
75    Progress(&'a [u8]),
76    /// A band carrying user readable errors.
77    Error(&'a [u8]),
78}
79
80/// Read pack lines one after another, without consuming more than needed from the underlying
81/// [`Read`][std::io::Read]. [`Flush`][PacketLineRef::Flush] lines cause the reader to stop producing lines forever,
82/// leaving [`Read`][std::io::Read] at the start of whatever comes next.
83///
84/// This implementation tries hard not to allocate at all which leads to quite some added complexity and plenty of extra memory copies.
85pub struct StreamingPeekableIter<T> {
86    read: T,
87    peek_buf: Vec<u8>,
88    #[cfg(any(feature = "blocking-io", feature = "async-io"))]
89    buf: Vec<u8>,
90    fail_on_err_lines: bool,
91    delimiters: &'static [PacketLineRef<'static>],
92    is_done: bool,
93    stopped_at: Option<PacketLineRef<'static>>,
94}
95
96/// Utilities to help decoding packet lines
97pub mod decode;
98#[doc(inline)]
99pub use decode::all_at_once as decode;
100/// Utilities to encode different kinds of packet lines
101pub mod encode;
102
103#[cfg(all(feature = "async-io", feature = "blocking-io"))]
104compile_error!("Cannot set both 'blocking-io' and 'async-io' features as they are mutually exclusive");
git_packetline/lib.rs

git_packetline/
lib.rs
