alien_bindings/

traits.rs

use crate::error::Result;
use crate::presigned::PresignedRequest;
use alien_core::{BuildConfig, BuildExecution};
use async_trait::async_trait;
use object_store::path::Path;
use object_store::ObjectStore;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use std::sync::Arc;
use std::time::Duration;
use url::Url;

#[cfg(feature = "openapi")]
use utoipa::ToSchema;

/// Marker trait for all binding types.
pub trait Binding: Send + Sync + std::fmt::Debug {}

/// A storage binding that provides object store capabilities.
#[async_trait]
pub trait Storage: Binding + ObjectStore {
    /// Gets the base directory path configured for this storage binding.
    fn get_base_dir(&self) -> Path;
    /// Gets the underlying URL configured for this storage binding.
    fn get_url(&self) -> Url;

    /// Creates a presigned request for uploading data to the specified path.
    /// The request can be serialized, stored, and executed later.
    async fn presigned_put(&self, path: &Path, expires_in: Duration) -> Result<PresignedRequest>;

    /// Creates a presigned request for downloading data from the specified path.
    /// The request can be serialized, stored, and executed later.
    async fn presigned_get(&self, path: &Path, expires_in: Duration) -> Result<PresignedRequest>;

    /// Creates a presigned request for deleting the object at the specified path.
    /// The request can be serialized, stored, and executed later.
    async fn presigned_delete(&self, path: &Path, expires_in: Duration)
        -> Result<PresignedRequest>;
}

/// A provider-backed key for small wrap and unwrap operations.
#[async_trait]
pub trait Key: Binding {
    async fn encrypt(
        &self,
        plaintext: &[u8],
        context: Option<&BTreeMap<String, String>>,
    ) -> Result<Vec<u8>>;

    async fn decrypt(
        &self,
        ciphertext: &[u8],
        context: Option<&BTreeMap<String, String>>,
    ) -> Result<Vec<u8>>;
}

/// A build binding that provides build execution capabilities.
#[async_trait]
pub trait Build: Binding {
    /// Starts a new build with the given configuration.
    /// Returns the build execution information.
    async fn start_build(&self, config: BuildConfig) -> Result<BuildExecution>;

    /// Gets the status of a specific build execution.
    async fn get_build_status(&self, build_id: &str) -> Result<BuildExecution>;

    /// Stops or cancels a running build.
    async fn stop_build(&self, build_id: &str) -> Result<()>;
}

/// AWS IAM Role service account information
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct AwsServiceAccountInfo {
    /// The IAM role name
    pub role_name: String,
    /// The IAM role ARN (for AssumeRole)
    pub role_arn: String,
}

/// GCP Service Account information
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct GcpServiceAccountInfo {
    /// The service account email (for impersonation)
    pub email: String,
    /// The service account unique ID
    pub unique_id: String,
}

/// Azure User-Assigned Managed Identity information
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct AzureServiceAccountInfo {
    /// The managed identity client ID (for authentication)
    pub client_id: String,
    /// The managed identity resource ID (ARM ID)
    pub resource_id: String,
    /// The managed identity principal ID
    pub principal_id: String,
}

/// Platform-specific service account information
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "platform", rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub enum ServiceAccountInfo {
    /// AWS IAM Role
    Aws(AwsServiceAccountInfo),
    /// GCP Service Account
    Gcp(GcpServiceAccountInfo),
    /// Azure User-Assigned Managed Identity
    Azure(AzureServiceAccountInfo),
}

/// Configuration for impersonation
#[derive(Debug, Clone)]
pub struct ImpersonationRequest {
    /// Optional session name (AWS only)
    pub session_name: Option<String>,
    /// Optional session duration in seconds
    pub duration_seconds: Option<i32>,
    /// Optional scopes (GCP only)
    pub scopes: Option<Vec<String>>,
}

impl Default for ImpersonationRequest {
    fn default() -> Self {
        Self {
            session_name: None,
            duration_seconds: Some(3600), // 1 hour default
            scopes: None,
        }
    }
}

/// A service account binding that provides identity and impersonation capabilities.
#[async_trait]
pub trait ServiceAccount: Binding {
    /// Gets information about the service account
    async fn get_info(&self) -> Result<ServiceAccountInfo>;

    /// Impersonates the service account and returns credentials as a ClientConfig.
    ///
    /// This performs the cloud-specific impersonation:
    /// - AWS: STS AssumeRole to get temporary credentials
    /// - GCP: IAM Credentials API generateAccessToken
    /// - Azure: Uses the attached managed identity (no API call needed)
    async fn impersonate(&self, request: ImpersonationRequest) -> Result<alien_core::ClientConfig>;

    /// Helper for downcasting trait object
    fn as_any(&self) -> &dyn std::any::Any;
}

/// Response from repository operations.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct RepositoryResponse {
    /// The **routable name** of the repository — the full, platform-specific
    /// path used for subsequent calls (`get_repository`, `delete_repository`,
    /// `generate_credentials`, `*_cross_account_access`).
    ///
    /// Per-platform format (matches
    /// `alien.dev/content/docs/infrastructure/artifact-registry/behavior.mdx`):
    ///
    /// | Platform | Format |
    /// |---|---|
    /// | AWS (ECR) | `{registry_prefix}-{logical}` (e.g. `alien-artifacts-my-app`) |
    /// | GCP (GAR) | `{project_id}/{gar_repo}/{logical}` |
    /// | Azure (ACR) | `{logical}` (used directly) |
    /// | Local | `{binding_name}/{logical}` |
    ///
    /// **Round-trip invariant:** callers MUST be able to pass this value back
    /// to any other method on the trait without further transformation.
    /// Implementations MUST NOT re-apply prefixing in receivers — assume
    /// `repo_id` arguments are already routable.
    pub name: String,
    /// Repository URI for pushing/pulling images. None if repository is not ready yet.
    pub uri: Option<String>,
    /// Optional creation timestamp in ISO8601 format.
    pub created_at: Option<String>,
}

/// Permissions level for artifact registry access.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub enum ArtifactRegistryPermissions {
    /// Pull-only access (download artifacts).
    Pull,
    /// Push and pull access (upload and download artifacts).
    PushPull,
}

/// How the registry expects credentials to be presented.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub enum RegistryAuthMethod {
    /// HTTP Basic auth (username:password). Used by ECR, GAR, Local.
    Basic,
    /// HTTP Bearer token. Used by ACR (Azure).
    Bearer,
}

