plexus-core 0.11.3

Core infrastructure for Plexus RPC: Activation trait, DynamicHub, schemas
Documentation

plexus-core

The core of a Plexus RPC service: the service that activations register with, the Activation trait, dispatch, schemas, the gate that decides each call, the in-process transport, and children mounted from another process.

Most people want plexus-rpc

plexus-rpc is the one dependency a service takes. It brings this crate as plexus_rpc::core, with the macros, the server and a prelude.

Install

[dependencies]
plexus-core = "0.11"
plexus-macros = "0.11"
plexus-client = "0.11"
async-trait = "0.1"
futures = "0.3"
jsonrpsee = { version = "0.26", features = ["server", "macros"] }
schemars = "1"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt"] }
uuid = "1"

#[activation] writes code that names these crates, so each is in the manifest.

An activation, called in process

use futures::stream::{self, Stream, StreamExt, TryStreamExt};
use plexus_core::plexus::HubTransport;
use plexus_core::DynamicHub;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum CountEvent {
    Tick { n: u32 },
}

#[derive(Clone)]
pub struct EchoActivation;

/// Say things back.
#[plexus_macros::activation(version = "1.0.0")]
impl EchoActivation {
    /// Ticks from 1 up to `to`.
    #[plexus_macros::method]
    pub async fn count(&self, to: u32) -> impl Stream<Item = CountEvent> + Send + 'static {
        stream::iter(1..=to).map(|n| CountEvent::Tick { n })
    }
}

#[tokio::test]
async fn count_is_called_in_process() {
    let service = Arc::new(DynamicHub::new("myservice").register(EchoActivation));
    let client = EchoClient::new(HubTransport::anonymous(service));

    let ticks: Vec<CountEvent> = client.count(3).try_collect().await.unwrap();

    assert_eq!(ticks, [1, 2, 3].map(|n| CountEvent::Tick { n }));
}

#[activation] writes EchoClient. HubTransport::anonymous calls as nobody, and HubTransport::as_ calls as an AuthContext. A service with a gate (DynamicHub::with_gate) decides each call by its caller's roles.

cargo test runs this file and holds this page to it.

More

  • docs.rs: the API.
  • Changelog.
  • Activations: hosting one, nesting, the two this crate ships.
  • The service root: a top level that changes while the service serves.
  • The gate: how each call is decided, and a role held on an address.
  • Held calls: a call is decided again when the grants move, and ended when it does not hold.
  • Keyed peers: the rules a child with a key and its service apply.

AGPL-3.0-only.