sail/sailbox/

types.rs

//! Typed domain models for the Sailbox API: lifecycle, listing, ingress
//! listeners, and volumes.
//!
//! The core owns the wire schema: it deserializes API responses into these
//! structs (applying the wire-schema field defaults) and serializes them back
//! out for bindings. A binding maps a struct onto its own public type by field
//! name without re-parsing the wire shape.

use std::time::Duration;

use serde::{Deserialize, Serialize};
use time::OffsetDateTime;

use crate::error::SailError;

/// Lifecycle status of a Sailbox. An unrecognized server value is preserved in
/// `Other` so a status a newer backend introduces never fails parsing. The
/// default is `Other("")`: the status of a handle no server response has
/// filled in yet.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SailboxStatus {
    /// Running and serving.
    Running,
    /// Paused in memory.
    Paused,
    /// Sleeping (checkpointed to disk).
    Sleeping,
    /// In a failed state.
    Failed,
    /// Terminated.
    Terminated,
    /// A status this SDK version does not recognize, kept verbatim.
    Other(String),
}

impl Default for SailboxStatus {
    fn default() -> Self {
        SailboxStatus::Other(String::new())
    }
}

impl SailboxStatus {
    /// The wire string for this status.
    pub fn as_str(&self) -> &str {
        match self {
            SailboxStatus::Running => "running",
            SailboxStatus::Paused => "paused",
            SailboxStatus::Sleeping => "sleeping",
            SailboxStatus::Failed => "failed",
            SailboxStatus::Terminated => "terminated",
            SailboxStatus::Other(s) => s,
        }
    }
}

impl From<&str> for SailboxStatus {
    fn from(s: &str) -> SailboxStatus {
        match s {
            "running" => SailboxStatus::Running,
            "paused" => SailboxStatus::Paused,
            "sleeping" => SailboxStatus::Sleeping,
            "failed" => SailboxStatus::Failed,
            "terminated" => SailboxStatus::Terminated,
            other => SailboxStatus::Other(other.to_string()),
        }
    }
}

impl std::fmt::Display for SailboxStatus {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl Serialize for SailboxStatus {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for SailboxStatus {
    fn deserialize<D: serde::Deserializer<'de>>(
        deserializer: D,
    ) -> Result<SailboxStatus, D::Error> {
        Ok(SailboxStatus::from(
            String::deserialize(deserializer)?.as_str(),
        ))
    }
}

/// A lifecycle status a client can filter by in [`ListSailboxesQuery`]. A closed set: a
/// client only filters by statuses the SDK knows. Server responses use the open
/// [`SailboxStatus`], which tolerates a status a newer backend introduces.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SailboxStatusFilter {
    /// Running and serving.
    Running,
    /// Paused in memory.
    Paused,
    /// Sleeping (checkpointed to disk).
    Sleeping,
    /// In a failed state.
    Failed,
    /// Terminated.
    Terminated,
}

/// Server-side ordering for list results.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SailboxListOrder {
    /// Most recently active first: active/restorable Sailboxes, then updated_at.
    #[default]
    NewestActive,
    /// Newest-created Sailboxes first.
    NewestCreated,
}

impl SailboxListOrder {
    /// The order's name, which is also the value the list API expects.
    pub fn as_str(&self) -> &'static str {
        match self {
            SailboxListOrder::NewestActive => "newest_active",
            SailboxListOrder::NewestCreated => "newest_created",
        }
    }

    /// Parse a canonical name.
    pub fn parse(raw: &str) -> Option<SailboxListOrder> {
        match raw.trim() {
            "newest_active" => Some(SailboxListOrder::NewestActive),
            "newest_created" => Some(SailboxListOrder::NewestCreated),
            _ => None,
        }
    }
}

impl std::str::FromStr for SailboxListOrder {
    type Err = SailError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        SailboxListOrder::parse(s).ok_or_else(|| SailError::InvalidArgument {
            message: format!(
                "unknown list order {s:?}; use \"newest_active\" or \"newest_created\""
            ),
        })
    }
}

impl std::fmt::Display for SailboxListOrder {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl SailboxStatusFilter {
    /// The wire string for this status.
    pub fn as_str(&self) -> &'static str {
        match self {
            SailboxStatusFilter::Running => "running",
            SailboxStatusFilter::Paused => "paused",
            SailboxStatusFilter::Sleeping => "sleeping",
            SailboxStatusFilter::Failed => "failed",
            SailboxStatusFilter::Terminated => "terminated",
        }
    }

    /// Parse a wire string, returning `None` for a status the SDK does not know.
    pub fn parse(s: &str) -> Option<SailboxStatusFilter> {
        match s {
            "running" => Some(SailboxStatusFilter::Running),
            "paused" => Some(SailboxStatusFilter::Paused),
            "sleeping" => Some(SailboxStatusFilter::Sleeping),
            "failed" => Some(SailboxStatusFilter::Failed),
            "terminated" => Some(SailboxStatusFilter::Terminated),
            _ => None,
        }
    }
}