/// Credentials for accessing a repository.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct ArtifactRegistryCredentials {
    /// How to present these credentials to the registry.
    pub auth_method: RegistryAuthMethod,
    /// Username for authentication (empty for Bearer auth).
    pub username: String,
    /// Password or token for authentication.
    pub password: String,
    /// Optional expiration time in ISO8601 format.
    pub expires_at: Option<String>,
}

/// Types of compute services that can access artifact registries.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub enum ComputeServiceType {
    /// Serverless functions
    Worker,
    // In the future, we could add Container, VirtualMachine, Kubernetes, etc.
}

/// Cross-account access configuration for AWS artifact registries.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct AwsCrossAccountAccess {
    /// AWS account IDs that should have cross-account access.
    pub account_ids: Vec<String>,
    /// AWS regions where the target Lambda functions run.
    /// Used to construct `aws:sourceArn` patterns for the Lambda service principal condition.
    pub regions: Vec<String>,
    /// Types of compute services that should have access.
    pub allowed_service_types: Vec<ComputeServiceType>,
    /// Specific IAM role ARNs to grant access to.
    /// These are typically deployment/management roles or service-specific roles.
    pub role_arns: Vec<String>,
}

/// Cross-account access configuration for GCP artifact registries.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct GcpCrossAccountAccess {
    /// GCP project numbers that should have access.
    pub project_numbers: Vec<String>,
    /// Types of compute services that should have access.
    pub allowed_service_types: Vec<ComputeServiceType>,
    /// Additional service account emails to grant access to.
    /// These are typically deployment/management service accounts.
    pub service_account_emails: Vec<String>,
}

/// Platform-specific cross-account access configuration.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "platform", rename_all = "lowercase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub enum CrossAccountAccess {
    /// AWS-specific cross-account access configuration.
    Aws(AwsCrossAccountAccess),
    /// GCP-specific cross-account access configuration.
    Gcp(GcpCrossAccountAccess),
}

/// Current cross-account access permissions for a repository.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct CrossAccountPermissions {
    /// Platform-specific access configuration currently applied.
    pub access: CrossAccountAccess,
    /// Timestamp when permissions were last updated.
    pub last_updated: Option<String>,
}

/// A trait for artifact registry bindings that provide container image repository management.
#[async_trait]
pub trait ArtifactRegistry: Binding {
    /// Returns the raw registry endpoint URL (e.g., "https://123456.dkr.ecr.us-east-1.amazonaws.com"
    /// or "http://localhost:5000"). Used by the push proxy to forward requests transparently.
    ///
    /// Default returns empty string — cloud provider implementations should override.
    fn registry_endpoint(&self) -> String {
        String::new()
    }

    /// Returns the OCI repository path prefix used for upstream operations.
    ///
    /// This identifier serves two related roles, both pointing at the same
    /// upstream location:
    ///
    /// 1. **Proxy routing.** When the push proxy forwards push/pull requests
    ///    to the upstream registry, this prefix is prepended to the image
    ///    name portion of the OCI path.
    /// 2. **Shared deployment-image repository name.** `alien release` pushes
    ///    every function image as `{prefix}:{logical}-{hash}` into one shared
    ///    repository whose routable name is exactly this prefix. Pass it as
    ///    `repo_id` when calling `add_cross_account_access` /
    ///    `remove_cross_account_access` for the deployment cross-account
    ///    flow.
    ///
    /// Examples:
    /// - ECR: `"alien-e2e"` — flat repo prefix; also the routable repo name
    ///   for the shared deployment-image repository
    /// - GAR: `"my-project/alien-e2e"` — project/repo structure
    /// - ACR: `"alien-e2e"` when configured, or `""` for registry-root
    ///   repositories; principal pull access is granted on the parent registry
    /// - Local: `"artifacts"` or similar — cross-account not supported
    ///
    /// An empty return value indicates the platform has no shared
    /// deployment-image repo at the binding level.
    ///
    /// Default returns empty string.
    fn upstream_repository_prefix(&self) -> String {
        String::new()
    }

    /// Creates a repository within the artifact registry.
    ///
    /// `repo_name` is the **logical** identifier the caller chose (e.g.
    /// `"my-app"`). The implementation transforms it to the routable
    /// platform-specific form before calling any backend API; what's
    /// returned in [`RepositoryResponse::name`] is the routable form.
    ///
    /// On platforms where image paths are implicit (GAR, ACR, Local),
    /// this may not call any backend API — but it still returns a valid
    /// routable name.
    async fn create_repository(&self, repo_name: &str) -> Result<RepositoryResponse>;

    /// Gets repository details. `repo_id` is the routable name returned by
    /// [`Self::create_repository`]; implementations MUST NOT re-apply
    /// prefixing.
    async fn get_repository(&self, repo_id: &str) -> Result<RepositoryResponse>;

    /// Adds cross-account access permissions for a repository.
    /// This adds the specified permissions to any existing cross-account permissions.
    ///
    /// `repo_id` is the routable name from [`Self::create_repository`].
    ///
    /// For AWS: grants access to specified account IDs with configurable principals and compute service types (ECR repository policy).
    /// For GCP: grants access to serverless robots and service accounts on the parent GAR registry (image-path-level IAM is not supported).
    /// For Azure: not supported — returns `OperationNotSupported`.
    async fn add_cross_account_access(
        &self,
        repo_id: &str,
        access: CrossAccountAccess,
    ) -> Result<()>;

    /// Removes cross-account access permissions for a repository.
    ///
    /// `repo_id` is the routable name from [`Self::create_repository`].
    ///
    /// For AWS: removes access from the ECR repository policy.
    /// For GCP: removes IAM bindings on the parent GAR registry.
    /// For Azure: not supported — returns `OperationNotSupported`.
    async fn remove_cross_account_access(
        &self,
        repo_id: &str,
        access: CrossAccountAccess,
    ) -> Result<()>;

    /// Gets the current cross-account access permissions for a repository.
    ///
    /// `repo_id` is the routable name from [`Self::create_repository`].
    /// For Azure: not supported — returns `OperationNotSupported`.
    async fn get_cross_account_access(&self, repo_id: &str) -> Result<CrossAccountPermissions>;

