Skip to main content

cpa_server/
home_session.rs

1//! Home picks kept by pooled upstream sockets (Go `HomeDispatchSelection` as an
2//! `ExecutionLifecycle`, `retainHomeWebsocketSelection` and
3//! `retainedHomeSessionSelection`).
4//!
5//! A downstream WebSocket turn on a Home credential hands its pick to the executor as
6//! a [`Pick`]. When the executor keeps the upstream socket for later turns it retains
7//! the pick, and after the turn succeeds the pick takes the lease over from the
8//! attempt: the credential stays leased while the socket is open. The pick ends, and
9//! the lease is released, when the socket is invalidated, replaced or closed, when
10//! Home drains it (the socket closes first), or when the downstream connection ends.
11//! The next turn of the same session runs on a still-active pick instead of asking
12//! Home again.
13
14use std::collections::HashMap;
15use std::sync::{Arc, Mutex, PoisonError, Weak};
16
17use cpa_core::credential::Credential;
18use cpa_core::exec::{Retainable, SessionLease};
19
20use crate::remote::Availability;
21use crate::runtime::Lease;
22
23/// One attempt's Home pick as the executor sees it.
24#[derive(Default)]
25pub(crate) struct Pick(Mutex<State>);
26
27#[derive(Default)]
28struct State {
29    retained: bool,
30    ended: bool,
31    /// Closes the socket that retained the pick.
32    close: Option<Box<dyn FnOnce() + Send>>,
33    /// Held once the turn succeeded on a retaining socket.
34    lease: Option<Lease>,
35    /// Closes the pick when Home drains its lease.
36    watcher: Option<tokio::task::AbortHandle>,
37    /// Forgets the session's view of the credential when the pick ends.
38    forget: Option<Box<dyn FnOnce() + Send>>,
39}
40
41impl Retainable for Pick {
42    fn retain(&self, close: Box<dyn FnOnce() + Send>) -> bool {
43        let mut state = self.state();
44        if state.ended {
45            return false;
46        }
47        state.retained = true;
48        state.close = Some(close);
49        true
50    }
51
52    fn end(&self) {
53        let (lease, watcher, forget) = {
54            let mut state = self.state();
55            state.ended = true;
56            state.close = None;
57            (state.lease.take(), state.watcher.take(), state.forget.take())
58        };
59        if let Some(watcher) = watcher {
60            watcher.abort();
61        }
62        if let Some(forget) = forget {
63            forget();
64        }
65        drop(lease);
66    }
67}
68
69impl Pick {
70    fn state(&self) -> std::sync::MutexGuard<'_, State> {
71        self.0.lock().unwrap_or_else(PoisonError::into_inner)
72    }
73
74    pub(crate) fn lease(self: &Arc<Self>) -> SessionLease {
75        SessionLease(self.clone())
76    }
77
78    /// After a successful turn: the pick keeps `lease` when a socket retained it and
79    /// still holds it. Otherwise the lease comes back to the attempt.
80    pub(crate) fn keep(self: &Arc<Self>, lease: Lease) -> Option<Lease> {
81        let drained = lease.remote_cancelled();
82        let mut state = self.state();
83        if !state.retained || state.ended {
84            return Some(lease);
85        }
86        state.lease = Some(lease);
87        if let Some(drained) = drained {
88            let pick: Weak<Self> = Arc::downgrade(self);
89            let watcher = tokio::spawn(async move {
90                drained.await;
91                if let Some(pick) = pick.upgrade() {
92                    pick.close();
93                }
94            });
95            state.watcher = Some(watcher.abort_handle());
96        }
97        None
98    }
99
100    /// Go `End` from the request side: closes the retaining socket, then releases the
101    /// lease. Idempotent.
102    pub(crate) fn close(&self) {
103        let (close, lease, watcher, forget) = {
104            let mut state = self.state();
105            state.ended = true;
106            (
107                state.close.take(),
108                state.lease.take(),
109                state.watcher.take(),
110                state.forget.take(),
111            )
112        };
113        if let Some(close) = close {
114            close();
115        }
116        if let Some(forget) = forget {
117            forget();
118        }
119        drop(lease);
120        if let Some(watcher) = watcher {
121            watcher.abort();
122        }
123    }
124
125    fn release_into(&self, releases: &crate::remote::PendingReleases) {
126        if let Some(lease) = self.state().lease.as_mut() {
127            lease.release_into(releases);
128        }
129    }
130
131    /// Lends the kept lease to the session's next turn, which runs on this same pick:
132    /// the socket stays bound to it.
133    fn lend(&self) -> Option<Lease> {
134        let (lease, watcher) = {
135            let mut state = self.state();
136            if state.ended
137                || !state
138                    .lease
139                    .as_ref()
140                    .is_some_and(|lease| !lease.remote_cancel_requested())
141            {
142                return None;
143            }
144            (state.lease.take(), state.watcher.take())
145        };
146        if let Some(watcher) = watcher {
147            watcher.abort();
148        }
149        lease
150    }
151}
152
153/// Closes a pick unless the turn handed its lease to it; dropped before the attempt's
154/// lease, so a socket closes before its credential is released.
155pub(crate) struct PickGuard(Option<Arc<Pick>>);
156
157impl PickGuard {
158    pub(crate) fn new(pick: Arc<Pick>) -> Self {
159        Self(Some(pick))
160    }
161
162    /// The pick holds the lease now; it no longer ends with the attempt.
163    pub(crate) fn defuse(&mut self) -> Option<Arc<Pick>> {
164        self.0.take()
165    }
166}
167
168impl Drop for PickGuard {
169    fn drop(&mut self) {
170        if let Some(pick) = self.0.take() {
171            pick.close();
172        }
173    }
174}
175
176struct Kept {
177    pick: Arc<Pick>,
178    credential: String,
179    /// Canonical route model.
180    route: String,
181    /// The client key Home authenticated when it granted the pick.
182    user_key: String,
183    /// Home's request-retry limit with the pick (Go `selection.requestRetry`).
184    request_retry: Option<i64>,
185    /// The lease is out with the next turn's attempt.
186    lent: bool,
187}
188
189/// The pick a downstream WebSocket connection keeps between turns (Go
190/// `homeSessionSelections` for one session).
191#[derive(Default)]
192pub struct SessionHome {
193    kept: Mutex<Option<Kept>>,
194    /// Home's request-retry limit with the session's latest fresh pick.
195    granted_retry: Mutex<Option<i64>>,
196    /// The Home credentials this session's kept picks hold, by ID, each with the pick
197    /// that owns the entry (Go `homeRuntimeAuths` and `homeRuntimeAuthOwners` for one
198    /// session): the turn loop's view of its pin, which the local store does not hold.
199    /// An entry goes when its owning pick ends.
200    auths: Mutex<HashMap<String, Remembered>>,
201}
202
203/// A remembered credential with its runtime state, and the pick that owns the entry.
204type Remembered = (Weak<Pick>, Arc<Credential>, Arc<Availability>);
205
206impl SessionHome {
207    fn slot(&self) -> std::sync::MutexGuard<'_, Option<Kept>> {
208        self.kept.lock().unwrap_or_else(PoisonError::into_inner)
209    }
210
211    /// Records the request-retry limit Home sent with a fresh pick, which a kept pick
212    /// carries to later turns.
213    pub(crate) fn granted(&self, request_retry: Option<i64>) {
214        *self.granted_retry.lock().unwrap_or_else(PoisonError::into_inner) = request_retry;
215    }
216
217    /// Go `retainHomeWebsocketSelection`: a pick kept for a previous turn ends
218    /// (`target_replaced`).
219    /// The session remembers a credential with WebSockets enabled until this pick ends
220    /// (Go `bindHomeSelectionRuntimeAuth`).
221    pub(crate) fn keep(
222        self: &Arc<Self>,
223        pick: Arc<Pick>,
224        credential: &Arc<Credential>,
225        availability: Arc<Availability>,
226        route: &str,
227        user_key: String,
228    ) {
229        let request_retry = *self.granted_retry.lock().unwrap_or_else(PoisonError::into_inner);
230        if cpa_exec::websockets_enabled(credential) {
231            self.remember(&pick, credential, availability);
232        }
233        let previous = self.slot().replace(Kept {
234            pick,
235            credential: credential.id.clone(),
236            route: crate::scheduler::canonical_model(route).to_owned(),
237            user_key,
238            request_retry,
239            lent: false,
240        });
241        if let Some(previous) = previous {
242            previous.pick.close();
243        }
244    }
245
246    /// Go `retainedHomeSessionSelection`: the kept lease, its client key and Home's
247    /// request-retry limit when this
248    /// pick may run on it (a first pick of the first round, same route, a credential
249    /// neither excluded nor other than the pinned one, not drained). Any other kept
250    /// pick ends (`target_changed`); its release joins `releases`.
251    pub(crate) fn reuse(
252        &self,
253        first_pick: bool,
254        route: &str,
255        excluded: &[String],
256        pinned: Option<&str>,
257        releases: &crate::remote::PendingReleases,
258    ) -> Option<(Lease, String, Option<i64>)> {
259        let mut slot = self.slot();
260        let kept = slot.take()?;
261        kept.pick.release_into(releases);
262        let route = crate::scheduler::canonical_model(route);
263        let matches = first_pick
264            && !kept.lent
265            && !route.is_empty()
266            && kept.route == route
267            && !excluded.contains(&kept.credential)
268            && pinned.is_none_or(|id| id.is_empty() || id == kept.credential);
269        if matches && let Some(lease) = kept.pick.lend() {
270            let (user_key, request_retry) = (kept.user_key.clone(), kept.request_retry);
271            *slot = Some(Kept { lent: true, ..kept });
272            return Some((lease, user_key, request_retry));
273        }
274        drop(slot);
275        kept.pick.close();
276        None
277    }
278
279    /// The pick for an attempt on `credential`: the lent one when its lease came back
280    /// for this attempt, else a new one. A lent pick the attempt does not take ends.
281    pub(crate) fn pick(&self, credential: &str) -> Arc<Pick> {
282        let lent = {
283            let mut slot = self.slot();
284            match slot.take() {
285                Some(kept) if kept.lent => Some(kept),
286                other => {
287                    *slot = other;
288                    None
289                }
290            }
291        };
292        match lent {
293            Some(kept) if kept.credential == credential => kept.pick,
294            Some(kept) => {
295                kept.pick.close();
296                Arc::default()
297            }
298            None => Arc::default(),
299        }
300    }
301
302    fn remember(self: &Arc<Self>, pick: &Arc<Pick>, credential: &Arc<Credential>, availability: Arc<Availability>) {
303        let id = credential.id.clone();
304        let owner = Arc::downgrade(pick);
305        self.auths
306            .lock()
307            .unwrap_or_else(PoisonError::into_inner)
308            .insert(id.clone(), (owner.clone(), credential.clone(), availability));
309        // Go `forgetHomeRuntimeAuth`: only while this pick still owns the entry, so an
310        // ended pick never erases a newer pick's credential with the same ID.
311        let session = Arc::downgrade(self);
312        let forget = move || {
313            if let Some(session) = session.upgrade() {
314                let mut auths = session.auths.lock().unwrap_or_else(PoisonError::into_inner);
315                if auths.get(&id).is_some_and(|(current, _, _)| current.ptr_eq(&owner)) {
316                    auths.remove(&id);
317                }
318            }
319        };
320        let mut state = pick.state();
321        if state.ended {
322            drop(state);
323            forget();
324        } else {
325            state.forget = Some(Box::new(forget));
326        }
327    }
328
329    /// Go `GetExecutionSessionAuthByID`: a Home credential a live kept pick holds. Every
330    /// pick ends before it drops (a session's `Kept` holds it, an attempt's `PickGuard`
331    /// closes it), so no entry outlives its owner.
332    pub(crate) fn auth(&self, id: &str) -> Option<(Arc<Credential>, Arc<Availability>)> {
333        self.auths
334            .lock()
335            .unwrap_or_else(PoisonError::into_inner)
336            .get(id)
337            .map(|(_, credential, availability)| (credential.clone(), availability.clone()))
338    }
339
340    /// The downstream connection ended (Go `CloseExecutionSession`).
341    pub(crate) fn close(&self) {
342        self.auths.lock().unwrap_or_else(PoisonError::into_inner).clear();
343        if let Some(kept) = self.slot().take() {
344            kept.pick.close();
345        }
346    }
347}
348
349#[cfg(test)]
350mod tests {
351    use super::*;
352    use crate::remote::{ModelsError, RemoteDispatch, RemoteError, RemoteGrant, RemoteRequest};
353    use futures_util::future::BoxFuture;
354
355    /// Grants one credential on every pick.
356    struct Grant(Credential);
357
358    impl RemoteDispatch for Grant {
359        fn available(&self) -> bool {
360            true
361        }
362
363        fn dispatch(&self, _: RemoteRequest) -> BoxFuture<'_, Result<RemoteGrant, RemoteError>> {
364            let credential = self.0.clone();
365            Box::pin(async move {
366                Ok(RemoteGrant {
367                    credential,
368                    end: Box::new(|| None),
369                    cancel: None,
370                    request_retry: None,
371                    user_api_key: String::new(),
372                    private: Default::default(),
373                })
374            })
375        }
376
377        fn models(
378            &self,
379            _: Vec<(String, String)>,
380            _: Vec<(String, String)>,
381        ) -> BoxFuture<'_, Result<Vec<u8>, ModelsError>> {
382            Box::pin(async { Err(ModelsError::Unavailable) })
383        }
384    }
385
386    fn home_credential(id: &str, websockets: &str) -> Credential {
387        let mut credential = Credential::relay_session(id);
388        credential.attributes.insert("websockets".into(), websockets.into());
389        credential
390    }
391
392    struct Fixture {
393        rt: crate::runtime::Runtime,
394        releases: crate::remote::PendingReleases,
395    }
396
397    impl Fixture {
398        fn new() -> Self {
399            let executors = cpa_exec::Executors {
400                claude: cpa_exec::claude::ClaudeExecutor::new("http://127.0.0.1:9").unwrap(),
401                codex: Default::default(),
402                devices: Default::default(),
403                openai: Default::default(),
404                google: Default::default(),
405            };
406            Self {
407                rt: crate::testing::runtime(Default::default(), Vec::new(), executors),
408                releases: Default::default(),
409            }
410        }
411
412        /// A successful turn on `credential` for route `gpt-5` whose socket retained its
413        /// pick, which the session keeps.
414        async fn keep(&self, home: &Arc<SessionHome>, credential: Credential) -> Arc<Pick> {
415            let selection = crate::runtime::Selection {
416                model: "gpt-5".into(),
417                ..Default::default()
418            };
419            let (lease, _, _) = self
420                .rt
421                .acquire_remote(&Grant(credential), selection, RemoteRequest::default(), &self.releases)
422                .await
423                .unwrap();
424            let credential = lease.credential.clone();
425            let pick: Arc<Pick> = Arc::default();
426            assert!(pick.retain(Box::new(|| ())));
427            assert!(pick.keep(lease).is_none());
428            home.keep(pick.clone(), &credential, Default::default(), "gpt-5", String::new());
429            pick
430        }
431
432        fn reuse(&self, home: &SessionHome, first_pick: bool, route: &str, excluded: &[String]) -> bool {
433            home.reuse(first_pick, route, excluded, Some("home-a"), &self.releases)
434                .is_some()
435        }
436    }
437
438    /// Go `TestPickNextViaHomeDoesNotReuseTriedPinnedWebsocketAuth` and
439    /// `TestPickNextViaHomeDoesNotReusePinnedWebsocketAuthAfterFirstHomeAttempt`: a live
440    /// kept pick serves only the first pick of the first round, for the same route, of
441    /// a credential not tried yet. Any other pick ends it, and the session forgets its
442    /// credential (Go `forgetHomeRuntimeAuth` from the selection's end), so a later
443    /// turn back on the route cannot pin it.
444    #[tokio::test]
445    async fn a_kept_pick_serves_only_a_first_untried_pick_and_takes_its_credential_along() {
446        let fixture = Fixture::new();
447        let home = Arc::new(SessionHome::default());
448        let tried = ["home-a".to_owned()];
449        for (first_pick, route, excluded) in [
450            (false, "gpt-5", &[][..]),
451            (true, "gpt-5", &tried[..]),
452            (true, "claude-x", &[][..]),
453        ] {
454            fixture.keep(&home, home_credential("home-a", "true")).await;
455            assert!(home.auth("home-a").is_some());
456            assert!(
457                !fixture.reuse(&home, first_pick, route, excluded),
458                "{first_pick} {route} {excluded:?}"
459            );
460            assert!(home.auth("home-a").is_none(), "{first_pick} {route} {excluded:?}");
461        }
462        // The control: the same kept pick serves a fitting first pick and stays known.
463        fixture.keep(&home, home_credential("home-a", "true")).await;
464        assert!(fixture.reuse(&home, true, "gpt-5", &[]));
465        assert!(home.auth("home-a").is_some());
466    }
467
468    /// Go `bindHomeSelectionRuntimeAuth`, `forgetHomeRuntimeAuth`'s owner check,
469    /// `TestPickNextViaHomeDoesNotReusePinnedNonWebsocketAuth` and
470    /// `TestCloseExecutionSessionClearsHomeRuntimeAuthForSession`: the session sees a
471    /// kept credential only while its pick lives, a replaced pick with the same ID does
472    /// not erase its successor's entry, a credential without WebSockets is never
473    /// remembered, and closing one session forgets only its own.
474    #[tokio::test]
475    async fn a_remembered_home_credential_lives_with_its_pick() {
476        let fixture = Fixture::new();
477        let (one, two) = (Arc::new(SessionHome::default()), Arc::new(SessionHome::default()));
478
479        let first = fixture.keep(&one, home_credential("home-a", "true")).await;
480        Retainable::end(first.as_ref());
481        assert!(one.auth("home-a").is_none(), "the socket's end forgets it");
482
483        let first = fixture.keep(&one, home_credential("home-a", "true")).await;
484        let second = fixture.keep(&one, home_credential("home-a", "true")).await;
485        assert!(first.state().ended, "target_replaced");
486        first.close();
487        assert!(
488            one.auth("home-a").is_some(),
489            "the old pick does not erase its successor"
490        );
491        second.close();
492        assert!(one.auth("home-a").is_none());
493
494        fixture.keep(&one, home_credential("home-b", "false")).await;
495        assert!(one.auth("home-b").is_none(), "no WebSockets, no view");
496
497        fixture.keep(&one, home_credential("home-a", "true")).await;
498        fixture.keep(&two, home_credential("home-a", "true")).await;
499        one.close();
500        assert!(one.auth("home-a").is_none());
501        assert!(two.auth("home-a").is_some(), "another session keeps its own");
502        two.close();
503        assert!(two.auth("home-a").is_none());
504    }
505}