impl std::str::FromStr for SailboxStatusFilter {
    type Err = SailError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        SailboxStatusFilter::parse(s).ok_or_else(|| SailError::InvalidArgument {
            message: format!(
                "unknown status filter {s:?}; use \"running\", \"paused\", \"sleeping\", \
                 \"failed\", or \"terminated\""
            ),
        })
    }
}

impl std::fmt::Display for SailboxStatusFilter {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// Wire protocol for an ingress port or listener. An unrecognized value is
/// preserved in `Other` so a protocol a newer backend introduces never fails.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ListenerProtocol {
    /// Raw TCP.
    Tcp,
    /// HTTP.
    Http,
    /// A protocol this SDK version does not recognize, kept verbatim.
    Other(String),
}

impl ListenerProtocol {
    /// The wire string for this protocol.
    pub fn as_str(&self) -> &str {
        match self {
            ListenerProtocol::Tcp => "tcp",
            ListenerProtocol::Http => "http",
            ListenerProtocol::Other(s) => s,
        }
    }
}

impl From<&str> for ListenerProtocol {
    fn from(s: &str) -> ListenerProtocol {
        match s {
            "tcp" => ListenerProtocol::Tcp,
            "http" => ListenerProtocol::Http,
            other => ListenerProtocol::Other(other.to_string()),
        }
    }
}

impl std::fmt::Display for ListenerProtocol {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl Serialize for ListenerProtocol {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for ListenerProtocol {
    fn deserialize<D: serde::Deserializer<'de>>(
        deserializer: D,
    ) -> Result<ListenerProtocol, D::Error> {
        Ok(ListenerProtocol::from(
            String::deserialize(deserializer)?.as_str(),
        ))
    }
}

/// Status of a listener's ingress route. An unrecognized value is preserved in
/// `Other` so a status a newer backend introduces never fails to parse.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ListenerRouteStatus {
    /// The route state is not yet known.
    Unknown,
    /// The route is being set up.
    Pending,
    /// The route is active and ready to carry traffic.
    Active,
    /// The route is being restored after a checkpoint or migration.
    Restoring,
    /// The route is temporarily unavailable.
    Unavailable,
    /// A status this SDK version does not recognize, kept verbatim.
    Other(String),
}

impl ListenerRouteStatus {
    /// The user-facing string for this status. The backend's proto spelling
    /// (`LISTENER_ROUTE_STATUS_*`) is normalized here, once, so no wrapper
    /// ever sees it.
    pub fn as_str(&self) -> &str {
        match self {
            ListenerRouteStatus::Unknown => "unknown",
            ListenerRouteStatus::Pending => "pending",
            ListenerRouteStatus::Active => "active",
            ListenerRouteStatus::Restoring => "restoring",
            ListenerRouteStatus::Unavailable => "unavailable",
            ListenerRouteStatus::Other(s) => s,
        }
    }
}

impl From<&str> for ListenerRouteStatus {
    /// Parse the backend's proto spelling (`LISTENER_ROUTE_STATUS_*`) or the
    /// friendly form that [`as_str`](Self::as_str) emits, so a serialized
    /// [`Listener`](crate::Listener) round-trips through serde. An unrecognized
    /// value is kept in `Other` with the `LISTENER_ROUTE_STATUS_` prefix
    /// stripped and lowercased.
    fn from(s: &str) -> ListenerRouteStatus {
        match s {
            "LISTENER_ROUTE_STATUS_UNSPECIFIED" | "unknown" => ListenerRouteStatus::Unknown,
            "LISTENER_ROUTE_STATUS_PENDING" | "pending" => ListenerRouteStatus::Pending,
            "LISTENER_ROUTE_STATUS_ACTIVE" | "active" => ListenerRouteStatus::Active,
            "LISTENER_ROUTE_STATUS_RESTORING" | "restoring" => ListenerRouteStatus::Restoring,
            "LISTENER_ROUTE_STATUS_UNAVAILABLE" | "unavailable" => ListenerRouteStatus::Unavailable,
            other => ListenerRouteStatus::Other(
                other
                    .strip_prefix("LISTENER_ROUTE_STATUS_")
                    .map_or_else(|| other.to_string(), str::to_ascii_lowercase),
            ),
        }
    }
}

impl std::fmt::Display for ListenerRouteStatus {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl Serialize for ListenerRouteStatus {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for ListenerRouteStatus {
    fn deserialize<D: serde::Deserializer<'de>>(
        deserializer: D,
    ) -> Result<ListenerRouteStatus, D::Error> {
        Ok(ListenerRouteStatus::from(
            String::deserialize(deserializer)?.as_str(),
        ))
    }
}

/// Transport protocol a client requests when exposing an ingress port. A closed
/// set: a client can only request a protocol the SDK supports. Server responses
/// use the open [`ListenerProtocol`], which tolerates a protocol a newer backend adds.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IngressProtocol {
    /// Raw TCP.
    Tcp,
    /// HTTP.
    Http,
}

