lib.rs

/********************************************************************************
 * Copyright (c) 2023 Contributors to the Eclipse Foundation
 *
 * See the NOTICE file(s) distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Apache License Version 2.0 which is available at
 * https://www.apache.org/licenses/LICENSE-2.0
 *
 * SPDX-License-Identifier: Apache-2.0
 ********************************************************************************/

/*!
# uProtocol in Rust

uProtocol separates application messaging from the transport used to carry
messages across an IPC or network boundary. Applications can use five
**Communication Layer** role APIs across four messaging patterns:

* `Publisher` emits events;
* `Subscriber` consumes events;
* `Notifier` targets a one-way message;
* `RpcClient` invokes a service, while `RpcServer` serves it.

Each role is an API over a [`UTransport`]. Applications can instead call
[`UTransport::send`] directly and receive messages through registered
listeners for push, [`UTransport::receive`] for pull, or both. A transport maps
the contract to its broker, bus, or peer-to-peer protocol.

```rust
use up_rust::{UMessageBuilder, UPayloadFormat, UStatus, UTransport, UUri};

async fn publish_engine_temp(
    transport: &dyn UTransport,
) -> Result<(), UStatus> {
    let topic = UUri::try_from_parts("my-vehicle", 0x1_0001, 1, 0x8001)
        .expect("valid topic URI");
    let message = UMessageBuilder::publish(topic)
        .build_with_payload("92.5", UPayloadFormat::Text)
        .expect("valid publish message");

    transport.send(message).await
}
```

The [`guide`] provides:

* [application role examples](crate::guide::applications::communication),
* [direct Transport Layer examples](crate::guide::applications::transport),
* [transport implementation guidance](crate::guide::utransport), and
* [a public trait map](crate::guide::trait_map).

## Features

None of the following features are enabled by default, so you can pick and choose which parts of the library you want to use by enabling the corresponding features. Note that some features depend on each other, so enabling one feature might automatically enable other features as well. For example, enabling `up-core-types` will also enable `protobuf-support` since the generated types require that.

* `cloudevents` Enables support for mapping [crate::UMessage]s to/from `CloudEvent`s using Protobuf Format according to the
  [uProtocol specification](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.7/up-l1/cloudevents.adoc).
* `communication` Enables default implementations for all [Communication Layer API](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.7/up-l2/api.adoc) traits on top of the [Transport & Session Layer API](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.7/up-l1/README.adoc).
* `protobuf-support` Enables convenience functions on the Transport & Session as well as the Communication Layer APIs for implicitly mapping objects to protobuf payloads on the fly. This is particularly useful for using protoc-generated types as payloads using `UMessageBuilder::build_with_protobuf_payload` or `UPayload::try_from_protobuf`. The only requirement for the object types is that they implement `ProtobufMappable`. A blanket implementation for types generated by the `protobuf` crate is also provided. Note that it is still possible to use protobufs as payloads even without enabling this feature. The payload of a [crate::UMessage] can be set to an arbitrary byte array, so protobuf messages can be serialized to bytes and set as payload without any support from the library. Enabling this feature just adds some convenient helper functions for automatically handling the mapping to protobuf payloads. The examples also illustrate the usage of these helper functions.
* `symphony` Enables support for implementing an [Eclipse Symphony](https://github.com/eclipse-symphony) Target Provider as a uService exposed via the Communication Layer API's `RpcServer`.
* `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.
* `up-core-types` Enables support for mapping the crate's public API types to protobufs as defined in the uProtocol specification. This includes, for example, the [`UStatus`] type which is used in the Communication Layer API for conveying errors. Enabling this feature also enables `protobuf-support` since the generated types require that.
* `up-l2-api` Enables support for the [Communication Layer API](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.7/up-l2/api.adoc). This includes the trait definitions for the various roles defined by the API, such as `Notifier`, `Publisher`, `Subscriber`, `RpcClient`, and `RpcServer`.
* `up-l2-notifier` Enables a default implementation of the `Notifier` trait on top of the Transport Layer API.
* `up-l2-publisher` Enables a default implementation of the `Publisher` trait on top of the Transport Layer API.
* `up-l2-subscriber` Enables a default implementation of the `Subscriber` trait on top of the Transport Layer API.
* `up-l2-rpc-client` Enables a default implementation of the `RpcClient` trait on top of the Transport Layer API.
* `up-l2-rpc-server` Enables a default implementation of the `RpcServer` trait on top of the Transport Layer API.
* `udiscovery` Enables support for types required to interact with [uDiscovery service](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.7/up-l3/udiscovery/v3/README.adoc)
  implementations.
* `usubscription` Enables support for types required to interact with [uSubscription service](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.7/up-l3/usubscription/v3/README.adoc)
  implementations.
* `util` provides some useful helper structs. In particular, it provides the local, in-memory `LocalTransport` for exchanging messages within a single process. This transport is also used by the examples illustrating usage of the Communication Layer API.

## References

* [uProtocol Specification](https://github.com/eclipse-uprotocol/up-spec/tree/v1.6.0-alpha.7)

*/

