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 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()
    }
}

/// Represents options for put operations in KV stores.
#[derive(Debug, Clone, Default)]
pub struct PutOptions {
    /// Optional TTL for automatic expiration (soft hint - items MAY be deleted after expiry)
    pub ttl: Option<Duration>,
    /// Only put if the key does not exist
    pub if_not_exists: bool,
}

/// Represents the result of a scan operation.
#[derive(Debug)]
pub struct ScanResult {
    /// Key-value pairs found (may be ≤ limit, no guarantee to fill)
    pub items: Vec<(String, Vec<u8>)>,
    /// Opaque cursor for pagination. None if no more results.
    /// **Warning**: Cursor may become invalid if data changes. No TTL guarantees.
    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, Redis, and Azure Table Storage.
#[async_trait]
pub trait Kv: Binding {
    /// Get a value by key. Returns None if 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<Vec<u8>>>;

    /// Put a value with optional options. When options.if_not_exists is true, returns true if created,
    /// false if already exists. When options.if_not_exists is false or options is None, always returns 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**: The if_not_exists operation maps to backend primitives:
    /// - Redis: SETNX
    /// - DynamoDB: PutItem with condition_expression="attribute_not_exists(pk)"
    /// - Firestore: create() with Precondition::DoesNotExist
    /// - Azure Table Storage: InsertEntity (409 on conflict)
    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.
    async fn delete(&self, key: &str) -> Result<()>;

    /// 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 (Redis SCAN, Azure fan-out, etc.)
    /// - **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)
    ///
    /// **Cursor Behavior**:
    /// - Opaque string, implementation-specific format
    /// - **May become invalid** anytime 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 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 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>>;

    /// 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)
    }
}