Skip to main content

Crate rustbinary

Crate rustbinary 

Source
Expand description

RustBinary is a bounded nextjson binary codec with explicit wire profiles.

Serialization is driven entirely by nextjson’s format-neutral contracts (nextjson::NsonSerialize / nextjson::NsonDeserialize + nextjson::FormatEncoder / nextjson::FormatDecoder), replacing the former Serde dependency. The binary wire format is a type-tagged, self-describing stream: every value carries a one-byte type tag and containers are terminator-delimited, so Option, Value, untagged enums and borrowed strings all round-trip unambiguously.

The top-level functions and options select the strict compact profile: canonical marker varints, ZigZag signed integers, bounded input, and rejected trailing bytes. legacy_options explicitly selects the old fixed-width, unbounded migration profile. Format-changing systems are explicit wrappers, so enabling a Cargo feature never silently changes an existing payload.

§Quick start

use nextjson::{NsonDeserialize, NsonSerialize};

#[derive(Debug, PartialEq, NsonSerialize, NsonDeserialize)]
struct Packet<'a> {
    sequence: u64,
    topic: &'a str,
    #[njson(borrow)]
    note: &'a str,
}

let config = rustbinary::options()
    .with_limit(4096)
    .with_collection_limit(256);
let packet = Packet {
    sequence: 42,
    topic: "telemetry/temperature",
    note: "ok",
};

let mut frame = [0_u8; 256];
let written = config.serialize_into_slice(&mut frame, &packet)?;
let decoded: Packet<'_> = config.deserialize(&frame[..written])?;
assert_eq!(decoded, packet);

Borrowed strings point into the input frame. Owned targets such as String and Vec<T> may allocate as required by their type.

§Format selection

  • Config is the core binary profile (type-tagged, self-describing).
  • compact is a schema-guided compact profile for statically typed values: no per-value tags, no field names, length-prefixed containers, and byte/float/string fast paths. Select it with Config::with_compact_format and derive CompactEncode/CompactDecode with #[derive(rustbinary::CompactBinary)].
  • adaptive contains canonical cost-selected string and integer frames.
  • bitpack provides generated bit-level layouts.
  • cbor provides RFC 8949 payloads and deterministic map ordering.
  • evolution provides stable-field-ID schema evolution.
  • compression and encryption form an ordered transform pipeline.
  • parallel encodes independent records into deterministic batch frames.

§Untrusted input

Always set both Config::with_limit and Config::with_collection_limit at trust boundaries. Encryption authenticates bytes but does not replace resource limits. Schema fingerprints detect accidental type/configuration drift; they are not cryptographic hashes.

Re-exports§

