tzcraft/
binary.rs

1//! `rustbinary` compact binary facade.
2//!
3//! The binary profile is not a separate codec — it is the same
4//! `NsonSerialize` / `NsonDeserialize` implementations selected by the
5//! codec's `is_human_readable() == false`. These helpers just shorten the
6//! call path to `rustbinary`'s bounded, self-describing wire format.
7//!
8//! The dependency is pinned to `rustbinary = "=0.1.7"` with only the
9//! `alloc` core enabled (`default-features = false`). Two facts about that
10//! version matter here:
11//!
12//! - **The standard profile is bounded.** `options()` /
13//!   [`Config::standard`] rejects trailing bytes, canonicalizes marker
14//!   varints, and enforces a per-value byte limit
15//!   ([`DEFAULT_SIZE_LIMIT`]) plus a per-collection element limit
16//!   ([`DEFAULT_COLLECTION_LIMIT`]). Every helper in this module inherits
17//!   those defaults.
18//!
19//! For untrusted input, tune the limits down with [`decode_bounded`] — the
20//! pattern `rustbinary` documents for trust boundaries — instead of relying
21//! on the generous defaults.
22//!
23//! ```
24//! # use tzcraft::{Date, Ticks};
25//! let date = Date::from_ymd(2024, 6, 15).unwrap();
26//! let bytes = tzcraft::binary::encode(&date).unwrap();
27//! let back: Date = tzcraft::binary::decode(&bytes).unwrap();
28//! assert_eq!(date, back);
29//!
30//! let back: Date =
31//!     tzcraft::binary::decode_bounded(&bytes, 64, 8).unwrap();
32//! assert_eq!(date, back);
33//! ```
34
35use alloc::vec::Vec;
36
37pub use rustbinary::{
38    options, BinaryProfile, Config, Endian, Error as BinaryError, ErrorCategory, IntEncoding,
39    Result as BinaryResult, TrailingBytes, DEFAULT_COLLECTION_LIMIT, DEFAULT_SIZE_LIMIT,
40};
41
42use nextjson::{NsonDeserialize, NsonSerialize};
43
44/// Encode a value into a `Vec<u8>` with the standard compact profile.
45pub fn encode<T: NsonSerialize + ?Sized>(value: &T) -> BinaryResult<Vec<u8>> {
46    rustbinary::serialize(value)
47}
48
49/// Decode a value from a byte slice with the standard compact profile.
50///
51/// Borrowed targets may point into `input`. Equivalent to
52/// `options().deserialize(input)`.
53pub fn decode<'de, T: NsonDeserialize<'de>>(input: &'de [u8]) -> BinaryResult<T> {
54    rustbinary::deserialize(input)
55}
56
57/// Decode with explicit resource limits for a trust boundary.
58///
59/// `size_limit` caps the bytes one decoded value may consume;
60/// `collection_limit` caps the elements in one sequence or map. This is the
61/// `rustbinary` 0.1.7 `Config`-based entry point for untrusted input; the
62/// plain [`decode`] uses the crate-wide defaults (64 MiB / 1,000,000).
63pub fn decode_bounded<'de, T: NsonDeserialize<'de>>(
64    input: &'de [u8],
65    size_limit: u64,
66    collection_limit: u64,
67) -> BinaryResult<T> {
68    rustbinary::options()
69        .with_limit(size_limit)
70        .with_collection_limit(collection_limit)
71        .deserialize(input)
72}
73
74/// Encode into a caller-owned slice without codec-owned allocation.
75///
76/// Returns the number of bytes written; `Error::BufferTooSmall` carries the
77/// exact required capacity when `output` is undersized.
78pub fn encode_into_slice<T: NsonSerialize + ?Sized>(
79    output: &mut [u8],
80    value: &T,
81) -> BinaryResult<usize> {
82    rustbinary::serialize_into_slice(output, value)
83}
84
85/// Exact serialized byte count without allocating output.
86pub fn encoded_size<T: NsonSerialize + ?Sized>(value: &T) -> BinaryResult<u64> {
87    rustbinary::serialized_size(value)
88}
tzcraft/binary.rs

tzcraft/
binary.rs
