mirror of
https://github.com/Astatin3/unshell.git
synced 2026-06-09 06:47:59 -06:00
Deepen protocol docs and explain runtime flow
This commit is contained in:
Michael Mikovsky
+265
-2
@@ -14,6 +14,22 @@ use super::{
|
||||
};
|
||||
|
||||
/// 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.
|
||||
@@ -29,6 +45,30 @@ pub struct Call<T> {
|
||||
}
|
||||
|
||||
/// 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.
|
||||
@@ -38,6 +78,31 @@ pub struct IncomingCall {
|
||||
}
|
||||
|
||||
/// 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.
|
||||
@@ -49,6 +114,27 @@ pub struct IncomingData {
|
||||
}
|
||||
|
||||
/// 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.
|
||||
@@ -60,6 +146,16 @@ pub struct IncomingFault {
|
||||
}
|
||||
|
||||
/// 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.
|
||||
@@ -69,6 +165,22 @@ pub enum CallResult<T> {
|
||||
}
|
||||
|
||||
/// 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.
|
||||
@@ -84,6 +196,16 @@ pub struct OutgoingData {
|
||||
}
|
||||
|
||||
/// 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.
|
||||
@@ -93,6 +215,17 @@ pub enum CallReply {
|
||||
}
|
||||
|
||||
/// 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.
|
||||
@@ -119,6 +252,17 @@ where
|
||||
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.
|
||||
@@ -151,6 +295,21 @@ impl<E> From<EndpointError> for LeafRuntimeError<E> {
|
||||
}
|
||||
|
||||
/// 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;
|
||||
@@ -172,6 +331,16 @@ pub trait CallLeaf: ProtocolLeaf {
|
||||
}
|
||||
|
||||
/// 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,
|
||||
@@ -179,6 +348,16 @@ pub struct LeafRuntime<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.
|
||||
@@ -190,28 +369,68 @@ pub struct RuntimeOutcome {
|
||||
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
|
||||
}
|
||||
@@ -222,6 +441,13 @@ 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,
|
||||
@@ -232,6 +458,13 @@ where
|
||||
}
|
||||
|
||||
/// 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)
|
||||
@@ -309,8 +542,9 @@ where
|
||||
}
|
||||
Ok(CallReply::NoReply) => Ok(RuntimeOutcome::default()),
|
||||
Err(error) => {
|
||||
let frames = self.emit_internal_fault_if_possible(fault_hook)?;
|
||||
let _ = frames;
|
||||
// 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))
|
||||
}
|
||||
}
|
||||
@@ -402,6 +636,21 @@ where
|
||||
}
|
||||
|
||||
/// 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,
|
||||
@@ -413,6 +662,20 @@ where
|
||||
}
|
||||
|
||||
/// 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<
|
||||
|
||||
Reference in New Issue
Block a user