mirror of
https://github.com/Astatin3/unshell.git
synced 2026-06-09 06:47:59 -06:00
Michael Mikovsky
54c44b407e
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.
86 lines
2.9 KiB
Markdown
86 lines
2.9 KiB
Markdown
# UnShell Macros
|
|
|
|
This crate owns the compile-time declaration layer for UnShell application-facing
|
|
leaves.
|
|
|
|
## Purpose
|
|
|
|
The protocol crate intentionally stays generic: it knows how to route packets,
|
|
validate framing, and deliver local events, but it should not need handwritten
|
|
registration code for every leaf.
|
|
|
|
The macro layer exists to move as much of that registration work as possible to
|
|
compile time.
|
|
|
|
In practical terms, the macro system is responsible for:
|
|
|
|
- deriving canonical procedure identifiers
|
|
- generating compile-time procedure inventories for leaves
|
|
- binding one leaf declaration to separate endpoint and TUI host structs without
|
|
repeating the metadata on each host
|
|
- generating dispatch glue for simple call-driven leaves
|
|
|
|
## Model
|
|
|
|
There are three layers in the intended design.
|
|
|
|
### 1. Leaf declaration
|
|
|
|
One declaration is the source of truth for one protocol leaf.
|
|
|
|
The declaration answers:
|
|
|
|
- what is this leaf called on the wire?
|
|
- which procedure suffixes belong to it?
|
|
- which host structs implement its endpoint and TUI roles?
|
|
|
|
The goal is that this information is written once and reused everywhere.
|
|
|
|
### 2. Host structs
|
|
|
|
One leaf can have multiple host structs with different responsibilities.
|
|
|
|
- the endpoint host owns runtime state and protocol-side behavior
|
|
- the TUI host owns user-interface state and interpretation behavior
|
|
|
|
Those hosts should not each have to repeat the leaf name or procedure inventory.
|
|
They bind to the declaration instead.
|
|
|
|
### 3. Procedure and method metadata
|
|
|
|
Procedures and future typed remote methods need stable canonical identifiers.
|
|
|
|
The macro layer generates those identifiers from the leaf declaration and the
|
|
local suffix for each procedure or method. That lets the runtime consume a
|
|
compile-time inventory instead of handwritten lists.
|
|
|
|
## Current direction
|
|
|
|
The public declaration model is now centered on `leaf!`.
|
|
|
|
- `leaf!` declares the canonical protocol surface once
|
|
- `#[derive(Procedure)]` derives stateful procedure metadata
|
|
- `#[procedures]` derives one-shot call dispatch for simple leaves
|
|
|
|
The next evolution from here is typed remote-method metadata on top of the same
|
|
declaration model.
|
|
|
|
## Design constraints
|
|
|
|
The system is optimized for a few constraints that matter to this repository.
|
|
|
|
- compile-time declaration should replace handwritten runtime registration where
|
|
possible
|
|
- protocol-visible names should remain deterministic and canonical
|
|
- generated code should stay explicit enough to debug
|
|
- endpoint and TUI roles should share metadata but not be forced into the same
|
|
runtime trait when their behavior differs
|
|
- migration should be low-breakage for the existing examples and tests
|
|
|
|
## Non-goals
|
|
|
|
This crate does not own transport, connection management, or packet execution.
|
|
Those remain in `unshell-protocol` and higher application layers.
|
|
|
|
The macro crate should generate metadata and glue, not hide the runtime model.
|