Crate wip_protocol

Expand description

Canonical transport-independent logical types for the Web Interface Protocol.

This crate follows the Core Model and 3-protocol.md without assigning HTTP routes, methods, headers, URL encodings, or JSON envelopes. The correspondence between canonical logical concepts and this crate is direct:

Canonical protocol concept	Rust API
Object projection and ordered interface set	`Object`
Optional object identity / state precondition	`Object::ref` / `Object::validator`
Interface Descriptor	`InterfaceDescriptor`
Named declaration and all schema expressions	`TypeDeclaration` / `TypeExpr`
Schema-neutral primitive/composite value	`Value`
`observe`	`ObserveRequest` / `ObserveResponse`
`fetch_interface`	`FetchInterfaceRequest` / `FetchInterfaceResponse`
Object and interface call preconditions	`Target` / `InterfaceTarget`
`call_operation`	`CallOperationRequest` / `CallOperationResponse`
Stable Host failure taxonomy	`ProtocolErrorCode` / `ProtocolError`
Per-interaction allowed failure codes	`ProtocolInteraction` / `ProtocolErrorCode::is_allowed_for`

ProtocolErrorCode is a closed set of Host-returned wire failures. After a Client receives a response, an invalid Object, Descriptor, operation result, malformed error, or error code disallowed by ProtocolInteraction is a Client-local InvalidResponse, not another wire error. A descriptor whose format is not supported is a Client-local UnsupportedDescriptorFormat.

For call_operation, ProtocolErrorCode::Internal and ProtocolErrorCode::ResourceLimitExceeded guarantee that the operation did not run or that all effects were rolled back. Only ProtocolErrorCode::OperationOutcomeUnknown means the Host cannot make that guarantee; Clients must not automatically retry it.

Paths, object refs, interface refs, and validators remain separate concepts. They are represented by ordinary protocol strings/bytes in the corresponding fields. In particular, object refs are optional, operation targeting uses a path, and this crate defines no interaction that fetches an object by ref.

Value contains only the canonical raw value kinds. A descriptor interprets enum values as strings, entries as canonical-path strings, and unions as records with a $case string plus an optional value payload. JSON uses the same value tree (Unit is JSON null) and rejects bytes.

Structs§

CallOperationRequest: Transport-independent request to execute one operation.
CallOperationResponse: Successful operation response.
Documentation: Human-readable plain-text documentation attached to a protocol declaration.
EnumCase: One payload-free enum case.
FetchInterfaceRequest: Request for the current descriptor of one opaque interface reference.
FetchInterfaceResponse: Successful fetch_interface response.
FieldDeclaration: Declaration of a record field.
InterfaceDescriptor: Transport-independent description of one interface.
InterfaceTarget: Interface portion of an operation target.
Object: The protocol projection currently published at one Worldspace path.
ObjectObservation: One node in an object observation.
ObserveRequest: Request for the object currently published at one path and its indexable descendants.
OperationDeclaration: Declaration of one interface operation.
ParameterDeclaration: Declaration of one operation parameter.
ProtocolError: Transport-independent protocol failure.
ReturnDeclaration: Declaration of an operation return value.
Target: Object portion of an operation target.
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§

NameNamespace: Namespace in which a declaration name must be unique.
PathSegment: A typed segment identifying a declaration or value location.
ProtocolErrorCode: Stable protocol failure code returned by a host.
ProtocolInteraction: One core interaction whose failure codes form a closed set.
ProtocolResult: Logical outcome of any core interaction.
TypeExpr: A type expression used by declarations, fields, parameters, and returns.
ValidationErrorKind: Machine-readable reason why logical protocol validation failed.
Value: A schema-neutral logical protocol value.
ValueKind: Structural kind of a schema-neutral logical value.

Constants§

INTERFACE_FORMAT_V1: Canonical format identifier for the first Interface Descriptor format.
MAX_SAFE_INTEGER: Largest integer exactly interoperable with a JavaScript Number.
MIN_SAFE_INTEGER: Smallest integer exactly interoperable with a JavaScript Number.
UNION_CASE_FIELD: Discriminator field used by a union’s raw record value.
UNION_VALUE_FIELD: Optional payload field used by a union’s raw record value.

Functions§

validate_path: Validates a canonical absolute Worldspace path.

Type Aliases§

ObserveResponse: Successful observe response.