pub use adaptive::AdaptiveConfig;adaptive
pub use adaptive::AdaptiveMode;adaptive
pub use adaptive::CollectionStrategy;adaptive
pub use adaptive::StringStrategy;adaptive
pub use adaptive::HEURISTIC_SAMPLE;adaptive
pub use bitpack::BitPack;bit-packing
pub use bitpack::BitPackedConfig;bit-packing
pub use bitpack::BitReader;bit-packing
pub use bitpack::BitValue;bit-packing
pub use bitpack::BitWriter;bit-packing
pub use bounded::decode_bounded;bounded
pub use bounded::Budget;bounded
pub use bounded::BudgetExceeded;bounded
pub use bounded::DecodeBounded;bounded
pub use bounded::DecodeError;bounded
pub use bounded::Decoded;bounded
pub use bounded::ResourceUse;bounded
pub use bounded::ELEMENT_STRUCTURE_BYTES;bounded
pub use cbor::CborConfig;cbor
pub use cbor::FingerprintedCborConfig;cbor and fingerprint
pub use compact::CompactConfig;compact
pub use compact::CompactCursor;compact
pub use compact::CompactDecode;compact
pub use compact::CompactEncode;compact
pub use compression::CompressedConfig;compression
pub use config::BinaryProfile;
pub use config::Config;
pub use config::Endian;
pub use config::IntEncoding;
pub use config::Options;
pub use config::TrailingBytes;
pub use config::DEFAULT_COLLECTION_LIMIT;
pub use config::DEFAULT_SIZE_LIMIT;
pub use delta::DeltaConfig;reconcile
pub use delta::DeltaTable;reconcile
pub use encryption::EncryptedConfig;encryption
pub use encryption::EncryptionKey;encryption
pub use error::Error;
pub use error::ErrorCategory;
pub use error::Result;
pub use evolution::EvolutionConfig;schema-evolution
pub use evolution::FieldDecoder;schema-evolution
pub use evolution::FieldEncoder;schema-evolution
pub use evolution::SchemaDecode;schema-evolution
pub use evolution::SchemaEncode;schema-evolution
pub use evolution::UnknownField;schema-evolution
pub use ibl::encode_set;reconcile
pub use ibl::reconcile;reconcile
pub use ibl::splitmix64;reconcile
pub use ibl::Cell;reconcile
pub use ibl::Iblt;reconcile
pub use ibl::IbltEntry;reconcile
pub use parallel::ParallelConfig;parallel
pub use probe::probe;
pub use probe::Probe;
pub use projection::prove;projection
pub use projection::schema_root;projection
pub use projection::verify;projection
pub use projection::verify_query;projection
pub use projection::verify_untrusted;projection
pub use projection::Projection;projection
pub use projection::ProjectionError;projection
pub use projection::ProjectionLimits;projection
pub use projection::ProjectionProof;projection
pub use projection::ProofLeaf;projection
pub use projection::ProofSibling;projection
pub use projection::Record as ProjectedRecord;projection
pub use projection::RecordBuilder;projection
pub use projection::VerifiedField;projection
pub use projection::DEFAULT_MAX_FIELDS;projection
pub use projection::DEFAULT_MAX_PAYLOAD_LEN;projection
pub use projection::DEFAULT_MAX_RECORD_LEN;projection
pub use rans::EntropyConfig;entropy
pub use rans::FieldModel;entropy
pub use rans::Model;entropy
pub use rans::RansDecoder;entropy
pub use rans::RansEncoder;entropy
pub use rans::SchemaModel;entropy
pub use rans::RANS_M;entropy
pub use reflection::FieldInfo;reflection
pub use reflection::Reflect;reflection
pub use reflection::TypeShape;reflection
pub use reflection::VariantInfo;reflection
pub use schema::Fingerprint;fingerprint
pub use schema::FingerprintedConfig;fingerprint
pub use simd::hardware_capabilities;simd
pub use simd::simd_backend;simd
pub use simd::HardwareCapabilities;simd
pub use simd::SimdBackend;simd
pub use static_size::StaticSize;static-size
pub use trust::AuthLevel;trust
pub use trust::Authenticated;trust
pub use trust::Closed;trust
pub use trust::Codec;trust
pub use trust::TrustedConfig;trust
pub use trust::Untrusted;trust
pub use trust::Verified;trust
pub use trust::Verifier;trust
pub use trust::Handshake;std and trust
pub use trust::Session;std and trust
pub use writer::CountWriter;
pub use writer::EncodeWriter;
pub use writer::SliceWriter;

Modules§