impl IngressProtocol {
    /// The wire string for this protocol.
    pub fn as_str(&self) -> &'static str {
        match self {
            IngressProtocol::Tcp => "tcp",
            IngressProtocol::Http => "http",
        }
    }

    /// Parse a wire string, returning `None` for a protocol the SDK does not
    /// support.
    pub fn parse(s: &str) -> Option<IngressProtocol> {
        match s {
            "tcp" => Some(IngressProtocol::Tcp),
            "http" => Some(IngressProtocol::Http),
            _ => None,
        }
    }
}

impl std::str::FromStr for IngressProtocol {
    type Err = SailError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        IngressProtocol::parse(s).ok_or_else(|| SailError::InvalidArgument {
            message: format!("unknown ingress protocol {s:?}; use \"tcp\" or \"http\""),
        })
    }
}

impl std::fmt::Display for IngressProtocol {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl Serialize for IngressProtocol {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

/// Options for [`Sailbox::checkpoint`](crate::Sailbox::checkpoint).
#[derive(Debug, Clone, Default)]
pub struct CheckpointOptions {
    /// Human-readable label for the checkpoint.
    pub name: Option<String>,
    /// Retention override; must be positive when given.
    pub ttl: Option<std::time::Duration>,
}

/// Options for
/// [`Sailbox::wait_for_listener`](crate::Sailbox::wait_for_listener).
/// `Default` gives up after a minute.
#[derive(Debug, Clone)]
pub struct WaitForListenerOptions {
    /// Fail with a timeout error after this long. `Duration::MAX` waits
    /// indefinitely.
    pub timeout: std::time::Duration,
}

impl Default for WaitForListenerOptions {
    fn default() -> WaitForListenerOptions {
        WaitForListenerOptions {
            timeout: std::time::Duration::from_mins(1),
        }
    }
}

/// Options for [`Sailbox::fork`](crate::Sailbox::fork).
#[derive(Debug, Clone, Default)]
pub struct ForkOptions {
    /// Display name for the child Sailbox; `None` lets the server derive one.
    pub name: Option<String>,
    /// Accepted and ignored. The call blocks until the fork finishes, so apply
    /// your own deadline if you need one. Must be positive when given.
    pub timeout: Option<std::time::Duration>,
}

/// Named Sailbox resource size. Sailboxes are offered in a small discrete CPU
/// menu rather than free-form vCPU/memory/disk. Each size sets the vCPU count
/// plus a default memory and disk ceiling. Ongoing billing is by observed
/// usage, so a larger size raises the ceiling without reserving resources;
/// each size also has its documented one-time creation charge.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SailboxSize {
    /// Small (1 vCPU): fastest cold starts, forks, and resumes, with
    /// lower ceilings that cap what a runaway workload can consume.
    Small,
    /// Medium (4 vCPU, default).
    Medium,
    /// Large (8 vCPU).
    Large,
}

impl SailboxSize {
    /// The wire string for this size.
    pub fn as_str(&self) -> &'static str {
        match self {
            SailboxSize::Small => "s",
            SailboxSize::Medium => "m",
            SailboxSize::Large => "l",
        }
    }

    /// Parse a wire string, returning `None` for an unsupported size.
    pub fn parse(s: &str) -> Option<SailboxSize> {
        match s {
            "s" => Some(SailboxSize::Small),
            "m" => Some(SailboxSize::Medium),
            "l" => Some(SailboxSize::Large),
            _ => None,
        }
    }

    /// The allowed size labels in ascending order, for error messages and help.
    pub fn allowed() -> &'static [&'static str] {
        &["s", "m", "l"]
    }
}

impl std::str::FromStr for SailboxSize {
    type Err = SailError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        SailboxSize::parse(s).ok_or_else(|| SailError::InvalidArgument {
            message: format!("unknown size {s:?}; use one of s, m, l"),
        })
    }
}

