# ridl-rt
The library that code generated from [ridl](https://github.com/driftsys/ridl)
links, and a runtime implements.
`ridl-rt` defines, once, the vocabulary that generated code and a runtime agree
on: identity and the interaction descriptors (`contract`), the payload encodings
(`encoding`), the contract and transport errors and the two errors a generated
client call and a generated `serve` return (`error`), encoding and decoding a
payload (`payload`), the ports a runtime implements and generated code calls
(`port`), and time, the envelope, and the values a read returns (`sample`). It
contains no runtime: a runtime is a separate crate that implements the `port`
module's traits. It also carries the caller-side call table and the waker
registry every runtime would otherwise write alone (`correlate`), and the traits
a generated face implements for its fixed methods — `Bind::new`,
`Events::next_event`, `Publish::commit`, and under `std` `Timeout` — which a
consumer brings into scope with the generated `prelude` of each interface whose
face it uses (`face`). One more module holds the optional trace context that a
call or an event carries across a port (`trace`); with the `std` feature it also
holds the application's hook for that context (`Propagation`, `AlreadySet`,
`set_propagation` and `propagation`).
With its default features the crate is `no_std` and allocates nothing; it
contains no `unsafe` code and has no dependency in any feature combination. It
declares one cargo feature per payload encoding — `flatbuffers`, which enables
the FlatBuffers reading and writing helpers, `proto3`, which enables the proto3
varint, tag, reader and writer helpers, and `repr-c`, which enables nothing in
this version — and a `std` feature, off by default, that links the standard
library and enables `task::block_on`, `task::noop_waker` and `task::flag_waker`,
and the propagation hook of the `trace` module.
## Versioning
`ridl-rt` is a 0.x crate. A breaking change bumps the minor version (0.1 → 0.2),
not the major version. A public struct whose fields are all public and that
carries no `#[non_exhaustive]` cannot gain a field without a breaking change,
because code outside the crate can build it as a struct literal: `CatalogRef`,
`Member`, `Timing`, `PayloadInfo`, `Encoded`, `Violation`, `RawSample`,
`RawOccurrence`, `Claim`, `Watermark`, `Changed`, `Envelope`, `Sample`,
`Occurrence`, `TraceContext`. The public tuple structs — `Ordinal`,
`InterfaceNo`, `CatalogHash`, `Correlation`, `ClaimId`, `Timestamp`, `Duration`
— follow the same rule. So do the unit structs `FlatBuffers`, `Proto3` and
`ReprC` (`src/encoding.rs`), `TrackerFull` (`src/sample.rs`) and `AlreadySet`
(`src/trace.rs`): each is a unit struct with no field that code outside the
crate uses as a value or a pattern, so a field added to any of them breaks that
code.
The API questions that the reviews of 0.1 raised are settled; the issue that
tracked them is <https://github.com/driftsys/ridl/issues/350>.
`ridl-rt` supports Rust 1.88 or newer (`rust-version = "1.88"`). Raising that
minimum is a breaking change, shipped in a 0.x minor release like any other.
Releases before the one that raised it to 1.88 supported Rust 1.83.
The crate builds as edition 2021 and edition 2024: edition 2021 is tested with
Rust 1.88 and with the pinned toolchain, and edition 2024 is tested with the
pinned toolchain.
## What 0.1 leaves out
- streams
- `Inline`
- the three payload codecs (proto3, FlatBuffers, `repr(C)`)
- `Encoding::FORMAT`
- `Family`
- `Access`
- `Constrained`
- the runtimes (`ridl-loopback`, `ridl-transport-ws`)
- the engine
## License
MIT. See [LICENSE](https://github.com/driftsys/ridl/blob/main/LICENSE).