#[cfg(feature = "cloudevents")]
mod cloudevents;
#[cfg(feature = "cloudevents")]
pub use cloudevents::{CloudEvent, CONTENT_TYPE_CLOUDEVENTS_PROTOBUF};

// [impl->dsn~communication-layer-api-namespace~1]
#[cfg(feature = "up-l2-api")]
pub mod communication;

#[cfg(any(feature = "udiscovery", feature = "usubscription"))]
pub mod core;

#[cfg(feature = "util")]
pub mod local_transport;

/// Audience-oriented examples and implementation guidance.
pub mod guide {
    #![doc = include_str!("guide/README.md")]

    #[cfg_attr(
        all(feature = "communication", feature = "util"),
        doc = include_str!("guide/applications.md")
    )]
    #[cfg_attr(
        not(all(feature = "communication", feature = "util")),
        doc = "Enable `communication` and `util` for the runnable application guide."
    )]
    pub mod applications {
        #[cfg_attr(
            all(feature = "communication", feature = "util"),
            doc = include_str!("guide/communication.md")
        )]
        #[cfg_attr(
            not(all(feature = "communication", feature = "util")),
            doc = "Enable `communication` and `util` for the runnable Communication Layer guide."
        )]
        pub mod communication {}

        #[doc = include_str!("guide/transport.md")]
        pub mod transport {}
    }

    #[doc = include_str!("guide/utransport.md")]
    pub mod utransport {}

    #[cfg_attr(
        feature = "communication",
        doc = include_str!("guide/trait_map.md")
    )]
    #[cfg_attr(
        not(feature = "communication"),
        doc = include_str!("guide/trait_map_core.md")
    )]
    pub mod trait_map {}
}

#[cfg(feature = "symphony")]
pub mod symphony;

mod uattributes;
pub use uattributes::{
    NotificationValidator, PublishValidator, RequestValidator, ResponseValidator, UAttributes,
    UAttributesError, UAttributesValidator, UAttributesValidators, UMessageType, UPayloadFormat,
    UPriority,
};

mod umessage;
pub use umessage::{
    BuilderState, NotificationBuilderState, PublishBuilderState, RequestBuilderState,
    ResponseBuilderState, UMessage, UMessageBuilder, UMessageError,
};

mod uri;
pub use uri::{UUri, UUriError};

mod ustatus;
pub use ustatus::{UAny, UCode, UStatus};

mod utransport;
pub use utransport::{
    verify_filter_criteria, ComparableListener, LocalUriProvider, StaticUriProvider, UListener,
    UTransport,
};
#[cfg(feature = "test-util")]
pub use utransport::{MockLocalUriProvider, MockTransport, MockUListener};

mod uuid;
pub use uuid::UUID;

#[cfg(feature = "up-core-types")]
// protoc-generated types, see build.rs
pub(crate) mod up_core_api {
    include!(concat!(env!("OUT_DIR"), "/uprotocol/mod.rs"));
}

#[cfg(feature = "protobuf-support")]
mod protobuf_mappable;
#[cfg(feature = "protobuf-support")]
pub use protobuf_mappable::ProtobufMappable;

mod serialization_error;
pub use serialization_error::SerializationError;