    /// Generates credentials for accessing a repository with the specified
    /// permissions.
    ///
    /// `repo_id` is the routable name from [`Self::create_repository`].
    ///
    /// Most platforms produce registry-scoped (not repo-scoped) credentials,
    /// so `repo_id` typically only affects logging — not the credentials
    /// themselves.
    async fn generate_credentials(
        &self,
        repo_id: &str,
        permissions: ArtifactRegistryPermissions,
        ttl_seconds: Option<u32>,
    ) -> Result<ArtifactRegistryCredentials>;

    /// Deletes a repository and all contained images.
    ///
    /// `repo_id` is the routable name from [`Self::create_repository`].
    /// Implementations MUST NOT delete the *parent* registry (which is owned
    /// by `alien-infra`); on platforms with implicit image paths (GAR, ACR,
    /// Local) this is a no-op.
    async fn delete_repository(&self, repo_id: &str) -> Result<()>;
}

/// A trait for vault bindings that provide secure secret management.
#[async_trait]
pub trait Vault: Binding {
    /// Gets a secret value by name.
    async fn get_secret(&self, secret_name: &str) -> Result<String>;

    /// Sets a secret value, creating it if it doesn't exist or updating it if it does.
    async fn set_secret(&self, secret_name: &str, value: &str) -> Result<()>;

    /// Deletes a secret by name.
    async fn delete_secret(&self, secret_name: &str) -> Result<()>;

    /// Lists the names of all secrets stored in this vault.
    ///
    /// Returned names are in the vault's own namespace (any provider-specific
    /// prefix is stripped), so each name can be passed straight back to
    /// [`Vault::get_secret`].
    ///
    /// Implementations backed by a flat namespace (a single string prefix
    /// with no reserved separator, e.g. `"{vault_prefix}-{secret_name}"`)
    /// cannot implement this safely with a prefix/`BeginsWith` scan: a vault
    /// named `"app"` would also match a sibling vault named `"app-prod"`,
    /// aliasing across vaults. Such providers should return
    /// `OperationNotSupported` rather than list under this hazard.
    async fn list_secrets(&self) -> Result<Vec<String>>;
}

/// TLS policy used when building a Postgres connection string.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SslMode {
    /// Plain TCP, no TLS (Local or an explicit BYO opt-out).
    Disable,
    /// Require TLS and verify the server certificate against a trusted CA.
    VerifyCa,
    /// Require TLS and verify both the trusted CA chain and the dialed hostname
    /// (BYO / External default, Aurora, and Flexible Server).
    VerifyFull,
}

impl SslMode {
    /// The `sslmode` query-parameter value, and the wire form embedders (the napi addon)
    /// hand to their own callers.
    pub fn as_str(self) -> &'static str {
        match self {
            SslMode::Disable => "disable",
            SslMode::VerifyCa => "verify-ca",
            SslMode::VerifyFull => "verify-full",
        }
    }
}

/// Invalid PEM roots supplied to a verified Postgres TLS policy.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct InvalidPostgresCaCertificates;

impl std::fmt::Display for InvalidPostgresCaCertificates {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("expected one or more non-empty PEM certificates")
    }
}

impl std::error::Error for InvalidPostgresCaCertificates {}

/// A complete Postgres TLS policy.
///
/// The fields are private so callers cannot pair plaintext with CA roots or construct
/// `verify-ca` without a root. Cloning the policy is cheap: certificate bundles are
/// reference-counted and copied only when crossing an FFI boundary.
#[derive(Clone, PartialEq, Eq)]
pub struct PostgresTlsPolicy {
    sslmode: SslMode,
    ca_certificates: Arc<[String]>,
}

impl std::fmt::Debug for PostgresTlsPolicy {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PostgresTlsPolicy")
            .field("sslmode", &self.sslmode)
            .field("ca_certificate_count", &self.ca_certificates.len())
            .finish()
    }
}

impl PostgresTlsPolicy {
    /// Plain TCP with no certificate roots.
    pub fn disabled() -> Self {
        Self {
            sslmode: SslMode::Disable,
            ca_certificates: Arc::default(),
        }
    }

    /// TLS with CA verification but no hostname verification.
    ///
    /// This mode requires at least one valid PEM root.
    pub fn verify_ca(
        ca_certificates: Vec<String>,
    ) -> std::result::Result<Self, InvalidPostgresCaCertificates> {
        Self::verified(SslMode::VerifyCa, ca_certificates, true)
    }

    /// TLS with CA and hostname verification.
    ///
    /// An empty root set intentionally selects the runtime's system trust store.
    pub fn verify_full(
        ca_certificates: Vec<String>,
    ) -> std::result::Result<Self, InvalidPostgresCaCertificates> {
        Self::verified(SslMode::VerifyFull, ca_certificates, false)
    }

    /// TLS with CA and hostname verification using the runtime's system trust store.
    pub fn verify_full_with_system_roots() -> Self {
        Self {
            sslmode: SslMode::VerifyFull,
            ca_certificates: Arc::default(),
        }
    }

    fn verified(
        sslmode: SslMode,
        ca_certificates: Vec<String>,
        require_roots: bool,
    ) -> std::result::Result<Self, InvalidPostgresCaCertificates> {
        if (require_roots && ca_certificates.is_empty())
            || ca_certificates.iter().any(|certificate| {
                let certificate = certificate.trim();
                !certificate.starts_with("-----BEGIN CERTIFICATE-----")
                    || !certificate.ends_with("-----END CERTIFICATE-----")
            })
        {
            return Err(InvalidPostgresCaCertificates);
        }

        Ok(Self {
            sslmode,
            ca_certificates: ca_certificates.into(),
        })
    }

    /// The libpq-compatible `sslmode` represented by this complete policy.
    pub fn sslmode(&self) -> SslMode {
        self.sslmode
    }

    /// PEM-encoded roots, or an empty slice when this policy uses no roots or the
    /// runtime's system trust store.
    pub fn ca_certificates(&self) -> &[String] {
        &self.ca_certificates
    }
}

/// Resolved connection details for a Postgres database.
#[derive(Clone)]
pub struct PostgresConnectionParams {
    pub host: String,
    pub port: u16,
    pub database: String,
    pub username: String,
    pub password: String,
    pub tls: PostgresTlsPolicy,
}

// Hand-written Debug so the resolved password never reaches logs, error chains, or panic output
// (`Binding`/`BindingsProviderApi` require Debug). Mirrors the KV providers' redacting Debug.
impl std::fmt::Debug for PostgresConnectionParams {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PostgresConnectionParams")
            .field("host", &self.host)
            .field("port", &self.port)
            .field("database", &self.database)
            .field("username", &self.username)
            .field("password", &"<redacted>")
            .field("tls", &self.tls)
            .finish()
    }
}

