pub const MAGIC_AND_VERSION: [u8;
crate::internal_core::contract::VALUE_ENVELOPE_MAGIC_AND_VERSION.len()] =
crate::internal_core::contract::VALUE_ENVELOPE_MAGIC_AND_VERSION;
pub const MAX_ENCODING_BYTES: usize =
crate::internal_core::contract::VALUE_ENVELOPE_MAX_ENCODING_BYTES;
pub const MAX_TYPE_NAME_BYTES: usize =
crate::internal_core::contract::VALUE_ENVELOPE_MAX_TYPE_NAME_BYTES;
const LENGTH_FIELD_BYTES: usize = std::mem::size_of::<u16>();
const ENCODING_LENGTH_OFFSET: usize = MAGIC_AND_VERSION.len();
const TYPE_NAME_LENGTH_OFFSET: usize = ENCODING_LENGTH_OFFSET + LENGTH_FIELD_BYTES;
const HEADER_BYTES: usize = TYPE_NAME_LENGTH_OFFSET + LENGTH_FIELD_BYTES;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ValueEnvelope<'a> {
pub encoding: &'a str,
pub type_name: &'a str,
pub payload: &'a [u8],
}
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
#[error("invalid value encoding {encoding:?}")]
InvalidEncoding {
encoding: String,
},
#[error("value type name contains {size} bytes, maximum is {maximum}")]
TypeNameTooLong {
size: usize,
maximum: usize,
},
#[error("value envelope length overflow")]
LengthOverflow,
#[error("failed to allocate {size} bytes for value envelope")]
Allocation {
size: usize,
},
#[error("value envelope contains {size} bytes, header requires {minimum}")]
HeaderTruncated {
size: usize,
minimum: usize,
},
#[error("unsupported value envelope magic or version {found:02x?}")]
UnsupportedMagicOrVersion {
found: [u8; MAGIC_AND_VERSION.len()],
},
#[error("value envelope metadata requires {required} bytes, input contains {actual}")]
MetadataTruncated {
required: usize,
actual: usize,
},
#[error("value encoding is not valid UTF-8: {0}")]
EncodingUtf8(#[source] std::str::Utf8Error),
#[error("value type name is not valid UTF-8: {0}")]
TypeNameUtf8(#[source] std::str::Utf8Error),
}
pub type Result<T> = std::result::Result<T, Error>;
pub fn encode(encoding: &str, type_name: &str, payload: &[u8]) -> Result<Vec<u8>> {
validate_encoding(encoding)?;
if type_name.len() > MAX_TYPE_NAME_BYTES {
return Err(Error::TypeNameTooLong {
size: type_name.len(),
maximum: MAX_TYPE_NAME_BYTES,
});
}
let type_name_length = u16::try_from(type_name.len()).map_err(|_| Error::TypeNameTooLong {
size: type_name.len(),
maximum: MAX_TYPE_NAME_BYTES,
})?;
let total_length = HEADER_BYTES
.checked_add(encoding.len())
.and_then(|length| length.checked_add(type_name.len()))
.and_then(|length| length.checked_add(payload.len()))
.ok_or(Error::LengthOverflow)?;
let mut bytes = Vec::new();
bytes
.try_reserve_exact(total_length)
.map_err(|_| Error::Allocation { size: total_length })?;
bytes.extend_from_slice(&MAGIC_AND_VERSION);
bytes.extend_from_slice(
&u16::try_from(encoding.len())
.map_err(|_| Error::InvalidEncoding {
encoding: encoding.to_owned(),
})?
.to_be_bytes(),
);
bytes.extend_from_slice(&type_name_length.to_be_bytes());
bytes.extend_from_slice(encoding.as_bytes());
bytes.extend_from_slice(type_name.as_bytes());
bytes.extend_from_slice(payload);
Ok(bytes)
}
pub fn decode(bytes: &[u8]) -> Result<ValueEnvelope<'_>> {
if bytes.len() < HEADER_BYTES {
return Err(Error::HeaderTruncated {
size: bytes.len(),
minimum: HEADER_BYTES,
});
}
let mut found = [0; MAGIC_AND_VERSION.len()];
found.copy_from_slice(&bytes[..MAGIC_AND_VERSION.len()]);
if found != MAGIC_AND_VERSION {
return Err(Error::UnsupportedMagicOrVersion { found });
}
let encoding_length = decode_length(bytes, ENCODING_LENGTH_OFFSET);
let type_name_length = decode_length(bytes, TYPE_NAME_LENGTH_OFFSET);
let payload_offset = HEADER_BYTES
.checked_add(encoding_length)
.and_then(|length| length.checked_add(type_name_length))
.ok_or(Error::LengthOverflow)?;
if payload_offset > bytes.len() {
return Err(Error::MetadataTruncated {
required: payload_offset,
actual: bytes.len(),
});
}
let encoding_end = HEADER_BYTES + encoding_length;
let encoding =
std::str::from_utf8(&bytes[HEADER_BYTES..encoding_end]).map_err(Error::EncodingUtf8)?;
validate_encoding(encoding)?;
let type_name =
std::str::from_utf8(&bytes[encoding_end..payload_offset]).map_err(Error::TypeNameUtf8)?;
if type_name.len() > MAX_TYPE_NAME_BYTES {
return Err(Error::TypeNameTooLong {
size: type_name.len(),
maximum: MAX_TYPE_NAME_BYTES,
});
}
Ok(ValueEnvelope {
encoding,
type_name,
payload: &bytes[payload_offset..],
})
}
fn decode_length(bytes: &[u8], offset: usize) -> usize {
u16::from_be_bytes([bytes[offset], bytes[offset + 1]]) as usize
}
fn validate_encoding(encoding: &str) -> Result<()> {
let bytes = encoding.as_bytes();
let valid = (1..=MAX_ENCODING_BYTES).contains(&bytes.len())
&& bytes[0].is_ascii_lowercase()
&& bytes[1..].iter().all(|byte| {
byte.is_ascii_lowercase() || byte.is_ascii_digit() || matches!(byte, b'.' | b'-')
});
if valid {
Ok(())
} else {
Err(Error::InvalidEncoding {
encoding: encoding.to_owned(),
})
}
}