sail-rs 0.2.11

Official Rust SDK for Sail: create and drive sailboxes (sandboxed cloud VMs) with lifecycle, streaming exec, file transfer, and ingress.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

//! Typed app discovery over the central API.
//!
//! `find` hits `/v1/apps/find` and `list` hits `/v1/apps`, both on the central
//! API host. Both map non-2xx responses onto the canonical [`SailError`]
//! taxonomy.

use serde::Serialize;
use serde_json::{json, Value};
use time::OffsetDateTime;

use crate::error::SailError;
use crate::http::{HttpCore, IdempotencyKey, Method, RequestSpec};
use crate::retry::DEFAULT_RETRY_POLICY;

/// A Sail application.
#[derive(Debug, Clone, Serialize)]
pub struct App {
    /// Stable server-assigned app identifier.
    pub id: String,
    /// Human-readable app name unique within the owning org.
    pub name: String,
    /// App creation time. Decoded from the central API's Unix-timestamp
    /// integer; serialized to RFC 3339 for the bindings like every other
    /// timestamp.
    #[serde(with = "time::serde::rfc3339")]
    pub created_at: OffsetDateTime,
}

impl App {
    /// Parse an app row from an API response object, defaulting missing fields.
    fn from_json(row: &Value) -> App {
        App {
            id: row
                .get("id")
                .and_then(Value::as_str)
                .unwrap_or("")
                .to_string(),
            name: row
                .get("name")
                .and_then(Value::as_str)
                .unwrap_or("")
                .to_string(),
            created_at: OffsetDateTime::from_unix_timestamp(
                row.get("created_at").and_then(Value::as_i64).unwrap_or(0),
            )
            .unwrap_or(OffsetDateTime::UNIX_EPOCH),
        }
    }
}

/// Find an app by name on the central API, optionally minting it.
pub async fn find_app(
    api_http: &HttpCore,
    name: &str,
    mint_if_missing: bool,
) -> Result<App, SailError> {
    let body = json!({ "name": name, "mint_if_missing": mint_if_missing });
    let bytes = serde_json::to_vec(&body).map_err(|e| SailError::Internal {
        message: format!("failed to serialize request body: {e}"),
    })?;
    let (status, data) = api_http
        .request(&RequestSpec {
            method: Method::Post,
            path: "/v1/apps/find".to_string(),
            query: Vec::new(),
            body: Some(bytes),
            extra_headers: Vec::new(),
            timeout: None,
            policy: DEFAULT_RETRY_POLICY,
            idempotency_key: IdempotencyKey::Auto,
        })
        .await?;
    // find returns 404 for any miss (not type-gated, unlike sailbox lookups).
    if status == 404 {
        return Err(SailError::NotFound {
            message: format!("App {name:?} not found"),
        });
    }
    raise_app_error(status, &data, "Failed to find app")?;
    Ok(App::from_json(&data))
}

/// Every app the org owns, newest first, from the central app index.
///
/// This reads the canonical apps table, so apps with no sailboxes yet are
/// included. The response is not paginated; the per-org app count is small.
pub async fn list_apps(api_http: &HttpCore) -> Result<Vec<App>, SailError> {
    let (status, data) = api_http
        .request(&RequestSpec {
            method: Method::Get,
            path: "/v1/apps".to_string(),
            query: Vec::new(),
            body: None,
            extra_headers: Vec::new(),
            timeout: None,
            policy: DEFAULT_RETRY_POLICY,
            idempotency_key: IdempotencyKey::Auto,
        })
        .await?;
    raise_app_error(status, &data, "Failed to list apps")?;
    let Some(rows) = data.get("data").and_then(Value::as_array) else {
        return Ok(Vec::new());
    };
    Ok(rows.iter().map(App::from_json).collect())
}

/// App ladder: 401/403 → PermissionDenied, any other non-2xx → Api
/// (transient/unexpected). 404 is handled by the caller where it is meaningful.
fn raise_app_error(status: u16, data: &Value, context: &str) -> Result<(), SailError> {
    if status < 300 {
        return Ok(());
    }
    let detail = crate::http::api_error_message(data, "unknown error");
    let message = format!("{context}: {detail}");
    if status == 401 || status == 403 {
        return Err(SailError::PermissionDenied { message });
    }
    Err(SailError::Api {
        status,
        message,
        body: data.clone(),
    })
}