impl PostgresConnectionParams {
    /// Creates resolved connection details from a complete, internally consistent TLS
    /// policy.
    pub fn new(
        host: String,
        port: u16,
        database: String,
        username: String,
        password: String,
        tls: PostgresTlsPolicy,
    ) -> Self {
        Self {
            host,
            port,
            database,
            username,
            password,
            tls,
        }
    }

    /// The libpq-compatible TLS mode used by this connection.
    pub fn sslmode(&self) -> SslMode {
        self.tls.sslmode()
    }

    /// PEM-encoded root CA certificates.
    pub fn ca_certificates(&self) -> &[String] {
        self.tls.ca_certificates()
    }

    /// Builds a `postgres://` URL. Username and password are percent-encoded so a
    /// generated password containing URL-special characters can never corrupt it.
    pub fn connection_string(&self) -> String {
        format!(
            "postgres://{}:{}@{}:{}/{}?sslmode={}",
            encode_userinfo(&self.username),
            encode_userinfo(&self.password),
            self.host,
            self.port,
            // Encode the database path segment so this URL stays byte-identical to the TS
            // resolver's `encodeUserinfo` (the same RFC 3986 unreserved-set encoding).
            encode_userinfo(&self.database),
            self.sslmode().as_str(),
        )
    }
}

/// Percent-encodes a URL userinfo component; the RFC 3986 unreserved set passes through.
fn encode_userinfo(value: &str) -> String {
    let mut out = String::with_capacity(value.len());
    for byte in value.bytes() {
        match byte {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
                out.push(byte as char)
            }
            _ => out.push_str(&format!("%{:02X}", byte)),
        }
    }
    out
}

/// Connection-only Postgres binding. Unlike every other resource, Postgres ships no
/// gRPC service and wraps no operations (by design): every backend
/// speaks the same wire protocol, so the binding returns connection details and the
/// application uses its own driver.
pub trait Postgres: Binding {
    fn connection_params(&self) -> &PostgresConnectionParams;

    /// `postgres://` connection string, derived from `connection_params` and never stored.
    fn connection_string(&self) -> String {
        self.connection_params().connection_string()
    }
}

/// A precondition for a KV put operation.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub enum PutCondition {
    /// Replace any current value, or create the key when it is absent.
    #[default]
    None,
    /// Create the key only when it is absent or logically expired.
    Absent,
    /// Replace the value only when the key still has this opaque version.
    Version(String),
}

/// Options for KV put operations.
#[derive(Debug, Clone, Default)]
pub struct PutOptions {
    /// Optional TTL for automatic expiration (soft hint - items MAY be deleted after expiry)
    pub ttl: Option<Duration>,
    /// Optional atomic write precondition.
    pub condition: PutCondition,
}

/// A KV entry together with its opaque version.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KvEntry {
    /// Stored key.
    pub key: String,
    /// Stored value bytes.
    pub value: Vec<u8>,
    /// Provider-neutral version for conditional writes. Callers must treat it as opaque.
    pub version: String,
}

/// Represents the result of a scan operation.
#[derive(Debug)]
pub struct ScanResult {
    /// Entries found (may be ≤ limit, no guarantee to fill).
    pub items: Vec<KvEntry>,
    /// Opaque, prefix-bound cursor for pagination. None if the traversal is complete.
    /// A non-empty cursor may lead to an empty page when records expire between pages.
    pub next_cursor: Option<String>,
}

/// A trait for key-value store bindings that provide minimal, platform-agnostic KV operations.
/// This API is designed to work consistently across DynamoDB, Firestore, Azure Table Storage,
/// and the local provider.
#[async_trait]
pub trait Kv: Binding {
    /// Get an entry by key. Returns `None` if the key doesn't exist or has expired.
    ///
    /// **TTL Behavior**: TTL is a soft hint for automatic cleanup. If `now >= expires_at`,
    /// implementations SHOULD behave as if the key is absent, even if the item still exists
    /// physically in the backend. Physical deletion is eventual and not guaranteed.
    ///
    /// **Validation**: Keys are validated against MAX_KEY_BYTES and portable charset.
    /// Invalid keys return `KvError::InvalidKey` immediately.
    async fn get(&self, key: &str) -> Result<Option<KvEntry>>;

    /// Put a value with optional options. Conditional writes return `false` when their precondition
    /// does not match. Unconditional writes return `true`.
    ///
    /// **Size Limits**:
    /// - Keys: ≤ MAX_KEY_BYTES (512 bytes) with portable ASCII charset
    /// - Values: ≤ MAX_VALUE_BYTES (24,576 bytes = 24 KiB)
    ///
    /// **Validation**: Size and charset constraints are enforced before backend calls.
    /// Invalid inputs return `KvError::InvalidKey` or `KvError::InvalidValue` immediately.
    ///
    /// **TTL Behavior**: TTL is a soft hint for automatic cleanup. If TTL is specified,
    /// item expires at `put_time + ttl`. Expired items SHOULD appear absent on subsequent
    /// reads, but physical deletion is eventual and not guaranteed.
    ///
    /// **Conditional Logic**: [`PutCondition::Absent`] uses each backend's atomic create
    /// primitive, with a version-guarded takeover when an expired row still exists physically.
    /// [`PutCondition::Version`] uses DynamoDB conditions, Firestore update-time preconditions,
    /// Azure entity tags, or the local database's conditional update.
    async fn put(&self, key: &str, value: Vec<u8>, options: Option<PutOptions>) -> Result<bool>;

    /// Delete a key. No error if key doesn't exist.
    ///
    /// **Validation**: Keys are validated against MAX_KEY_BYTES and portable charset.
    /// Invalid keys return `KvError::InvalidKey` immediately.
    /// When `if_version` is supplied, delete only if the key still has that opaque version.
    /// Returns `false` when a conditional delete finds the key absent, expired, or changed.
    /// Unconditional deletes return `true`, including when the key is already absent.
    async fn delete(&self, key: &str, if_version: Option<&str>) -> Result<bool>;

    /// Check if a key exists without retrieving the value.
    ///
    /// **TTL Behavior**: TTL is a soft hint for automatic cleanup. If `now >= expires_at`,
    /// SHOULD return false even if physically present. Physical deletion is eventual and not guaranteed.
    ///
    /// **Validation**: Keys are validated against MAX_KEY_BYTES and portable charset.
    /// Invalid keys return `KvError::InvalidKey` immediately.
    async fn exists(&self, key: &str) -> Result<bool>;

