arcly-stream 0.1.6

//! Multi-node clustering contracts: origin/edge discovery and stream relay.
//!
//! These are **contracts only** — the engine defines the seams an edge tier
//! plugs into, but ships no concrete discovery or transport (those depend on the
//! deployment's service mesh / gossip / control plane). An edge node implements
//! [`ClusterRelay`] to locate a stream's origin, pull it locally, and announce
//! the streams it serves.

use crate::{Result, StreamKey};
use async_trait::async_trait;

/// Address of a node in the cluster (opaque to the engine).
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct NodeAddr(pub String);

impl<T: Into<String>> From<T> for NodeAddr {
    fn from(s: T) -> Self {
        NodeAddr(s.into())
    }
}

/// Origin/edge relay contract. Implement to federate streams across nodes:
/// an edge that lacks a stream locally [`locate`](Self::locate)s its origin and
/// [`pull`](Self::pull)s it; an origin [`announce`](Self::announce)s what it has.
#[async_trait]
pub trait ClusterRelay: Send + Sync + 'static {
    /// Find a node currently serving `key`, if any (e.g. via the control plane).
    async fn locate(&self, key: &StreamKey) -> Result<Option<NodeAddr>>;

    /// Begin relaying `key` from `origin` into the local engine, returning once
    /// the local mirror is publishing.
    async fn pull(&self, key: &StreamKey, origin: &NodeAddr) -> Result<()>;

    /// Advertise that this node serves `key` so edges can discover it.
    async fn announce(&self, key: &StreamKey) -> Result<()>;

    /// Withdraw a previous [`announce`](Self::announce) when the stream ends.
    async fn withdraw(&self, key: &StreamKey) -> Result<()>;
}