astatin3/unshell
1
0
Fork 0
mirror of https://github.com/Astatin3/unshell.git synced 2026-06-08 22:38:01 -06:00
Code Issues Packages Projects Releases Wiki Activity

Remove the old leaf declaration path

Browse Source 
Delete the deprecated Leaf derive path, migrate the remaining tests and example to leaf!, and add direct coverage for endpoint-only, TUI-only, and shared-host leaf declarations.
This commit is contained in:
Michael Mikovsky
2026-04-26 14:14:49 -06:00
parent 0aa0b187d7
commit 54c44b407e
17 changed files with 284 additions and 380 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/protocol/leaf_derive.rs
+63 -25
View File
@@ -1,22 +1,28 @@
//! Small end-to-end example for the `Leaf` and `procedures` derive macros.
//! Small end-to-end example for the `leaf!` and `Procedure` macros.
//!
//! This stays entirely local. A controller endpoint opens one call against a single in-process
//! leaf runtime, and the example decodes the returned reply payload.
//! This stays entirely local. A controller endpoint opens one hook-backed procedure against a
//! single in-process leaf runtime, and the example decodes the returned reply payload.
use std::error::Error;
use std::{convert::Infallible, string::String};
use std::{collections::BTreeMap, convert::Infallible, string::String};
use rkyv::{Archive, Deserialize, Serialize};
use unshell::protocol::tree::{
Call, CallLeaf, ChildRoute, EndpointOutcome, Ingress, LeafRuntime, ProtocolEndpoint,
Call, ChildRoute, EndpointOutcome, HookKey, Ingress, OutgoingData, Procedure, ProcedureEffect,
ProcedureRuntime, ProcedureStore, ProtocolEndpoint,
};
use unshell::protocol::{PacketType, decode_frame};
use unshell::{Leaf, procedures};
use unshell::{Procedure, leaf};
#[derive(Leaf)]
#[leaf(org = "org", product = "example", version = "v1", leaf_name = "echo")]
#[derive(Default)]
struct EchoLeaf {
prefix: String,
sessions: BTreeMap<HookKey, EchoOpen>,
}
leaf! {
id = "org.example.v1.echo",
procedures = [EchoOpen],
endpoint_struct = EchoLeaf,
}
#[derive(Archive, Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
@@ -29,18 +35,53 @@ struct EchoResponse {
text: String,
}
#[procedures(error = Infallible)]
impl EchoLeaf {
#[call]
fn echo(&mut self, request: Call<EchoRequest>) -> EchoResponse {
EchoResponse {
text: format!("{}{}", self.prefix, request.input.text),
#[derive(Debug, Clone, PartialEq, Eq, Procedure)]
#[procedure(leaf = EchoLeaf, name = "echo")]
struct EchoOpen {
prefix: String,
return_path: Vec<String>,
hook_id: u64,
sent_reply: bool,
}
impl ProcedureStore<EchoOpen> for EchoLeaf {
fn procedure_sessions(&mut self) -> &mut BTreeMap<HookKey, EchoOpen> {
&mut self.sessions
}
}
impl CallLeaf for EchoLeaf {
impl Procedure<EchoLeaf> for EchoOpen {
type Error = Infallible;
type Input = EchoRequest;
fn open(_leaf: &mut EchoLeaf, call: Call<Self::Input>) -> Result<Self, Self::Error> {
let response_hook = call
.response_hook
.expect("example call declares a response hook");
Ok(Self {
prefix: call.input.text,
return_path: response_hook.return_path,
hook_id: response_hook.hook_id,
sent_reply: false,
})
}
fn poll(_leaf: &mut EchoLeaf, session: &mut Self) -> Result<ProcedureEffect, Self::Error> {
if session.sent_reply {
return Ok(ProcedureEffect::default());
}
session.sent_reply = true;
Ok(ProcedureEffect::close(vec![OutgoingData {
dst_path: session.return_path.clone(),
hook_id: session.hook_id,
procedure_id: EchoOpen::protocol_procedure_id(),
data: unshell::protocol::tree::encode_call_reply(&EchoResponse {
text: format!("echo: {}", session.prefix),
})
.expect("response should encode"),
end_hook: true,
}]))
}
}
fn path(parts: &[&str]) -> Vec<String> {
@@ -54,12 +95,7 @@ fn main() -> Result<(), Box<dyn Error>> {
Vec::new(),
vec![EchoLeaf::protocol_leaf_spec()],
);
let mut runtime = LeafRuntime::new(
endpoint,
EchoLeaf {
prefix: String::from("echo: "),
},
);
let mut runtime = ProcedureRuntime::<EchoLeaf, EchoOpen>::new(endpoint, EchoLeaf::default());
let mut controller = ProtocolEndpoint::new(
Vec::new(),
@@ -74,7 +110,7 @@ fn main() -> Result<(), Box<dyn Error>> {
let controller_outcome = controller.send_call(
path(&["agent"]),
Some(EchoLeaf::protocol_leaf_name()),
EchoLeaf::protocol_procedure_id("echo").expect("known procedure suffix"),
EchoOpen::protocol_procedure_id(),
Some(hook_id),
unshell::protocol::tree::encode_call_reply(&EchoRequest {
text: String::from("hello leaf"),
@@ -84,7 +120,9 @@ fn main() -> Result<(), Box<dyn Error>> {
return Err("expected controller to forward call".into());
};
let outcome = runtime.receive(&Ingress::Parent, frame)?;
let receive_outcome = runtime.receive(&Ingress::Parent, frame)?;
assert!(receive_outcome.frames.is_empty());
let outcome = runtime.poll()?;
let [response_frame] = outcome.frames.as_slice() else {
return Err("expected one response frame".into());
};
@@ -100,7 +138,7 @@ fn main() -> Result<(), Box<dyn Error>> {
println!(
"leaf={} procedure={} response={}",
EchoLeaf::protocol_leaf_name(),
EchoLeaf::protocol_procedure_id("echo").expect("known procedure suffix"),
EchoOpen::protocol_procedure_id(),
response.text,
);
Ok(())
src/lib.rs
+1 -1
View File
@@ -26,6 +26,6 @@ pub use unshell_protocol as protocol;
/// Re-export the leaf library crate behind the historical `unshell::leaves` path
pub use unshell_leaves as leaves;
pub use unshell_macros::{Leaf, Procedure, leaf, procedures};
pub use unshell_macros::{Procedure, leaf, procedures};
// pub use ush_obfuscate as obfuscate;
unshell-leaves/src/lib.rs
+1 -1
View File
@@ -12,7 +12,7 @@ pub extern crate alloc;
use unshell_protocol::DataMessage;
pub use unshell_macros::{Leaf, Procedure, leaf, procedures};
pub use unshell_macros::{Procedure, leaf, procedures};
pub use unshell_protocol as protocol;
/// Re-exports one role-specific type behind a stable public alias.
unshell-leaves/src/remote_shell/mod.rs
+19
View File
@@ -6,6 +6,8 @@
//! - `leaf_tui` builds a placeholder client-side TUI surface
use rkyv::{Archive, Deserialize, Serialize};
#[cfg(not(feature = "leaf_endpoint"))]
use std::string::String;
#[cfg(feature = "leaf_endpoint")]
pub mod endpoint;
@@ -24,6 +26,23 @@ pub use tui::RemoteShellTui;
/// not built, so the leaf declaration still validates its declared inventory.
pub struct Open;
#[cfg(not(feature = "leaf_endpoint"))]
#[doc(hidden)]
pub struct RemoteShellDeclarationPlaceholder;
#[cfg(not(feature = "leaf_endpoint"))]
impl crate::protocol::tree::ProtocolLeaf for RemoteShellDeclarationPlaceholder {
fn leaf_name() -> String {
String::from("remote_shell")
}
}
#[cfg(not(feature = "leaf_endpoint"))]
impl crate::protocol::tree::ProcedureMetadata for Open {
type Leaf = RemoteShellDeclarationPlaceholder;
const PROCEDURE_SUFFIX: &'static str = "open";
}
/// Open-request payload for the remote shell leaf.
///
/// The shell currently needs no structured arguments, but a named payload type is
unshell-macros/ABOUT.md
+6 -11
View File
@@ -14,7 +14,6 @@ compile time.
In practical terms, the macro system is responsible for:
- deriving canonical leaf identities
- deriving canonical procedure identifiers
- generating compile-time procedure inventories for leaves
- binding one leaf declaration to separate endpoint and TUI host structs without
@@ -57,18 +56,14 @@ compile-time inventory instead of handwritten lists.
## Current direction
The current migration keeps the older derive-based APIs working while adding a
new declaration-first API.
The public declaration model is now centered on `leaf!`.
That migration is intentionally incremental:
- `leaf!` declares the canonical protocol surface once
- `#[derive(Procedure)]` derives stateful procedure metadata
- `#[procedures]` derives one-shot call dispatch for simple leaves
1. keep `#[derive(Leaf)]`, `#[derive(Procedure)]`, and `#[procedures]` working
2. introduce one declaration macro for compile-time leaf metadata
3. let endpoint and TUI structs bind to the declaration instead of duplicating
metadata
4. remove leaf-owned endpoint-construction boilerplate by generating leaf specs
from the declaration
5. add typed remote-method metadata on top of the same declaration model
The next evolution from here is typed remote-method metadata on top of the same
declaration model.
## Design constraints
unshell-macros/src/leaf.rs
-161
View File
@@ -1,161 +0,0 @@
use quote::quote;
use syn::{Attribute, Data, DeriveInput, Error, Ident, LitStr, Result};
use crate::utils::{looks_like_canonical_leaf_name, option_litstr_tokens};
#[derive(Default)]
struct LeafAttributes {
name: Option<LitStr>,
id: Option<LitStr>,
org: Option<LitStr>,
product: Option<LitStr>,
version: Option<LitStr>,
leaf_name: Option<LitStr>,
}
impl LeafAttributes {
fn parse_from(attrs: &[Attribute]) -> Result<Self> {
let mut parsed = Self::default();
for attr in attrs {
if !attr.path().is_ident("leaf") {
continue;
}
attr.parse_nested_meta(|meta| {
if meta.path.is_ident("name") {
if parsed.name.is_some() {
return Err(meta.error("duplicate leaf name attribute"));
}
parsed.name = Some(meta.value()?.parse()?);
return Ok(());
}
if meta.path.is_ident("id") {
if parsed.id.is_some() {
return Err(meta.error("duplicate leaf id attribute"));
}
parsed.id = Some(meta.value()?.parse()?);
return Ok(());
}
if meta.path.is_ident("org") {
if parsed.org.is_some() {
return Err(meta.error("duplicate leaf org attribute"));
}
parsed.org = Some(meta.value()?.parse()?);
return Ok(());
}
if meta.path.is_ident("product") {
if parsed.product.is_some() {
return Err(meta.error("duplicate leaf product attribute"));
}
parsed.product = Some(meta.value()?.parse()?);
return Ok(());
}
if meta.path.is_ident("version") {
if parsed.version.is_some() {
return Err(meta.error("duplicate leaf version attribute"));
}
parsed.version = Some(meta.value()?.parse()?);
return Ok(());
}
if meta.path.is_ident("leaf_name") {
if parsed.leaf_name.is_some() {
return Err(meta.error("duplicate leaf_name attribute"));
}
parsed.leaf_name = Some(meta.value()?.parse()?);
return Ok(());
}
Err(meta.error("unsupported #[leaf(...)] attribute"))
})?;
}
Ok(parsed)
}
fn explicit_id_value(&self) -> Option<&LitStr> {
self.id.as_ref().or(self.name.as_ref())
}
fn leaf_name_expression(&self, struct_name: &Ident) -> proc_macro2::TokenStream {
let id = option_litstr_tokens(self.id.as_ref().or(self.name.as_ref()));
let org = option_litstr_tokens(self.org.as_ref());
let product = option_litstr_tokens(self.product.as_ref());
let version = option_litstr_tokens(self.version.as_ref());
let leaf_name = option_litstr_tokens(self.leaf_name.as_ref());
quote! {
::unshell::protocol::tree::derive_leaf_name(
::core::env!("CARGO_PKG_NAME"),
::core::env!("CARGO_PKG_VERSION_MAJOR"),
::core::env!("CARGO_PKG_VERSION_MINOR"),
::core::env!("CARGO_PKG_VERSION_PATCH"),
::core::module_path!(),
::core::stringify!(#struct_name),
#org,
#product,
#version,
#leaf_name,
#id,
)
}
}
}
pub(crate) fn expand_leaf(input: DeriveInput) -> Result<proc_macro2::TokenStream> {
let struct_name = input.ident;
match input.data {
Data::Struct(_) => {}
_ => {
return Err(Error::new_spanned(
struct_name,
"Leaf can only be derived for structs",
));
}
};
let parsed = LeafAttributes::parse_from(&input.attrs)?;
let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
let leaf_name_expr = parsed.leaf_name_expression(&struct_name);
let warning_note = parsed
.explicit_id_value()
.as_ref()
.filter(|name| !name.value().is_empty())
.filter(|name| !looks_like_canonical_leaf_name(&name.value()))
.map(|name| {
LitStr::new(
&format!(
"leaf id `{}` does not follow the recommended dotted format `org.product.vN.leaf_name[.part]`",
name.value()
),
proc_macro2::Span::call_site(),
)
})
.map(|note| quote! { #[deprecated(note = #note)] });
let leaf_name_warning_attr = warning_note.unwrap_or_else(|| quote! {});
Ok(quote! {
impl #impl_generics ::unshell::protocol::tree::ProtocolLeaf for #struct_name #ty_generics #where_clause {
fn leaf_name() -> ::unshell::alloc::string::String {
#leaf_name_expr
}
}
impl #impl_generics ::unshell::protocol::tree::LeafBinding for #struct_name #ty_generics #where_clause {
type Declaration = Self;
}
impl #impl_generics #struct_name #ty_generics #where_clause {
/// Returns the canonical dotted leaf name declared for this type.
#leaf_name_warning_attr
pub fn protocol_leaf_name() -> ::unshell::alloc::string::String {
<Self as ::unshell::protocol::tree::ProtocolLeaf>::leaf_name()
}
}
})
}
unshell-macros/src/leaf_decl.rs
+30 -42
View File
@@ -17,7 +17,7 @@ pub(crate) struct LeafDeclarationInput {
version: Option<LitStr>,
endpoint_struct: Option<Ident>,
tui_struct: Option<Ident>,
procedures: Vec<Ident>,
procedures: Vec<ProcedureRef>,
}
impl Parse for LeafDeclarationInput {
@@ -119,7 +119,21 @@ enum LeafAssignment {
Version(LitStr),
EndpointStruct(Ident),
TuiStruct(Ident),
Procedures(Vec<Ident>),
Procedures(Vec<ProcedureRef>),
}
enum ProcedureRef {
Symbol(Ident),
Suffix(LitStr),
}
impl Parse for ProcedureRef {
fn parse(input: ParseStream<'_>) -> Result<Self> {
if input.peek(LitStr) {
return Ok(Self::Suffix(input.parse()?));
}
Ok(Self::Symbol(input.parse()?))
}
}
impl Parse for LeafAssignment {
@@ -137,7 +151,7 @@ impl Parse for LeafAssignment {
"procedures" => {
let content;
syn::bracketed!(content in input);
let values = Punctuated::<Ident, Token![,]>::parse_terminated(&content)?
let values = Punctuated::<ProcedureRef, Token![,]>::parse_terminated(&content)?
.into_iter()
.collect::<Vec<_>>();
Ok(Self::Procedures(values))
@@ -165,9 +179,20 @@ pub(crate) fn expand_leaf_declaration(input: LeafDeclarationInput) -> Result<Tok
let procedure_suffixes = input
.procedures
.iter()
.map(|procedure| LitStr::new(&normalize_suffix(&procedure.to_string()), procedure.span()))
.map(|procedure| match procedure {
ProcedureRef::Symbol(procedure) => {
quote! { <#procedure as ::unshell::protocol::tree::ProcedureMetadata>::PROCEDURE_SUFFIX }
}
ProcedureRef::Suffix(suffix) => quote! { #suffix },
})
.collect::<Vec<_>>();
let procedure_type_checks = input.procedures.iter();
let procedure_type_checks = input
.procedures
.iter()
.filter_map(|procedure| match procedure {
ProcedureRef::Symbol(procedure) => Some(procedure),
ProcedureRef::Suffix(_) => None,
});
let endpoint_impl = input
.endpoint_struct
@@ -273,40 +298,3 @@ fn expand_binding_impl(host: &Ident, declaration: &Ident) -> TokenStream {
}
}
}
fn normalize_suffix(value: &str) -> String {
let mut normalized = String::with_capacity(value.len());
let mut previous_was_separator = false;
for character in value.chars() {
if character.is_ascii_uppercase() {
if !normalized.is_empty() && !previous_was_separator {
normalized.push('_');
}
normalized.push(character.to_ascii_lowercase());
previous_was_separator = false;
continue;
}
if character.is_ascii_lowercase() || character.is_ascii_digit() {
normalized.push(character);
previous_was_separator = false;
continue;
}
if !normalized.is_empty() && !previous_was_separator {
normalized.push('_');
previous_was_separator = true;
}
}
while normalized.ends_with('_') {
normalized.pop();
}
if normalized.is_empty() {
String::from("procedure")
} else {
normalized
}
}
unshell-macros/src/lib.rs
+16 -34
View File
@@ -1,6 +1,5 @@
//! Proc macros for `unshell` application-layer leaf declarations.
mod leaf;
mod leaf_decl;
mod procedure;
mod procedures;
@@ -38,33 +37,6 @@ pub fn leaf(input: TokenStream) -> TokenStream {
}
}
/// Derives canonical protocol-leaf identity helpers for one host type.
///
/// What it is: a derive macro that implements `ProtocolLeaf` and generates the
/// `protocol_leaf_name()` convenience method.
///
/// Why it exists: simple leaves and compatibility paths still need a lightweight
/// way to say "this host type exposes this canonical wire name" without writing
/// the trait implementation by hand.
///
/// # Example
/// ```ignore
/// use unshell::Leaf;
///
/// #[derive(Leaf)]
/// #[leaf(leaf_name = "echo")]
/// struct EchoLeaf;
///
/// assert!(EchoLeaf::protocol_leaf_name().contains("echo"));
/// ```
#[proc_macro_derive(Leaf, attributes(leaf))]
pub fn derive_leaf(input: TokenStream) -> TokenStream {
match leaf::expand_leaf(parse_macro_input!(input as DeriveInput)) {
Ok(tokens) => tokens.into(),
Err(error) => error.to_compile_error().into(),
}
}
/// Derives canonical stateful-procedure metadata for one procedure type.
///
/// What it is: a derive macro that records one procedure suffix and generates
@@ -75,10 +47,16 @@ pub fn derive_leaf(input: TokenStream) -> TokenStream {
///
/// # Example
/// ```ignore
/// use unshell::{Leaf, Procedure};
/// use unshell::{Procedure, leaf};
///
/// struct ShellLeaf;
///
/// leaf! {
/// name = "shell",
/// procedures = [OpenSession],
/// endpoint_struct = ShellLeaf,
/// }
///
/// #[derive(Leaf)]
/// #[leaf(leaf_name = "shell")]
/// struct ShellLeaf;
///
/// #[derive(Procedure)]
@@ -106,12 +84,16 @@ pub fn derive_procedure(input: TokenStream) -> TokenStream {
///
/// # Example
/// ```ignore
/// use unshell::{Leaf, procedures};
/// use unshell::{leaf, procedures};
///
/// #[derive(Leaf)]
/// #[leaf(id = "org.example.v1.echo")]
/// struct EchoLeaf;
///
/// leaf! {
/// id = "org.example.v1.echo",
/// procedures = [echo],
/// endpoint_struct = EchoLeaf,
/// }
///
/// #[procedures(error = core::convert::Infallible)]
/// impl EchoLeaf {
/// #[call]
unshell-macros/src/procedure.rs
+1 -3
View File
@@ -95,9 +95,7 @@ pub(crate) fn expand_procedure(input: DeriveInput) -> Result<proc_macro2::TokenS
{
type Leaf = #leaf_ty;
fn procedure_suffix() -> &'static str {
#suffix
}
const PROCEDURE_SUFFIX: &'static str = #suffix;
}
impl #impl_generics #procedure_name #ty_generics #where_clause {
unshell-macros/src/procedures.rs
+6 -32
View File
@@ -108,25 +108,11 @@ pub(crate) fn expand_procedures(
));
}
let suffix_literals = dispatch_arms
.iter()
.map(|arm| arm.suffix_literal.clone())
.collect::<Vec<_>>();
let procedure_matches = dispatch_arms.iter().map(|arm| {
let suffix = &arm.suffix_literal;
quote! { #suffix => <Self as ::unshell::protocol::tree::LeafDeclaration>::procedure_id(#suffix), }
});
let dispatch_checks = dispatch_arms.iter().map(|arm| arm.dispatch_tokens.clone());
Ok(quote! {
#item
impl #impl_generics_tokens ::unshell::protocol::tree::LeafDeclaration for #self_ty #where_clause {
fn procedure_suffixes() -> &'static [&'static str] {
&[#(#suffix_literals),*]
}
}
impl #impl_generics_tokens ::unshell::protocol::tree::CallProcedures for #self_ty #where_clause {
type Error = #error_ty;
@@ -142,22 +128,6 @@ pub(crate) fn expand_procedures(
}
}
impl #impl_generics_tokens #self_ty #where_clause {
/// Returns the canonical protocol leaf metadata for this type.
pub fn protocol_leaf_spec() -> ::unshell::protocol::tree::LeafSpec {
<Self as ::unshell::protocol::tree::LeafDeclaration>::leaf_spec()
}
/// Resolves one local procedure suffix to its full canonical `procedure_id`.
pub fn protocol_procedure_id(
suffix: &str,
) -> ::core::option::Option<::unshell::alloc::string::String> {
match suffix {
#(#procedure_matches)*
_ => ::core::option::Option::None,
}
}
}
})
}
@@ -165,8 +135,12 @@ fn expand_call_arm(method: &ImplItemFn) -> Result<CallArm> {
let method_name = &method.sig.ident;
let suffix_literal = call_suffix_literal(method)?;
let call_id_expr = quote! {
<Self as ::unshell::protocol::tree::LeafDeclaration>::procedure_id(#suffix_literal)
.expect("generated procedure id must exist")
{
let mut __unshell_id = <Self as ::unshell::protocol::tree::ProtocolLeaf>::leaf_name();
__unshell_id.push('.');
__unshell_id.push_str(#suffix_literal);
__unshell_id
}
};
let inputs = method
unshell-macros/src/utils.rs
-45
View File
@@ -9,33 +9,6 @@ pub(crate) fn option_litstr_tokens(value: Option<&LitStr>) -> TokenStream {
}
}
pub(crate) fn looks_like_canonical_leaf_name(name: &str) -> bool {
let segments = name.split('.').collect::<Vec<_>>();
if segments.len() < 4 {
return false;
}
for segment in &segments {
if segment.is_empty() {
return false;
}
if !segment.chars().all(|character| {
character.is_ascii_lowercase() || character.is_ascii_digit() || character == '_'
}) {
return false;
}
}
if !segments[2].starts_with('v') || segments[2].len() <= 1 {
return false;
}
segments[2][1..]
.chars()
.all(|character| character.is_ascii_digit() || character == '_')
}
pub(crate) fn extract_outer_type_argument<'a>(ty: &'a Type, expected: &str) -> Option<&'a Type> {
let Type::Path(TypePath { path, .. }) = ty else {
return None;
@@ -85,21 +58,3 @@ pub(crate) fn take_call_attr(attrs: &mut Vec<Attribute>) -> bool {
attrs.retain(|attr| !attr.path().is_ident("call"));
original_len != attrs.len()
}
#[cfg(test)]
mod tests {
use super::looks_like_canonical_leaf_name;
#[test]
fn canonical_leaf_name_accepts_minimal_valid_shape() {
assert!(looks_like_canonical_leaf_name("org.example.v1.echo"));
assert!(looks_like_canonical_leaf_name("org.example.v1.echo.abc123"));
}
#[test]
fn canonical_leaf_name_rejects_wrong_shapes() {
assert!(!looks_like_canonical_leaf_name("org.example.echo"));
assert!(!looks_like_canonical_leaf_name("org.example.1.echo"));
assert!(!looks_like_canonical_leaf_name("Org.example.v1.echo"));
}
}
unshell-protocol/src/lib.rs
+1 -1
View File
@@ -17,4 +17,4 @@ pub mod protocol;
pub use protocol::*;
#[cfg(test)]
pub use unshell_macros::{Leaf, Procedure, procedures};
pub use unshell_macros::{Procedure, leaf, procedures};
unshell-protocol/src/protocol/tests/call.rs
+7 -3
View File
@@ -8,18 +8,22 @@ use crate::protocol::tree::{
decode_call_input, encode_call_reply,
};
use crate::protocol::{PacketType, decode_frame};
use crate::{Leaf, procedures};
use crate::{leaf, procedures};
fn path(parts: &[&str]) -> Vec<String> {
parts.iter().map(|part| (*part).to_owned()).collect()
}
#[derive(Leaf)]
#[leaf(id = "org.example.v1.echo")]
struct EchoLeaf {
prefix: String,
}
leaf! {
id = "org.example.v1.echo",
endpoint_struct = EchoLeaf,
procedures = ["echo"],
}
#[derive(Archive, Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
struct EchoRequest {
text: String,
unshell-protocol/src/protocol/tests/leaf_decl.rs
+98
View File
@@ -0,0 +1,98 @@
use alloc::{string::String, vec};
use crate::leaf;
use crate::protocol::tree::{LeafBinding, LeafDeclaration, ProcedureMetadata, ProtocolLeaf};
struct EndpointHost;
struct Open;
struct Reset;
impl ProcedureMetadata for Open {
type Leaf = EndpointHost;
const PROCEDURE_SUFFIX: &'static str = "open";
}
impl ProcedureMetadata for Reset {
type Leaf = EndpointHost;
const PROCEDURE_SUFFIX: &'static str = "reset";
}
leaf! {
id = "org.example.v1.demo",
procedures = [Open, Reset],
endpoint_struct = EndpointHost,
}
struct EndpointHalf;
struct TuiHalf;
struct Connect;
impl ProcedureMetadata for Connect {
type Leaf = EndpointHalf;
const PROCEDURE_SUFFIX: &'static str = "connect";
}
leaf! {
name = "chat",
org = "org",
product = "example",
version = "v2",
procedures = [Connect],
endpoint_struct = EndpointHalf,
tui_struct = TuiHalf,
}
struct TuiOnly;
struct Tail;
impl ProcedureMetadata for Tail {
type Leaf = TuiOnly;
const PROCEDURE_SUFFIX: &'static str = "tail";
}
leaf! {
id = "org.example.v1.transcript",
procedures = [Tail],
tui_struct = TuiOnly,
}
#[test]
fn leaf_declaration_generates_endpoint_host_metadata() {
assert_eq!(EndpointHost::protocol_leaf_name(), "org.example.v1.demo");
assert_eq!(
EndpointHost::protocol_leaf_spec().procedures,
vec![
String::from("org.example.v1.demo.open"),
String::from("org.example.v1.demo.reset"),
]
);
assert_eq!(
<EndpointHost as LeafBinding>::Declaration::leaf_name(),
"org.example.v1.demo"
);
}
#[test]
fn leaf_declaration_shares_metadata_between_endpoint_and_tui_hosts() {
assert_eq!(
EndpointHalf::protocol_leaf_name(),
TuiHalf::protocol_leaf_name()
);
assert_eq!(
EndpointHalf::protocol_leaf_spec().procedures,
TuiHalf::protocol_leaf_spec().procedures
);
assert_eq!(
<EndpointHalf as LeafBinding>::Declaration::procedure_id("connect"),
Some(String::from("org.example.v2.chat.connect"))
);
}
#[test]
fn leaf_declaration_supports_tui_only_hosts() {
assert_eq!(TuiOnly::protocol_leaf_name(), "org.example.v1.transcript");
assert_eq!(
<TuiOnly as LeafDeclaration>::procedure_id("tail"),
Some(String::from("org.example.v1.transcript.tail"))
);
}
unshell-protocol/src/protocol/tests/mod.rs
+1
View File
@@ -1,4 +1,5 @@
mod call;
mod leaf_decl;
mod procedure;
mod protocol;
mod tree;
unshell-protocol/src/protocol/tests/procedure.rs
+17 -13
View File
@@ -6,18 +6,23 @@ use crate::protocol::tree::{
ProcedureEffect, ProcedureRuntime, ProcedureStore, ProtocolEndpoint, encode_call_reply,
};
use crate::protocol::{PacketType, decode_frame};
use crate::{Leaf, Procedure};
use crate::{Procedure, leaf};
fn path(parts: &[&str]) -> Vec<String> {
parts.iter().map(|part| (*part).to_owned()).collect()
}
#[derive(Default, Leaf)]
#[leaf(id = "org.example.v1.stream")]
#[derive(Default)]
struct StreamLeaf {
sessions: BTreeMap<HookKey, ProcedureOpen>,
}
leaf! {
id = "org.example.v1.stream",
procedures = [ProcedureOpen],
endpoint_struct = StreamLeaf,
}
impl ProcedureStore<ProcedureOpen> for StreamLeaf {
fn procedure_sessions(&mut self) -> &mut BTreeMap<HookKey, ProcedureOpen> {
&mut self.sessions
@@ -67,10 +72,7 @@ fn procedure_runtime_routes_data_to_stored_session() {
path(&["agent"]),
Some(Vec::new()),
Vec::new(),
vec![crate::protocol::tree::LeafSpec {
name: StreamLeaf::protocol_leaf_name(),
procedures: vec![ProcedureOpen::protocol_procedure_id()],
}],
vec![StreamLeaf::protocol_leaf_spec()],
);
let mut runtime =
ProcedureRuntime::<StreamLeaf, ProcedureOpen>::new(endpoint, StreamLeaf::default());
@@ -139,12 +141,17 @@ fn procedure_runtime_routes_data_to_stored_session() {
assert!(runtime.leaf_mut().procedure_sessions().is_empty());
}
#[derive(Default, Leaf)]
#[leaf(id = "org.example.v1.duplex")]
#[derive(Default)]
struct DuplexLeaf {
sessions: BTreeMap<HookKey, DuplexProcedure>,
}
leaf! {
id = "org.example.v1.duplex",
procedures = [DuplexProcedure],
endpoint_struct = DuplexLeaf,
}
impl ProcedureStore<DuplexProcedure> for DuplexLeaf {
fn procedure_sessions(&mut self) -> &mut BTreeMap<HookKey, DuplexProcedure> {
&mut self.sessions
@@ -197,10 +204,7 @@ fn procedure_runtime_keeps_session_after_local_end_until_explicit_close() {
path(&["agent"]),
Some(Vec::new()),
Vec::new(),
vec![crate::protocol::tree::LeafSpec {
name: DuplexLeaf::protocol_leaf_name(),
procedures: vec![DuplexProcedure::protocol_procedure_id()],
}],
vec![DuplexLeaf::protocol_leaf_spec()],
);
let mut runtime =
ProcedureRuntime::<DuplexLeaf, DuplexProcedure>::new(endpoint, DuplexLeaf::default());
unshell-protocol/src/protocol/tree/procedure.rs
+16 -7
View File
@@ -46,7 +46,7 @@ use super::{
/// struct Open;
/// impl ProcedureMetadata for Open {
/// type Leaf = ExampleLeaf;
/// fn procedure_suffix() -> &'static str { "open" }
/// const PROCEDURE_SUFFIX: &'static str = "open";
/// }
/// assert_eq!(Open::procedure_id(), "org.example.v1.shell.open");
/// ```
@@ -55,7 +55,12 @@ pub trait ProcedureMetadata: Sized {
type Leaf: ProtocolLeaf;
/// Returns the local suffix used to derive the full canonical `procedure_id`.
fn procedure_suffix() -> &'static str;
const PROCEDURE_SUFFIX: &'static str;
/// Returns the local suffix used to derive the full canonical `procedure_id`.
fn procedure_suffix() -> &'static str {
Self::PROCEDURE_SUFFIX
}
/// Returns the canonical `procedure_id` for this procedure.
fn procedure_id() -> String {
@@ -81,8 +86,7 @@ pub trait ProcedureMetadata: Sized {
/// struct Open;
/// impl ProcedureMetadata for Open {
/// type Leaf = ExampleLeaf;
///
/// fn procedure_suffix() -> &'static str { "open" }
/// const PROCEDURE_SUFFIX: &'static str = "open";
/// }
/// fn _compat<T: StatefulProcedureMetadata<ExampleLeaf>>() {}
/// _compat::<Open>();
@@ -133,15 +137,20 @@ pub trait ProcedureStore<P> {
/// ```rust
/// use std::collections::BTreeMap;
/// use std::string::String;
/// use unshell::{Leaf, Procedure};
/// use unshell::{Procedure, leaf};
/// use unshell::protocol::tree::{Call, HookKey, Procedure, ProcedureEffect, ProcedureStore};
///
/// #[derive(Default, Leaf)]
/// #[leaf(id = "org.example.v1.stream")]
/// #[derive(Default)]
/// struct StreamLeaf {
/// sessions: BTreeMap<HookKey, OpenProcedure>,
/// }
///
/// leaf! {
/// id = "org.example.v1.stream",
/// procedures = [OpenProcedure],
/// endpoint_struct = StreamLeaf,
/// }
///
/// impl ProcedureStore<OpenProcedure> for StreamLeaf {
/// fn procedure_sessions(&mut self) -> &mut BTreeMap<HookKey, OpenProcedure> {
/// &mut self.sessions