impl std::fmt::Display for SailboxSize {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl Serialize for SailboxSize {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

/// A handle to a running Sailbox: the fields needed to exec against it, copy
/// files, or reach a listener. Returned by create/resume/from_checkpoint.
#[derive(Debug, Clone, Default, Serialize)]
#[non_exhaustive]
pub struct SailboxHandle {
    /// The Sailbox's stable identifier.
    pub sailbox_id: String,
    /// The Sailbox's name: the one given at create, or the one Sail derived
    /// from the source when a fork or a restore left it out.
    pub name: String,
    /// The Sailbox's lifecycle status (for example `running`).
    pub status: SailboxStatus,
    /// Internal routing address for the host serving the Sailbox.
    #[doc(hidden)]
    pub worker_address: String,
    /// Internal endpoint for opening exec/file/listener streams to the Sailbox.
    #[doc(hidden)]
    pub exec_endpoint: String,
}

/// Actionable notice that a Sailbox's runtime should be upgraded.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct SailboxDeprecation {
    /// Date after which the Sailbox may be upgraded automatically on its
    /// next wake, stopping running processes and clearing in-memory state.
    pub deadline: String,
    /// Upgrade guidance from the server.
    pub message: String,
}

/// Read-only snapshot from get/list. Deliberately omits worker_address /
/// exec_endpoint (the list/get endpoints do not return them).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct SailboxInfo {
    /// The Sailbox's stable identifier.
    pub sailbox_id: String,
    /// Identifier of the owning app.
    pub app_id: String,
    /// Name of the owning app.
    pub app_name: String,
    /// Identifier of the image the Sailbox was created from.
    pub image_id: String,
    /// The Sailbox's display name: the one given at create, restore, or fork
    /// time, or one derived from the source when that call omitted it.
    pub name: String,
    /// The Sailbox's lifecycle status (for example `running`).
    pub status: SailboxStatus,
    /// Configured memory size, in mebibytes.
    pub memory_mib: i64,
    /// Configured number of virtual CPUs.
    pub vcpu_count: i64,
    /// Configured state-disk size, in gibibytes.
    pub state_disk_size_gib: i64,
    /// Requested CPU allocation, in vCPUs.
    pub cpu_requested_vcpu: i64,
    /// Current CPU usage, in vCPUs.
    pub cpu_used_vcpu: f64,
    /// Requested memory allocation, in bytes.
    pub memory_requested_bytes: i64,
    /// Current memory usage, in bytes.
    pub memory_used_bytes: i64,
    /// Requested disk allocation, in bytes.
    pub disk_requested_bytes: i64,
    /// Current disk usage, in bytes.
    pub disk_used_bytes: i64,
    /// CPU architecture of the Sailbox, in the create-side vocabulary
    /// (`amd64` or `arm64`).
    #[serde(default)]
    pub architecture: String,
    /// Guest schema version the Sailbox is running, when reported by the backend.
    #[serde(default)]
    pub guest_schema_version: Option<i64>,
    /// Actionable runtime deprecation notice, when an upgrade is needed.
    #[serde(default)]
    pub deprecation: Option<SailboxDeprecation>,
    /// Human-readable error detail, present when the Sailbox is in an error state.
    #[serde(default)]
    pub error_message: Option<String>,
    /// Monotonic checkpoint generation counter for the Sailbox.
    pub checkpoint_generation: i64,
    /// When the Sailbox first started running, if it has. A resume does not
    /// rewrite it.
    #[serde(with = "crate::rfc3339_micros::option", default)]
    pub started_at: Option<OffsetDateTime>,
    /// When the most recent checkpoint was taken, if any.
    #[serde(with = "crate::rfc3339_micros::option", default)]
    pub last_checkpointed_at: Option<OffsetDateTime>,
    /// When the Sailbox was created.
    #[serde(with = "crate::rfc3339_micros")]
    pub created_at: OffsetDateTime,
    /// When the Sailbox was last updated.
    #[serde(with = "crate::rfc3339_micros")]
    pub updated_at: OffsetDateTime,
    /// The user whose credential created this Sailbox (for a fork or restore, the
    /// user who ran it). `None` for service-key creates.
    #[serde(default)]
    pub created_by_user_id: Option<String>,
    /// Access visibility: `Some("private")` restricts exec/files/SSH and
    /// lifecycle to the creator; `None`/`Some("org")` is org-wide access.
    #[serde(default)]
    pub visibility: Option<String>,
}

/// The identity behind the presented API key.
#[doc(hidden)]
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct WhoAmI {
    /// The organization the key belongs to.
    pub org_id: String,
    /// The user the key is scoped to, or `None` for a service key.
    #[serde(default)]
    pub user_id: Option<String>,
}

/// One page of list results plus the pagination envelope.
#[derive(Debug, Clone, Serialize)]
#[non_exhaustive]
pub struct SailboxPage {
    /// The Sailboxes in this page.
    pub items: Vec<SailboxInfo>,
    /// Maximum number of items requested for this page.
    pub limit: i64,
    /// Zero-based offset of the first item in this page.
    pub offset: i64,
    /// Total number of Sailboxes matching the query across all pages.
    pub total: i64,
    /// True when further pages exist beyond this one.
    pub has_more: bool,
}

