Skip to main content

plexus_core/plexus/remote_child/
dial_out.rs

1//! VISION-5 (LOCAL-5) ยท dial-out: a service with no listening port opens one
2//! WebSocket to another service (a relay), signs in with its key on the
3//! upgrade (spec/00), offers an activation on that socket (spec/14,
4//! `{svc}.offer`) and serves it there โ€” the far side of spec/12, the calls
5//! coming in on the socket it opened. The same socket carries its own calls
6//! out ([`Exposed::call`]): to the relay, and through it to every other
7//! peer connected there.
8//!
9//! ```ignore
10//! let exposed = Exposed::new(DialOut::new("wss://relay.example/ws", "~/.plexus/keys/alice.key").mount("alice"));
11//! exposed.serve(Greeter::new(exposed.clone()));   // reconnects, within its backoff, until stopped
12//! exposed.mounted(Duration::from_secs(10)).await?; // `peers.alice` at the relay
13//! let items = exposed.call("peers.bob.hello", json!({ "name": "alice" })).await;
14//! ```
15//!
16//! | when | then |
17//! | -- | -- |
18//! | the socket opens | `_info` names the relay's `{svc}`; the offer goes as `{svc}.offer {namespace, activations, mount?}`; the relay asks the schema over the socket and answers the offer once mounted |
19//! | the relay calls `{ns}.call {method, params, hop}` | served as a child serves (RETURNS-47's host): each call in the hop's context, the hop believed from the relay alone ([`DialOut::trust`]) |
20//! | this side calls [`Exposed::call`] | `{svc}.call {method, params}` on the same socket: decided by the relay's gate as this key |
21//! | the socket drops | every call either way ends; the state is `down`; it dials again within [`DialOut::backoff`] and offers again |
22//! | the offer is refused | the state is `refused` naming why; it does not dial again until [`Exposed::serve`] is called again |
23
24use std::path::PathBuf;
25use std::sync::{Arc, Mutex};
26use std::time::Duration;
27
28use futures::{SinkExt, StreamExt};
29use serde::Serialize;
30use serde_json::{json, Value};
31use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
32use tokio::sync::{mpsc, oneshot, watch};
33use tokio_tungstenite::tungstenite::client::IntoClientRequest;
34use tokio_tungstenite::tungstenite::http::{header::AUTHORIZATION, HeaderValue};
35use tokio_tungstenite::tungstenite::Message;
36
37use super::host::{serve_child_on, ChildPeer};
38use super::link::{unavailable, Conn, Counters, SubKey};
39use super::ws::{key_proof, principal_of, read_seed};
40use super::Backoff;
41use crate::plexus::plexus::Activation;
42use crate::plexus::streaming::PlexusStream;
43use crate::plexus::types::PlexusStreamItem;
44
45/// Where a service dials out to, as whom, and under what name it asks to be
46/// mounted.
47#[derive(Debug, Clone)]
48pub struct DialOut {
49    /// The relay's socket: `ws://HOST:PORT/ws` (`wss://` with `child-wss`).
50    pub url: String,
51    /// The key file the upgrade's proof is signed with (spec/00): synapse's
52    /// `~/.plexus/keys/<name>.key`, 0600. Read at each dial, never kept.
53    pub key: PathBuf,
54    /// The proof's agent id.
55    pub agent: String,
56    /// The mount name asked for (`peers.<mount>`); none: the activation's
57    /// namespace.
58    pub mount: Option<String>,
59    /// The relay's principal, pinned (spec/14 rule 4): a hop is believed
60    /// only when it names this principal as the service acting. None: the
61    /// socket this side dialed is the relay's alone, and every hop on it is
62    /// the relay's (as a pipe's are its parent's).
63    pub trust: Option<String>,
64    /// Dialing again after the socket drops.
65    pub backoff: Backoff,
66    /// `_info`, the offer's answer, and each of this side's calls' opens.
67    pub timeout: Duration,
68}
69
70impl DialOut {
71    /// Dial `url`, signed in with the key in `key`.
72    pub fn new(url: impl Into<String>, key: impl Into<PathBuf>) -> Self {
73        Self {
74            url: url.into(),
75            key: key.into(),
76            agent: "plexus-service".into(),
77            mount: None,
78            trust: None,
79            backoff: Backoff { initial: Duration::from_millis(250), max: Duration::from_secs(10), per_minute: usize::MAX },
80            timeout: Duration::from_secs(10),
81        }
82    }
83
84    /// Ask to be mounted as `name`.
85    pub fn mount(mut self, name: impl Into<String>) -> Self {
86        self.mount = Some(name.into());
87        self
88    }
89
90    /// Believe hops only from `principal` (the relay's key, pinned).
91    pub fn trust(mut self, principal: impl Into<String>) -> Self {
92        self.trust = Some(principal.into());
93        self
94    }
95
96    /// The proof's agent id.
97    pub fn agent(mut self, agent: impl Into<String>) -> Self {
98        self.agent = agent.into();
99        self
100    }
101}
102
103/// Where a dialed-out service stands.
104#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
105#[serde(tag = "state", rename_all = "snake_case")]
106pub enum DialState {
107    /// Not yet dialed, or dialing.
108    Connecting,
109    /// Mounted at the relay as `path` (`peers.<mount>`).
110    Mounted { mount: String, path: String, service: String, relay: String },
111    /// The socket dropped or could not open; dialing again.
112    Down { why: String },
113    /// The relay refused the offer; not dialing again.
114    Refused { why: String },
115    /// [`Exposed::stop`]ped.
116    Stopped,
117}
118
119struct Live {
120    conn: Arc<Conn>,
121    service: String,
122}
123
124struct ExposedInner {
125    opts: DialOut,
126    live: Mutex<Option<Live>>,
127    state: watch::Sender<DialState>,
128    task: Mutex<Option<tokio::task::AbortHandle>>,
129    counters: Arc<Counters>,
130}
131
132impl Drop for ExposedInner {
133    fn drop(&mut self) {
134        if let Some(t) = self.task.lock().unwrap().take() {
135            t.abort();
136        }
137    }
138}
139
140/// A service's one outbound socket to a relay: what it serves there, and
141/// the calls it makes over it. Cheap to clone; [`Self::serve`] holds a weak
142/// reference, so the socket goes with the last clone (or [`Self::stop`]).
143#[derive(Clone)]
144pub struct Exposed {
145    inner: Arc<ExposedInner>,
146}
147
148impl std::fmt::Debug for Exposed {
149    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
150        f.debug_struct("Exposed").field("url", &self.inner.opts.url).field("state", &self.state()).finish()
151    }
152}
153
154impl Exposed {
155    /// Not dialed until [`Self::serve`]: an activation that calls out through
156    /// the relay holds a clone of this before it is served.
157    pub fn new(opts: DialOut) -> Self {
158        Self {
159            inner: Arc::new(ExposedInner {
160                opts,
161                live: Mutex::new(None),
162                state: watch::channel(DialState::Connecting).0,
163                task: Mutex::new(None),
164                counters: Arc::new(Counters::default()),
165            }),
166        }
167    }
168
169    /// The options it dials with.
170    pub fn options(&self) -> &DialOut {
171        &self.inner.opts
172    }
173
174    /// The principal this side signs in as (its key's), or why the key does
175    /// not read.
176    pub fn principal(&self) -> Result<String, String> {
177        read_seed(&self.inner.opts.key).map(|k| principal_of(&k))
178    }
179
180    /// Where it stands now.
181    pub fn state(&self) -> DialState {
182        self.inner.state.borrow().clone()
183    }
184
185    /// Its state, watched.
186    pub fn watch(&self) -> watch::Receiver<DialState> {
187        self.inner.state.subscribe()
188    }
189
190    /// Wait until mounted (its `path` at the relay), or refused, or `timeout`.
191    pub async fn mounted(&self, timeout: Duration) -> Result<String, String> {
192        let mut rx = self.watch();
193        let settled = tokio::time::timeout(timeout, async {
194            rx.wait_for(|s| matches!(s, DialState::Mounted { .. } | DialState::Refused { .. } | DialState::Stopped)).await.map(|s| s.clone())
195        })
196        .await;
197        match settled {
198            Ok(Ok(DialState::Mounted { path, .. })) => Ok(path),
199            Ok(Ok(other)) => Err(format!("{other:?}")),
200            Ok(Err(_)) => Err("stopped".into()),
201            Err(_) => Err(format!("not mounted in {timeout:?} ({:?})", self.state())),
202        }
203    }
204
205    /// Dial, offer `activation`, serve it; dial again whenever the socket
206    /// drops. Replaces a previous `serve`.
207    pub fn serve<A: Activation + Clone>(&self, activation: A) {
208        let weak = Arc::downgrade(&self.inner);
209        let task = tokio::spawn(async move {
210            let mut failures = 0usize;
211            loop {
212                let Some(inner) = weak.upgrade() else { return };
213                inner.state.send_replace(DialState::Connecting);
214                let outcome = session(&inner, activation.clone()).await;
215                inner.live.lock().unwrap().take();
216                let backoff = inner.opts.backoff;
217                match outcome {
218                    Outcome::Refused(why) => {
219                        tracing::warn!(target: "plexus::dial", url = %inner.opts.url, "the offer was refused: {why}");
220                        inner.state.send_replace(DialState::Refused { why });
221                        return;
222                    }
223                    Outcome::Dropped { why, was_mounted } => {
224                        tracing::warn!(target: "plexus::dial", url = %inner.opts.url, "{why}; dialing again");
225                        inner.state.send_replace(DialState::Down { why });
226                        failures = if was_mounted { 0 } else { failures + 1 };
227                    }
228                }
229                drop(inner);
230                tokio::time::sleep(backoff.delay(failures)).await;
231            }
232        });
233        if let Some(old) = self.inner.task.lock().unwrap().replace(task.abort_handle()) {
234            old.abort();
235        }
236    }
237
238    /// Close the socket and stop dialing.
239    pub fn stop(&self) {
240        if let Some(t) = self.inner.task.lock().unwrap().take() {
241            t.abort();
242        }
243        if let Some(live) = self.inner.live.lock().unwrap().take() {
244            live.conn.shutdown.notify_one();
245        }
246        self.inner.state.send_replace(DialState::Stopped);
247    }
248
249    /// Call `method` (a path at the relay: `peers.bob.hello`, `peers.list`)
250    /// over this side's socket, as this side's key: `{svc}.call`, decided by
251    /// the relay's gate. Not connected: one `child_unavailable` item.
252    pub async fn call(&self, method: &str, params: Value) -> PlexusStream {
253        let one = |item: PlexusStreamItem| -> PlexusStream { Box::pin(futures::stream::iter([item])) };
254        let live = self.inner.live.lock().unwrap().as_ref().map(|l| (Arc::clone(&l.conn), l.service.clone()));
255        let Some((conn, service)) = live else {
256            return one(unavailable("relay", &format!("not connected to {} ({:?})", self.inner.opts.url, self.state())));
257        };
258        match conn.open(&format!("{service}.call"), json!({ "method": method, "params": params }), self.inner.opts.timeout).await {
259            Ok((sid, rx)) => Box::pin(Items { rx, sid, conn, over: false }),
260            Err(item) => one(item),
261        }
262    }
263}
264
265/// A call's items, until its terminal one; dropped before it, unsubscribed.
266struct Items {
267    rx: mpsc::Receiver<PlexusStreamItem>,
268    sid: SubKey,
269    conn: Arc<Conn>,
270    over: bool,
271}
272
273impl futures::Stream for Items {
274    type Item = PlexusStreamItem;
275
276    fn poll_next(mut self: std::pin::Pin<&mut Self>, cx: &mut std::task::Context<'_>) -> std::task::Poll<Option<PlexusStreamItem>> {
277        if self.over {
278            return std::task::Poll::Ready(None);
279        }
280        match self.rx.poll_recv(cx) {
281            std::task::Poll::Ready(Some(item)) => {
282                self.over = matches!(item, PlexusStreamItem::Done { .. } | PlexusStreamItem::Error { .. });
283                std::task::Poll::Ready(Some(item))
284            }
285            std::task::Poll::Ready(None) => {
286                self.over = true;
287                std::task::Poll::Ready(Some(unavailable("relay", "the connection closed")))
288            }
289            std::task::Poll::Pending => std::task::Poll::Pending,
290        }
291    }
292}
293
294impl Drop for Items {
295    fn drop(&mut self) {
296        if !self.over {
297            self.conn.unsubscribe(&self.sid);
298        }
299    }
300}
301
302enum Outcome {
303    Refused(String),
304    Dropped { why: String, was_mounted: bool },
305}
306
307fn nonce() -> [u8; 32] {
308    let mut n = [0u8; 32];
309    n[..16].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
310    n[16..].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
311    n
312}
313
314/// The offer's request id: a string, so it can never be one of the client
315/// `Conn`'s numbered requests (spec/14 rule 2: ids are per direction).
316const OFFER_ID: &str = "offer";
317
318/// One socket, from dial to drop.
319async fn session<A: Activation + Clone>(inner: &Arc<ExposedInner>, activation: A) -> Outcome {
320    let opts = &inner.opts;
321    let dropped = |why: String| Outcome::Dropped { why, was_mounted: false };
322    if opts.url.starts_with("wss://") && !cfg!(feature = "child-wss") {
323        return Outcome::Refused("a wss:// relay needs plexus-core's `child-wss` feature (TLS)".into());
324    }
325    let mut req = match opts.url.as_str().into_client_request() {
326        Ok(r) => r,
327        Err(e) => return Outcome::Refused(format!("`{}`: {e}", opts.url)),
328    };
329    let key = match read_seed(&opts.key) {
330        Ok(k) => k,
331        Err(e) => return Outcome::Refused(e),
332    };
333    let ts = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map_or(0, |d| d.as_secs() as i64);
334    let proof = key_proof(&key, opts.url.trim_end_matches('/'), &opts.agent, &nonce(), ts);
335    drop(key);
336    match HeaderValue::from_str(&format!("Bearer {proof}")) {
337        Ok(v) => req.headers_mut().insert(AUTHORIZATION, v),
338        Err(e) => return Outcome::Refused(e.to_string()),
339    };
340    // spec/14: a client that serves must not delay small writes (Nagle).
341    let socket = match tokio_tungstenite::connect_async_with_config(req, None, true).await {
342        Ok((s, _)) => s,
343        Err(tokio_tungstenite::tungstenite::Error::Http(resp)) => return dropped(format!("the upgrade to {} was refused: HTTP {}", opts.url, resp.status())),
344        Err(e) => return dropped(format!("dialing {}: {e}", opts.url)),
345    };
346    let (mut sink, mut stream) = socket.split();
347
348    // This side's calls out: a client `Conn` on the socket's outbound queue.
349    let (out, mut out_rx) = mpsc::unbounded_channel::<Vec<u8>>();
350    let conn = Conn::new("relay", None, out.clone(), 64, Arc::clone(&inner.counters));
351    // The calls in: RETURNS-47's host, on a pipe of lines this side feeds.
352    let (mut host_in, host_r) = tokio::io::duplex(1 << 16);
353    let (host_w, host_out) = tokio::io::duplex(1 << 16);
354    let peer = match &opts.trust {
355        Some(p) => ChildPeer::connection(p.clone(), [p.clone()]),
356        None => ChildPeer::Pipe,
357    };
358    let host = tokio::spawn(serve_child_on(activation.clone(), host_r, host_w, peer));
359
360    // Writer: the client's frames and the host's lines, in the order made.
361    let out_host = out.clone();
362    let host_lines = tokio::spawn(async move {
363        let mut lines = BufReader::new(host_out).lines();
364        while let Ok(Some(l)) = lines.next_line().await {
365            if out_host.send(l.into_bytes()).is_err() {
366                break;
367            }
368        }
369    });
370    let shutdown = Arc::clone(&conn);
371    let writer = tokio::spawn(async move {
372        loop {
373            tokio::select! {
374                first = out_rx.recv() => {
375                    let Some(first) = first else { break };
376                    let mut ok = sink.feed(Message::text(String::from_utf8_lossy(&first).into_owned())).await.is_ok();
377                    while let (true, Ok(more)) = (ok, out_rx.try_recv()) {
378                        ok = sink.feed(Message::text(String::from_utf8_lossy(&more).into_owned())).await.is_ok();
379                    }
380                    if !ok || sink.flush().await.is_err() {
381                        break;
382                    }
383                }
384                _ = shutdown.shutdown.notified() => {
385                    let _ = sink.close().await;
386                    break;
387                }
388            }
389        }
390    });
391
392    // Reader: by the frame's shape (spec/14 rule 2) โ€” a call into this side
393    // to the host; the offer's answer to its waiter; the rest to the client.
394    let (offer_tx, offer_rx) = oneshot::channel::<Value>();
395    let reader_conn = Arc::clone(&conn);
396    let reader = tokio::spawn(async move {
397        let mut offer_tx = Some(offer_tx);
398        let why = loop {
399            let text = match stream.next().await {
400                Some(Ok(Message::Text(t))) => t.as_bytes().to_vec(),
401                Some(Ok(Message::Binary(b))) => b.to_vec(),
402                Some(Ok(Message::Close(f))) => break format!("the relay closed the socket ({})", f.map(|f| f.code.to_string()).unwrap_or_else(|| "no code".into())),
403                Some(Ok(_)) => continue,
404                Some(Err(e)) => break format!("the socket: {e}"),
405                None => break "the relay closed the socket".to_string(),
406            };
407            let shape: Value = match serde_json::from_slice(&text) {
408                Ok(v) => v,
409                Err(_) => continue,
410            };
411            let (method, id) = (shape.get("method"), shape.get("id"));
412            if method.is_some() && id.is_some() {
413                let mut line = text;
414                line.push(b'\n');
415                if host_in.write_all(&line).await.is_err() {
416                    break "the host stopped".to_string();
417                }
418            } else if method.is_none() && id.and_then(Value::as_str) == Some(OFFER_ID) {
419                if let Some(tx) = offer_tx.take() {
420                    let _ = tx.send(shape);
421                }
422            } else {
423                reader_conn.on_message(&text).await;
424            }
425        };
426        reader_conn.on_gone(&why);
427        reader_conn.shutdown.notify_one();
428        why
429    });
430
431    let ended = |why: String, was_mounted: bool| {
432        host.abort();
433        host_lines.abort();
434        writer.abort();
435        Outcome::Dropped { why, was_mounted }
436    };
437
438    // The relay's namespace: its `_info`.
439    let info = async {
440        let (_, mut rx) = conn.open("_info", Value::Null, opts.timeout).await.map_err(|e| format!("{e:?}"))?;
441        while let Some(item) = rx.recv().await {
442            if let PlexusStreamItem::Data { content, .. } = item {
443                if let Some(b) = content.into_value().get("backend").and_then(Value::as_str) {
444                    return Ok(b.to_string());
445                }
446            }
447        }
448        Err::<String, String>("its `_info` names no backend".into())
449    };
450    let service = match tokio::time::timeout(opts.timeout, info).await {
451        Ok(Ok(s)) => s,
452        Ok(Err(why)) => {
453            reader.abort();
454            return ended(format!("asking the relay's `_info`: {why}"), false);
455        }
456        Err(_) => {
457            reader.abort();
458            return ended(format!("the relay did not answer `_info` in {:?}", opts.timeout), false);
459        }
460    };
461    let _ = conn.ns.set(service.clone());
462
463    // The offer (spec/14), answered once the relay has mounted this side.
464    let ns = activation.namespace().to_string();
465    let schema_hash = activation.plugin_schema().hash;
466    let mut params = json!({ "namespace": ns, "activations": [ns], "schema_hash": schema_hash, "schema": null });
467    if let Some(m) = &opts.mount {
468        params["mount"] = json!(m);
469    }
470    let _ = out.send(serde_json::to_vec(&json!({ "jsonrpc": "2.0", "id": OFFER_ID, "method": format!("{service}.offer"), "params": params })).unwrap_or_default());
471    let answer = match tokio::time::timeout(opts.timeout * 2, offer_rx).await {
472        Ok(Ok(a)) => a,
473        Ok(Err(_)) => {
474            let why = reader.await.unwrap_or_else(|_| "the socket".into());
475            return ended(format!("before the offer was answered: {why}"), false);
476        }
477        Err(_) => {
478            reader.abort();
479            return ended(format!("the offer was not answered in {:?}", opts.timeout * 2), false);
480        }
481    };
482    if let Some(e) = answer.get("error") {
483        reader.abort();
484        ended(String::new(), false);
485        let kind = e.pointer("/data/error_kind").and_then(Value::as_str).unwrap_or("refused");
486        let message = e.get("message").and_then(Value::as_str).unwrap_or("");
487        return Outcome::Refused(format!("{kind}: {message}"));
488    }
489    let result = answer.get("result").cloned().unwrap_or(Value::Null);
490    let mount = result.get("mount").and_then(Value::as_str).unwrap_or(&ns).to_string();
491    let path = result.get("path").and_then(Value::as_str).unwrap_or(&mount).to_string();
492    let relay = result.pointer("/service/principal").and_then(Value::as_str).unwrap_or("").to_string();
493    if let Some(pinned) = &opts.trust {
494        if *pinned != relay {
495            tracing::warn!(target: "plexus::dial", %pinned, named = %relay, "the relay names another principal than the one pinned; its hops will be refused");
496        }
497    }
498    *inner.live.lock().unwrap() = Some(Live { conn: Arc::clone(&conn), service: service.clone() });
499    tracing::info!(target: "plexus::dial", url = %opts.url, %path, %relay, "mounted at the relay");
500    inner.state.send_replace(DialState::Mounted { mount, path, service, relay });
501
502    let why = reader.await.unwrap_or_else(|_| "the socket".into());
503    ended(why, true)
504}
505
506/// The principal a key file's proof proves (`key:<64 hex>`), or why the key
507/// does not read โ€” a service naming itself, as a relay does in its hops.
508pub fn key_principal(path: &std::path::Path) -> Result<String, String> {
509    read_seed(path).map(|k| principal_of(&k))
510}