up_rust/
lib.rs

1/********************************************************************************
2 * Copyright (c) 2023 Contributors to the Eclipse Foundation
3 *
4 * See the NOTICE file(s) distributed with this work for additional
5 * information regarding copyright ownership.
6 *
7 * This program and the accompanying materials are made available under the
8 * terms of the Apache License Version 2.0 which is available at
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * SPDX-License-Identifier: Apache-2.0
12 ********************************************************************************/
13
14/*!
15up-rust is the [Eclipse uProtocol&trade; Language Library](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/languages.adoc) for the
16Rust programming language.
17
18This crate can be used to
19
20* implement uEntities that communicate with each other using the uProtocol [Communication Layer API](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l2/api.adoc)
21  over one of the supported transport protocols.
22* implement support for an additional transport protocol by means of implementing the [Transport Layer API](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l1/README.adoc).
23
24## Library contents
25
26* `communication` module, which defines uProtocol's Communication Layer API for publishing and subscribing to topics and invoking RPC methods.
27  It also contains a default implementation employing the Transport Layer API.
28* `uattributes` module, with uProtocol message attribute types and validators
29* `umessage` module, which defines the uProtocol core message type and provides related convenience functionality
30* `upayload` module, which defines payload representation for uProtocol messages
31* `uri` module, providing convenience wrappers for creation and validation of uProtocol-style resource identifiers
32* `ustatus` module, which provides uProtocol types for representing status and status codes
33* `utransport` module, as an interface contract between uProtocol and specific transport protocol implementations
34* `uuid` module, which generates and validates UUIDs as per the uProtocol specification
35
36For user convenience, all of these modules export their types on up_rust top-level, except for (future) optional features.
37
38## Features
39
40* `cloudevents` enables support for mapping UMessages to/from CloudEvents using Protobuf Format according to the
41  [uProtocol specification](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l1/cloudevents.adoc).
42
43* `communication` enables support for the [Communication Layer API](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l2/api.adoc) and its
44  default implementation on top of the [Transport Layer API](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l1/README.adoc).
45  Enabled by default.
46* `udiscovery` enables support for types required to interact with [uDiscovery service](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l3/udiscovery/v3/README.adoc)
47  implementations.
48* `usubscription` enables support for types required to interact with [uSubscription service](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l3/usubscription/v3/README.adoc)
49  implementations. Enabled by default.
50* `utwin` enables support for types required to interact with [uTwin service](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.5/up-l3/utwin/v2/README.adoc)
51  implementations.
52* `test-util` provides some useful mock implementations for testing. In particular, provides mock implementations of UTransport and Communication Layer API traits which make implementing unit tests a lot easier.
53* `util` provides some useful helper structs. In particular, provides a local, in-memory UTransport for exchanging messages within a single process. This transport is also used by the examples illustrating usage of the Communication Layer API.
54
55## References
56
57* [uProtocol Specification](https://github.com/eclipse-uprotocol/up-spec/tree/v1.6.0-alpha.5)
58
59*/
60
61// up_core_api types used and augmented by up_rust - symbols re-exported to toplevel, errors are module-specific
62#[cfg(feature = "cloudevents")]
63mod cloudevents;
64#[cfg(feature = "cloudevents")]
65pub use cloudevents::{CloudEvent, CONTENT_TYPE_CLOUDEVENTS_PROTOBUF};
66
67// [impl->dsn~communication-layer-api-namespace~1]
68#[cfg(feature = "communication")]
69pub mod communication;
70
71#[cfg(feature = "util")]
72pub mod local_transport;
73
74mod uattributes;
75pub use uattributes::{
76    NotificationValidator, PublishValidator, RequestValidator, ResponseValidator, UAttributes,
77    UAttributesError, UAttributesValidator, UAttributesValidators, UMessageType, UPayloadFormat,
78    UPriority,
79};
80
81mod umessage;
82pub use umessage::{UMessage, UMessageBuilder, UMessageError};
83
84mod uri;
85pub use uri::{UUri, UUriError};
86
87mod ustatus;
88pub use ustatus::{UCode, UStatus};
89
90mod utransport;
91pub use utransport::{
92    verify_filter_criteria, ComparableListener, LocalUriProvider, StaticUriProvider, UListener,
93    UTransport,
94};
95#[cfg(feature = "test-util")]
96pub use utransport::{MockLocalUriProvider, MockTransport, MockUListener};
97
98mod uuid;
99pub use uuid::UUID;
100
101// protoc-generated stubs, see build.rs
102mod up_core_api {
103    include!(concat!(env!("OUT_DIR"), "/uprotocol/mod.rs"));
104}
105
106// Types from up_core_api that we're not re-exporting for now (might change if need arises)
107// pub use up_core_api::file;
108// pub use up_core_api::uprotocol_options;
109pub mod core;
up_rust/lib.rs

up_rust/
lib.rs