/// Query parameters for [`Client::sailbox_spend`](crate::Client::sailbox_spend).
#[derive(Debug, Clone, Default)]
pub struct SailboxSpendQuery {
    /// Restrict spend to Sailboxes owned by this app id.
    pub app_id: Option<String>,
    /// Restrict spend to one Sailbox id.
    pub sailbox_id: Option<String>,
    /// Inclusive lower bound for the spend window. The API defaults to the
    /// current UTC month when omitted.
    pub from: Option<OffsetDateTime>,
    /// Exclusive upper bound for the spend window. The API defaults to now when
    /// omitted.
    pub to: Option<OffsetDateTime>,
}

/// Estimated Sailbox spend over a requested time window.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct SailboxSpendResponse {
    /// Start of the spend window.
    #[serde(with = "crate::rfc3339_micros")]
    pub start_at: OffsetDateTime,
    /// End of the spend window.
    #[serde(with = "crate::rfc3339_micros")]
    pub end_at: OffsetDateTime,
    /// Cost from closed billing segments, in USD nanos.
    pub finalized_cost_usd_nanos: i64,
    /// Estimated cost from still-open billing segments, in USD nanos.
    pub estimated_active_cost_usd_nanos: i64,
    /// Total estimated cost, in USD nanos.
    pub estimated_total_cost_usd_nanos: i64,
    /// Total observed duration, in seconds.
    pub duration_seconds: i64,
    /// Total vCPU-seconds observed.
    pub vcpu_seconds: f64,
    /// Total GiB-seconds of memory observed.
    pub memory_gib_seconds: f64,
    /// Total GiB-seconds of state disk observed.
    pub state_disk_gib_seconds: f64,
    /// Whether non-zero pricing rates were configured by the backend.
    pub pricing_configured: bool,
    /// Pricing rates used for the local estimate.
    pub rates: SailboxSpendRates,
    /// Per-Sailbox spend summaries.
    pub sailboxes: Vec<SailboxSpendItem>,
}

/// Rate metadata returned with a Sailbox spend estimate.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct SailboxSpendRates {
    /// Nanodollars per vCPU-second.
    pub vcpu_second_usd_nanos: i64,
    /// Nanodollars per memory GiB-second.
    pub memory_gib_second_usd_nanos: i64,
    /// Nanodollars per arm64 state-disk GiB-second.
    pub state_disk_gib_second_usd_nanos: i64,
    /// Nanodollars per Sailbox creation.
    pub creation_usd_nanos: i64,
    /// Nanodollars per amd64 state-disk GiB-second.
    #[serde(default)]
    pub amd64_state_disk_gib_second_usd_nanos: i64,
}

/// Estimated spend for one Sailbox over a requested time window.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct SailboxSpendItem {
    /// Sailbox id.
    pub sailbox_id: String,
    /// Owning app id.
    pub app_id: String,
    /// Cost from closed billing segments, in USD nanos.
    pub finalized_cost_usd_nanos: i64,
    /// Estimated cost from still-open billing segments, in USD nanos.
    pub estimated_active_cost_usd_nanos: i64,
    /// Total estimated cost, in USD nanos.
    pub estimated_total_cost_usd_nanos: i64,
    /// Observed duration, in seconds.
    pub duration_seconds: i64,
    /// Observed vCPU-seconds.
    pub vcpu_seconds: f64,
    /// Observed GiB-seconds of memory.
    pub memory_gib_seconds: f64,
    /// Observed GiB-seconds of state disk.
    pub state_disk_gib_seconds: f64,
    /// Whether this row includes an active billing segment.
    pub active: bool,
}

/// Query parameters for [`Client::sailbox_metrics`](crate::Client::sailbox_metrics).
#[derive(Debug, Clone)]
pub struct SailboxMetricsQuery {
    /// Window name accepted by the API, for example `1h`, `6h`, `24h`, or `7d`.
    pub range: String,
}

impl Default for SailboxMetricsQuery {
    fn default() -> SailboxMetricsQuery {
        SailboxMetricsQuery {
            range: "24h".to_string(),
        }
    }
}

/// Resource-usage time series for one Sailbox.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct SailboxMetricsResponse {
    /// Echoed range selected by the API.
    pub range: String,
    /// Time-ordered metric points.
    pub data: Vec<SailboxMetricPoint>,
}

/// One bucket in a Sailbox resource-usage time series.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct SailboxMetricPoint {
    /// Bucket timestamp.
    #[serde(with = "crate::rfc3339_micros")]
    pub timestamp: OffsetDateTime,
    /// Current CPU usage, in vCPUs.
    pub cpu_used_vcpu: f64,
    /// Requested CPU allocation, in vCPUs.
    pub cpu_requested_vcpu: i64,
    /// Current memory usage, in bytes.
    pub memory_used_bytes: i64,
    /// Requested memory allocation, in bytes.
    pub memory_requested_bytes: i64,
    /// Current disk usage, in bytes.
    pub disk_used_bytes: i64,
    /// Requested disk allocation, in bytes.
    pub disk_requested_bytes: i64,
}

