macro_rules! wire_enum {
(
$(#[$metadata:meta])*
pub enum $name:ident {
$($variant:ident = $value:expr),+ $(,)?
}
unknown => $unknown:ident
) => {
$(#[$metadata])*
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[repr(u8)]
pub enum $name {
$($variant = $value),+
}
impl TryFrom<u8> for $name {
type Error = ProtocolError;
fn try_from(value: u8) -> Result<Self> {
match value {
$(value if value == Self::$variant as u8 => Ok(Self::$variant),)+
_ => Err(ProtocolError::$unknown(value)),
}
}
}
};
}
include!("contract_snapshot/wire_values.rs");
impl Status {
pub const fn is_error(self) -> bool {
(self as u8) >= ERROR_STATUS_MINIMUM
}
}
pub mod operation {
use super::{Opcode, OptionalValueCodec, Status};
include!("contract_snapshot/operation_contract.rs");
}
pub use operation::{
MAX_OPERATION_FIELDS, MAX_OPERATION_REQUEST_FIELDS, MAX_REQUEST_FRAME_BYTES,
OPERATION_CODEC_NAMES, OperationFieldLayout, OperationFieldPlan, OperationFramePolicy,
OperationLayoutFraming, OperationLayoutPlan, OperationRequestFraming, OperationResponseFraming,
OperationWireSpec, WIRE_CODEC_DESCRIPTORS, WIRE_CODEC_NAMES, WireCodecCardinality,
WireCodecDescriptor, WireCodecKind, WireCodecLengthEncoding, WireCodecWidth,
operation_registry, operation_wire_spec, request_fields, response_fields, wire_codec_kind,
wire_request_layout,
};
pub mod compat_v1;
pub mod codec;
pub mod compact;
pub mod layout;
pub mod optional_values;
pub mod owner_pool;
pub mod request;
mod request_encoder;
pub mod response;
pub mod segments;
pub use compact::{
FieldSequenceView, LengthDelimitedView, decode_varuint, decode_vu128, encode_varuint,
encode_vu128, read_length_delimited,
};
pub use layout::{
DenseFields, decode_planned_fields, encode_dense_fields, encode_planned_field_segments,
encode_planned_fields,
};
pub use optional_values::{
OptionalValueCodec, OptionalValues, OptionalValuesEncoder, decode_optional_values,
encode_optional_values, optional_values_encoded_len, optional_values_encoded_len_from_lengths,
optional_values_max_encoded_len,
};
pub use owner_pool::{StableOwnerLease, StableOwnerPool};
pub use request::{
OpaqueRequestFrame, RequestFieldProjection, RequestFrameHeader, RequestFrameLayout,
RequestFramePackedField, RequestFramePackedValue, RequestFrameStep,
decode_request_frame_header, project_request_frame, project_request_frame_header,
};
pub use request_encoder::{encode_request_frame, encode_request_frame_with_id};
pub use response::{
OwnedResponseFrame, Response, ResponseFrame, ResponseHeader, ResponseHeaderBytes, ResponseParts,
};
pub use segments::{
InlineBytes, OwnedFrame, OwnedRange, OwnedRequestFrame, ResponseSegment, SegmentFrame,
StableByteOwner, StableBytes, WireByteOwner, WireSegment,
};
pub const MAX_ITEM_ID_BYTES: usize = ITEM_ID_BYTES;
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct ItemId {
len: u8,
bytes: [u8; ITEM_ID_BYTES],
}
impl ItemId {
pub const fn new(bytes: [u8; ITEM_ID_BYTES]) -> Self {
Self {
len: ITEM_ID_BYTES as u8,
bytes,
}
}
pub fn from_slice(bytes: &[u8]) -> Result<Self> {
if bytes.len() > MAX_ITEM_ID_BYTES {
return Err(ProtocolError::InvalidItemIdLength {
maximum: MAX_ITEM_ID_BYTES,
actual: bytes.len(),
});
}
let mut item_id = Self {
len: bytes.len() as u8,
bytes: [0; ITEM_ID_BYTES],
};
item_id.bytes[..bytes.len()].copy_from_slice(bytes);
Ok(item_id)
}
pub const fn len(&self) -> usize {
self.len as usize
}
pub const fn is_empty(&self) -> bool {
self.len == 0
}
pub fn as_bytes(&self) -> &[u8] {
&self.bytes[..self.len as usize]
}
pub fn into_bytes(self) -> Vec<u8> {
self.as_bytes().to_vec()
}
}
impl AsRef<[u8]> for ItemId {
fn as_ref(&self) -> &[u8] {
self.as_bytes()
}
}
pub fn encode_field_sequence(values: &[Option<&[u8]>]) -> Result<Vec<u8>> {
let mask_bytes = values.len().saturating_add(7) / 8;
if mask_bytes > MAX_VALUE_BYTES {
return Err(ProtocolError::ValueTooLarge {
size: mask_bytes,
maximum: MAX_VALUE_BYTES,
});
}
let capacity = field_sequence_encoded_len(values)?;
let mut payload = Vec::with_capacity(capacity);
append_field_sequence(values, &mut payload)?;
debug_assert_eq!(payload.len(), capacity);
Ok(payload)
}
fn append_field_sequence(values: &[Option<&[u8]>], payload: &mut Vec<u8>) -> Result<()> {
let mask_bytes = values.len().saturating_add(7) / 8;
let mask_start = payload.len();
payload.resize(
mask_start
.checked_add(mask_bytes)
.ok_or(ProtocolError::FrameLengthOverflow)?,
0,
);
let last_present = values.iter().rposition(Option::is_some);
for (index, value) in values.iter().enumerate() {
let Some(value) = value else {
continue;
};
validate_value_length(value.len())?;
payload[mask_start + index / 8] |= 1 << (index % 8);
let (encoded, encoded_len) = encode_varuint(
u64::try_from(value.len()).map_err(|_| ProtocolError::FrameLengthOverflow)?,
);
if Some(index) != last_present {
payload.extend_from_slice(&encoded[..encoded_len]);
}
payload.extend_from_slice(value);
}
validate_value_length(payload.len())?;
Ok(())
}
pub fn field_sequence_encoded_len(values: &[Option<&[u8]>]) -> Result<usize> {
field_sequence_encoded_len_iter(values.iter().map(|value| value.map(<[u8]>::len)))
}
pub fn field_sequence_encoded_len_from_lengths(lengths: &[Option<usize>]) -> Result<usize> {
field_sequence_encoded_len_iter(lengths.iter().copied())
}
fn field_sequence_encoded_len_iter(lengths: impl Iterator<Item = Option<usize>>) -> Result<usize> {
let mut field_count = 0usize;
let mut encoded_len = 0usize;
let mut pending_length = None;
for length in lengths {
field_count = field_count
.checked_add(1)
.ok_or(ProtocolError::FrameLengthOverflow)?;
let Some(length) = length else {
continue;
};
validate_value_length(length)?;
if let Some(previous_length) = pending_length.replace(length) {
encoded_len = encoded_len
.checked_add(
encode_varuint(
u64::try_from(previous_length)
.map_err(|_| ProtocolError::FrameLengthOverflow)?,
)
.1,
)
.and_then(|total| total.checked_add(previous_length))
.ok_or(ProtocolError::FrameLengthOverflow)?;
}
}
if let Some(last_length) = pending_length {
encoded_len = encoded_len
.checked_add(last_length)
.ok_or(ProtocolError::FrameLengthOverflow)?;
}
let mask_bytes = field_count.saturating_add(7) / 8;
if mask_bytes > MAX_VALUE_BYTES {
return Err(ProtocolError::ValueTooLarge {
size: mask_bytes,
maximum: MAX_VALUE_BYTES,
});
}
let total = mask_bytes
.checked_add(encoded_len)
.ok_or(ProtocolError::FrameLengthOverflow)?;
validate_value_length(total)?;
Ok(total)
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct FieldSequence<'a, 'b> {
payload: &'a [u8],
offsets: &'b [(usize, usize)],
field_count: usize,
}
impl<'a, 'b> FieldSequence<'a, 'b> {
fn validate_entries(
payload: &[u8],
field_count: usize,
required: Option<&[bool]>,
mut offsets: Option<&mut [(usize, usize)]>,
) -> Result<()> {
if let Some(required) = required {
if required.len() != field_count {
return Err(ProtocolError::InvalidFieldSequence(
"requiredness does not match the modeled field count",
));
}
}
if offsets
.as_ref()
.is_some_and(|offsets| offsets.len() < field_count)
{
return Err(ProtocolError::InvalidFieldSequence(
"field offset storage is smaller than the modeled field count",
));
}
let mask_bytes = field_count.saturating_add(7) / 8;
if payload.len() < mask_bytes {
return Err(ProtocolError::InvalidFieldSequence(
"field sequence is missing its presence mask",
));
}
validate_value_length(payload.len())?;
if mask_bytes > 0 && field_count % 8 != 0 {
let unused = payload[mask_bytes - 1] & !((1 << (field_count % 8)) - 1);
if unused != 0 {
return Err(ProtocolError::InvalidFieldSequence(
"field sequence presence mask has unused bits set",
));
}
}
let last_present = (0..field_count)
.rev()
.find(|&index| payload[index / 8] & (1 << (index % 8)) != 0);
let mut cursor = mask_bytes;
for index in 0..field_count {
let present = payload[index / 8] & (1 << (index % 8)) != 0;
if !present {
if required.is_some_and(|required| required[index]) {
return Err(ProtocolError::InvalidFieldSequence(
"required field is missing from the field sequence",
));
}
if let Some(offsets) = offsets.as_deref_mut() {
offsets[index] = (usize::MAX, usize::MAX);
}
continue;
}
if Some(index) == last_present {
let end = payload.len();
let length = end
.checked_sub(cursor)
.ok_or(ProtocolError::FrameLengthOverflow)?;
validate_value_length(length)?;
if let Some(offsets) = offsets.as_deref_mut() {
offsets[index] = (cursor, end);
}
cursor = end;
continue;
}
let Some((length, encoded_len)) = decode_varuint(
payload
.get(cursor..)
.ok_or(ProtocolError::InvalidFieldSequence(
"field sequence entry is truncated",
))?,
"field sequence length",
)?
else {
return Err(ProtocolError::InvalidFieldSequence(
"field sequence entry is missing its length",
));
};
let length = usize::try_from(length).map_err(|_| ProtocolError::FrameLengthOverflow)?;
cursor = cursor
.checked_add(encoded_len)
.ok_or(ProtocolError::FrameLengthOverflow)?;
validate_value_length(length)?;
let end = cursor
.checked_add(length)
.ok_or(ProtocolError::FrameLengthOverflow)?;
if payload.get(cursor..end).is_none() {
return Err(ProtocolError::InvalidFieldSequence(
"field sequence entry is truncated",
));
}
if let Some(offsets) = offsets.as_deref_mut() {
offsets[index] = (cursor, end);
}
cursor = end;
}
if cursor != payload.len() {
return Err(ProtocolError::InvalidFieldSequence(
"field sequence contains trailing bytes",
));
}
Ok(())
}
pub fn validate(payload: &[u8], field_count: usize) -> Result<()> {
Self::validate_entries(payload, field_count, None, None)
}
pub fn validate_with_required(payload: &[u8], required: &[bool]) -> Result<()> {
Self::validate_entries(payload, required.len(), Some(required), None)
}
pub fn decode(
payload: &'a [u8],
field_count: usize,
offsets: &'b mut [(usize, usize)],
) -> Result<Self> {
Self::validate_entries(payload, field_count, None, Some(offsets))?;
Ok(Self {
payload,
offsets: &offsets[..field_count],
field_count,
})
}
pub fn decode_with_required(
payload: &'a [u8],
required: &[bool],
offsets: &'b mut [(usize, usize)],
) -> Result<Self> {
Self::validate_entries(payload, required.len(), Some(required), Some(offsets))?;
Ok(Self {
payload,
offsets: &offsets[..required.len()],
field_count: required.len(),
})
}
pub const fn len(self) -> usize {
self.field_count
}
pub fn get(self, index: usize) -> Option<&'a [u8]> {
if index >= self.field_count {
return None;
}
let (start, end) = *self.offsets.get(index)?;
if start == usize::MAX {
None
} else {
Some(&self.payload[start..end])
}
}
}
pub fn encode_field_groups(groups: &[&[Option<&[u8]>]]) -> Result<Vec<u8>> {
let outer_mask_bytes = groups.len().saturating_add(7) / 8;
let mut encoded_len = outer_mask_bytes;
for (index, group) in groups.iter().enumerate() {
let group_len = field_sequence_encoded_len(group)?;
let prefix_len = if index + 1 < groups.len() {
let group_len_u64 =
u64::try_from(group_len).map_err(|_| ProtocolError::FrameLengthOverflow)?;
encode_varuint(group_len_u64).1
} else {
0
};
encoded_len = encoded_len
.checked_add(prefix_len)
.and_then(|length| length.checked_add(group_len))
.ok_or(ProtocolError::FrameLengthOverflow)?;
}
validate_value_length(encoded_len)?;
let mut payload = Vec::with_capacity(encoded_len);
payload.resize(outer_mask_bytes, 0);
for (index, group) in groups.iter().enumerate() {
let group_len = field_sequence_encoded_len(group)?;
payload[index / 8] |= 1 << (index % 8);
let (encoded, prefix_len) = if index + 1 < groups.len() {
let group_len_u64 =
u64::try_from(group_len).map_err(|_| ProtocolError::FrameLengthOverflow)?;
encode_varuint(group_len_u64)
} else {
([0; MAX_VARUINT_BYTES], 0)
};
payload.extend_from_slice(&encoded[..prefix_len]);
append_field_sequence(group, &mut payload)?;
}
debug_assert_eq!(payload.len(), encoded_len);
Ok(payload)
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct FieldGroups<'a, 'b> {
payload: &'a [u8],
offsets: &'b [(usize, usize)],
}
impl<'a, 'b> FieldGroups<'a, 'b> {
pub fn decode(
payload: &'a [u8],
group_widths: &[usize],
offsets: &'b mut [(usize, usize)],
) -> Result<Self> {
if offsets.len() < group_widths.len() {
return Err(ProtocolError::InvalidFieldSequence(
"group offset storage is smaller than the modeled group count",
));
}
let outer = FieldSequence::decode(payload, group_widths.len(), offsets)?;
for (index, width) in group_widths.iter().enumerate() {
let group = outer.get(index).ok_or(ProtocolError::InvalidFieldSequence(
"field group is missing",
))?;
validate_field_sequence_payload(group, *width)?;
}
Ok(Self {
payload,
offsets: &offsets[..group_widths.len()],
})
}
pub fn group_payload(self, index: usize) -> Option<&'a [u8]> {
let (start, end) = *self.offsets.get(index)?;
if start == usize::MAX {
None
} else {
Some(&self.payload[start..end])
}
}
}
fn validate_field_sequence_payload(payload: &[u8], field_count: usize) -> Result<()> {
FieldSequence::validate(payload, field_count)
}
fn validate_value_length(value_len: usize) -> Result<()> {
if value_len > MAX_VALUE_BYTES {
return Err(ProtocolError::ValueTooLarge {
size: value_len,
maximum: MAX_VALUE_BYTES,
});
}
Ok(())
}
#[derive(Debug, thiserror::Error)]
pub enum ProtocolError {
#[error("unknown opcode 0x{0:02x}")]
UnknownOpcode(u8),
#[error("unknown status 0x{0:02x}")]
UnknownStatus(u8),
#[error("frame is too short: expected at least {expected} bytes, got {actual}")]
FrameTooShort { expected: usize, actual: usize },
#[error("frame length does not match header: expected {expected} bytes, got {actual}")]
FrameLength { expected: usize, actual: usize },
#[error("frame length overflow")]
FrameLengthOverflow,
#[error("{context} uses a non-canonical vu128 encoding")]
NonCanonicalVaruint { context: &'static str },
#[error("{context} exceeds the supported 64-bit vu128 range")]
VaruintOverflow { context: &'static str },
#[error("value is too large: {size} bytes exceeds {maximum}")]
ValueTooLarge { size: usize, maximum: usize },
#[error("item ID has {actual} bytes; maximum is {maximum}")]
InvalidItemIdLength { maximum: usize, actual: usize },
#[error("request packed byte at offset {offset} violates its bit contract")]
InvalidRequestPackedBits { offset: usize },
#[error("request constant does not match at offset {offset}")]
RequestConstantMismatch { offset: usize },
#[error("invalid optional-value payload: {0}")]
InvalidOptionalValues(&'static str),
#[error("invalid operation field sequence: {0}")]
InvalidFieldSequence(&'static str),
}
pub type Result<T> = std::result::Result<T, ProtocolError>;