adaptersstd
Bridges between the slice-based core and std::io readers and writers. Standard-library adapters around the no_std Compact V1 core.
adaptiveadaptive
Canonical data-aware encodings for strings and integer collections.
archivearchive
Validated relative-pointer archives for read-only memory mapping. Validated relative-pointer archives for read-only memory mapping.
archive_codecarchive
In-tree zero-copy archive codec (replaces the rkyv dependency). In-tree zero-copy archive codec (replaces the rkyv dependency).
bitpackbit-packing
Bit-level caller-buffer codecs and the BitPack contract.
boundedbounded
Resource-bounded decoding with a schema-derived cost algebra. Parser budgets and schema estimates for the self-describing profile. Runtime limits cover bytes, cumulative reads, global tokens, collection size and container depth. Depth alone does not bound branching.
cborcbor
RFC 8949 CBOR configuration and deterministic encoding. CBOR configuration over the native streaming codec. Supports the JSON-compatible RFC 8949 subset, native byte strings and bignums. Byte, per-collection and configured depth limits apply; trailing bytes are rejected by default. Custom trait allocations are outside these limits.
compactcompact
Schema-guided compact binary profile (no tags, no field names, length-prefixed containers). Schema-guided binary encoding through CompactEncode and CompactDecode. Fields have no type tags or names; both sides must use the same schema. Dynamic nextjson values use the separate self-describing profile.
compressioncompression
Adaptive lossless compression framing.
config
Core wire-profile configuration.
core
Minimal stable binary codec product surface. Minimal stable binary format and resource-policy API.
deltareconcile
Baseline-relative differential frames for ordered state. Differential frames for gossip and consensus state exchange.
encryptionencryption
Authenticated XChaCha20-Poly1305 framing.
error
Codec result and error types.
evolutionschema-evolution
Stable-field-ID schema evolution.
iblreconcile
Invertible Bloom Lookup Tables for unordered set reconciliation. Invertible Bloom Lookup Tables (IBLT) for set reconciliation.
parallelparallel
Ordered multi-core batch encoding and decoding.
pipeline
Optional transform product surface. Opt-in CBOR, compression, encryption, and parallel transform APIs.
probe
Exact structural probe for one value (allocation-free preflight). Allocation-free structural inspection using the self-describing decoder’s parser. Reports consumed bytes, containers, elements and maximum depth, with the same wire validation and limits as decoding. Target-type compatibility and work spent on speculative deserialization still require a full decode.
projectionprojection
Projectable self-authenticating records with projection soundness. Merkle membership proofs for projectable binary records.
protocol
Schema and wire-governance product surface. Opt-in schema, compatibility, and compact-layout governance APIs.
ransentropy
Static-model rANS entropy coding driven by schema metadata. Static-model rANS entropy coding driven by compile-time schema metadata.
reflectionreflection
Allocation-free structural metadata generated by Reflect.
schemafingerprint
Compile-time schema identity and fingerprinted frame support.
simdsimd
Runtime-dispatched SIMD primitives used by codec hot paths.
static_sizestatic-size
Compile-time upper bounds for statically sized data.
trusttrust
Type-level trust calculus and session state machine. Type-level trust calculus: unauthenticated deserialization is unrepresentable.
writer
Core output sinks for caller-owned and counting serialization.

Traits§

NsonDeserializederive
Re-exports nextjson’s format-neutral serialization contracts.
NsonSchemaderive
Re-exports nextjson’s format-neutral serialization contracts.
NsonSerializederive
Re-exports nextjson’s format-neutral serialization contracts.

Functions§

deserialize
Deserializes from a slice with the bounded compact Core profile.
deserialize_fromstd
Deserializes an owned value from a reader with the bounded compact Core profile.
legacy_options
Returns the fixed-width compatibility profile used by the top-level API.
options
Returns the standard compact profile.
serialize
Serializes a value with the bounded compact Core profile.
serialize_intostd
Serializes a value directly into a writer with the bounded compact Core profile.
serialize_into_slice
Serializes into a caller-owned slice without codec-owned heap allocation.
serialized_size
Computes the exact serialized byte count without allocating an output buffer.

Derive Macros§

Archivearchive and derive
Derives the zero-copy archived mirror used by rustbinary::archive::build / OwnedArchive / MappedArchive.
BitPackedbit-packing and derive
Derives rustbinary::BitPack for structs and enums.
CompactBinarycompact and derive
Derives rustbinary::compact::CompactEncode and rustbinary::compact::CompactDecode — the schema-guided compact binary profile.
DecodeBoundedbounded and derive
Derives rustbinary::DecodeBounded, the schema-derived resource cost algebra (B, A, D, W) = (max input bytes, max allocation, max nesting depth, max work) that mirrors the parser structure.
Fingerprintderive and fingerprint
Derives rustbinary::Fingerprint from structural type metadata.
NsonDeserializederive
Re-exports nextjson’s format-neutral serialization contracts.
NsonSerializederive
Re-exports nextjson’s format-neutral serialization contracts.
Reflectderive and reflection
Derives allocation-free structural reflection metadata.
Serializearchive and derive
Derives rustbinary::archive_codec::ArchiveWrite, the two-phase archive serializer (skeleton pass then bodies pass).
StaticSizederive and static-size
Derives compile-time normal and bit-packed size bounds.