/// A durable checkpoint handle. `status` echoes the source Sailbox's lifecycle
/// status after checkpointing (a running Sailbox is snapshotted; a paused/sleeping
/// one returns its existing checkpoint), so the binding can sync its handle.
#[derive(Debug, Clone, Serialize)]
#[non_exhaustive]
pub struct SailboxCheckpoint {
    /// Stable identifier of the checkpoint.
    pub checkpoint_id: String,
    /// Identifier of the Sailbox the checkpoint was taken from.
    pub sailbox_id: String,
    /// Checkpoint generation counter captured by this checkpoint.
    pub checkpoint_generation: i64,
    /// When the checkpoint expires: seven days out unless `ttl` asked for a
    /// different window. Starting a Sailbox from it after that fails.
    #[serde(with = "crate::rfc3339_micros::option")]
    pub expires_at: Option<OffsetDateTime>,
    /// Source Sailbox's lifecycle status after checkpointing.
    pub status: SailboxStatus,
}

/// Filters for list/list_page.
#[derive(Debug, Clone)]
pub struct ListSailboxesQuery {
    /// Restrict results to Sailboxes owned by the app with this id.
    pub app_id: Option<String>,
    /// Restrict results to Sailboxes in this lifecycle status.
    pub status: Option<SailboxStatusFilter>,
    /// Free-text search filter applied by the backend.
    pub search: Option<String>,
    /// Restrict results to Sailboxes with the credential injection policy
    /// with this id attached.
    #[doc(hidden)]
    pub credential_policy_id: Option<String>,
    /// Ordering to apply before pagination.
    pub order: SailboxListOrder,
    /// Maximum number of items to return.
    pub limit: i64,
    /// Zero-based offset of the first item to return.
    pub offset: i64,
}

/// Default page size for listing, matching the Sailbox API's own default. The
/// API rejects `limit=0`, so the derived all-zero default cannot be used.
#[doc(hidden)]
pub const DEFAULT_LIST_LIMIT: i64 = 50;

/// Largest page size the listing endpoints accept; larger limits are rejected,
/// not clamped. Auto-paginating listers request full pages of this size.
#[doc(hidden)]
pub const MAX_LIST_LIMIT: i64 = 100;

impl Default for ListSailboxesQuery {
    fn default() -> ListSailboxesQuery {
        ListSailboxesQuery {
            app_id: None,
            status: None,
            search: None,
            credential_policy_id: None,
            order: SailboxListOrder::NewestActive,
            limit: DEFAULT_LIST_LIMIT,
            offset: 0,
        }
    }
}

/// One guest ingress port to reserve at create time.
#[derive(Debug, Clone, Serialize)]
pub struct IngressPort {
    /// Port inside the guest to expose for ingress.
    pub guest_port: u32,
    /// Transport protocol for the port (for example `tcp`).
    pub protocol: IngressProtocol,
    /// Sources allowed to reach the port: an address or a range, or a Sail app
    /// name on an `http` listener. An app name cannot read as an address or a
    /// range, and cannot contain a `/`. An address must not carry an IPv6 zone,
    /// such as `fe80::1%eth0`, which names an interface on one machine rather
    /// than a source. Empty means all sources are allowed.
    pub allowlist: Vec<String>,
}

/// One NFS volume mount.
#[derive(Debug, Clone, Serialize)]
pub struct VolumeMount {
    /// Identifier of the NFS volume to mount.
    pub volume_id: String,
    /// Absolute path inside the guest where the volume is mounted.
    pub mount_path: String,
}

/// A custom domain attached to a Sailbox HTTP listener.
#[doc(hidden)]
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct CustomDomainInfo {
    /// Normalized hostname.
    pub domain: String,
    /// Sailbox receiving requests for the hostname.
    pub sailbox_id: String,
    /// Guest HTTP port receiving requests for the hostname.
    pub guest_port: u32,
    /// HTTPS URL served by the hostname.
    pub url: String,
    /// Organization-specific hostname the domain's CNAME record must target.
    pub cname_target: String,
    /// When the domain was attached.
    #[serde(with = "crate::rfc3339_micros")]
    pub created_at: OffsetDateTime,
}

/// A managed NFS volume as returned by the volume API.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct VolumeInfo {
    /// Stable identifier of the volume.
    pub volume_id: String,
    /// Caller-supplied volume name.
    pub name: String,
    /// Storage backend serving the volume.
    pub backend: String,
    /// Lifecycle status of the volume.
    pub status: String,
    /// When the volume was created, if reported.
    #[serde(with = "crate::rfc3339_micros::option", default)]
    pub created_at: Option<OffsetDateTime>,
    /// When the volume was last updated, if reported.
    #[serde(with = "crate::rfc3339_micros::option", default)]
    pub updated_at: Option<OffsetDateTime>,
}

