feat(interface): add authoring macros and codecs

Add the wip-interface facade and proc-macro implementation for typed interface descriptors, DTO value codecs, validated dispatch, metadata extraction, and span-aware compile failures.
2026-09-28 23:11:17 +09:00
parent 6b6e96c303
commit 18ac8844b0
32 changed files with 2991 additions and 1 deletions
@@ -0,0 +1,67 @@
+# wip-rs
+
+Rust building blocks for the Web Interface Protocol (WIP).
+
+## Interface authoring
+
+Applications depend on `wip-interface`, normally imported as `wip`:
+
+```rust
+use wip_interface as wip;
+
+#[derive(wip::WipType)]
+struct Message {
+    /// Message body.
+    text: String,
+}
+
+#[wip::interface]
+pub trait Messenger {
+    /// Sends a message.
+    ///
+    /// # Returns
+    /// Whether the application accepted the message.
+    fn send(
+        &self,
+        /// Message to send.
+        message: Message,
+    ) -> wip::OperationResult<bool>;
+}
+```
+
+The `interface` attribute and `WipType` derive are re-exported by the facade;
+users do not import `wip-interface-macros` directly. The generated
+`MessengerDefinition` constructs an `InterfaceDescriptor`, decodes named
+arguments, encodes results, validates both boundaries, and provides typed
+dispatch for any `T: Messenger`.
+
+### Type mapping
+
+| Rust | Protocol |
+| --- | --- |
+| `()` as an operation result | no returned value |
+| `bool` | boolean |
+| integer primitives | JavaScript-lossless integer |
+| `f32`, `f64` | finite number |
+| `String` | string |
+| `wip::Bytes` | bytes |
+| `wip::wip_protocol::JsonValue` | JSON |
+| `wip::Entry<K, V>` | entry |
+| `Vec<T>` | list |
+| named-field `#[derive(wip::WipType)]` struct | named record |
+| all-unit `#[derive(wip::WipType)]` enum | named enum |
+| all-newtype `#[derive(wip::WipType)]` enum | named tagged union |
+
+`Option<T>` is accepted only for a direct DTO field or operation parameter and
+means that the named value may be omitted. It is not protocol null. Domain
+failures are modeled in the application result (usually a derived union) and
+returned through `Ok`; `wip::HostError` is only for host/runtime failures.
+
+Rust doc comments become descriptor metadata. For an operation, a `# Returns`
+section documents the return declaration; text before that section documents
+the operation itself.
+
+The supported interface slice is deliberately non-generic: public traits,
+`&self`, named parameters, and `OperationResult<T>`. Generic traits or methods,
+associated items, custom lifetimes, inheritance, default method bodies, and
+other receiver forms are rejected at their source spans.