Crate up_rust

Expand description

up-rust is the Rust language library for Eclipse uProtocol™ — a protocol that lets software components (in vehicles and beyond) publish data, subscribe to it, and call each other’s services over whatever messaging technology a deployment happens to use: MQTT, Zenoh, DDS, shared memory, and more.

The idea in one sentence: you write against one small messaging API, and the technology underneath stays swappable.

§Your first message

use up_rust::{UMessageBuilder, UPayloadFormat, UTransport, UUri};

async fn publish_engine_temp(transport: &dyn UTransport) -> Result<(), Box<dyn std::error::Error>> {
    // Every message has a source address: authority / entity / version / resource.
    let topic = UUri::try_from_parts("my-vehicle", 0x1_0001, 1, 0x8001)?;

    let message = UMessageBuilder::publish(topic)
        .build_with_payload("92.5", UPayloadFormat::Text)?;

    transport.send(message).await?;
    Ok(())
}

That is the whole application-side model: build a UMessage, hand it to a UTransport someone has configured, done. Receiving is the mirror image — register a UListener for the addresses you care about.

§Which reader are you?

You want to…	Start at	Cargo features
Write an application — publish, subscribe, or call/serve RPC	The role traits in `communication`: `Publisher`, `Subscriber`, `Notifier`, `RpcClient`, `RpcServer` — ready-made on top of any transport	`communication`
Connect a messaging technology — make uProtocol run over your broker/bus	`UTransport` (start here), then the `guide`’s transport chapter for the richer frame-based options	`transport-implementer-api`
Add a payload encoding — carry a new serialization format efficiently	The `guide`’s wire chapter and `wire_implementer_api`	`wire-implementer-api`
Move large payloads without copies — camera frames, LiDAR scans, big tables	The typed path in the transport chapter (apps) or the zero-copy tutorial (transports)	`zero-copy-transport` (+ your side’s feature above)

The guide walks each path end to end with code.

§Five words you’ll meet everywhere

uEntity — any software component that talks uProtocol (an app, a service, a sensor feed).
Transport Layer (“up-L1”) — the layer that physically moves message bytes; a transport is one implementation of it (Zenoh, MQTT, DDS, …).
Communication Layer (“up-L2”) — the friendly role API (publish/subscribe/RPC) built on top of any transport.
Wire format — how a payload is encoded into bytes (protobuf, CDR, Arrow, …). Wires and transports are independent: any wire can ride any capable transport.
Zero-copy loan — for large payloads, a transport can lend you its own transmit buffer so you write data exactly once, directly where it will be sent from. The receive side hands payloads out the same way, as read-only leases.

§Module map

communication — the up-L2 roles most applications use.
umessage, uri, uattributes — the core message model.
utransport — the up-L1 contract transports implement.
wire and payload — wire identities and payload codecs.
frame — the validated frame model advanced transports exchange.
guide — tutorials for every audience above.

§Features

No feature is enabled by default; enable what your role needs. Each feature below silently enables everything it requires. Constrained publish-only builds need no feature at all: use the Transport Layer directly — it’s the first example above, and it carries no protobuf and no tokio. No documented features in Cargo.toml

§References

uProtocol Specification

Re-exports§