/// The wire shape of the add-listener response: the scheduler resolves the
/// public endpoint in the response (so a caller renders it without a second
/// lookup) but reports nothing about routing, so it converts to a [`Listener`]
/// with an unknown route status.
#[derive(Debug, Clone, Deserialize)]
pub(crate) struct AddListenerWire {
    pub(crate) guest_port: u32,
    pub(crate) protocol: ListenerProtocol,
    #[serde(default)]
    pub(crate) public_url: String,
    #[serde(default)]
    pub(crate) public_host: String,
    #[serde(default)]
    pub(crate) public_port: u32,
}

impl From<AddListenerWire> for crate::worker::Listener {
    fn from(wire: AddListenerWire) -> crate::worker::Listener {
        crate::worker::Listener {
            guest_port: wire.guest_port,
            protocol: wire.protocol,
            // The expose response says nothing about reachability; confirm
            // with wait_for_listener or re-fetch via get/list.
            route_status: ListenerRouteStatus::Unknown,
            public_url: wire.public_url,
            public_host: wire.public_host,
            public_port: wire.public_port,
        }
    }
}

/// A CA-signed SSH user certificate plus the key id that identifies the signing
/// org (`org=<id>;fp=...;iat=...`).
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct IssuedUserCert {
    /// The OpenSSH certificate (`<type>-cert-v01@openssh.com AAAA...`).
    pub certificate: String,
    /// The certificate key id.
    pub key_id: String,
}

/// How to reach an exposed listener: a routable HTTPS URL for `http`
/// listeners, or a host/port any TCP client can dial for `tcp` listeners.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ListenerEndpoint {
    /// The HTTPS URL to reach the guest service.
    Http {
        /// Routable URL.
        url: String,
    },
    /// The address to dial for a raw-TCP listener.
    Tcp {
        /// Hostname to dial.
        host: String,
        /// Port to dial.
        port: u32,
    },
}

impl std::fmt::Display for ListenerEndpoint {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ListenerEndpoint::Http { url } => f.write_str(url),
            ListenerEndpoint::Tcp { host, port } => write!(f, "{host}:{port}"),
        }
    }
}

/// Inputs to create a Sailbox. The image is a typed [`ImageSpec`](crate::image::ImageSpec);
/// describe a custom build by filling an
/// [`ImageDefinition`](crate::imagebuild::ImageDefinition). `Default` selects
/// the Debian base image and the platform defaults for everything else;
/// `app_id` (and usually `name`) must be set before the request is valid.
#[derive(Debug, Clone)]
pub struct CreateSailboxRequest {
    /// Identifier of the app that will own the Sailbox.
    pub app_id: String,
    /// Caller-supplied name for the Sailbox.
    pub name: String,
    /// Guest ingress ports to reserve at create time.
    pub ingress_ports: Vec<IngressPort>,
    /// NFS volumes to mount into the guest.
    pub volume_mounts: Vec<VolumeMount>,
    /// The image to create the Sailbox from. Serialized to canonical proto-JSON
    /// and sent as the `image` field.
    pub image: crate::image::ImageSpec,
    /// Requested resource size; defaults server-side when absent.
    pub size: Option<SailboxSize>,
    /// Optional memory limit in whole GiB, within the size's range; the
    /// size's default when absent.
    pub memory_gib: Option<u32>,
    /// Optional disk size in whole GiB, within the size's range; the size's
    /// default when absent.
    pub disk_gib: Option<u32>,
    /// Enable SSH on the new Sailbox after create: trust the org SSH CA, start
    /// `sshd`, and expose guest port 22 as TCP once the CA-only daemon owns it.
    /// An explicit port-22 ingress entry contributes just its allowlist.
    pub ssh: bool,
    /// By default a Sailbox is org-wide: any credential in the org can exec,
    /// copy files, SSH, or run lifecycle operations on it. `true` restricts all
    /// of that to the creating user. An org admin can override that with a
    /// recorded reason for exec, files, setting a wake time, and the pause,
    /// sleep, resume, terminate, and upgrade operations. SSH, exposing or
    /// removing listeners, and fork/checkpoint/restore stay creator-only.
    /// Requires a user-scoped API key.
    pub private: bool,
    /// Budget for rebuilding the image if Sail needs to rebuild it before
    /// the Sailbox is created; the default build budget applies when absent.
    pub image_build_timeout: Option<Duration>,
}

