1use crate::budget::DecodeBuf;
7use crate::error::{Error, LimitKind};
8use crate::limits::{ChargeError, Meter};
9use crate::stream::Endian;
10use bytes::Bytes;
11use std::sync::Arc;
12
13#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
15pub enum SaveLayout {
16 #[default]
20 Semantic,
21 UnityPy,
24}
25
26#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
28pub struct SaveOptions {
29 pub layout: SaveLayout,
31}
32
33#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
35#[non_exhaustive]
36pub enum SaveError {
37 #[error("this CAB already exists and is not a writer")]
39 CabExists,
40 #[error("HEAD-tier writes are not implemented")]
43 HeadTierWritesNotImplemented,
44 #[error("save is not implemented for {0}")]
46 Unsupported(&'static str),
47 #[error("compression is not implemented for {0:?}")]
49 UnsupportedCodec(crate::codec::Codec),
50 #[error("{codec:?} compression failed: {detail}")]
52 Compress {
53 codec: crate::codec::Codec,
55 detail: &'static str,
57 },
58 #[error(transparent)]
61 Charge(#[from] ChargeError),
62 #[error(transparent)]
64 Read(#[from] Error),
65 #[error(transparent)]
67 Object(#[from] crate::walk::WriteError),
68 #[error("save field {0} is out of range")]
70 Range(&'static str),
71 #[error("save field {0} is missing")]
73 Missing(&'static str),
74}
75
76pub(crate) fn required<T>(value: Option<T>, name: &'static str) -> Result<T, SaveError> {
77 value.ok_or(SaveError::Missing(name))
78}
79
80pub(crate) fn narrow<T: TryFrom<U>, U>(value: U, name: &'static str) -> Result<T, SaveError> {
81 T::try_from(value).map_err(|_| SaveError::Range(name))
82}
83
84pub(crate) struct Writer {
85 buf: DecodeBuf,
86 endian: Endian,
87 sequential_window: bool,
88 window_tail: bool,
89}
90
91impl Writer {
92 pub(crate) fn new(meter: &Arc<Meter>, endian: Endian) -> Result<Self, SaveError> {
93 Ok(Self {
94 buf: DecodeBuf::counted(meter, u64::MAX, LimitKind::InputMemory)?,
95 endian,
96 sequential_window: false,
97 window_tail: false,
98 })
99 }
100 pub(crate) fn metadata(
101 meter: &Arc<Meter>,
102 endian: Endian,
103 layout: SaveLayout,
104 ) -> Result<Self, SaveError> {
105 let mut out = Self::new(meter, endian)?;
106 out.sequential_window = layout == SaveLayout::Semantic;
107 Ok(out)
108 }
109 pub(crate) fn meter(&self) -> &Arc<Meter> {
110 self.buf.meter()
111 }
112 pub(crate) fn len(&self) -> usize {
113 self.buf.len()
114 }
115 pub(crate) fn bytes(&mut self, b: &[u8]) -> Result<(), SaveError> {
116 self.buf.extend_from_slice(b)?;
117 if !b.is_empty() {
118 self.window_tail = false;
119 }
120 Ok(())
121 }
122 pub(crate) fn write_at(&mut self, offset: usize, bytes: &[u8]) -> Result<(), SaveError> {
123 self.buf.write_at(offset, bytes)?;
124 Ok(())
125 }
126 pub(crate) fn write_zeroes_at(&mut self, offset: usize, count: usize) -> Result<(), SaveError> {
127 self.buf.write_zeroes_at(offset, count)?;
128 Ok(())
129 }
130 pub(crate) fn slice(&self) -> &[u8] {
131 self.buf.as_slice()
132 }
133 pub(crate) fn finish(self) -> Result<Bytes, SaveError> {
134 Ok(self.buf.into_bytes()?)
135 }
136 pub(crate) fn align(&mut self, n: usize) -> Result<(), SaveError> {
137 let padding = (n - self.len() % n) % n;
138 self.buf.grow_zeroed(padding)?;
139 if padding != 0 {
140 self.window_tail = false;
141 }
142 Ok(())
143 }
144 pub(crate) fn cstr(&mut self, b: &[u8]) -> Result<(), SaveError> {
145 if self.sequential_window && b.len() > crate::stream::STRING_TO_NULL_WINDOW {
149 return Err(SaveError::Range("metadata string window"));
150 }
151 self.bytes(b)?;
152 if self.sequential_window && b.len() == crate::stream::STRING_TO_NULL_WINDOW {
153 self.window_tail = true;
154 return Ok(());
155 }
156 self.bytes(&[0])
157 }
158 pub(crate) fn end_metadata(&mut self) -> Result<(), SaveError> {
162 if self.window_tail {
163 self.bytes(&[0])?;
164 }
165 Ok(())
166 }
167 pub(crate) fn fixed16(&mut self, b: &[u8], field: &'static str) -> Result<(), SaveError> {
168 if self.sequential_window && b.len() != 16 {
172 return Err(SaveError::Range(field));
173 }
174 self.bytes(b)
175 }
176 pub(crate) fn boolean(&mut self, v: bool) -> Result<(), SaveError> {
177 self.bytes(&[u8::from(v)])
178 }
179 pub(crate) fn count(&mut self, n: usize) -> Result<(), SaveError> {
180 self.i32(narrow(n, "count")?)
181 }
182 pub(crate) fn number<const N: usize>(&mut self, mut little: [u8; N]) -> Result<(), SaveError> {
183 if self.endian == Endian::Big {
184 little.reverse();
185 }
186 self.bytes(&little)
187 }
188 pub(crate) fn i16(&mut self, n: i16) -> Result<(), SaveError> {
189 self.number(n.to_le_bytes())
190 }
191 pub(crate) fn u16(&mut self, n: u16) -> Result<(), SaveError> {
192 self.number(n.to_le_bytes())
193 }
194 pub(crate) fn i32(&mut self, n: i32) -> Result<(), SaveError> {
195 self.number(n.to_le_bytes())
196 }
197 pub(crate) fn u32(&mut self, n: u32) -> Result<(), SaveError> {
198 self.number(n.to_le_bytes())
199 }
200 pub(crate) fn i64(&mut self, n: i64) -> Result<(), SaveError> {
201 self.number(n.to_le_bytes())
202 }
203 pub(crate) fn u64(&mut self, n: u64) -> Result<(), SaveError> {
204 self.number(n.to_le_bytes())
205 }
206}
207
208#[cfg(test)]
209mod tests {
210 use super::*;
211 use crate::budget::{Reservation, Unbounded};
212
213 #[test]
216 fn primitives_and_null_strings_roundtrip_through_the_reader() {
217 use crate::stream::Reader;
218
219 for endian in [Endian::Big, Endian::Little] {
220 let meter =
221 Meter::with_decode_work(1 << 20, 1 << 20, Arc::new(Unbounded), Reservation::Input);
222 let mut writer = Writer::new(&meter, endian).unwrap();
223 writer.boolean(true).unwrap();
224 writer.boolean(false).unwrap();
225 writer.i16(i16::MIN).unwrap();
226 writer.u16(u16::MAX).unwrap();
227 writer.i32(i32::MIN).unwrap();
228 writer.u32(u32::MAX).unwrap();
229 writer.i64(i64::MIN).unwrap();
230 writer.u64(u64::MAX).unwrap();
231 writer.cstr(b"a\xff\xc3\xa9").unwrap();
232 let unaligned = writer.len();
233 writer.align(8).unwrap();
234 assert!(writer.slice()[unaligned..].iter().all(|byte| *byte == 0));
235 let bytes = writer.finish().unwrap();
236 assert_eq!(meter.decoded(), bytes.len() as u64);
237 assert!(meter.used() > 0);
238 let mut reader = Reader::new(&bytes, endian);
239 assert!(reader.read_bool().unwrap());
240 assert!(!reader.read_bool().unwrap());
241 assert_eq!(reader.read_i16().unwrap(), i16::MIN);
242 assert_eq!(reader.read_u16().unwrap(), u16::MAX);
243 assert_eq!(reader.read_i32().unwrap(), i32::MIN);
244 assert_eq!(reader.read_u32().unwrap(), u32::MAX);
245 assert_eq!(reader.read_i64().unwrap(), i64::MIN);
246 assert_eq!(reader.read_u64().unwrap(), u64::MAX);
247 assert_eq!(reader.read_string_to_null().unwrap(), b"a\xff\xc3\xa9");
248 reader.align(8).unwrap();
249 assert_eq!(reader.position(), bytes.len() as i128);
250 drop(bytes);
251 assert_eq!(meter.used(), 0);
252 }
253 }
254
255 #[test]
256 fn positioned_writes_preserve_tails_and_refusals_preserve_bytes() {
257 let meter = Meter::with_decode_work(1 << 20, 2048, Arc::new(Unbounded), Reservation::Input);
258 let mut writer = Writer::new(&meter, Endian::Little).unwrap();
259 writer.bytes(b"abc").unwrap();
260 writer.write_at(0, b"Z").unwrap();
261 writer.write_at(5, b"Q").unwrap();
262 assert_eq!(writer.slice(), b"Zbc\0\0Q");
263 writer.write_at(100, b"").unwrap();
264 assert_eq!(writer.slice(), b"Zbc\0\0Q");
265 let before = meter.used();
266 let work = meter.decoded();
267 let held = meter.charge(meter.limit() - before).unwrap();
268 let error = writer.write_at(1, &[b'x'; 1024]).unwrap_err();
269 assert!(matches!(error, SaveError::Charge(ChargeError::Limit(_))));
270 assert_eq!(writer.slice(), b"Zbc\0\0Q");
271 assert_eq!(meter.decoded(), work);
272 drop(held);
273 writer.write_at(1, &[b'x'; 1024]).unwrap();
274 assert_eq!(writer.len(), 1025);
275 assert_eq!(writer.slice().first(), Some(&b'Z'));
276 meter.count_decode(2048 - meter.decoded()).unwrap();
277 let error = writer.write_at(0, b"W").unwrap_err();
278 assert!(matches!(error, SaveError::Charge(ChargeError::Limit(_))));
279 assert_eq!(writer.slice().first(), Some(&b'Z'));
280 }
281
282 #[test]
283 fn memory_refused_alignment_can_retry_with_its_exact_work_allowance() {
284 let meter = Meter::with_decode_work(1 << 20, 16, Arc::new(Unbounded), Reservation::Input);
285 let mut writer = Writer::new(&meter, Endian::Little).unwrap();
286 writer.bytes(&[7; 8]).unwrap();
287 let before = meter.used();
288 let held = meter.charge(meter.limit() - before).unwrap();
289 let SaveError::Charge(ChargeError::Limit(error)) = writer.align(16).unwrap_err() else {
290 panic!("alignment must refuse memory")
291 };
292 assert_eq!(error.kind(), LimitKind::InputMemory);
293 assert_eq!(writer.slice(), &[7; 8]);
294 assert_eq!(meter.decoded(), 8, "refused padding writes nothing");
295 drop(held);
296 assert_eq!(meter.used(), before);
297 writer.align(16).unwrap();
298 assert_eq!(
299 writer.slice(),
300 &[7, 7, 7, 7, 7, 7, 7, 7, 0, 0, 0, 0, 0, 0, 0, 0]
301 );
302 assert_eq!(meter.decoded(), 16);
303 drop(writer);
304 assert_eq!(meter.used(), 0);
305 }
306}