    /// Scan keys with a prefix, with pagination support.
    ///
    /// **Scan Contract**:
    /// - Returns an **arbitrary, unordered subset** in backend-natural order
    /// - **No ordering guarantees** across backends (for example, Azure partition fan-out)
    /// - **May return ≤ limit items** (not guaranteed to fill even if more data exists)
    /// - **Clients MUST de-duplicate** keys across pages (backends may return duplicates)
    /// - **No completeness guarantee** under concurrent writes (may miss or duplicate)
    /// - Without concurrent changes, following every returned cursor until `None`
    ///   visits every matching, unexpired key visible to the backend
    ///
    /// **Cursor Behavior**:
    /// - Opaque string, implementation-specific format
    /// - Bound to the prefix that created it; using it with another prefix is invalid
    /// - May become invalid after backend state changes
    /// - **No TTL guarantees** - can expire without notice
    /// - Passing invalid cursor should return error, not partial results
    ///
    /// **TTL Behavior**: TTL is a soft hint for automatic cleanup. Expired items SHOULD
    /// be filtered out from results, but physical deletion is eventual and not guaranteed.
    ///
    /// **Validation**: Prefix follows same key validation rules.
    /// Invalid prefix returns `KvError::InvalidKey` immediately.
    async fn scan_prefix(
        &self,
        prefix: &str,
        limit: Option<usize>,
        cursor: Option<String>,
    ) -> Result<ScanResult>;
}

/// JSON/Text message payload for Queue
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "lowercase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub enum MessagePayload {
    /// JSON-serializable value
    Json(serde_json::Value),
    /// UTF-8 text payload
    Text(String),
}

/// A queue message with payload and receipt handle for acknowledgment
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct QueueMessage {
    /// JSON-first message payload
    pub payload: MessagePayload,
    /// Opaque receipt handle for acknowledgment (backend-specific, short-lived)
    pub receipt_handle: String,
    /// Delivery attempt for this message, 1-based (1 = first delivery).
    ///
    /// Providers that do not report redelivery counts always set 1; the local
    /// provider reports the real per-message count so handlers can enforce
    /// retry limits.
    #[serde(default = "first_attempt")]
    pub attempt: u32,
}

/// Serde default for [`QueueMessage::attempt`]: treat missing counts as the
/// first delivery.
fn first_attempt() -> u32 {
    1
}

/// Maximum message size in bytes (64 KiB = 65,536 bytes)
///
/// This limit ensures compatibility across all queue backends:
/// - **AWS SQS**: 256KB message limit (much higher, not constraining)
/// - **Azure Service Bus**: 1MB message limit (much higher, not constraining)
/// - **GCP Pub/Sub**: 10MB message limit (much higher, not constraining)
///
/// The 64KB limit provides:
/// - Reasonable message sizes for most use cases
/// - Fast network transfer and low latency
/// - Consistent behavior across all cloud providers
/// - Efficient memory usage during batch processing
pub const MAX_MESSAGE_BYTES: usize = 65_536; // 64 KiB

/// Maximum number of messages per receive call
///
/// This limit balances throughput with processing simplicity:
/// - **AWS SQS**: Supports up to 10 messages per ReceiveMessage call
/// - **Azure Service Bus**: Can receive multiple messages via prefetch/batching
/// - **GCP Pub/Sub**: Supports configurable max_messages per Pull request
///
/// The 10-message limit ensures:
/// - Portable batch sizes across all backends
/// - Manageable memory usage
/// - Reasonable processing latency per batch
pub const MAX_BATCH_SIZE: usize = 10;

/// Fixed lease duration in seconds
///
/// Messages are leased for exactly 30 seconds after delivery:
/// - Long enough for most processing tasks
/// - Short enough to enable fast retry on failures
/// - Eliminates complexity of dynamic lease management
/// - Consistent across all platforms
pub const LEASE_SECONDS: u64 = 30;

/// A trait for queue bindings providing minimal, portable queue operations.
#[async_trait]
pub trait Queue: Binding {
    /// Send a message to the specified queue
    async fn send(&self, queue: &str, message: MessagePayload) -> Result<()>;

    /// Receive up to `max_messages` (1..=10) from the specified queue
    async fn receive(&self, queue: &str, max_messages: usize) -> Result<Vec<QueueMessage>>;

    /// Acknowledge a message using its receipt handle (idempotent)
    async fn ack(&self, queue: &str, receipt_handle: &str) -> Result<()>;

    /// Negative-acknowledge a message: release its lease so it becomes
    /// immediately available for redelivery, without waiting out the
    /// visibility timeout. Receipt-handle rules mirror [`Queue::ack`].
    async fn nack(&self, queue: &str, receipt_handle: &str) -> Result<()>;

    /// Delete every message in the queue, whether visible or in flight.
    async fn purge(&self, queue: &str) -> Result<()>;
}

/// Request for invoking a function directly
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct WorkerInvokeRequest {
    /// Worker identifier (name, ARN, URL, etc.)
    pub target_worker: String,
    /// HTTP method
    pub method: String,
    /// Request path
    pub path: String,
    /// HTTP headers
    pub headers: BTreeMap<String, String>,
    /// Request body bytes
    pub body: Vec<u8>,
    /// Optional timeout for the invocation
    pub timeout: Option<Duration>,
}

/// Response from worker invocation.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct WorkerInvokeResponse {
    /// HTTP status code
    pub status: u16,
    /// HTTP response headers
    pub headers: BTreeMap<String, String>,
    /// Response body bytes
    pub body: Vec<u8>,
}

/// A trait for worker bindings that enable direct worker-to-worker calls.
#[async_trait]
pub trait Worker: Binding {
    /// Invoke a worker with HTTP request data.
    ///
    /// This enables direct, low-latency worker-to-worker communication within
    /// the same cloud environment, bypassing Commands for internal calls.
    ///
    /// Platform implementations:
    /// - AWS: Uses InvokeWorker API directly
    /// - GCP: Calls private service URL directly
    /// - Azure: Calls private container app URL directly
    /// - Kubernetes: HTTP call to internal service
    async fn invoke(&self, request: WorkerInvokeRequest) -> Result<WorkerInvokeResponse>;

