Skip to main content

cpa_exec/
wsrelay.rs

1//! The `/v1/ws` relay (internal/wsrelay): an AI Studio browser bridge connects over a
2//! websocket and performs HTTP requests on the proxy's behalf. Each connection is a
3//! session named `aistudio-<16 random characters>`; requests and their responses are
4//! JSON messages correlated by ID.
5//!
6//! The server route owns the transport (upgrade, ping heartbeat, read deadline, frame
7//! limit) and feeds frames in and out of a [`Session`]; this module owns the sessions,
8//! Go's message encoding and the request bookkeeping, shared with the AI Studio executor
9//! through one [`Relay`].
10
11use std::collections::{BTreeMap, HashMap, VecDeque};
12use std::sync::{Arc, Mutex, PoisonError, Weak};
13
14use bytes::Bytes;
15use cpa_common::gostr::GoStr;
16use cpa_common::json::{self as gj, GoValue};
17use tokio::sync::{Notify, mpsc, watch};
18
19use crate::meta_wire;
20
21/// The route Go attaches the relay to (`wsrelay.Options.Path`).
22pub const PATH: &str = "/v1/ws";
23
24pub const HTTP_REQUEST: &str = "http_request";
25pub const HTTP_RESPONSE: &str = "http_response";
26pub const STREAM_START: &str = "stream_start";
27pub const STREAM_CHUNK: &str = "stream_chunk";
28pub const STREAM_END: &str = "stream_end";
29pub const ERROR: &str = "error";
30pub const PING: &str = "ping";
31pub const PONG: &str = "pong";
32
33/// `pendingChannelBuffer`: messages a request may hold before the reader waits.
34const PENDING_BUFFER: usize = 64;
35
36/// The cause sessions end with when the reader stops without an error of its own.
37pub const CLOSED: &str = "websocket session closed";
38
39/// `wsrelay.Message`.
40#[derive(Debug, Clone, Default, PartialEq)]
41pub struct Message {
42    pub id: String,
43    pub kind: String,
44    /// Go's `map[string]any`; `None` when absent or `null`.
45    pub payload: Option<BTreeMap<String, GoValue>>,
46}
47
48impl Message {
49    /// `conn.WriteJSON(msg)`: `id`, `type`, then a non-empty `payload` (keys sorted,
50    /// HTML escaped), and the encoder's newline.
51    pub fn encode(&self) -> String {
52        let mut out = Vec::new();
53        out.extend_from_slice(b"{\"id\":");
54        gj::marshal_str(&mut out, self.id.as_bytes(), true);
55        out.extend_from_slice(b",\"type\":");
56        gj::marshal_str(&mut out, self.kind.as_bytes(), true);
57        if let Some(payload) = self.payload.as_ref().filter(|p| !p.is_empty()) {
58            out.extend_from_slice(b",\"payload\":");
59            out.extend_from_slice(&GoValue::Object(payload.clone()).marshal());
60        }
61        out.extend_from_slice(b"}\n");
62        String::from_utf8(out).unwrap_or_default()
63    }
64
65    /// `conn.ReadJSON(&msg)`: a `json.Decoder` reads the frame's first value into
66    /// `Message`. Anything after that value is never read; any decoding error ends the
67    /// session. Names match case-insensitively and a later member wins; `null` leaves a
68    /// string as it was but clears the payload, and payload objects merge into one map,
69    /// as Go's decoder does.
70    pub fn decode(frame: &[u8]) -> Result<Self, String> {
71        let start = frame
72            .iter()
73            .position(|c| !matches!(c, b' ' | b'\t' | b'\r' | b'\n'))
74            .ok_or("EOF")?;
75        let value = &frame[start..];
76        if value.starts_with(b"null") {
77            return Ok(Self::default());
78        }
79        if !value.starts_with(b"{") {
80            meta_wire::check_valid(value)?;
81            return Err("json: cannot unmarshal into Go value of type wsrelay.Message".into());
82        }
83        let value = &value[..meta_wire::object_end(value).ok_or("unexpected EOF")?];
84        meta_wire::check_valid(value)?;
85        let mut msg = Self::default();
86        let mut error = None;
87        gj::parse(value).each(|key, item| {
88            let key = gj::go_unquote(key.raw()).unwrap_or_default();
89            let field = ["id", "type", "payload"]
90                .into_iter()
91                .find(|name| *name == key)
92                .or_else(|| {
93                    ["id", "type", "payload"]
94                        .into_iter()
95                        .find(|name| meta_wire::fold(name) == meta_wire::fold(&key))
96                });
97            let result = match (field, item.kind) {
98                // `null` resets a map to nil and leaves a string as it was.
99                (Some("payload"), gj::Kind::Null) => {
100                    msg.payload = None;
101                    Ok(())
102                }
103                (None, _) | (Some(_), gj::Kind::Null) => Ok(()),
104                (Some("id"), gj::Kind::String) => {
105                    msg.id = gj::go_unquote(item.raw()).unwrap_or_default();
106                    Ok(())
107                }
108                (Some("type"), gj::Kind::String) => {
109                    msg.kind = gj::go_unquote(item.raw()).unwrap_or_default();
110                    Ok(())
111                }
112                (Some("payload"), gj::Kind::Json) if item.is_object() => {
113                    match GoValue::parse_f64(item.raw()).map(GoValue::into_object) {
114                        Some(Ok(map)) => {
115                            msg.payload.get_or_insert_with(BTreeMap::new).extend(map);
116                            Ok(())
117                        }
118                        _ => Err("json: cannot unmarshal number into Go value of type float64".to_owned()),
119                    }
120                }
121                (Some(name), _) => Err(format!(
122                    "json: cannot unmarshal {} into Go struct field Message.{name}",
123                    meta_wire::kind_name(&item)
124                )),
125            };
126            if let Err(e) = result {
127                error.get_or_insert(e);
128            }
129            true
130        });
131        error.map_or(Ok(msg), Err)
132    }
133
134    fn payload_str(&self, key: &str) -> Option<&str> {
135        match self.payload.as_ref()?.get(key)? {
136            GoValue::String(s) => Some(s),
137            _ => None,
138        }
139    }
140
141    /// A float64 payload field as Go's `int(v)`.
142    fn payload_int(&self, key: &str) -> Option<i64> {
143        match self.payload.as_ref()?.get(key)? {
144            GoValue::Number(n) => n.parse::<f64>().ok().map(|f| f as i64),
145            _ => None,
146        }
147    }
148}
149
150/// An HTTP request carried over the relay (`wsrelay.HTTPRequest`). Headers keep Go's
151/// canonical names, each with its values.
152#[derive(Debug, Clone, Default)]
153pub struct HttpRequest {
154    pub method: String,
155    pub url: String,
156    pub headers: Vec<(String, Vec<String>)>,
157    pub body: Bytes,
158}
159
160impl HttpRequest {
161    /// `encodeRequest`. `body` is a Go string, so invalid UTF-8 becomes U+FFFD per byte
162    /// when marshaled; `sent_at` is the wall clock in RFC 3339 with nanoseconds.
163    fn payload(&self) -> BTreeMap<String, GoValue> {
164        let headers = self
165            .headers
166            .iter()
167            .map(|(k, v)| {
168                (
169                    k.clone(),
170                    GoValue::Array(v.iter().cloned().map(GoValue::String).collect()),
171                )
172            })
173            .collect();
174        BTreeMap::from([
175            ("method".to_owned(), GoValue::String(self.method.clone())),
176            ("url".to_owned(), GoValue::String(self.url.clone())),
177            ("headers".to_owned(), GoValue::Object(headers)),
178            ("body".to_owned(), GoValue::String(go_lossy(&self.body))),
179            ("sent_at".to_owned(), GoValue::String(rfc3339_nano(chrono::Utc::now()))),
180        ])
181    }
182}
183
184/// An HTTP response from the relay (`wsrelay.HTTPResponse`).
185#[derive(Debug, Clone, Default, PartialEq)]
186pub struct HttpResponse {
187    pub status: i64,
188    /// Canonical names with their values, in name order (Go's `http.Header`).
189    pub headers: BTreeMap<String, Vec<String>>,
190    pub body: Vec<u8>,
191}
192
193/// One event of a streamed relay response (`wsrelay.StreamEvent`).
194#[derive(Debug, Clone, Default, PartialEq)]
195pub struct StreamEvent {
196    pub kind: String,
197    pub payload: Vec<u8>,
198    pub status: i64,
199    pub headers: BTreeMap<String, Vec<String>>,
200    pub error: Option<String>,
201}
202
203/// Each invalid UTF-8 byte becomes U+FFFD, as Go's `string` marshaling does.
204fn go_lossy(bytes: &[u8]) -> String {
205    let mut out = String::with_capacity(bytes.len());
206    for chunk in bytes.utf8_chunks() {
207        out.push_str(chunk.valid());
208        out.extend(std::iter::repeat_n('\u{FFFD}', chunk.invalid().len()));
209    }
210    out
211}
212
213/// Go's `time.RFC3339Nano`: fractional seconds without trailing zeros.
214fn rfc3339_nano(t: chrono::DateTime<chrono::Utc>) -> String {
215    let nanos = format!("{:09}", t.timestamp_subsec_nanos());
216    let nanos = nanos.trim_end_matches('0');
217    let fraction = if nanos.is_empty() {
218        String::new()
219    } else {
220        format!(".{nanos}")
221    };
222    format!("{}{fraction}Z", t.format("%Y-%m-%dT%H:%M:%S"))
223}
224
225/// `decodeResponse`.
226fn decode_response(msg: &Message) -> HttpResponse {
227    let Some(payload) = &msg.payload else {
228        return HttpResponse {
229            status: 502,
230            ..HttpResponse::default()
231        };
232    };
233    let mut resp = HttpResponse {
234        status: msg.payload_int("status").unwrap_or(200),
235        ..HttpResponse::default()
236    };
237    if let Some(GoValue::Object(headers)) = payload.get("headers") {
238        for (key, raw) in headers {
239            let name = crate::proxy::canonical_header(key);
240            match raw {
241                GoValue::Array(items) => {
242                    for item in items {
243                        if let GoValue::String(s) = item {
244                            resp.headers.entry(name.clone()).or_default().push(s.clone());
245                        }
246                    }
247                }
248                GoValue::String(s) => {
249                    resp.headers.insert(name, vec![s.clone()]);
250                }
251                _ => {}
252            }
253        }
254    }
255    if let Some(body) = msg.payload_str("body") {
256        resp.body = body.as_bytes().to_vec();
257    }
258    resp
259}
260
261/// `decodeChunk`.
262fn decode_chunk(msg: &Message) -> Vec<u8> {
263    msg.payload_str("data")
264        .map(|d| d.as_bytes().to_vec())
265        .unwrap_or_default()
266}
267
268/// `decodeError`.
269fn decode_error(msg: &Message) -> String {
270    if msg.payload.is_none() {
271        return "wsrelay: unknown error".into();
272    }
273    let message = msg
274        .payload_str("error")
275        .filter(|m| !m.is_empty())
276        .unwrap_or("wsrelay: upstream error");
277    format!("{message} (status={})", msg.payload_int("status").unwrap_or(0))
278}
279
280fn terminal(kind: &str) -> bool {
281    matches!(kind, HTTP_RESPONSE | ERROR | STREAM_END)
282}
283
284/// Called with `(provider, None)` when a browser connects and `(provider, Some(cause))`
285/// when its session ends (Go `OnConnected` / `OnDisconnected`).
286pub type Observer = Arc<dyn Fn(&str, Option<&str>) + Send + Sync>;
287
288/// The relay's sessions by provider name (`wsrelay.Manager`).
289#[derive(Default)]
290pub struct Relay {
291    sessions: Mutex<HashMap<String, Arc<Session>>>,
292    observer: Mutex<Option<Observer>>,
293}
294
295impl std::fmt::Debug for Relay {
296    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
297        f.debug_struct("Relay").finish_non_exhaustive()
298    }
299}
300
301fn lock<T>(m: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
302    m.lock().unwrap_or_else(PoisonError::into_inner)
303}
304
305/// `randomProviderName`: `aistudio-` and 16 characters of `[a-z0-9]`.
306fn random_provider_name() -> String {
307    const ALPHABET: &[u8] = b"abcdefghijklmnopqrstuvwxyz0123456789";
308    let bytes = *uuid::Uuid::new_v4().as_bytes();
309    let name: String = bytes
310        .iter()
311        .map(|b| char::from(ALPHABET[usize::from(*b) % ALPHABET.len()]))
312        .collect();
313    format!("aistudio-{name}")
314}
315
316impl Relay {
317    pub fn set_observer(&self, observer: Observer) {
318        *lock(&self.observer) = Some(observer);
319    }
320
321    fn observer(&self) -> Option<Observer> {
322        lock(&self.observer).clone()
323    }
324
325    /// `handleWebsocket` after the upgrade: a session under a new provider name, which
326    /// replaces any session of that name, then `OnConnected`. Returns the session and the
327    /// frames the route must write.
328    pub fn connect(self: &Arc<Self>) -> (Arc<Session>, mpsc::UnboundedReceiver<String>) {
329        self.connect_as(random_provider_name())
330    }
331
332    /// [`Relay::connect`] under a given name (tests).
333    pub fn connect_as(self: &Arc<Self>, provider: String) -> (Arc<Session>, mpsc::UnboundedReceiver<String>) {
334        let (out, frames) = mpsc::unbounded_channel();
335        let (closed, _) = watch::channel(false);
336        let session = Arc::new(Session {
337            provider: provider.go_lower(),
338            relay: Arc::downgrade(self),
339            out,
340            closed,
341            pending: Mutex::new(HashMap::new()),
342        });
343        let replaced = lock(&self.sessions).insert(session.provider.clone(), session.clone());
344        if let Some(replaced) = replaced {
345            replaced.close("replaced by new connection");
346        }
347        if let Some(observer) = self.observer() {
348            observer(&session.provider, None);
349        }
350        (session, frames)
351    }
352
353    /// `Manager.Stop`: every session ends with "wsrelay: manager stopped".
354    pub fn stop(&self) {
355        let sessions: Vec<_> = lock(&self.sessions).drain().map(|(_, s)| s).collect();
356        for session in sessions {
357            session.close("wsrelay: manager stopped");
358        }
359    }
360
361    /// The connected provider names.
362    pub fn providers(&self) -> Vec<String> {
363        lock(&self.sessions).keys().cloned().collect()
364    }
365
366    fn session(&self, provider: &str) -> Option<Arc<Session>> {
367        lock(&self.sessions).get(&provider.trim().go_lower()).cloned()
368    }
369
370    /// `Manager.Send`.
371    fn send(&self, provider: &str, msg: Message) -> Result<Responses, String> {
372        let session = self
373            .session(provider)
374            .ok_or_else(|| format!("wsrelay: provider {provider} not connected"))?;
375        session.request(msg)
376    }
377
378    fn http_message(req: &HttpRequest) -> Message {
379        Message {
380            id: uuid::Uuid::new_v4().to_string(),
381            kind: HTTP_REQUEST.into(),
382            payload: Some(req.payload()),
383        }
384    }
385
386    /// `Manager.NonStream`: an `http_response`, or the body of a streamed answer
387    /// collected until `stream_end` (or the session closing).
388    pub async fn non_stream(&self, provider: &str, req: &HttpRequest) -> Result<HttpResponse, String> {
389        let mut responses = self.send(provider, Self::http_message(req))?;
390        let mut stream: Option<HttpResponse> = None;
391        let mut body = Vec::new();
392        loop {
393            let Some(msg) = responses.recv().await else {
394                return match stream {
395                    Some(mut resp) => {
396                        resp.body = body;
397                        Ok(resp)
398                    }
399                    None => Err("wsrelay: connection closed during response".into()),
400                };
401            };
402            match msg.kind.as_str() {
403                HTTP_RESPONSE => {
404                    let mut resp = decode_response(&msg);
405                    if stream.is_some() && !body.is_empty() && resp.body.is_empty() {
406                        resp.body = body;
407                    }
408                    return Ok(resp);
409                }
410                ERROR => return Err(decode_error(&msg)),
411                STREAM_START => {
412                    stream = Some(decode_response(&msg));
413                    body.clear();
414                }
415                STREAM_CHUNK => {
416                    stream.get_or_insert_with(|| HttpResponse {
417                        status: 200,
418                        ..HttpResponse::default()
419                    });
420                    body.extend_from_slice(&decode_chunk(&msg));
421                }
422                STREAM_END => {
423                    let mut resp = stream.unwrap_or(HttpResponse {
424                        status: 200,
425                        ..HttpResponse::default()
426                    });
427                    resp.body = body;
428                    return Ok(resp);
429                }
430                _ => {}
431            }
432        }
433    }
434
435    /// `Manager.Stream`: start, chunk, end, error and complete-response events; a
436    /// closed session ends with an "wsrelay: stream closed" error event.
437    pub async fn stream(&self, provider: &str, req: &HttpRequest) -> Result<mpsc::Receiver<StreamEvent>, String> {
438        let mut responses = self.send(provider, Self::http_message(req))?;
439        let (tx, rx) = mpsc::channel(1);
440        tokio::spawn(async move {
441            loop {
442                // A dropped receiver must free the request (dropping `responses`)
443                // instead of waiting for the next upstream message.
444                let next = tokio::select! {
445                    next = responses.recv() => next,
446                    () = tx.closed() => return,
447                };
448                let Some(msg) = next else {
449                    let _ = tx
450                        .send(StreamEvent {
451                            error: Some("wsrelay: stream closed".into()),
452                            ..StreamEvent::default()
453                        })
454                        .await;
455                    return;
456                };
457                let event = match msg.kind.as_str() {
458                    STREAM_START => {
459                        let resp = decode_response(&msg);
460                        StreamEvent {
461                            kind: STREAM_START.into(),
462                            status: resp.status,
463                            headers: resp.headers,
464                            ..StreamEvent::default()
465                        }
466                    }
467                    STREAM_CHUNK => StreamEvent {
468                        kind: STREAM_CHUNK.into(),
469                        payload: decode_chunk(&msg),
470                        ..StreamEvent::default()
471                    },
472                    STREAM_END => StreamEvent {
473                        kind: STREAM_END.into(),
474                        ..StreamEvent::default()
475                    },
476                    ERROR => StreamEvent {
477                        kind: ERROR.into(),
478                        error: Some(decode_error(&msg)),
479                        ..StreamEvent::default()
480                    },
481                    HTTP_RESPONSE => {
482                        let resp = decode_response(&msg);
483                        StreamEvent {
484                            kind: HTTP_RESPONSE.into(),
485                            status: resp.status,
486                            headers: resp.headers,
487                            payload: resp.body,
488                            error: None,
489                        }
490                    }
491                    _ => continue,
492                };
493                let last = terminal(&event.kind);
494                if tx.send(event).await.is_err() || last {
495                    return;
496                }
497            }
498        });
499        Ok(rx)
500    }
501}
502
503/// Resolves once `closed` reports the session ended.
504pub async fn wait_closed(closed: &mut watch::Receiver<bool>) {
505    let _ = closed.wait_for(|c| *c).await;
506}
507
508/// One connected browser (`wsrelay.session`).
509pub struct Session {
510    provider: String,
511    relay: Weak<Relay>,
512    out: mpsc::UnboundedSender<String>,
513    closed: watch::Sender<bool>,
514    pending: Mutex<HashMap<String, Arc<Pending>>>,
515}
516
517/// One waiting request (`pendingRequest`): up to [`PENDING_BUFFER`] messages the
518/// reader has not taken yet. Delivery, the terminal message and the session's close
519/// decide under one lock, as Go's `pr.mu` serializes `deliver`, `deliverTerminal`
520/// and `cancelWithError`.
521#[derive(Default)]
522struct Pending {
523    state: Mutex<PendingState>,
524    /// Signalled when a message is queued or the request ends.
525    readable: Notify,
526    /// Signalled to every waiting delivery when a slot frees or the request ends.
527    /// Each delivery creates its `Notified` before checking the state, so
528    /// `notify_waiters` cannot miss it.
529    writable: Notify,
530}
531
532#[derive(Default)]
533struct PendingState {
534    queue: VecDeque<Message>,
535    /// No more messages are accepted; the reader drains the queue and then ends.
536    closed: bool,
537    /// A terminal message was queued; nothing follows it, not even the close error.
538    terminal: bool,
539}
540
541impl Pending {
542    /// `deliver` and `deliverTerminal`: waits for a free slot, or gives up once the
543    /// request has ended.
544    async fn deliver(&self, msg: Message) {
545        let last = terminal(&msg.kind);
546        let mut msg = Some(msg);
547        loop {
548            let writable = self.writable.notified();
549            {
550                let mut state = lock(&self.state);
551                if state.closed || state.terminal {
552                    return;
553                }
554                if state.queue.len() < PENDING_BUFFER {
555                    state.queue.extend(msg.take());
556                    state.terminal = last;
557                    drop(state);
558                    self.readable.notify_one();
559                    if last {
560                        // Other deliveries waiting for a slot now give up.
561                        self.writable.notify_waiters();
562                    }
563                    return;
564                }
565            }
566            writable.await;
567        }
568    }
569
570    /// `cancelWithError` (with `cause`) or `cancel`: once, the request stops taking
571    /// messages. Unless a terminal message already won, the error is queued last; a
572    /// full queue loses its oldest message to it. A reader taking a message at the
573    /// same time decides which one that is, as in Go.
574    fn end(&self, cause: Option<&str>) {
575        let mut state = lock(&self.state);
576        if state.closed {
577            return;
578        }
579        state.closed = true;
580        if let Some(cause) = cause.filter(|_| !state.terminal) {
581            if state.queue.len() >= PENDING_BUFFER {
582                state.queue.pop_front();
583            }
584            state.queue.push_back(Message {
585                id: String::new(),
586                kind: ERROR.into(),
587                payload: Some(BTreeMap::from([(
588                    "error".to_owned(),
589                    GoValue::String(cause.to_owned()),
590                )])),
591            });
592        }
593        drop(state);
594        self.readable.notify_one();
595        self.writable.notify_waiters();
596    }
597}
598
599/// The responses to one request; dropping it forgets the request (Go's context
600/// cancellation).
601struct Responses {
602    pending: Arc<Pending>,
603    session: Arc<Session>,
604    id: String,
605}
606
607impl Responses {
608    /// The next message, or `None` once the request has ended and its queue is empty.
609    async fn recv(&mut self) -> Option<Message> {
610        loop {
611            let readable = self.pending.readable.notified();
612            {
613                let mut state = lock(&self.pending.state);
614                if let Some(msg) = state.queue.pop_front() {
615                    drop(state);
616                    self.pending.writable.notify_waiters();
617                    return Some(msg);
618                }
619                if state.closed || state.terminal {
620                    return None;
621                }
622            }
623            readable.await;
624        }
625    }
626}
627
628impl Drop for Responses {
629    fn drop(&mut self) {
630        lock(&self.session.pending).remove(&self.id);
631        self.pending.end(None);
632    }
633}
634
635impl Session {
636    pub fn provider(&self) -> &str {
637        &self.provider
638    }
639
640    /// Resolves when the session has ended; the route then stops its transport.
641    pub fn closed(&self) -> watch::Receiver<bool> {
642        self.closed.subscribe()
643    }
644
645    pub fn is_closed(&self) -> bool {
646        *self.closed.borrow()
647    }
648
649    /// `session.send`.
650    fn send(&self, msg: &Message) -> Result<(), String> {
651        if self.is_closed() {
652            return Err(CLOSED.into());
653        }
654        self.out.send(msg.encode()).map_err(|_| CLOSED.to_owned())
655    }
656
657    /// `session.request`.
658    fn request(self: &Arc<Self>, msg: Message) -> Result<Responses, String> {
659        if msg.id.is_empty() {
660            return Err("wsrelay: message id is required".into());
661        }
662        let pending = Arc::new(Pending::default());
663        {
664            let mut map = lock(&self.pending);
665            if map.contains_key(&msg.id) {
666                return Err(format!("wsrelay: duplicate message id {}", msg.id));
667            }
668            map.insert(msg.id.clone(), pending.clone());
669        }
670        let responses = Responses {
671            pending,
672            session: self.clone(),
673            id: msg.id.clone(),
674        };
675        self.send(&msg)?;
676        Ok(responses)
677    }
678
679    /// One frame read from the socket (`session.run` and `dispatch`). An error ends the
680    /// session with that cause. A full request buffer makes the reader wait, as Go's does.
681    pub async fn receive(&self, frame: &[u8]) -> Result<(), String> {
682        let msg = match Message::decode(frame) {
683            Ok(msg) => msg,
684            Err(e) => {
685                self.close(&e);
686                return Err(e);
687            }
688        };
689        if msg.kind == PING {
690            let _ = self.send(&Message {
691                id: msg.id,
692                kind: PONG.into(),
693                payload: None,
694            });
695            return Ok(());
696        }
697        let Some(pending) = lock(&self.pending).get(&msg.id).cloned() else {
698            if terminal(&msg.kind) {
699                tracing::debug!(id = %msg.id, provider = %self.provider, "wsrelay: received terminal message for unknown id");
700            }
701            return Ok(());
702        };
703        let (id, last) = (msg.id.clone(), terminal(&msg.kind));
704        pending.deliver(msg).await;
705        // A terminal message closes the request: its receiver sees the end after it.
706        if last {
707            lock(&self.pending).remove(&id);
708        }
709        Ok(())
710    }
711
712    /// `session.cleanup`: once, every waiting request gets an error message carrying
713    /// `cause` (see [`Pending::end`]), the session leaves the relay and the observer
714    /// hears of it.
715    pub fn close(&self, cause: &str) {
716        if self.closed.send_replace(true) {
717            return;
718        }
719        let pending: Vec<_> = lock(&self.pending).drain().map(|(_, p)| p).collect();
720        for p in pending {
721            p.end(Some(cause));
722        }
723        let Some(relay) = self.relay.upgrade() else {
724            return;
725        };
726        {
727            let mut sessions = lock(&relay.sessions);
728            if sessions
729                .get(&self.provider)
730                .is_some_and(|s| std::ptr::eq(s.as_ref(), self))
731            {
732                sessions.remove(&self.provider);
733            }
734        }
735        if let Some(observer) = relay.observer() {
736            observer(&self.provider, Some(cause));
737        }
738    }
739}
740
741#[cfg(test)]
742#[path = "wsrelay_tests.rs"]
743mod tests;