pub use local_transport::LocalTransport;
pub use frame::metadata::FrameMessageKind;
pub use frame::metadata::FramePriority;
pub use frame::metadata::PayloadEncoding;
pub use frame::metadata::UFrameMetadata;
pub use frame::metadata::UFrameMetadataError;
pub use frame::validate_frame_view_for_transport;
pub use frame::UFrameView;
pub use payload::UWireError;
pub use frame::envelope::UFrameWireError;
pub use frame::envelope::UFrameWireFormat;
pub use payload::codec::DecodePayload;
pub use payload::codec::EncodePayload;
pub use payload::codec::PayloadCodec;
pub use payload::codec::PayloadFormat;
pub use payload::codec::PayloadLayout;
pub use payload::codec::ProtobufPayload;
pub use payload::codec::ReadDecodePayload;
pub use payload::loan::LoanPayload;
pub use payload::loan::LoanUninitPayload;
pub use payload::loan::LoanedInitPayload;
pub use payload::loan::LoanedUninitPayload;
pub use payload::stable::assert_stable_payload_byte_backed_uninit;
pub use payload::stable::stable_payload_supports_byte_backed_uninit;
pub use payload::stable::ByteBackedStablePayload;
pub use payload::stable::InitializedStablePayload;
pub use payload::stable::StableContainerPayload;
pub use payload::stable::StableContainerPayloadInfo;
pub use payload::stable::StablePayload;
pub use payload::stable::StablePayloadInit;
pub use payload::stable::StablePayloadInitContext;
pub use wire::NativePrefixFrameMetadataCodec;
pub use wire::ProtobufWire;
pub use wire::StableContainerWireFormat;
pub use wire::UProtocolNativeWire;
pub use wire::WireCompatibility;
pub use wire::WireIdentity;
pub use wire::WireIdentityRef;
pub use wire::NATIVE_EXPLICIT_PAYLOAD_FAMILY_ID;
pub use wire::NATIVE_PREFIX_METADATA_LAYOUT_ID;
pub use wire::PROTOBUF_PAYLOAD_FAMILY_ID;
pub use wire::PROTOBUF_WIRE_ID;
pub use wire::STABLE_CONTAINER_PAYLOAD_FAMILY_ID;
pub use wire::STABLE_CONTAINER_WIRE_ID;
pub use wire::UFRAME_FIELDS_METADATA_LAYOUT_ID;
pub use wire::UPROTOCOL_NATIVE_WIRE_ID;
pub use wire::XCDR_V2_PAYLOAD_FAMILY_ID;
pub use wire::XCDR_V2_WIRE_ID;
pub use wire::UWire;
pub use wire::UWireDecode;
pub use wire::UWireEncode;
pub use wire::UWirePayload;
pub use wire::UWireReadDecode;
pub use wire::UWireMetadataCodec;
pub use wire::UWireMetadataCodecFor;
pub use wire::UWireMetadataContext;
pub use wire::UWireMetadataError;
pub use wire_transport::UEncodedRxFrame;
pub use wire_transport::USelectedWireZeroCopyTransport;
pub use wire_transport::UWireTransport;
pub use wire_transport::EncodedOwnedFrame;
pub use wire_transport::PreparedOwnedFrame;
pub use wire_transport::UEncodedOwnedListener;
pub use wire_transport::UOwnedTransportCore;
pub use wire_transport::PreparedTxLoanSpec;
pub use wire_transport::UEncodedLoanedRxFrame;
pub use wire_transport::UEncodedZeroCopyListener;
pub use wire_transport::UZeroCopyTransportCore;
pub use wire_transport::UZeroCopyUninitTransportCore;
pub use wire_transport::ProtobufWireTransport;
pub use wire_transport::StableContainerWireTransport;
pub use wire_transport::UNativePrefixWireTransport;
pub use wire_transport::UWithNativePrefixWire;
pub use wire_transport::UHasWire;
pub use wire_transport::UWireRx;

Modules§

bench_fixtures: Cross-crate benchmark and contract-test fixtures (plumbing).
communication: Traits representing uProtocol’s Communication Layer API for publishing and subscribing to topics and for invoking RPC methods. Also contains default implementations of the traits employing uProtocol’s Transport & Session Layer API.
core: Default client implementations for interacting with uProtocol’s Core entities.
frame: The native frame data model: metadata, canonical field-block codec, and the read-side frame view contract.
guide: Guide: tutorials for every audience
local_transport: Provides an implementation of uProtocol’s Transport & Session Layer API which can be used for connecting uEntities that are running in the same process.
payload: Payload codec contracts shared by the frame families.
selected_wire_user_api: Compatibility import surface for selected-wire users.
symphony: Types and helpers that allow implementing an Eclipse Symphony™ Target Provider as a uService exposed via the Communication Layer API’s RpcServer.
test_support: Test, fake, proof, and fixture support. These are not production transport evidence.
transport_implementer_api: Compatibility import surface for transport implementers.
wire: Selected-wire identities, payload codecs, and metadata profiles.
wire_implementer_api: Compatibility import surface for wire-format implementers.
wire_transport: Selected-wire transport adapter core.

Macros§

bind_wire_self_codec: Binds payload types to a wire whose marker is its own codec (Codec = Self), removing the most repetitive line of an all-in-one wire implementation.

Structs§

CloudEvent
ComparableListener: A wrapper type that allows comparing UListeners to each other.
ExactUUri: A UUri that has been checked to contain no wildcard components.
InMemoryOwnedTransport: In-memory owned-frame transport for unit tests, examples, and guide doctests.
InMemoryZeroCopyTransport: In-memory zero-copy transport for tests and examples.
LoanedPayload: Immutable payload bytes with explicit transport-loan provenance.
LoanedPayloadUninitMut: Mutable uninitialized payload bytes with explicit transport-loan provenance.
MockLocalUriProvider: A factory for URIs representing this uEntity’s resources.
MockTransport: This extra struct is necessary in order to comply with mockall’s requirements regarding the parameter lifetimes see https://github.com/asomers/mockall/issues/571
MockUListener: A handler for processing uProtocol messages.
NotificationBuilderState: The item.
NotificationValidator: Validates attributes describing a Notification message.
PayloadAlignment: Validated visible application payload alignment in bytes.
PublishBuilderState: The item.
PublishValidator: Validates attributes describing a Publish message.
RequestBuilderState: The item.
RequestValidator: Validate UAttributes with type UMessageType::Request
ResponseBuilderState: The item.
ResponseValidator: Validate UAttributes with type UMessageType::Response
SerializationError: Error produced when a value cannot be serialized or deserialized.
StaticUriProvider: A URI provider that is statically configured with the uEntity’s authority, entity ID and version.
UAny: Minimal google.protobuf.Any carrier: a type URL plus serialized bytes.
UAttributes: Message metadata: addressing, identity, type, and delivery options for one UMessage.
UMessage: One uProtocol message: attributes plus optional payload bytes.
UMessageBuilder: A builder for creating UMessages.
UOwnedFrame: Owned, serialization-neutral native uProtocol frame.
UStatus: Operation status: a UCode with optional message and details.
UTxLoanSpec: Validated transport-independent transmit loan specification.
UUID: A uProtocol UUIDv7 message identifier (RFC 9562 layout).
UUri: A URI that represents a uProtocol resource identifier.
UVecRxLease: In-memory receive lease for tests and examples that need receive-lease shape.
UVecTxBuffer: Owned buffer useful for tests, examples, and adapters that emulate a transmit loan.
UVecUninitTxBuffer: Owned uninitialized buffer useful for tests and examples.