    /// Get the public URL of the worker, if available.
    ///
    /// Returns the worker's public URL if it exists and is accessible.
    /// This is useful for exposing public endpoints or getting URLs for
    /// external integration.
    ///
    /// Platform implementations:
    /// - AWS: Uses GetWorkerUrlConfig API or returns URL from binding
    /// - GCP: Returns Cloud Run service URL or calls get_service API
    /// - Azure: Returns Container App URL or calls get_container_app API
    async fn get_worker_url(&self) -> Result<Option<String>>;

    /// Get a reference to this object as `Any` for dynamic casting
    fn as_any(&self) -> &dyn std::any::Any;
}

/// A trait for container bindings that enable container-to-container communication
#[async_trait]
pub trait Container: Binding {
    /// Get the internal URL for container-to-container communication.
    ///
    /// This returns the internal service discovery URL that other containers
    /// in the same network can use to communicate with this container.
    ///
    /// Platform implementations:
    /// - Managed cloud (AWS/GCP/Azure): Returns internal DNS URL (e.g., "http://api.svc:8080")
    /// - Local (Docker): Returns Docker network DNS URL (e.g., "http://api.svc:3000")
    fn get_internal_url(&self) -> &str;

    /// Get the public URL of the container, if available.
    ///
    /// Returns the container's public URL if it exists and is accessible
    /// from outside the cluster/network.
    ///
    /// Platform implementations:
    /// - Managed cloud: Returns load balancer URL if exposed publicly
    /// - Local: Returns localhost URL with mapped port (e.g., "http://localhost:62844")
    fn get_public_url(&self) -> Option<&str>;

    /// Get the container name/ID.
    fn get_container_name(&self) -> &str;

    /// Get a reference to this object as `Any` for dynamic casting
    fn as_any(&self) -> &dyn std::any::Any;
}

/// A request to create a sandbox.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct CreateSandboxRequest {
    /// Sandbox id to reconnect to, for the verbs that take one. AWS, Azure and GCP always
    /// allocate their own on `create` and ignore this; only Local and Kubernetes honor it as the
    /// new sandbox's id. Read the id back from the response rather than assume the one sent.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sandbox_id: Option<String>,
    /// Opaque tenant key. Never sent to a provider verbatim — the binding derives a
    /// fixed-length identifier from it with a deployment-scoped HMAC.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tenant_key: Option<String>,
    /// Environment variables to place in the sandbox.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub env: BTreeMap<String, String>,
    /// Wall-clock lifetime, after which the platform terminates the sandbox.
    ///
    /// Requires `sandboxLifetime`; a backend without it refuses rather than accepting a ceiling
    /// it would never apply. It only ever shortens: a declared ceiling still bounds the sandbox,
    /// so a caller cannot buy itself more life than the deployment allows.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout_ms: Option<u64>,
}

/// A live sandbox.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct SandboxInstance {
    /// Provider-scoped sandbox identifier
    pub sandbox_id: String,
    /// Current lifecycle state
    pub state: SandboxState,
    /// Lifecycle generation. A capability from another generation is rejected, which is how
    /// terminate revokes without distributing a revocation list.
    ///
    /// Differs by backend: AWS/Azure allocate a fresh id per sandbox, so a constant carries the
    /// whole meaning; GCP has none, so this is the guest's boot id — which a snapshot restore
    /// reports unchanged, so restore and replacement need the resource name too to tell apart.
    pub generation: u64,
}

/// A sandbox from `get_or_create`, and which of the two things happened.
///
/// A reconnect and a create are separate paths in every provider; `created` carries that
/// distinction out to the caller, which would otherwise make its own first-run work idempotent.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedSandbox {
    /// The sandbox, whether it was made here or found.
    pub sandbox: SandboxInstance,
    /// Whether this request is what created it.
    pub created: bool,
}

impl ResolvedSandbox {
    /// This request created the sandbox.
    pub fn created(sandbox: SandboxInstance) -> Self {
        Self {
            sandbox,
            created: true,
        }
    }

    /// An existing sandbox, whatever it took to reach it — a wait, a wake — but not made here.
    pub fn found(sandbox: SandboxInstance) -> Self {
        Self {
            sandbox,
            created: false,
        }
    }
}

/// Lifecycle state of a sandbox.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase")]
pub enum SandboxState {
    /// Created but not yet able to run a command.
    ///
    /// A real state, not a placeholder: a MicroVM takes seconds to reach `RUNNING`, and calling
    /// that Running would tell a caller to send commands to something that cannot answer.
    Starting,
    /// Executing, consuming CPU and memory
    Running,
    /// Paused with state preserved
    Paused,
    /// Terminated; the id will not run again
    Terminated,
}

/// A command to run inside a sandbox.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct RunCommandRequest {
    /// The program to run
    pub command: String,
    /// Arguments handed to the program, each as one argument — nothing re-parses their text
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub args: Vec<String>,
    /// Working directory inside the sandbox
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cwd: Option<String>,
    /// Environment overlaid on the sandbox's own
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub env: BTreeMap<String, String>,
    /// How long this command may run. Required — a defaulted timeout is a hang waiting for a slow
    /// day.
    ///
    /// `CreateSandboxRequest::timeout_ms` is an outer bound this timeout cannot see. Neither
    /// shortens the other, but on AWS and GCP the platform reaps the sandbox at its lifetime
    /// whatever is running inside: a command still going is cut off mid-flight and reports
    /// `SANDBOX_OUTCOME_UNKNOWN`, never `timeoutExceeded`, because nothing survived to say what it
    /// did. A lifetime has to leave room for the longest command it must cover.
    ///
    /// It bounds the command, not the call, and the call lands just after it. Where the agent
    /// supervises the process it kills the process group; where the data plane has no timeout of
    /// its own the command runs under `timeout` inside the sandbox. Either way the sandbox stays
    /// usable. Only a sandbox that cannot run `timeout` is ended instead, and that call returns
    /// once the sandbox is gone.
    ///
    /// On every backend `timeoutExceeded` is reported only once the command has verifiably
    /// stopped — the agent waits for its kill, and where there is no agent the sandbox kills the
    /// command itself and says so. It is never reported on a stop that was merely requested: a
    /// timeout that leaves untrusted code running is not a timeout.
    ///
    /// What stops is the command and its process group. A descendant that detaches itself into a
    /// session of its own is beyond any signal sent from inside, on every backend; it is bounded
    /// by the sandbox, which ends on terminate or at its own lifetime ceiling.
    pub timeout: Duration,
}

