mirror of
https://github.com/Astatin3/unshell.git
synced 2026-06-09 06:47:59 -06:00
Michael Mikovsky
688 lines
23 KiB
Rust
688 lines
23 KiB
Rust
//! Stateful application-layer call runtime built on top of `ProtocolEndpoint`.
|
|
|
|
use alloc::{string::String, vec, vec::Vec};
|
|
use core::fmt;
|
|
|
|
use rkyv::{Archive, Serialize, rancor::Error, to_bytes, util::AlignedVec};
|
|
|
|
use crate::protocol::{
|
|
CallMessage, DataMessage, FrameBytes, FrameError, HookTarget, PacketHeader, ProtocolFault,
|
|
};
|
|
|
|
use super::{
|
|
Endpoint, EndpointError, HookKey, Ingress, LocalEvent, ProtocolEndpoint, ProtocolLeaf,
|
|
};
|
|
|
|
/// One typed incoming `Call` passed to a leaf procedure.
|
|
///
|
|
/// This exists so application code can work with a decoded request type plus the protocol context
|
|
/// that matters for authorization, routing, or replies.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::{Call, HookKey};
|
|
/// let call = Call {
|
|
/// input: String::from("hello"),
|
|
/// caller_path: vec!["root".into()],
|
|
/// procedure_id: "org.example.v1.echo.invoke".into(),
|
|
/// dst_leaf: Some("echo".into()),
|
|
/// response_hook: Some(HookKey::new(vec!["root".into()], 7)),
|
|
/// };
|
|
/// assert_eq!(call.input, "hello");
|
|
/// ```
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct Call<T> {
|
|
/// Decoded application input payload.
|
|
pub input: T,
|
|
/// Endpoint path of the caller that opened this call.
|
|
pub caller_path: Vec<String>,
|
|
/// Canonical procedure identifier chosen by the caller.
|
|
pub procedure_id: String,
|
|
/// Optional destination leaf targeted by the call.
|
|
pub dst_leaf: Option<String>,
|
|
/// Hook key declared by the caller when it expects a response.
|
|
pub response_hook: Option<HookKey>,
|
|
}
|
|
|
|
/// One incoming local call event that already passed protocol validation.
|
|
///
|
|
/// This exists for dispatch layers that still want direct access to the raw protocol payload
|
|
/// before converting it into a typed [`Call<T>`].
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::{CallMessage, PacketHeader, PacketType};
|
|
/// use unshell::protocol::tree::IncomingCall;
|
|
/// let call = IncomingCall {
|
|
/// header: PacketHeader {
|
|
/// packet_type: PacketType::Call,
|
|
/// src_path: vec!["root".into()],
|
|
/// dst_path: vec!["worker".into()],
|
|
/// dst_leaf: None,
|
|
/// hook_id: None,
|
|
/// },
|
|
/// message: CallMessage {
|
|
/// procedure_id: "example.invoke".into(),
|
|
/// data: vec![],
|
|
/// response_hook: None,
|
|
/// },
|
|
/// };
|
|
/// assert_eq!(call.message.procedure_id, "example.invoke");
|
|
/// ```
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct IncomingCall {
|
|
/// Validated protocol header for the call.
|
|
pub header: PacketHeader,
|
|
/// Application payload for the call.
|
|
pub message: CallMessage,
|
|
}
|
|
|
|
/// One incoming local data event tied to an active hook.
|
|
///
|
|
/// This exists so hook-aware leaf code receives both the payload and the resolved hook identity
|
|
/// that owns the stream.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::{DataMessage, PacketHeader, PacketType};
|
|
/// use unshell::protocol::tree::{HookKey, IncomingData};
|
|
/// let data = IncomingData {
|
|
/// header: PacketHeader {
|
|
/// packet_type: PacketType::Data,
|
|
/// src_path: vec!["worker".into()],
|
|
/// dst_path: vec!["root".into()],
|
|
/// dst_leaf: None,
|
|
/// hook_id: Some(7),
|
|
/// },
|
|
/// message: DataMessage {
|
|
/// procedure_id: "example.invoke".into(),
|
|
/// data: vec![1],
|
|
/// end_hook: false,
|
|
/// },
|
|
/// hook_key: HookKey::new(vec!["root".into()], 7),
|
|
/// };
|
|
/// assert_eq!(data.hook_key.hook_id, 7);
|
|
/// ```
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct IncomingData {
|
|
/// Validated protocol header for the data packet.
|
|
pub header: PacketHeader,
|
|
/// Hook-associated data payload.
|
|
pub message: DataMessage,
|
|
/// Resolved hook key for the active session.
|
|
pub hook_key: HookKey,
|
|
}
|
|
|
|
/// One incoming local fault event tied to a pending or active hook.
|
|
///
|
|
/// This exists so leaf code can observe upstream protocol termination and release any
|
|
/// application-level resources associated with the hook.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::{FaultMessage, PacketHeader, PacketType, ProtocolFault};
|
|
/// use unshell::protocol::tree::{HookKey, IncomingFault};
|
|
/// let fault = IncomingFault {
|
|
/// header: PacketHeader {
|
|
/// packet_type: PacketType::Fault,
|
|
/// src_path: vec!["worker".into()],
|
|
/// dst_path: vec!["root".into()],
|
|
/// dst_leaf: None,
|
|
/// hook_id: Some(7),
|
|
/// },
|
|
/// fault: FaultMessage { fault: ProtocolFault::INTERNAL_ERROR },
|
|
/// hook_key: HookKey::new(vec!["root".into()], 7),
|
|
/// };
|
|
/// assert_eq!(fault.hook_key.hook_id, 7);
|
|
/// ```
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct IncomingFault {
|
|
/// Validated protocol header for the fault packet.
|
|
pub header: PacketHeader,
|
|
/// Fault payload emitted by the peer.
|
|
pub fault: crate::protocol::FaultMessage,
|
|
/// Hook key for the pending or active session that faulted.
|
|
pub hook_key: HookKey,
|
|
}
|
|
|
|
/// Outcome of one generated initial call procedure.
|
|
///
|
|
/// This exists for generated one-shot leaf procedures that either emit one reply payload or
|
|
/// intentionally complete without any returned hook traffic.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::CallResult;
|
|
/// let reply: CallResult<String> = CallResult::Reply("hello".into());
|
|
/// assert!(matches!(reply, CallResult::Reply(_)));
|
|
/// ```
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub enum CallResult<T> {
|
|
/// Return one reply payload to the caller.
|
|
Reply(T),
|
|
/// Complete the call without any response data.
|
|
NoReply,
|
|
}
|
|
|
|
/// One hook-associated `Data` packet emitted by leaf code.
|
|
///
|
|
/// This exists as the normalized outbound unit produced by leaf code before the runtime turns it
|
|
/// into framed protocol traffic.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::OutgoingData;
|
|
/// let packet = OutgoingData {
|
|
/// dst_path: vec!["root".into()],
|
|
/// hook_id: 7,
|
|
/// procedure_id: "example.invoke".into(),
|
|
/// data: vec![1, 2, 3],
|
|
/// end_hook: true,
|
|
/// };
|
|
/// assert!(packet.end_hook);
|
|
/// ```
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct OutgoingData {
|
|
/// Destination endpoint path for the hook packet.
|
|
pub dst_path: Vec<String>,
|
|
/// Hook identifier scoped to the receiving endpoint.
|
|
pub hook_id: u64,
|
|
/// Procedure identifier that owns this hook stream.
|
|
pub procedure_id: String,
|
|
/// Serialized application data to send.
|
|
pub data: Vec<u8>,
|
|
/// Whether this packet closes the local side of the hook.
|
|
pub end_hook: bool,
|
|
}
|
|
|
|
/// One runtime-normalized reply produced by generated call dispatch.
|
|
///
|
|
/// This exists because generated call dispatch always normalizes leaf return values into either
|
|
/// serialized reply bytes or an explicit “no reply” outcome.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::CallReply;
|
|
/// let reply = CallReply::Reply(vec![1, 2, 3]);
|
|
/// assert!(matches!(reply, CallReply::Reply(_)));
|
|
/// ```
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub enum CallReply {
|
|
/// Serialized reply bytes that should be returned upstream.
|
|
Reply(Vec<u8>),
|
|
/// Complete without emitting any reply packet.
|
|
NoReply,
|
|
}
|
|
|
|
/// Error surfaced while decoding one incoming call or encoding one generated reply.
|
|
///
|
|
/// This exists so generated dispatch can keep decode, encode, and handler failures distinct while
|
|
/// still using one error channel.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::{FrameError};
|
|
/// use unshell::protocol::tree::DispatchError;
|
|
/// let error: DispatchError<core::convert::Infallible> = DispatchError::Decode(FrameError::Truncated);
|
|
/// assert!(matches!(error, DispatchError::Decode(_)));
|
|
/// ```
|
|
#[derive(Debug)]
|
|
pub enum DispatchError<E> {
|
|
/// Failed to decode the typed call input.
|
|
Decode(FrameError),
|
|
/// Failed to encode the typed call output.
|
|
Encode(FrameError),
|
|
/// The leaf-specific call handler returned an error.
|
|
Handler(E),
|
|
}
|
|
|
|
impl<E> fmt::Display for DispatchError<E>
|
|
where
|
|
E: fmt::Display,
|
|
{
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
match self {
|
|
Self::Decode(error) => write!(f, "call decode failed: {error}"),
|
|
Self::Encode(error) => write!(f, "call reply encode failed: {error}"),
|
|
Self::Handler(error) => write!(f, "call handler failed: {error}"),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl<E> core::error::Error for DispatchError<E> where E: core::error::Error + 'static {}
|
|
|
|
/// Error surfaced by the stateful leaf runtime.
|
|
///
|
|
/// This exists so callers can distinguish transport/runtime failures from leaf-local business
|
|
/// logic failures.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::{FrameError};
|
|
/// use unshell::protocol::tree::{DispatchError, LeafRuntimeError};
|
|
/// let error: LeafRuntimeError<core::convert::Infallible> = LeafRuntimeError::Dispatch(DispatchError::Decode(FrameError::Truncated));
|
|
/// assert!(matches!(error, LeafRuntimeError::Dispatch(_)));
|
|
/// ```
|
|
#[derive(Debug)]
|
|
pub enum LeafRuntimeError<E> {
|
|
/// Protocol endpoint routing or framing failed.
|
|
Endpoint(EndpointError),
|
|
/// Typed call dispatch failed.
|
|
Dispatch(DispatchError<E>),
|
|
/// Leaf-local data or fault handling failed.
|
|
Leaf(E),
|
|
}
|
|
|
|
impl<E> fmt::Display for LeafRuntimeError<E>
|
|
where
|
|
E: fmt::Display,
|
|
{
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
match self {
|
|
Self::Endpoint(error) => write!(f, "{error}"),
|
|
Self::Dispatch(error) => write!(f, "{error}"),
|
|
Self::Leaf(error) => write!(f, "{error}"),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl<E> core::error::Error for LeafRuntimeError<E> where E: core::error::Error + 'static {}
|
|
|
|
impl<E> From<EndpointError> for LeafRuntimeError<E> {
|
|
fn from(value: EndpointError) -> Self {
|
|
Self::Endpoint(value)
|
|
}
|
|
}
|
|
|
|
/// High-level leaf behavior layered on top of validated protocol events.
|
|
///
|
|
/// This exists for leaves that want validated call/data/fault delivery without managing endpoint
|
|
/// routing details themselves.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::CallLeaf;
|
|
/// struct ExampleLeaf;
|
|
/// impl unshell::protocol::tree::ProtocolLeaf for ExampleLeaf {
|
|
/// fn leaf_name() -> String { "org.example.v1.echo".into() }
|
|
/// }
|
|
/// impl CallLeaf for ExampleLeaf {
|
|
/// type Error = core::convert::Infallible;
|
|
/// }
|
|
/// ```
|
|
pub trait CallLeaf: ProtocolLeaf {
|
|
/// Leaf-specific error surfaced by call, data, or fault handling.
|
|
type Error;
|
|
|
|
/// Handles hook-associated inbound `Data` after protocol validation.
|
|
fn on_data(&mut self, _data: IncomingData) -> Result<Vec<OutgoingData>, Self::Error> {
|
|
Ok(Vec::new())
|
|
}
|
|
|
|
/// Observes one inbound `Fault` after protocol validation.
|
|
fn on_fault(&mut self, _fault: IncomingFault) -> Result<(), Self::Error> {
|
|
Ok(())
|
|
}
|
|
|
|
/// Polls the leaf for locally-generated hook traffic.
|
|
fn poll(&mut self) -> Result<Vec<OutgoingData>, Self::Error> {
|
|
Ok(Vec::new())
|
|
}
|
|
}
|
|
|
|
/// Stateful runtime that combines a protocol endpoint with one leaf instance.
|
|
///
|
|
/// This exists as the high-level runtime for simple one-shot call procedures plus hook data/fault
|
|
/// handling.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::LeafRuntime;
|
|
/// # struct Leaf;
|
|
/// # let _ = core::marker::PhantomData::<LeafRuntime<Leaf>>;
|
|
/// ```
|
|
#[derive(Debug)]
|
|
pub struct LeafRuntime<L> {
|
|
endpoint: ProtocolEndpoint,
|
|
leaf: L,
|
|
}
|
|
|
|
/// Frames emitted by the runtime after one receive or poll step.
|
|
///
|
|
/// This exists so callers can flush emitted frames to transport while also learning whether the
|
|
/// inbound packet was intentionally dropped.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::RuntimeOutcome;
|
|
/// let outcome = RuntimeOutcome::default();
|
|
/// assert!(outcome.frames.is_empty());
|
|
/// ```
|
|
#[derive(Debug, Default)]
|
|
pub struct RuntimeOutcome {
|
|
/// Frames emitted while processing the step.
|
|
pub frames: Vec<FrameBytes>,
|
|
/// Whether the endpoint dropped the incoming packet.
|
|
pub dropped: bool,
|
|
}
|
|
|
|
impl<L> LeafRuntime<L> {
|
|
/// Builds a runtime from one endpoint and one leaf instance.
|
|
#[must_use]
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::{LeafRuntime, ProtocolEndpoint};
|
|
/// struct ExampleLeaf;
|
|
/// let runtime = LeafRuntime::new(ProtocolEndpoint::new(Vec::new(), None, Vec::new(), Vec::new()), ExampleLeaf);
|
|
/// let _ = runtime;
|
|
/// ```
|
|
pub fn new(endpoint: ProtocolEndpoint, leaf: L) -> Self {
|
|
Self { endpoint, leaf }
|
|
}
|
|
|
|
/// Returns the underlying protocol endpoint.
|
|
#[must_use]
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::{LeafRuntime, ProtocolEndpoint};
|
|
/// struct ExampleLeaf;
|
|
/// let runtime = LeafRuntime::new(ProtocolEndpoint::new(Vec::new(), None, Vec::new(), Vec::new()), ExampleLeaf);
|
|
/// let _endpoint = runtime.endpoint();
|
|
/// ```
|
|
pub fn endpoint(&self) -> &ProtocolEndpoint {
|
|
&self.endpoint
|
|
}
|
|
|
|
/// Returns a mutable reference to the underlying endpoint.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::{LeafRuntime, ProtocolEndpoint};
|
|
/// struct ExampleLeaf;
|
|
/// let mut runtime = LeafRuntime::new(ProtocolEndpoint::new(Vec::new(), None, Vec::new(), Vec::new()), ExampleLeaf);
|
|
/// let _endpoint = runtime.endpoint_mut();
|
|
/// ```
|
|
pub fn endpoint_mut(&mut self) -> &mut ProtocolEndpoint {
|
|
&mut self.endpoint
|
|
}
|
|
|
|
/// Returns the hosted leaf instance.
|
|
#[must_use]
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::{LeafRuntime, ProtocolEndpoint};
|
|
/// struct ExampleLeaf;
|
|
/// let runtime = LeafRuntime::new(ProtocolEndpoint::new(Vec::new(), None, Vec::new(), Vec::new()), ExampleLeaf);
|
|
/// let _leaf = runtime.leaf();
|
|
/// ```
|
|
pub fn leaf(&self) -> &L {
|
|
&self.leaf
|
|
}
|
|
|
|
/// Returns a mutable reference to the hosted leaf instance.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use unshell::protocol::tree::{LeafRuntime, ProtocolEndpoint};
|
|
/// struct ExampleLeaf;
|
|
/// let mut runtime = LeafRuntime::new(ProtocolEndpoint::new(Vec::new(), None, Vec::new(), Vec::new()), ExampleLeaf);
|
|
/// let _leaf = runtime.leaf_mut();
|
|
/// ```
|
|
pub fn leaf_mut(&mut self) -> &mut L {
|
|
&mut self.leaf
|
|
}
|
|
}
|
|
|
|
impl<L> LeafRuntime<L>
|
|
where
|
|
L: CallLeaf + super::CallProcedures<Error = <L as CallLeaf>::Error>,
|
|
{
|
|
/// Delivers one inbound frame into the stateful leaf runtime.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// # use unshell::protocol::tree::{LeafRuntime, ProtocolEndpoint};
|
|
/// # struct ExampleLeaf;
|
|
/// # let _ = core::marker::PhantomData::<LeafRuntime<ExampleLeaf>>;
|
|
/// ```
|
|
pub fn receive(
|
|
&mut self,
|
|
ingress: &Ingress,
|
|
frame: FrameBytes,
|
|
) -> Result<RuntimeOutcome, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
let outcome = self.endpoint.receive(ingress, frame)?;
|
|
self.process_endpoint_outcome(outcome)
|
|
}
|
|
|
|
/// Polls the leaf for locally-generated hook traffic and routes any emitted frames.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// # use unshell::protocol::tree::{LeafRuntime, ProtocolEndpoint};
|
|
/// # struct ExampleLeaf;
|
|
/// # let _ = core::marker::PhantomData::<LeafRuntime<ExampleLeaf>>;
|
|
/// ```
|
|
pub fn poll(&mut self) -> Result<RuntimeOutcome, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
let outgoing = self.leaf.poll().map_err(LeafRuntimeError::Leaf)?;
|
|
self.emit_outgoing(outgoing)
|
|
}
|
|
|
|
fn process_endpoint_outcome(
|
|
&mut self,
|
|
outcome: crate::protocol::tree::EndpointOutcome,
|
|
) -> Result<RuntimeOutcome, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
match outcome {
|
|
crate::protocol::tree::EndpointOutcome::Forward { frame, .. } => Ok(RuntimeOutcome {
|
|
frames: vec![frame],
|
|
dropped: false,
|
|
}),
|
|
crate::protocol::tree::EndpointOutcome::Dropped => Ok(RuntimeOutcome {
|
|
frames: Vec::new(),
|
|
dropped: true,
|
|
}),
|
|
crate::protocol::tree::EndpointOutcome::Local(event) => self.process_local_event(event),
|
|
}
|
|
}
|
|
|
|
fn process_local_event(
|
|
&mut self,
|
|
event: LocalEvent,
|
|
) -> Result<RuntimeOutcome, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
match event {
|
|
LocalEvent::Call { header, message } => self.process_local_call(header, message),
|
|
LocalEvent::Data {
|
|
header,
|
|
message,
|
|
hook_key,
|
|
} => self.process_local_data(header, message, hook_key),
|
|
LocalEvent::Fault {
|
|
header,
|
|
message,
|
|
hook_key,
|
|
} => self.process_local_fault(header, message, hook_key),
|
|
}
|
|
}
|
|
|
|
fn process_local_call(
|
|
&mut self,
|
|
header: PacketHeader,
|
|
message: CallMessage,
|
|
) -> Result<RuntimeOutcome, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
let CallMessage {
|
|
procedure_id,
|
|
data,
|
|
response_hook,
|
|
} = message;
|
|
let fault_hook = response_hook.as_ref();
|
|
let incoming = IncomingCall {
|
|
header,
|
|
// Split the payload apart so the reply path can reuse the owned procedure id and
|
|
// response hook without re-decoding the incoming bytes.
|
|
message: CallMessage {
|
|
procedure_id: procedure_id.clone(),
|
|
data,
|
|
response_hook: response_hook.clone(),
|
|
},
|
|
};
|
|
|
|
match self.leaf.dispatch_call(incoming) {
|
|
Ok(CallReply::Reply(bytes)) => {
|
|
let frames = if let Some(hook) = response_hook {
|
|
self.send_reply_data(hook, procedure_id, bytes, true)?
|
|
} else {
|
|
Vec::new()
|
|
};
|
|
Ok(RuntimeOutcome {
|
|
frames,
|
|
dropped: false,
|
|
})
|
|
}
|
|
Ok(CallReply::NoReply) => Ok(RuntimeOutcome::default()),
|
|
Err(error) => {
|
|
// Dispatch failures still emit a protocol fault for the remote caller when a
|
|
// response hook exists, even though the local runtime also surfaces the error.
|
|
let _ = self.emit_internal_fault_if_possible(fault_hook)?;
|
|
Err(LeafRuntimeError::Dispatch(error))
|
|
}
|
|
}
|
|
}
|
|
|
|
fn process_local_data(
|
|
&mut self,
|
|
header: PacketHeader,
|
|
message: DataMessage,
|
|
hook_key: HookKey,
|
|
) -> Result<RuntimeOutcome, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
let outgoing = self
|
|
.leaf
|
|
.on_data(IncomingData {
|
|
header,
|
|
message,
|
|
hook_key,
|
|
})
|
|
.map_err(LeafRuntimeError::Leaf)?;
|
|
self.emit_outgoing(outgoing)
|
|
}
|
|
|
|
fn process_local_fault(
|
|
&mut self,
|
|
header: PacketHeader,
|
|
message: crate::protocol::FaultMessage,
|
|
hook_key: HookKey,
|
|
) -> Result<RuntimeOutcome, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
self.leaf
|
|
.on_fault(IncomingFault {
|
|
header,
|
|
fault: message,
|
|
hook_key,
|
|
})
|
|
.map_err(LeafRuntimeError::Leaf)?;
|
|
Ok(RuntimeOutcome::default())
|
|
}
|
|
|
|
fn emit_outgoing(
|
|
&mut self,
|
|
outgoing: Vec<OutgoingData>,
|
|
) -> Result<RuntimeOutcome, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
let mut runtime = RuntimeOutcome::default();
|
|
for packet in outgoing {
|
|
let endpoint_outcome = self.endpoint.send_data(
|
|
packet.dst_path,
|
|
packet.hook_id,
|
|
packet.procedure_id,
|
|
packet.data,
|
|
packet.end_hook,
|
|
)?;
|
|
runtime
|
|
.frames
|
|
.extend(self.process_endpoint_outcome(endpoint_outcome)?.frames);
|
|
}
|
|
Ok(runtime)
|
|
}
|
|
|
|
fn send_reply_data(
|
|
&mut self,
|
|
hook: HookTarget,
|
|
procedure_id: String,
|
|
bytes: Vec<u8>,
|
|
end_hook: bool,
|
|
) -> Result<Vec<FrameBytes>, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
let endpoint_outcome = self.endpoint.send_data(
|
|
hook.return_path,
|
|
hook.hook_id,
|
|
procedure_id,
|
|
bytes,
|
|
end_hook,
|
|
)?;
|
|
Ok(self.process_endpoint_outcome(endpoint_outcome)?.frames)
|
|
}
|
|
|
|
fn emit_internal_fault_if_possible(
|
|
&mut self,
|
|
hook: Option<&HookTarget>,
|
|
) -> Result<Vec<FrameBytes>, LeafRuntimeError<<L as CallLeaf>::Error>> {
|
|
let Some(hook) = hook else {
|
|
return Ok(Vec::new());
|
|
};
|
|
let key = HookKey::new(hook.return_path.clone(), hook.hook_id);
|
|
let outcome = self
|
|
.endpoint
|
|
.emit_fault_if_possible(Some(key), ProtocolFault::INTERNAL_ERROR)?;
|
|
Ok(self.process_endpoint_outcome(outcome)?.frames)
|
|
}
|
|
}
|
|
|
|
/// Decodes one archived call payload into a typed application request.
|
|
///
|
|
/// This exists for generated and manual leaf code that stores its own typed `rkyv` payload inside
|
|
/// protocol `CallMessage::data` bytes.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use rkyv::{Archive, Deserialize, Serialize};
|
|
/// use unshell::protocol::tree::{decode_call_input, encode_call_reply};
|
|
/// #[derive(Archive, Serialize, Deserialize, Debug, PartialEq)]
|
|
/// struct Example { value: u32 }
|
|
/// let bytes = encode_call_reply(&Example { value: 7 })?;
|
|
/// let decoded = decode_call_input::<Example>(&bytes)?;
|
|
/// assert_eq!(decoded, Example { value: 7 });
|
|
/// # Ok::<(), unshell::protocol::FrameError>(())
|
|
/// ```
|
|
pub fn decode_call_input<T>(bytes: &[u8]) -> Result<T, FrameError>
|
|
where
|
|
T: Archive,
|
|
<T as Archive>::Archived: rkyv::Portable
|
|
+ for<'b> rkyv::bytecheck::CheckBytes<rkyv::api::high::HighValidator<'b, Error>>
|
|
+ rkyv::Deserialize<T, rkyv::api::high::HighDeserializer<Error>>,
|
|
{
|
|
crate::protocol::deserialize_archived_bytes::<<T as Archive>::Archived, T>(bytes)
|
|
}
|
|
|
|
/// Encodes one typed application reply into hook `Data` bytes.
|
|
///
|
|
/// This exists for generated and manual leaf code that wants to place one typed `rkyv` payload in
|
|
/// the `data` field of a returned hook packet.
|
|
///
|
|
/// # Example
|
|
/// ```rust
|
|
/// use rkyv::{Archive, Deserialize, Serialize};
|
|
/// use unshell::protocol::tree::encode_call_reply;
|
|
/// #[derive(Archive, Serialize, Deserialize, Debug, PartialEq)]
|
|
/// struct Example { value: u32 }
|
|
/// let bytes = encode_call_reply(&Example { value: 7 })?;
|
|
/// assert!(!bytes.is_empty());
|
|
/// # Ok::<(), unshell::protocol::FrameError>(())
|
|
/// ```
|
|
pub fn encode_call_reply<T>(value: &T) -> Result<Vec<u8>, FrameError>
|
|
where
|
|
T: for<'a> Serialize<
|
|
rkyv::api::high::HighSerializer<AlignedVec, rkyv::ser::allocator::ArenaHandle<'a>, Error>,
|
|
>,
|
|
{
|
|
let bytes = to_bytes::<Error>(value).map_err(FrameError::Serialize)?;
|
|
Ok(bytes.as_slice().to_vec())
|
|
}
|