Skip to main content

everruns_capabilities/
sandbox_state.rs

1//! Durable logical-sandbox and physical-incarnation state.
2//!
3//! Provider credentials never belong here. The store persists only the
4//! provider-neutral lifecycle record and the opaque, non-secret state a driver
5//! needs to reconnect to or replace one physical incarnation.
6
7use async_trait::async_trait;
8use thiserror::Error;
9
10use everruns_contracts::typed_id::SessionId;
11
12use crate::sandbox_checkpoint::SandboxRef;
13use crate::session_sandbox::{SESSION_SANDBOX_SECRET_NAME, SessionSandboxState};
14use everruns_core::{tool_context::ToolContext, tools::ToolExecutionResult};
15
16pub const MAX_SANDBOX_STATE_FIELD_BYTES: usize = 64 * 1024;
17
18#[derive(Debug, Error)]
19pub enum SandboxStateError {
20    #[error("sandbox state storage error: {0}")]
21    Storage(String),
22    #[error("sandbox {sandbox_id} is at generation {current}, write carried {carried}")]
23    StaleGeneration {
24        sandbox_id: uuid::Uuid,
25        current: i64,
26        carried: i64,
27    },
28    #[error("sandbox write carried {carried}, current logical sandbox is {current}")]
29    WrongSandbox {
30        current: uuid::Uuid,
31        carried: uuid::Uuid,
32    },
33    #[error("sandbox {field} is {size} bytes; maximum is {limit}")]
34    StateTooLarge {
35        field: &'static str,
36        size: usize,
37        limit: usize,
38    },
39}
40
41pub fn validate_sandbox_state(state: &SessionSandboxState) -> Result<(), SandboxStateError> {
42    for (field, value) in [
43        ("provider_state", &state.instance.provider_state),
44        ("metadata", &state.instance.metadata),
45    ] {
46        let size = serde_json::to_vec(value)
47            .map_err(|error| SandboxStateError::Storage(error.to_string()))?
48            .len();
49        if size > MAX_SANDBOX_STATE_FIELD_BYTES {
50            return Err(SandboxStateError::StateTooLarge {
51                field,
52                size,
53                limit: MAX_SANDBOX_STATE_FIELD_BYTES,
54            });
55        }
56    }
57    Ok(())
58}
59
60/// Persistence for the current physical incarnation of a logical sandbox.
61#[async_trait]
62pub trait SandboxStateStore: Send + Sync {
63    /// Load the session's current logical sandbox. Session scope permits at
64    /// most one; a second provider is rejected by product configuration.
65    async fn load_current_state(
66        &self,
67        session_id: SessionId,
68    ) -> Result<Option<SessionSandboxState>, SandboxStateError>;
69
70    /// Load the current incarnation for a session/provider pair.
71    async fn load_state(
72        &self,
73        session_id: SessionId,
74        provider: &str,
75    ) -> Result<Option<SessionSandboxState>, SandboxStateError>;
76
77    /// Persist the current incarnation. Changing `external_id` advances the
78    /// logical sandbox generation and retires the previous incarnation.
79    async fn save_state(
80        &self,
81        session_id: SessionId,
82        state: &SessionSandboxState,
83        expected: Option<&SandboxRef>,
84    ) -> Result<SandboxRef, SandboxStateError>;
85
86    /// Delete the logical sandbox and all subordinate incarnation/checkpoint
87    /// records after the provider resource has been released.
88    async fn delete_state(
89        &self,
90        session_id: SessionId,
91        provider: &str,
92        expected: Option<&SandboxRef>,
93    ) -> Result<bool, SandboxStateError>;
94}
95
96/// Hosted store installed on [`everruns_core::ToolContext`] as a typed
97/// extension. Framework/remote hosts that do not install it retain the legacy
98/// session-secret fallback.
99#[derive(Clone)]
100pub struct SandboxStateStoreExt(pub std::sync::Arc<dyn SandboxStateStore>);
101
102/// One hosted implementation normally owns logical identity, incarnation
103/// state, and checkpoint lineage in the same database.
104pub trait SandboxPersistenceStore:
105    SandboxStateStore + crate::sandbox_checkpoint::SandboxCheckpointStore
106{
107}
108
109impl<T> SandboxPersistenceStore for T where
110    T: SandboxStateStore + crate::sandbox_checkpoint::SandboxCheckpointStore
111{
112}
113
114/// Load managed environment state from durable hosted storage, adopting a
115/// legacy session-secret record on first access when necessary.
116pub async fn load_session_sandbox_state(
117    context: &ToolContext,
118) -> Result<Option<SessionSandboxState>, ToolExecutionResult> {
119    if let Some(store) = context.extensions.get::<SandboxStateStoreExt>() {
120        if let Some(current) = store
121            .0
122            .load_current_state(context.session_id)
123            .await
124            .map_err(ToolExecutionResult::internal_error)?
125        {
126            return Ok(Some(current));
127        }
128
129        if let Some(legacy) = load_legacy_session_sandbox_state(context).await? {
130            let sandbox = store
131                .0
132                .save_state(context.session_id, &legacy, None)
133                .await
134                .map_err(ToolExecutionResult::internal_error)?;
135            if let Some(storage) = context.storage_store.as_ref()
136                && let Err(error) = storage
137                    .delete_secret(context.session_id, SESSION_SANDBOX_SECRET_NAME)
138                    .await
139            {
140                tracing::warn!(%error, "adopted sandbox state but could not remove legacy secret");
141            }
142            return Ok(Some(SessionSandboxState {
143                sandbox: Some(sandbox),
144                ..legacy
145            }));
146        }
147    }
148
149    load_legacy_session_sandbox_state(context).await
150}
151
152pub(crate) async fn load_state_for_provider(
153    context: &ToolContext,
154    provider: &str,
155) -> Result<Option<SessionSandboxState>, ToolExecutionResult> {
156    if let Some(store) = context.extensions.get::<SandboxStateStoreExt>()
157        && let Some(state) = store
158            .0
159            .load_state(context.session_id, provider)
160            .await
161            .map_err(ToolExecutionResult::internal_error)?
162    {
163        return Ok(Some(state));
164    }
165    load_session_sandbox_state(context).await
166}
167
168async fn load_legacy_session_sandbox_state(
169    context: &ToolContext,
170) -> Result<Option<SessionSandboxState>, ToolExecutionResult> {
171    let Some(storage) = context.storage_store.as_ref() else {
172        return Ok(None);
173    };
174    let Some(raw) = storage
175        .get_secret(context.session_id, SESSION_SANDBOX_SECRET_NAME)
176        .await
177        .map_err(ToolExecutionResult::internal_error)?
178    else {
179        return Ok(None);
180    };
181    serde_json::from_str(&raw).map(Some).map_err(|error| {
182        ToolExecutionResult::internal_error_msg(format!(
183            "Corrupt legacy session sandbox state: {error}"
184        ))
185    })
186}
187
188/// Persist managed environment state. Hosted PostgreSQL contexts use
189/// first-class logical/instance rows; portable hosts retain the legacy secret
190/// fallback until they install a [`SandboxStateStore`].
191pub async fn save_session_sandbox_state(
192    context: &ToolContext,
193    state: &mut SessionSandboxState,
194) -> Result<(), ToolExecutionResult> {
195    validate_sandbox_state(state).map_err(ToolExecutionResult::internal_error)?;
196    if let Some(store) = context.extensions.get::<SandboxStateStoreExt>() {
197        let sandbox = store
198            .0
199            .save_state(context.session_id, state, state.sandbox.as_ref())
200            .await
201            .map_err(ToolExecutionResult::internal_error)?;
202        state.sandbox = Some(sandbox);
203        return Ok(());
204    }
205
206    let storage = context
207        .storage_store
208        .as_ref()
209        .ok_or_else(|| ToolExecutionResult::tool_error("Storage not available in this context"))?;
210    let raw = serde_json::to_string(state).map_err(|error| {
211        ToolExecutionResult::internal_error_msg(format!(
212            "Failed to encode session sandbox state: {error}"
213        ))
214    })?;
215    storage
216        .set_secret(context.session_id, SESSION_SANDBOX_SECRET_NAME, &raw)
217        .await
218        .map_err(ToolExecutionResult::internal_error)
219}
220
221/// Delete managed environment state after its provider resource is released.
222pub async fn delete_session_sandbox_state(
223    context: &ToolContext,
224    state: &SessionSandboxState,
225) -> Result<(), ToolExecutionResult> {
226    if let Some(store) = context.extensions.get::<SandboxStateStoreExt>() {
227        store
228            .0
229            .delete_state(context.session_id, &state.provider, state.sandbox.as_ref())
230            .await
231            .map_err(ToolExecutionResult::internal_error)?;
232    }
233    if let Some(storage) = context.storage_store.as_ref() {
234        storage
235            .delete_secret(context.session_id, SESSION_SANDBOX_SECRET_NAME)
236            .await
237            .map_err(ToolExecutionResult::internal_error)?;
238    }
239    Ok(())
240}
241
242#[cfg(test)]
243mod tests {
244    use std::{
245        collections::HashMap,
246        sync::{Arc, Mutex},
247    };
248
249    use async_trait::async_trait;
250    use chrono::Utc;
251    use everruns_core::session_services::{KeyInfo, SecretInfo, SessionStorageStore};
252    use serde_json::json;
253
254    use super::*;
255    use crate::session_sandbox::{SessionSandboxInstance, SessionSandboxStatus};
256
257    #[derive(Default)]
258    struct MemoryStateStore {
259        state: Mutex<Option<SessionSandboxState>>,
260    }
261
262    #[async_trait]
263    impl SandboxStateStore for MemoryStateStore {
264        async fn load_current_state(
265            &self,
266            _session_id: SessionId,
267        ) -> Result<Option<SessionSandboxState>, SandboxStateError> {
268            Ok(self.state.lock().unwrap().clone())
269        }
270
271        async fn load_state(
272            &self,
273            _session_id: SessionId,
274            provider: &str,
275        ) -> Result<Option<SessionSandboxState>, SandboxStateError> {
276            Ok(self
277                .state
278                .lock()
279                .unwrap()
280                .clone()
281                .filter(|state| state.provider == provider))
282        }
283
284        async fn save_state(
285            &self,
286            _session_id: SessionId,
287            state: &SessionSandboxState,
288            _expected: Option<&SandboxRef>,
289        ) -> Result<SandboxRef, SandboxStateError> {
290            let sandbox = SandboxRef {
291                id: uuid::Uuid::nil(),
292                generation: 1,
293            };
294            let mut persisted = state.clone();
295            persisted.sandbox = Some(sandbox.clone());
296            *self.state.lock().unwrap() = Some(persisted);
297            Ok(sandbox)
298        }
299
300        async fn delete_state(
301            &self,
302            _session_id: SessionId,
303            provider: &str,
304            _expected: Option<&SandboxRef>,
305        ) -> Result<bool, SandboxStateError> {
306            let mut state = self.state.lock().unwrap();
307            let matches = state
308                .as_ref()
309                .is_some_and(|state| state.provider == provider);
310            if matches {
311                *state = None;
312            }
313            Ok(matches)
314        }
315    }
316
317    #[derive(Clone, Default)]
318    struct MemorySecrets(Arc<Mutex<HashMap<String, String>>>);
319
320    #[async_trait]
321    impl SessionStorageStore for MemorySecrets {
322        async fn set_value(
323            &self,
324            _session_id: SessionId,
325            _key: &str,
326            _value: &str,
327        ) -> everruns_contracts::error::Result<()> {
328            unreachable!()
329        }
330
331        async fn get_value(
332            &self,
333            _session_id: SessionId,
334            _key: &str,
335        ) -> everruns_contracts::error::Result<Option<String>> {
336            unreachable!()
337        }
338
339        async fn delete_value(
340            &self,
341            _session_id: SessionId,
342            _key: &str,
343        ) -> everruns_contracts::error::Result<bool> {
344            unreachable!()
345        }
346
347        async fn list_keys(
348            &self,
349            _session_id: SessionId,
350        ) -> everruns_contracts::error::Result<Vec<KeyInfo>> {
351            unreachable!()
352        }
353
354        async fn set_secret(
355            &self,
356            _session_id: SessionId,
357            name: &str,
358            value: &str,
359        ) -> everruns_contracts::error::Result<()> {
360            self.0
361                .lock()
362                .unwrap()
363                .insert(name.to_string(), value.to_string());
364            Ok(())
365        }
366
367        async fn get_secret(
368            &self,
369            _session_id: SessionId,
370            name: &str,
371        ) -> everruns_contracts::error::Result<Option<String>> {
372            Ok(self.0.lock().unwrap().get(name).cloned())
373        }
374
375        async fn delete_secret(
376            &self,
377            _session_id: SessionId,
378            name: &str,
379        ) -> everruns_contracts::error::Result<bool> {
380            Ok(self.0.lock().unwrap().remove(name).is_some())
381        }
382
383        async fn list_secrets(
384            &self,
385            _session_id: SessionId,
386        ) -> everruns_contracts::error::Result<Vec<SecretInfo>> {
387            Ok(Vec::new())
388        }
389    }
390
391    #[tokio::test]
392    async fn hosted_state_lazily_adopts_and_removes_legacy_secret() {
393        let storage = Arc::new(MemorySecrets::default());
394        let session_id = SessionId::new();
395        let legacy_context = ToolContext::with_storage_store(session_id, storage.clone());
396        let now = Utc::now().to_rfc3339();
397        let mut state = SessionSandboxState {
398            sandbox: None,
399            provider: "daytona".to_string(),
400            status: SessionSandboxStatus::Running,
401            instance: SessionSandboxInstance {
402                external_id: "sb_legacy".to_string(),
403                display_name: None,
404                workspace_path: Some("/workspace".to_string()),
405                provider_state: json!({}),
406                metadata: json!({}),
407            },
408            init_completed_at: None,
409            last_init_error: None,
410            created_at: now.clone(),
411            updated_at: now,
412        };
413        save_session_sandbox_state(&legacy_context, &mut state)
414            .await
415            .unwrap();
416
417        let durable = Arc::new(MemoryStateStore::default());
418        let hosted_context =
419            legacy_context.with_extension(Arc::new(SandboxStateStoreExt(durable.clone())));
420        let adopted = load_session_sandbox_state(&hosted_context)
421            .await
422            .unwrap()
423            .expect("legacy state is adopted");
424
425        assert_eq!(adopted.instance.external_id, "sb_legacy");
426        assert!(storage.0.lock().unwrap().is_empty());
427        assert_eq!(
428            durable
429                .state
430                .lock()
431                .unwrap()
432                .as_ref()
433                .map(|state| state.instance.external_id.as_str()),
434            Some("sb_legacy")
435        );
436    }
437
438    #[test]
439    fn sandbox_state_rejects_oversized_provider_fields() {
440        let now = Utc::now().to_rfc3339();
441        let mut state = SessionSandboxState {
442            sandbox: None,
443            provider: "daytona".to_string(),
444            status: SessionSandboxStatus::Running,
445            instance: SessionSandboxInstance {
446                external_id: "sb_test".to_string(),
447                display_name: None,
448                workspace_path: Some("/workspace".to_string()),
449                provider_state: json!({"payload": "x".repeat(MAX_SANDBOX_STATE_FIELD_BYTES)}),
450                metadata: json!({}),
451            },
452            init_completed_at: None,
453            last_init_error: None,
454            created_at: now.clone(),
455            updated_at: now,
456        };
457
458        assert!(matches!(
459            validate_sandbox_state(&state),
460            Err(SandboxStateError::StateTooLarge {
461                field: "provider_state",
462                ..
463            })
464        ));
465
466        state.instance.provider_state = json!({});
467        state.instance.metadata = json!({"payload": "x".repeat(MAX_SANDBOX_STATE_FIELD_BYTES)});
468        assert!(matches!(
469            validate_sandbox_state(&state),
470            Err(SandboxStateError::StateTooLarge {
471                field: "metadata",
472                ..
473            })
474        ));
475    }
476}