impl RunCommandRequest {
    /// The program followed by its arguments, which is the shape every backend's exec takes.
    pub fn argv(&self) -> Vec<String> {
        std::iter::once(self.command.clone())
            .chain(self.args.iter().cloned())
            .collect()
    }
}

/// One frame of a running command's output.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase", tag = "type")]
pub enum CommandOutput {
    /// Bytes written to stdout
    #[serde(rename_all = "camelCase")]
    Stdout {
        /// Monotonic across both streams, so a caller can interleave them in production order
        seq: u64,
        /// Raw bytes; command output is not necessarily UTF-8
        data: Vec<u8>,
    },
    /// Bytes written to stderr
    #[serde(rename_all = "camelCase")]
    Stderr {
        /// Monotonic across both streams
        seq: u64,
        /// Raw bytes
        data: Vec<u8>,
    },
    /// The command finished. Exactly one terminal frame is emitted, always last.
    #[serde(rename_all = "camelCase")]
    Exit {
        /// Process exit code
        code: i32,
        /// Set when output was cut short by a bound rather than by the command finishing
        #[serde(default)]
        truncated: bool,
    },
}

/// The id a started job answers to.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct JobStart {
    /// Identifier every later poll and cancel addresses
    pub job_id: String,
}

/// A job's output so far, and how it ended once it has.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct JobPoll {
    /// Whether the command is still running
    pub running: bool,
    /// Output produced after the polled sequence. The ending is `exit` or `error`, never a frame.
    pub frames: Vec<CommandOutput>,
    /// How the command exited, once it has
    #[serde(skip_serializing_if = "Option::is_none")]
    pub exit: Option<JobExit>,
    /// Why the command ended without exiting
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<JobError>,
}

/// How a job's command exited.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct JobExit {
    /// Process exit code
    pub code: i32,
    /// Set when output was cut short by a bound rather than by the command finishing
    #[serde(default)]
    pub truncated: bool,
}

/// Why a job ended without its command exiting.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct JobError {
    /// Machine-readable cause, e.g. `timeoutExceeded`
    pub code: String,
    /// Human-readable detail
    pub message: String,
}

/// An authenticated, port-scoped capability to reach a service inside a sandbox.
///
/// Not a URL string: AWS needs a JWE and a port header, Azure an Entra token, and a bare
/// string cannot carry either. Returning one would push callers into building the request
/// themselves and getting the auth wrong.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct PreviewCapability {
    /// Endpoint the request must be sent to
    pub endpoint: String,
    /// Headers that must accompany every request
    pub headers: BTreeMap<String, String>,
    /// Ports this capability admits. A request to any other port is refused upstream.
    pub allowed_ports: Vec<u16>,
    /// Seconds until the capability expires
    pub expires_in_seconds: u64,
}

/// A sandbox binding: create sandboxes, run untrusted code in them, and tear them down.
///
/// Capabilities differ per platform. Call `capabilities()` and branch, or call and handle the
/// typed error — an unsupported capability is never a silent no-op.
#[async_trait]
pub trait Sandbox: Binding {
    /// What this platform's backend supports.
    fn capabilities(&self) -> alien_core::SandboxCapabilities;

    /// Creates a sandbox that can already take work.
    ///
    /// Returning before the sandbox can serve pushes a readiness poll into every caller for a
    /// condition only the backend can observe, and the resulting race fails a fraction of the
    /// time rather than every time. A backend whose start API returns early waits here.
    async fn create(&self, request: CreateSandboxRequest) -> Result<SandboxInstance>;

    /// Fetches a sandbox by id, or `None` if it does not exist.
    ///
    /// Requires `reconnect`. `None` means the sandbox does not exist; a backend that cannot
    /// answer the question returns the typed error instead, so an absent sandbox and an
    /// unreachable one are never the same result.
    async fn get(&self, sandbox_id: &str) -> Result<Option<SandboxInstance>>;

    /// Fetches a sandbox, creating it if absent, and reports which it did.
    ///
    /// Answer `created` from the path taken, never from a timestamp: the clocks are the provider's,
    /// not ours. No backend offers an atomic create-if-absent, so two callers naming one id can
    /// both be told they created it; a caller that cannot tolerate its setup running twice needs
    /// its own lock.
    ///
    /// `timeoutMs` bounds a sandbox this call creates. No backend can move a running sandbox's
    /// deadline, so one that is found keeps the lifetime it was created with, and `created` is
    /// how a caller tells the two apart.
    async fn get_or_create(&self, request: CreateSandboxRequest) -> Result<ResolvedSandbox>;

    /// Lists the sandboxes belonging to this binding's parent.
    ///
    /// Offered only where the backend has a verb for it and the grant covers it — GCP lists
    /// under its engine. AWS and Azure raise `OperationNotSupported`: enumerating there costs an
    /// account-wide grant the sandbox role deliberately withholds. Reaching a known id is `get`.
    async fn list(&self) -> Result<Vec<SandboxInstance>>;

    /// Runs a command, streaming output frames until exactly one terminal frame.
    ///
    /// The stream carries backpressure: a consumer that stops reading stops the sandbox's
    /// writer, rather than buffering without bound.
    async fn run_command(
        &self,
        sandbox_id: &str,
        request: RunCommandRequest,
    ) -> Result<futures::stream::BoxStream<'static, Result<CommandOutput>>>;

    /// Starts a command as a job, which outlives the call that started it. Requires `jobs`.
    ///
    /// A start that goes unanswered is `SANDBOX_OUTCOME_UNKNOWN` and not retryable: the sandbox
    /// may have taken the command, and repeating it would run it twice.
    async fn start_job(&self, sandbox_id: &str, request: RunCommandRequest) -> Result<JobStart>;

    /// Reads a job's output after `since_seq`, and its ending once it has one. Requires `jobs`.
    ///
    /// `None` reads from the first frame. Repeating a poll costs nothing and changes nothing, so
    /// a sandbox that cannot be reached is `SANDBOX_UNREACHABLE` and retryable.
    async fn poll_job(
        &self,
        sandbox_id: &str,
        job_id: &str,
        since_seq: Option<u64>,
    ) -> Result<JobPoll>;

    /// Cancels a job, stopping its command. Requires `jobs`.
    ///
    /// Classified like `poll_job`: a cancel that is repeated stops nothing a second time.
    async fn cancel_job(&self, sandbox_id: &str, job_id: &str) -> Result<()>;

