ruststream-rumqttc 0.7.0

//! The imports a routes file on MQTT writes every time, in one glob.
//!
//! Carries the framework's own prelude plus this crate's surface: the broker, the two
//! subscription descriptors and their quality of service, the publish policy as [`Publish`], the
//! per-message publish steps, and the per-delivery context with its key.
//!
//! A handler file usually needs none of it: a body binds its injected publisher with a capability
//! trait and names no broker type, so it imports the framework's prelude alone. This glob is the
//! mount site's, and importing it is the statement of which broker the routes run on. The one
//! exception is a body that adjusts a per-message setting: it names [`MqttPublishOptions`] in its
//! slot bound and takes a step from [`MqttPublishSteps`], both of which arrive here.
//!
//! A file that mixes two brokers imports the prefixed [`MqttPublish`](crate::MqttPublish) from
//! the crate root instead.
//!
//! # Examples
//!
//! ```
//! # mod demo {
//! use ruststream_rumqttc::prelude::*;
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(Deserialize)]
//! struct Telemetry {
//!     device: String,
//!     temperature: f64,
//! }
//!
//! #[derive(Serialize, Outgoing)]
//! #[outgoing(name = "alerts")]
//! struct Alert {
//!     device: String,
//! }
//!
//! #[subscriber(MqttFilter::new("devices/+/telemetry").qos(Qos::AtLeastOnce).shared("workers"))]
//! async fn check(telemetry: &Telemetry, Out(alerts): Out<impl Publisher>) -> HandlerOutcome {
//!     if telemetry.temperature <= 30.0 {
//!         return HandlerOutcome::ack();
//!     }
//!     let alert = Alert { device: telemetry.device.clone() };
//!     if alerts.message(&alert).publish().await.is_err() {
//!         return HandlerOutcome::retry();
//!     }
//!     HandlerOutcome::ack()
//! }
//!
//! #[ruststream::app]
//! fn app() -> impl App {
//!     RustStream::new(AppInfo::new("telemetry", "0.1.0")).with_broker(
//!         MqttBroker::new("mqtt://localhost:1883", "telemetry-svc"),
//!         |b| {
//!             b.include(check)
//!                 .out(DefaultSlot, Publish::default().qos(Qos::ExactlyOnce))
//!                 .out_retry(Publish::default())
//!                 .to("devices/retry/telemetry")
//!                 .build();
//!         },
//!     )
//! }
//! # }
//! # fn main() {}
//! ```

// Importing this prelude is itself a service's statement of which broker it runs on, which is why
// the core glob rides along here instead of being left to each service file.
pub use ruststream::prelude::*;

// Policies are re-exported under their broker-agnostic concept name; keep the alias when adding
// one. The name is this glob's to give: a handler bounds its slot with a capability trait through
// the framework's prelude, and never sees this one.
pub use crate::{
    DeliveryTopic, MqttBroker, MqttContext, MqttFilter, MqttPublish as Publish, MqttPublishOptions,
    MqttPublishSteps, MqttTopic, Qos,
};

// Capability manifest deliberately empty. Of the framework's optional capabilities MQTT
// implements only `BatchSubscriber` (see the crate overview), and the manifest is for the traits a
// handler bounds its slot with: a batch handler names a size at its mount site and never that
// trait. Add one here when a capability a body binds lands.

// Deliberately absent, do not add:
// - `MqttMessage`, `MqttSubscriber`, `MqttPublisher`, `ConnectedMqttBroker`: a service reaches
//   these through the framework's own surfaces.
// - `MqttError`: named where it is handled.

#[cfg(test)]
mod tests {
    use super::*;

    // The two vocabularies this glob has to serve, pinned where they are handed out rather than
    // in the service that would otherwise meet the failure: the capability a handler binds with
    // stays a trait, and the policy a mount site attaches answers to its concept name.
    fn _the_capability_a_handler_binds_with_is_a_trait<T: Publisher>() {}

    #[test]
    fn the_policy_answers_to_its_concept_name() {
        let _: Publish = Publish::default();
    }
}