Enums§

PayloadLoanProvenance: Diagnostic provenance for loan-backed payload storage.
UAttributesError: Errors produced when building or validating UAttributes.
UAttributesValidators: Enum that hold the implementations of uattributesValidator according to type.
UCode: Canonical status codes for uProtocol operations.
UMessageError: Errors produced when building or converting a UMessage.
UMessageType: The four uProtocol message kinds.
UPayloadFormat: Payload serialization formats defined by the uProtocol specification.
UPriority: QoS priority classes defined by the uProtocol specification.
UTxPayloadSpec: Payload presence and layout requested for a transmit loan.
UUriError: An error indicating a problem with creating or parsing a UUri.
Unvalidated: Typestate marker: not yet validated.
Validated: Typestate marker: validation has passed.

Constants§

CONTENT_TYPE_CLOUDEVENTS_PROTOBUF: MIME content type for protobuf-encoded CloudEvents.

Traits§

BuilderState: Represents the type of message being built by a UMessageBuilder. This is used to limit the available builder functions and to ensure that the builder is used in a consistent way. For example, only a builder for a request message can set the permission_level and token attributes and only a builder for a response message can set the comm_status and request_id attributes. This is achieved by having different builder state types for each message type and by using the BuilderState::merge_into_attributes function to add the state-specific attributes to the final message attributes when building the message.
LocalUriProvider: A factory for URIs representing this uEntity’s resources.
ProtobufMappable: Role: standalone utility letting protobuf-generated types ride as payloads implicitly; blanket-implemented for protobuf types — see the trait map.
UAttributesValidator: Role: standalone utility validating message attributes per message kind; used by transports at boundaries — see the trait map.
UListener: A handler for processing uProtocol messages.
ULoanedContiguousZeroCopyRxFrame: Role: a receive lease over contiguous loan-backed storage; lets typed payloads be borrowed without copying — see the trait map.
UOwnedListener: Role: implemented by applications to receive owned frames — see the trait map.
UOwnedTransport: Experimental serialization-neutral owned native-frame transport API.
UOwnedTransportImpl: Role: implemented by transports offering the owned-frame family; users call UOwnedTransport — see the trait map.
UTransport: The uProtocol Transport Layer interface that provides a common API for uEntity developers to send and receive messages.
UTxBuffer: Role: transmit storage a zero-copy transport lends; write the payload in place, then commit — see the trait map.
UUninitTxBuffer: Role: an uninitialized transmit loan; filled safely via the typed init API — see the trait map.
UZeroCopyListener: Role: implemented by applications to receive zero-copy leases — see the trait map.
UZeroCopyRxLease: Role: a received payload read in place; dropping it returns the storage — see the trait map.
UZeroCopyTransport: Role: called by users of the zero-copy family; transports implement UZeroCopyTransportImpl or the encoded core instead — see the trait map.
UZeroCopyTransportExt: Role: free blanket methods on every zero-copy transport; never implemented by hand — see the trait map.
UZeroCopyTransportImpl: Role: implemented by transports whose API speaks the library’s frame types; users call UZeroCopyTransport — see the trait map.
UZeroCopyUninitTransport: Role: called by users to obtain uninitialized loans; transports implement UZeroCopyUninitTransportImpl — see the trait map.
UZeroCopyUninitTransportExt: Role: free blanket methods for typed initialization into uninitialized loans; never implemented by hand — see the trait map.
UZeroCopyUninitTransportImpl: Role: implemented by transports that can lend uninitialized storage — see the trait map.

Functions§

validate_tx_buffer_for_transport: Validates a transmit buffer before committing it through a public zero-copy boundary.
verify_filter_criteria: Verifies that given UUris can be used as source and sink filter UUris for registering listeners.
verify_tx_buffer_payload_layout: Verifies the visible transmit payload layout exposed by a zero-copy loan.
verify_uninit_tx_buffer_payload_layout: Verifies the visible uninitialized transmit payload layout exposed by a loan.

Derive Macros§

ByteBackedStablePayload: Derives for stable payload types. Derives ByteBackedStablePayload: marks every byte pattern of the type as valid.
StablePayload: Derives for stable payload types. Derives StablePayload: a fixed-layout type whose bytes are stable across processes.
StablePayloadInit: Derives for stable payload types. Derives StablePayloadInit: a typestate initializer that writes the type into uninitialized storage field by field.

Crate up_rustCopy item path