Crate weida

Expand description

weida: a QUIC-native messaging framework.

This crate hosts the runtime, the native QUIC transport, the raw stream core and the brokerless messaging patterns: Req/Rep, Push/Pull, Pub/Sub, PAIR, SURVEY and BUS — the whole nanomsg set, none of which adds wire vocabulary. A completion is a cursor: a level plus an absolute byte offset, reported on a unidirectional stream of its own (Cursors, Reporter). docs/ARCHITECTURE.md describes the layer model, docs/PROTOCOL.md is the normative wire specification, and docs/FAILURE_MODEL.md defines what each outcome means.

use weida::{Runtime, RuntimeConfig, TransferMeta, Trust};

let runtime = Runtime::new(RuntimeConfig::default())?;

// Trust belongs to the dialling endpoint, not to the runtime. Here the
// address itself names the peer's public key, so nothing else is needed.
let requester = runtime.requester(Trust::by_address());
requester
    .connect("weida://sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08@127.0.0.1:7443/transform")
    .await?;

// One bidirectional stream: the request half and the reply half. The
// stream is the correlation, so nothing on the wire names the exchange.
let (mut transfer, reply) = requester.open(TransferMeta::default()).await?;
transfer.write_all(b"hello weida").await?;
transfer.finish()?;

let body = reply.recv().await?.collect(64 * 1024).await?;
println!("{}", String::from_utf8_lossy(&body));

The example above runs on the caller’s ambient Tokio reactor. A caller that has none — or whose executor is not Tokio at all — uses Runtime::owned instead: the runtime then owns the reactor quinn needs, and every task, timer and name lookup weida performs runs there, while the futures it hands back may be driven by any executor. Transfer payloads implement both the tokio::io and the futures-io traits for the same reason.

Modules§

codes: QUIC application error codes used in CONNECTION_CLOSE, RESET_STREAM and STOP_SENDING (docs/PROTOCOL.md §7).
filter: The topic filter grammar of docs/PROTOCOL.md §6.4.

Structs§

Acceptor: The bound side of the stream core.
Binding: One concrete transport binding of a Listener.
ClientTls: TLS configuration of a dialling endpoint: what it trusts and, optionally, who it is.
Consumer: One subscribed consumer, and the way to deliver to it.
ConsumerId: Identifies one consuming connection on one path.
CreditGrant: A consumer’s absolute delivery limit for one subscription.
CursorSet: The latest offset reported per level, for one transfer.
Cursors: The reader’s end of one transfer’s report.
Delivery: The transport receipt for a finished transfer.
Drained: What a drain achieved, counted locally.
Endpoint: A typed messaging endpoint.
EndpointAddr: A parsed weida://[fingerprint@]host[:port]/path address.
FanOut: A publish in progress: a payload written once and fanned out to one stream per subscriber, without ever being held whole.
FilesOptions: How a file source watches its directory.
Fingerprint: SHA-256 digest of a peer’s public key.
Gap: What a receiver observed about one transfer’s place in its producer’s sequence.
GuaranteeSet: One level per guarantee dimension, as declared in HELLO keys 5 and 6 (docs/PROTOCOL.md §6.5).
Identity: Who this endpoint is: a certificate chain and the private key behind it.
IdentityEvents: The event stream of one IdentitySource or TrustSource.
IdentitySource: Where an identity comes from, and the identity of the moment.
IncomingMeta: Metadata of an inbound transfer.
IncomingRequest: A request accepted by a crate::Replier or a raw crate::Acceptor.
IncomingTransfer: An inbound transfer: one receive stream plus the metadata that described it.
InprocAddr: A parsed weida+inproc://<bus>/<path> address.
Limits: Resource limits applied to one connection.
Listener: One externally reachable messaging namespace.
LocalBinding: One in-process binding: a bus name and nothing else.
LocalPrincipal: A principal the kernel proved, on a local transport.
OutgoingTransfer: An outgoing transfer: one QUIC send stream, owned outright.
Peer: The dialling side of the stream core.
PeerEvents: The event stream of one dialling endpoint.
PipeAddr: A parsed weida+pipe://<pipe-name>/<path> address.
ReconnectPolicy: How a dialling endpoint redials an address it has lost.
ReplyStream: The reply half of an exchange the requester is waiting on.
Reporter: The writer’s end: what a receiver uses to report on a transfer it got.
Runtime: A process-level execution and resource container.
RuntimeConfig: Configuration for one crate::Runtime.
ServerTls: TLS configuration of a binding: who it is and, optionally, whom it lets in.
SharedResolver: The resolver a configuration holds.
SurveyRun: One survey in progress: the answers, and what the deadline cost.
SystemResolver: The system resolver: an IP literal in place, everything else through getaddrinfo.
TopicDrops: What a publisher dropped on one topic, by cause.
TraceContext: A W3C Trace Context traceparent.
TransferMeta: Per-transfer metadata supplied by the application.
Trust: Whom a peer is accepted as.
TrustSource: Whom a peer is accepted as, as a source: the anchors and pins of the moment, changeable under a live binding.
UnixAddr: A parsed weida+unix://<percent-encoded-socket-path>/<path> address.
UnixBinding: One AF_UNIX binding: the socket file, removed when this drops.
WindowsPrincipal: A principal the kernel proved, on a Windows named pipe.

