#![doc = include_str!("../README.md")]
#![forbid(unsafe_code)]
use std::fmt::Debug;
use logit_loom_core::{CoreError, Digest};
use serde::{Deserialize, Serialize};
mod whole;
pub use whole::{
ClassifiedWholeGenerationError, DurabilityReceipt, MAX_WHOLE_GENERATION_EVIDENCE,
MAX_WHOLE_GENERATION_EVIDENCE_BYTES, MAX_WHOLE_GENERATION_INPUT_BYTES,
MAX_WHOLE_GENERATION_OUTPUT_BYTES, PendingGeneration, ProviderOwnedGenerationPlan,
ProviderOwnedSampler, WholeGenerationBackend, WholeGenerationCommitReceipt,
WholeGenerationEvidence, WholeGenerationFailure, WholeGenerationOutput, WholeGenerationPlan,
WholeGenerationReceipt, WholeGenerationRequest,
};
pub const MAX_MEDIA_TYPE_BYTES: usize = 128;
pub const MAX_EXECUTION_BUFFERS: usize = 64;
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ExecutorState {
Unloaded,
Resident,
Busy,
Poisoned,
Closed,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum FailureDisposition {
Rejected,
Cancelled,
Poisoned,
}
pub trait ClassifiedExecutionError: std::error::Error {
fn disposition(&self) -> FailureDisposition;
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BufferSpec {
pub identity: Digest,
pub byte_length: u64,
pub media_type: String,
}
impl BufferSpec {
pub fn new(
identity: Digest,
byte_length: u64,
media_type: impl Into<String>,
) -> Result<Self, CoreError> {
let value = Self {
identity,
byte_length,
media_type: media_type.into(),
};
value.validate()?;
Ok(value)
}
pub fn validate(&self) -> Result<(), CoreError> {
if self.byte_length == 0 {
return Err(CoreError::invalid(
"executor buffer length",
"must be positive",
));
}
if self.media_type.is_empty()
|| self.media_type.len() > MAX_MEDIA_TYPE_BYTES
|| self.media_type.contains('\0')
{
return Err(CoreError::invalid(
"executor buffer media type",
format!("must be non-empty, NUL-free, and at most {MAX_MEDIA_TYPE_BYTES} bytes"),
));
}
Ok(())
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("executor-buffer-spec-v1", self)
}
}
#[derive(Debug)]
pub struct InputBuffer<'a> {
specification: &'a BufferSpec,
bytes: &'a [u8],
}
impl<'a> InputBuffer<'a> {
pub fn new(specification: &'a BufferSpec, bytes: &'a [u8]) -> Result<Self, CoreError> {
specification.validate()?;
let actual = u64::try_from(bytes.len())
.map_err(|_| CoreError::invalid("executor input length", "exceeds u64"))?;
if actual != specification.byte_length {
return Err(CoreError::invalid(
"executor input length",
"does not match the exact buffer specification",
));
}
Ok(Self {
specification,
bytes,
})
}
pub const fn specification(&self) -> &BufferSpec {
self.specification
}
pub const fn bytes(&self) -> &[u8] {
self.bytes
}
}
#[derive(Debug)]
pub struct OutputBuffer<'a> {
specification: &'a BufferSpec,
bytes: &'a mut [u8],
written: usize,
}
impl<'a> OutputBuffer<'a> {
pub fn new(specification: &'a BufferSpec, bytes: &'a mut [u8]) -> Result<Self, CoreError> {
specification.validate()?;
let actual = u64::try_from(bytes.len())
.map_err(|_| CoreError::invalid("executor output length", "exceeds u64"))?;
if actual != specification.byte_length {
return Err(CoreError::invalid(
"executor output length",
"does not match the exact buffer specification",
));
}
Ok(Self {
specification,
bytes,
written: 0,
})
}
pub const fn specification(&self) -> &BufferSpec {
self.specification
}
pub fn bytes_mut(&mut self) -> &mut [u8] {
self.bytes
}
pub fn set_written(&mut self, written: usize) -> Result<(), CoreError> {
if written > self.bytes.len() {
return Err(CoreError::invalid(
"executor output written length",
"exceeds the output allocation",
));
}
self.written = written;
Ok(())
}
pub const fn written(&self) -> usize {
self.written
}
pub fn initialized(&self) -> &[u8] {
&self.bytes[..self.written]
}
}
pub trait CancellationProbe {
fn is_cancelled(&self) -> bool;
}
#[derive(Clone, Copy, Debug, Default)]
pub struct NeverCancel;
impl CancellationProbe for NeverCancel {
fn is_cancelled(&self) -> bool {
false
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CleanupReceipt {
pub backend: Digest,
pub cleared_epoch: u64,
pub confirmed: bool,
}
impl CleanupReceipt {
pub fn validate(&self) -> Result<(), CoreError> {
if !self.confirmed {
return Err(CoreError::invalid(
"executor cleanup receipt",
"cleanup was not confirmed",
));
}
Ok(())
}
}
pub trait LocalExecutor {
type Plan;
type Receipt;
type Error: ClassifiedExecutionError;
fn state(&self) -> ExecutorState;
fn warm(
&mut self,
plan: &Self::Plan,
cancellation: &dyn CancellationProbe,
) -> Result<Self::Receipt, Self::Error>;
fn execute(
&mut self,
plan: &Self::Plan,
inputs: &[InputBuffer<'_>],
outputs: &mut [OutputBuffer<'_>],
cancellation: &dyn CancellationProbe,
) -> Result<Self::Receipt, Self::Error>;
fn clear_session(&mut self) -> Result<CleanupReceipt, Self::Error>;
fn close(self) -> Result<CleanupReceipt, Self::Error>
where
Self: Sized;
}
pub trait LocalExecutorFactory {
type LoadPlan;
type Executor: LocalExecutor;
type Error: ClassifiedExecutionError;
fn load(
&self,
plan: &Self::LoadPlan,
artifacts: &[InputBuffer<'_>],
) -> Result<Self::Executor, Self::Error>;
}
#[cfg(test)]
mod tests {
use super::*;
fn specification(length: u64) -> BufferSpec {
BufferSpec::new(
Digest::of_bytes("test-buffer", b"bytes"),
length,
"application/octet-stream",
)
.unwrap()
}
#[test]
fn borrowed_buffers_require_exact_lengths() {
let specification = specification(3);
assert!(InputBuffer::new(&specification, b"abc").is_ok());
assert!(InputBuffer::new(&specification, b"ab").is_err());
let mut exact = [0_u8; 3];
assert!(OutputBuffer::new(&specification, &mut exact).is_ok());
let mut short = [0_u8; 2];
assert!(OutputBuffer::new(&specification, &mut short).is_err());
}
#[test]
fn output_tracks_only_the_initialized_prefix() {
let specification = specification(4);
let mut storage = [0_u8; 4];
let mut output = OutputBuffer::new(&specification, &mut storage).unwrap();
output.bytes_mut()[..2].copy_from_slice(b"ok");
output.set_written(2).unwrap();
assert_eq!(output.initialized(), b"ok");
assert!(output.set_written(5).is_err());
}
#[test]
fn metadata_round_trips_and_rejects_nul() {
let specification = specification(7);
let json = serde_json::to_string(&specification).unwrap();
assert_eq!(
serde_json::from_str::<BufferSpec>(&json).unwrap(),
specification
);
assert!(BufferSpec::new(Digest::of_bytes("test-buffer", b"x"), 1, "bad\0type").is_err());
}
}