    /// Reads a file out of the sandbox. Requires `files`. Paths are normalised and may not
    /// escape the root.
    async fn read_file(&self, sandbox_id: &str, path: &str) -> Result<Vec<u8>>;

    /// Writes files into the sandbox. Requires `files`. Parent directories are created as needed.
    async fn write_files(&self, sandbox_id: &str, files: BTreeMap<String, Vec<u8>>) -> Result<()>;

    /// Mints a capability to reach a declared port. Requires `preview`.
    async fn preview(&self, sandbox_id: &str, port: u16) -> Result<PreviewCapability>;

    /// Pauses a sandbox, preserving state. Requires `pauseResume`.
    ///
    /// A command already running is frozen with the guest rather than drained or stopped, and its
    /// own deadline freezes with it, so nothing inside the sandbox will end it. A caller streaming
    /// that command's output is failed within a bound rather than held for the length of the pause.
    /// On Azure the in-guest deadline is what stops an overrunning command, so one frozen by the
    /// pause is ended by terminating the sandbox instead and a later `resume` finds nothing.
    async fn pause(&self, sandbox_id: &str) -> Result<()>;

    /// Resumes a paused sandbox. Requires `pauseResume`.
    async fn resume(&self, sandbox_id: &str) -> Result<()>;

    /// Captures full sandbox state and returns its identifier. Requires `snapshot`.
    async fn snapshot(&self, sandbox_id: &str) -> Result<String>;

    /// Terminates a sandbox. Idempotent: terminating an absent sandbox succeeds.
    async fn terminate(&self, sandbox_id: &str) -> Result<()>;

    /// Get a reference to this object as `Any` for dynamic casting
    fn as_any(&self) -> &dyn std::any::Any;
}

/// A provider must implement methods to load the various types of bindings
/// based on environment variables or other configuration sources.
#[async_trait]
pub trait BindingsProviderApi: Send + Sync + std::fmt::Debug {
    /// Given a binding identifier, builds a Storage implementation.
    async fn load_storage(&self, binding_name: &str) -> Result<Arc<dyn Storage>>;

    /// Given a binding identifier, builds a Key implementation.
    async fn load_key(&self, binding_name: &str) -> Result<Arc<dyn Key>> {
        Err(alien_error::AlienError::new(
            crate::error::ErrorData::OperationNotSupported {
                operation: "load_key".to_string(),
                reason: format!("Key resource '{binding_name}' is not supported by this provider"),
            },
        ))
    }

    /// Given a binding identifier, builds a Build implementation.
    async fn load_build(&self, binding_name: &str) -> Result<Arc<dyn Build>>;

    /// Given a binding identifier, builds an ArtifactRegistry implementation.
    async fn load_artifact_registry(&self, binding_name: &str)
        -> Result<Arc<dyn ArtifactRegistry>>;

    /// Given a binding identifier, builds a Vault implementation.
    async fn load_vault(&self, binding_name: &str) -> Result<Arc<dyn Vault>>;

    /// Given a binding identifier, builds a KV implementation.
    async fn load_kv(&self, binding_name: &str) -> Result<Arc<dyn Kv>>;

    /// Given a binding identifier, builds a Postgres implementation.
    ///
    /// Every backend is resolved here. Local and External carry their password inline;
    /// Aurora, Cloud SQL, and Azure Flexible Server carry only a locator for it and read
    /// the value from that cloud's secret store during this call, using the workload's own
    /// identity. Resolution happens once per load, so the returned handle is synchronous.
    async fn load_postgres(&self, binding_name: &str) -> Result<Arc<dyn Postgres>>;

    /// Given a binding identifier, builds a Queue implementation.
    async fn load_queue(&self, binding_name: &str) -> Result<Arc<dyn Queue>>;

    /// Given a binding identifier, builds a Worker implementation.
    async fn load_worker(&self, binding_name: &str) -> Result<Arc<dyn Worker>>;

    /// Given a binding identifier, builds a Container implementation.
    async fn load_container(&self, binding_name: &str) -> Result<Arc<dyn Container>>;

    /// Given a binding identifier, builds a ServiceAccount implementation.
    async fn load_service_account(&self, binding_name: &str) -> Result<Arc<dyn ServiceAccount>>;

    /// Given a binding identifier, builds a Sandbox implementation.
    async fn load_sandbox(&self, binding_name: &str) -> Result<Arc<dyn Sandbox>>;

    /// Runtime-only binding env vars (a local Postgres connection with its password, a local
    /// BYO-key AI binding) for the given resource — re-resolved on every (re)start so the secret
    /// reaches the worker process but is never written to persisted worker metadata. The resource
    /// type routes resolution to the right local source. Default `None`: cloud providers carry a
    /// secret locator (not a raw secret) and use the normal persisted path.
    async fn resolve_runtime_only_binding_env(
        &self,
        _binding_name: &str,
        _resource_type: &str,
    ) -> Result<Option<std::collections::HashMap<String, String>>> {
        Ok(None)
    }
}

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

    /// A field this struct does not know is a caller asking for something it will not get, and
    /// the field it would most want is the one that bounds the sandbox. Read as "absent",
    /// `timeoutMs` misspelled is an unbounded sandbox reported as a bounded one.
    #[test]
    fn a_create_request_refuses_a_field_it_does_not_know() {
        for body in [
            r#"{"sessionId":"s1"}"#,
            r#"{"timeoutMillis":60000}"#,
            r#"{"timeout_ms":60000}"#,
            r#"{"workingDirectory":"/work"}"#,
        ] {
            let error = serde_json::from_str::<CreateSandboxRequest>(body)
                .expect_err("a field the request does not declare must be refused, not dropped");
            assert!(
                error.to_string().contains("unknown field"),
                "{body} was refused for the wrong reason: {error}"
            );
        }
    }

    #[test]
    fn a_create_request_takes_every_field_it_declares() {
        let parsed: CreateSandboxRequest = serde_json::from_str(
            r#"{"sandboxId":"s1","tenantKey":"t","env":{"A":"b"},"timeoutMs":60000}"#,
        )
        .expect("the declared fields parse");

        assert_eq!(parsed.sandbox_id.as_deref(), Some("s1"));
        assert_eq!(parsed.tenant_key.as_deref(), Some("t"));
        assert_eq!(parsed.env.get("A").map(String::as_str), Some("b"));
        assert_eq!(parsed.timeout_ms, Some(60_000));
    }
}