1use core::fmt;
8
9use crate::metadata::{ArchiveMetadata, EntryMetadata};
10use crate::{ArchiveError, ErrorKind};
11
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum EndOfInput {
15 More,
17 End,
19}
20
21#[derive(Debug, Clone, PartialEq, Eq)]
23#[non_exhaustive]
24pub enum ProbeResult<T> {
25 Match(T),
27 NeedMore {
29 minimum: usize,
31 },
32 NoMatch,
34}
35
36#[derive(Debug, Clone, Copy, PartialEq, Eq)]
38#[non_exhaustive]
39pub enum CodecStatus {
40 NeedInput,
42 NeedOutput,
44 Done,
46}
47
48#[derive(Debug, Clone, Copy, PartialEq, Eq)]
50pub struct CodecStep {
51 pub consumed: usize,
53 pub produced: usize,
55 pub status: CodecStatus,
57}
58
59impl CodecStep {
60 pub fn validate(self, input_len: usize, output_len: usize) -> Result<Self, ArchiveError> {
62 if self.consumed > input_len || self.produced > output_len {
63 return Err(ArchiveError::new(ErrorKind::Protocol)
64 .with_context("codec reported out-of-range progress"));
65 }
66 if self.consumed == 0 && self.produced == 0 {
67 let valid_wait = matches!(self.status, CodecStatus::NeedInput) && input_len == 0;
68 let valid_backpressure =
69 matches!(self.status, CodecStatus::NeedOutput) && output_len == 0;
70 if !valid_wait && !valid_backpressure && !matches!(self.status, CodecStatus::Done) {
71 return Err(
72 ArchiveError::new(ErrorKind::Protocol).with_context("codec made no progress")
73 );
74 }
75 }
76 Ok(self)
77 }
78}
79
80pub trait Codec {
82 fn process(
84 &mut self,
85 input: &[u8],
86 output: &mut [u8],
87 end: EndOfInput,
88 ) -> Result<CodecStep, ArchiveError>;
89}
90
91#[derive(Clone, Copy)]
93pub struct Chunk<'a> {
94 bytes: &'a [u8],
95}
96
97impl<'a> Chunk<'a> {
98 #[must_use]
100 pub const fn new(bytes: &'a [u8]) -> Self {
101 Self { bytes }
102 }
103
104 #[must_use]
106 pub const fn as_bytes(self) -> &'a [u8] {
107 self.bytes
108 }
109}
110
111impl fmt::Debug for Chunk<'_> {
112 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
113 f.debug_struct("Chunk")
114 .field("len", &self.bytes.len())
115 .finish()
116 }
117}
118
119#[derive(Debug)]
121#[non_exhaustive]
122#[allow(clippy::large_enum_variant)]
123pub enum DecodeEvent<'a> {
124 NeedInput,
126 NeedOutput,
128 ArchiveMetadata(ArchiveMetadata),
130 Entry(EntryMetadata),
132 Data(Chunk<'a>),
134 EndEntry,
136 Done,
138}
139
140#[derive(Debug)]
142pub struct DecodeStep<'a> {
143 pub consumed: usize,
145 pub produced: usize,
147 pub event: DecodeEvent<'a>,
149}
150
151impl DecodeStep<'_> {
152 pub fn validate(self, input_len: usize, output_len: usize) -> Result<Self, ArchiveError> {
154 if self.consumed > input_len || self.produced > output_len {
155 return Err(ArchiveError::new(ErrorKind::Protocol)
156 .with_context("archive decoder reported out-of-range progress"));
157 }
158 if self.consumed == 0 && self.produced == 0 {
159 let semantic_progress = match &self.event {
160 DecodeEvent::NeedInput
161 | DecodeEvent::NeedOutput
162 | DecodeEvent::ArchiveMetadata(_)
163 | DecodeEvent::Entry(_)
164 | DecodeEvent::EndEntry
165 | DecodeEvent::Done => true,
166 DecodeEvent::Data(chunk) => !chunk.bytes.is_empty(),
167 };
168 if !semantic_progress {
169 return Err(ArchiveError::new(ErrorKind::Protocol)
170 .with_context("archive decoder made no progress"));
171 }
172 }
173 Ok(self)
174 }
175}
176
177pub trait ArchiveDecoder {
179 fn step<'a>(
181 &'a mut self,
182 input: &'a [u8],
183 output: &'a mut [u8],
184 end: EndOfInput,
185 ) -> Result<DecodeStep<'a>, ArchiveError>;
186}
187
188#[derive(Debug)]
190#[non_exhaustive]
191pub enum EncodeCommand<'a> {
192 BeginEntry(&'a EntryMetadata),
194 Data(&'a [u8]),
196 EndEntry,
198 Finish,
200}
201
202#[derive(Debug, Clone, Copy, PartialEq, Eq)]
204#[non_exhaustive]
205pub enum EncodeStatus {
206 NeedCommand,
208 NeedOutput,
210 Done,
212}
213
214#[derive(Debug, Clone, Copy, PartialEq, Eq)]
216pub struct EncodeStep {
217 pub consumed: usize,
219 pub produced: usize,
221 pub status: EncodeStatus,
223}
224
225impl EncodeStep {
226 pub fn validate(
228 self,
229 data_input_len: Option<usize>,
230 output_len: usize,
231 ) -> Result<Self, ArchiveError> {
232 let maximum = data_input_len.unwrap_or(1);
233 if self.consumed > maximum || self.produced > output_len {
234 return Err(ArchiveError::new(ErrorKind::Protocol)
235 .with_context("archive encoder reported out-of-range progress"));
236 }
237 if data_input_len.is_some()
238 && self.consumed == 0
239 && self.produced == 0
240 && (!matches!(self.status, EncodeStatus::NeedOutput) || output_len != 0)
241 {
242 return Err(ArchiveError::new(ErrorKind::Protocol)
243 .with_context("archive encoder made no data progress"));
244 }
245 Ok(self)
246 }
247}
248
249pub trait ArchiveEncoder {
251 fn step(
253 &mut self,
254 command: EncodeCommand<'_>,
255 output: &mut [u8],
256 ) -> Result<EncodeStep, ArchiveError>;
257}