impl Default for CreateSailboxRequest {
    /// An empty request for a plain Debian-base Sailbox: fill in `app_id` and
    /// `name`, override the rest as needed.
    fn default() -> CreateSailboxRequest {
        CreateSailboxRequest {
            app_id: String::new(),
            name: String::new(),
            ingress_ports: Vec::new(),
            volume_mounts: Vec::new(),
            image: crate::image::ImageSpec {
                base: Some(crate::image::BaseImage::Debian),
                ..crate::image::ImageSpec::default()
            },
            size: None,
            memory_gib: None,
            disk_gib: None,
            ssh: false,
            private: false,
            image_build_timeout: None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn closed_enums_round_trip_through_fromstr_and_display() {
        for (text, value) in [
            ("newest_active", SailboxListOrder::NewestActive),
            ("newest_created", SailboxListOrder::NewestCreated),
        ] {
            assert_eq!(text.parse::<SailboxListOrder>().unwrap(), value);
            assert_eq!(value.to_string(), text);
        }
        for (text, value) in [
            ("running", SailboxStatusFilter::Running),
            ("terminated", SailboxStatusFilter::Terminated),
        ] {
            assert_eq!(text.parse::<SailboxStatusFilter>().unwrap(), value);
            assert_eq!(value.to_string(), text);
        }
        for (text, value) in [
            ("tcp", IngressProtocol::Tcp),
            ("http", IngressProtocol::Http),
        ] {
            assert_eq!(text.parse::<IngressProtocol>().unwrap(), value);
            assert_eq!(value.to_string(), text);
        }
        for (text, value) in [
            ("s", SailboxSize::Small),
            ("m", SailboxSize::Medium),
            ("l", SailboxSize::Large),
        ] {
            assert_eq!(text.parse::<SailboxSize>().unwrap(), value);
            assert_eq!(value.to_string(), text);
        }
        let err = "udp".parse::<IngressProtocol>().unwrap_err();
        assert!(matches!(err, SailError::InvalidArgument { .. }));
        assert!(err.to_string().contains("udp"));
    }

    #[test]
    fn list_query_default_uses_a_valid_nonzero_limit() {
        // The sailbox API rejects limit=0, so the default must be the API's own
        // page size, not the derived zero.
        let query = ListSailboxesQuery::default();
        assert_eq!(query.limit, DEFAULT_LIST_LIMIT);
        assert!(query.limit > 0);
        assert_eq!(query.offset, 0);
    }

    #[test]
    fn route_status_round_trips_through_serde() {
        // Serialize emits the friendly form (as_str), so a persisted Listener
        // read back must parse it rather than fall through to Other. Guards the
        // Serialize/Deserialize pair against drifting apart.
        for status in [
            ListenerRouteStatus::Unknown,
            ListenerRouteStatus::Pending,
            ListenerRouteStatus::Active,
            ListenerRouteStatus::Restoring,
            ListenerRouteStatus::Unavailable,
            ListenerRouteStatus::Other("degraded".to_string()),
        ] {
            let json = serde_json::to_string(&status).unwrap();
            let back: ListenerRouteStatus = serde_json::from_str(&json).unwrap();
            assert_eq!(
                status, back,
                "round-trip failed for {status:?} (json {json})"
            );
        }
        // The backend's proto spelling still parses to the same value.
        assert_eq!(
            ListenerRouteStatus::from("LISTENER_ROUTE_STATUS_ACTIVE"),
            ListenerRouteStatus::Active,
        );
    }

    #[test]
    fn info_deserializes_a_deprecation_notice() {
        let value = serde_json::json!({
            "sailbox_id": "sb-1", "app_id": "app-1", "app_name": "a", "name": "n",
            "image_id": "img-1",
            "status": "running", "memory_mib": 2048, "vcpu_count": 4,
            "state_disk_size_gib": 10,
            "cpu_requested_vcpu": 2, "cpu_used_vcpu": 1.5,
            "memory_requested_bytes": 1024, "memory_used_bytes": 512,
            "disk_requested_bytes": 4096, "disk_used_bytes": 2048,
            "architecture": "amd64", "checkpoint_generation": 7,
            "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-02T00:00:00Z",
            "deprecation": {
                "deadline": "2026-08-01",
                "message": "Upgrade this sailbox before 2026-08-01."
            }
        });
        let info: SailboxInfo = serde_json::from_value(value).unwrap();
        let notice = info.deprecation.unwrap();
        assert_eq!(notice.deadline, "2026-08-01");
        assert!(notice.message.starts_with("Upgrade this sailbox"));
    }

    #[test]
    fn add_listener_reads_the_tcp_dial_target() {
        for body in [
            r#"{"guest_port":2222,"protocol":"tcp","public_host":"tcp.example.com","public_port":22003}"#,
            // A response that repeats the pair under an older name reads the
            // same, because a field this type does not name is ignored.
            r#"{"guest_port":2222,"protocol":"tcp","public_host":"tcp.example.com","public_port":22003,"tcp_public_host":"old.example.com","tcp_public_port":1}"#,
        ] {
            let wire: AddListenerWire = serde_json::from_str(body).unwrap();
            let listener = crate::worker::Listener::from(wire);
            assert_eq!(listener.public_host, "tcp.example.com");
            assert_eq!(listener.public_port, 22003);
        }
    }
}