Crate wip_interface

Expand description

Public authoring API for Web Interface Protocol (WIP) interfaces.

Add wip-interface to an application and import it under the short name used by the attribute examples:

use wip_interface as wip;

#[derive(Debug, PartialEq, wip::WipType)]
struct Greeting {
    /// Text shown to the recipient.
    message: String,
}

#[wip::interface]
pub trait Greeter {
    /// Builds a greeting.
    ///
    /// # Returns
    /// The generated greeting.
    fn greet(&self, /// Person to greet.
        name: String) -> wip::OperationResult<Greeting>;
}

The attribute and derive are re-exported by this facade; applications do not depend on the implementation-only wip-interface-macros crate.

§Rust to protocol type mapping

Rust type	Protocol type/value
`()`	`Unit`
`bool`	`Boolean`
signed and unsigned integer primitives	JavaScript-lossless `Integer`
`f32`, `f64`	finite `Number`
`String`	`String`
`Bytes`	`Bytes`
`JsonValue`	schema-neutral `Json` value tree
`Entry`	canonical absolute Worldspace path (`Entry`)
`Vec<T>`	`List<T>`
a named-field struct deriving `WipType`	named record
an all-unit enum deriving `WipType`	named enum
an enum mixing unit and single-payload cases deriving `WipType`	named union

Option<T> is supported only directly as a record field or operation parameter. It means omission, not a null value. A domain failure belongs in an application return enum/union and is returned as Ok(value). HostError is reserved for host/runtime failure and requires an explicit HostErrorKind plus EffectGuarantee. The required OperationResult convention therefore keeps domain failures separate from runtime failures and makes outcome uncertainty visible to Host dispatch.

§Migration to canonical values

Earlier releases exposed Entry<K, V> and semantic Value::Json, Value::Entry, Value::Enum, and Value::Union variants. Those forms are intentionally gone: Entry is now one validated absolute Worldspace path, while JSON, enum, and union meaning comes only from the descriptor. Codecs exchange only raw Value strings, records, lists, and primitives. Unit operation results now cross the boundary as Value::Unit rather than an absent value.

§Supported interface syntax

An interface is a public, non-generic trait whose operations use exactly &self, simple named owned parameters, and an explicit OperationResult<T>. WipType derives support named-field structs, all-unit enums as protocol enums, and enums made from any mix of unit and single-payload cases as protocol unions.

The macros reject trait inheritance and associated items; const, async, unsafe, extern, variadic, generic, default-bodied, or non-&self methods; borrowed values and custom lifetimes; tuple, unit, or generic structs; unsupported named-field or multi-field enum variants; explicit discriminants; Rust unions; and Option anywhere except a direct DTO field or operation parameter. Unsupported inputs produce source-located compile errors rather than generating a partial interface.

Re-exports§

pub use wip_protocol;

Structs§

Bytes: An explicitly byte-oriented sequence.
CodecError: A failure while converting between a Rust value and a protocol Value.
Documentation: Human-readable plain-text documentation attached to a protocol declaration.
Entry: A canonical absolute path to an entry in the current Worldspace.
EnumCase: One payload-free enum case.
FieldDeclaration: Declaration of a record field.
HostError: A typed host/runtime failure, kept separate from the operation’s application return type.
InterfaceDescriptor: Transport-independent description of one interface.
JsonMember: One member in a JsonValue::Object.
OperationDeclaration: Declaration of one interface operation.
ParameterDeclaration: Declaration of one operation parameter.
ReturnDeclaration: Declaration of an operation return value.
TypeDeclaration: A descriptor-local named type declaration.
UnionCase: One union case with zero or one payload.
ValidationError: A validation failure with a typed path to the failing location.

Enums§

DispatchError: A failure produced by macro-generated typed operation dispatch.
DispatchPhase: Whether generated dispatch failed before or after typed implementation invocation began.
EffectGuarantee: Whether an operation failure proves that no effects were committed.
HostErrorKind: Host/runtime failure category used when effects are known not to be committed.
JsonValue: JSON data represented independently of any application schema.
TypeExpr: A type expression used by declarations, fields, parameters, and returns.
Value: A schema-neutral logical protocol value.

Constants§

MAX_SAFE_INTEGER: Largest integer exactly interoperable with a JavaScript Number.
MIN_SAFE_INTEGER: Smallest integer exactly interoperable with a JavaScript Number.

Traits§

InterfaceDefinition: Static metadata implemented by every companion generated by interface.
InterfaceImplementation: Typed dispatch implemented by every generated interface companion.
WipType: Converts one Rust application type to and from its protocol representation.

Type Aliases§

OperationResult: Result convention required for generated interface operations.

Attribute Macros§

interface: Declares a public Rust trait as a WIP interface.

Derive Macros§

WipType: Derives the WIP type declaration and logical value codec for a DTO.