Enums§

Acknowledgement: Acknowledgement/completion dimension. A ladder; the durability axes of Durability and replicas are not part of it.
Address: An address of any transport.
Backpressure: Backpressure dimension. Not ordered: these are behaviours, not strengths, so two peers state the same one or fail to negotiate.
Bus: A member of a BUS.
CursorLevel: A level a cursor can name: one weida defines, or one the application does.
Deduplication: Deduplication dimension. A ladder: later is stronger.
DeliveryLevel: Delivery dimension (GUARANTEES.md §3). A ladder: later is stronger.
Discovery: Whether a dialled authority may name a set of nodes.
Durability: Persistence axis of Stored/Replicated (decisions/0004 §4.1).
Error: Everything that can go wrong in a weida operation.
ErrorCode: Wire codes carried in an ERROR frame (docs/PROTOCOL.md §6.4).
GiveUp: Why a slot stopped redialling.
IdentityEvent: One transition of an IdentitySource.
Incoming: One inbound thing on a raw acceptor’s path, whichever kind the peer sent.
LossCause: Why a connection is gone.
OrderingMode: Ordering dimension. A ladder: later is stronger.
OutboxFull: What a send does when the outbox is at its bound (crate::RuntimeConfig::outbox_messages).
Pair: Either side of PAIR: one connection, one peer, both directions.
PeerEvent: One transition of one dialled address, reported on PeerEvents.
PeerIdentity: Who the peer is, once it has been proved.
Pem: Where PEM material comes from.
ProducerNaming: How a producer is named for the sequence field of decisions/0001 §7.3. Not ordered: two peers state the same one or fail.
Pub: The publishing side of Pub/Sub.
Pull: The receiving side of Push/Pull.
Push: The sending side of Push/Pull.
Rep: The replying side of Req/Rep.
ReportMode: How often a reporter emits a record (docs/PROTOCOL.md §6.2, key 11).
Reported: What a bounded wait for a cursor found.
Req: The requesting side of Req/Rep.
Respond: The answering side of SURVEY.
StopReason: Why a peer refused to receive more payload, as carried by STOP_SENDING’s QUIC application error code.
Sub: The subscribing side of Pub/Sub.
Survey: The asking side of SURVEY.

Constants§

ALPN: TLS ALPN token identifying the weida native QUIC protocol.
DEFAULT_PORT: The port a weida:// URL means when it writes none.
VERSION: Wire protocol version implemented by this crate (experimental).

Traits§

Pattern: A messaging pattern.
Resolver: What a name means.

Functions§

new_trace: Generates a fresh root trace context.

Type Aliases§

BusMember: One member of a BUS.
Paired: Either half of PAIR — the pattern is symmetric, so there is one role.
Publisher: The publishing half of Pub/Sub.
Puller: The receiving half of Push/Pull.
Pusher: The sending half of Push/Pull.
Replier: The replying half of Req/Rep.
Requester: The requesting half of Req/Rep.
Resolved: The future a Resolver returns.
Respondent: The answering half of SURVEY.
Result: Convenience alias used throughout the framework.
Subscriber: The subscribing half of Pub/Sub.
Surveyor: The asking half of SURVEY.

Crate weida

Crate weida Copy item path

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate weida