prvng_kcl/modes.k

# Info: KCL execution mode schemas for provisioning
# Author: Mode System Implementation
# Release: 1.0.0
# Date: 2025-10-06

"""
Execution mode schemas defining deployment patterns and service configurations

Modes:
  - solo: Single developer, local development
  - multi-user: Team collaboration with shared services
  - cicd: CI/CD pipeline execution
  - enterprise: Production enterprise deployment
"""

import provisioning.settings as cfg
import provisioning.kcl.oci_registry as oci

schema ExecutionMode:
    """
    Base execution mode schema defining common configuration

    All execution modes inherit from this base schema and must
    specify service deployment strategy, authentication, and
    workspace policies.
    """

    # Mode identifier
    mode_name: "solo" | "multi-user" | "cicd" | "enterprise"

    # Human-readable description
    description: str

    # Authentication strategy
    authentication: AuthenticationStrategy

    # Service deployment configurations
    services: ServiceDeployments

    # Extension source configuration
    extensions: ExtensionConfig

    # Workspace management policies
    workspaces: WorkspacePolicy

    # Security configuration
    security: SecurityConfig

    # Resource limits (optional, for multi-user/enterprise)
    resource_limits?: ResourceLimits

    check:
        len(description) > 0, "Mode description required"

schema AuthenticationStrategy:
    """Authentication configuration for mode"""

    # Authentication type
    auth_type: "none" | "token" | "mtls" | "oauth" | "kms"

    # Token configuration (for token auth)
    token_config?: TokenConfig

    # mTLS configuration (for mtls auth)
    mtls_config?: MTLSConfig

    # OAuth configuration (for oauth auth)
    oauth_config?: OAuthConfig

    # SSH key storage location
    ssh_key_storage: "local" | "kms" | "vault" = "local"

    check:
        auth_type == "none" or (
            (auth_type == "token" and token_config != Undefined) or
            (auth_type == "mtls" and mtls_config != Undefined) or
            (auth_type == "oauth" and oauth_config != Undefined) or
            (auth_type == "kms")
        ), "Auth config must match auth type"

schema TokenConfig:
    """Token-based authentication configuration"""

    token_path: str
    token_format: "jwt" | "opaque" = "jwt"
    expiry_seconds: int = 86400  # 24 hours
    refresh_enabled: bool = True

    check:
        len(token_path) > 0, "Token path required"
        expiry_seconds > 0, "Expiry must be positive"

schema MTLSConfig:
    """Mutual TLS authentication configuration"""

    client_cert_path: str
    client_key_path: str
    ca_cert_path: str
    verify_server: bool = True

    check:
        len(client_cert_path) > 0, "Client cert path required"
        len(client_key_path) > 0, "Client key path required"
        len(ca_cert_path) > 0, "CA cert path required"

schema OAuthConfig:
    """OAuth 2.0 authentication configuration"""

    provider_url: str
    client_id: str
    client_secret_path: str
    scopes: [str] = ["read", "write"]
    redirect_uri?: str

    check:
        len(provider_url) > 0, "Provider URL required"
        len(client_id) > 0, "Client ID required"

schema ServiceDeployments:
    """Service deployment configuration"""

    orchestrator: ServiceConfig
    control_center?: ServiceConfig
    coredns?: ServiceConfig
    gitea?: ServiceConfig
    oci_registry: oci.OCIRegistryConfig

    # Custom services
    custom_services?: {str: ServiceConfig}

schema ServiceConfig:
    """Individual service configuration"""

    # Deployment location
    deployment: "local" | "remote" | "k8s" | "disabled"

    # For local deployment
    local_config?: LocalServiceConfig

    # For remote deployment
    remote_config?: RemoteServiceConfig

    # For Kubernetes deployment
    k8s_config?: K8sServiceConfig

    # Auto-start service
    auto_start: bool = False

    # Health check configuration
    health_check?: HealthCheck

    check:
        deployment == "disabled" or (
            (deployment == "local" and local_config != Undefined) or
            (deployment == "remote" and remote_config != Undefined) or
            (deployment == "k8s" and k8s_config != Undefined)
        ), "Service config must match deployment type"

schema LocalServiceConfig:
    """Local service deployment configuration"""

    binary_path?: str
    config_path?: str
    data_dir: str
    port: int
    bind_address: str = "127.0.0.1"
    tls_enabled: bool = False

    check:
        port > 0 and port < 65536, "Port must be 1-65535"
        len(data_dir) > 0, "Data directory required"

schema RemoteServiceConfig:
    """Remote service configuration"""

    endpoint: str
    port?: int
    tls_enabled: bool = True
    verify_ssl: bool = True
    timeout: int = 30
    retries: int = 3

    check:
        len(endpoint) > 0, "Endpoint required"
        timeout > 0, "Timeout must be positive"

schema K8sServiceConfig:
    """Kubernetes service deployment configuration"""

    namespace: str = "provisioning"
    deployment_name: str
    service_name: str
    replicas: int = 1
    image: str
    image_pull_policy: "Always" | "IfNotPresent" | "Never" = "IfNotPresent"
    resources?: K8sResources

    check:
        len(namespace) > 0, "Namespace required"
        len(deployment_name) > 0, "Deployment name required"
        replicas > 0, "Replicas must be positive"

schema K8sResources:
    """Kubernetes resource requirements"""

    cpu_request: str = "100m"
    cpu_limit: str = "500m"
    memory_request: str = "128Mi"
    memory_limit: str = "512Mi"

schema HealthCheck:
    """Service health check configuration"""

    enabled: bool = True
    endpoint: str = "/health"
    interval: int = 10  # seconds
    timeout: int = 5
    healthy_threshold: int = 2
    unhealthy_threshold: int = 3

    check:
        interval > 0, "Interval must be positive"
        timeout > 0 and timeout < interval, "Timeout must be less than interval"

schema ExtensionConfig:
    """Extension source and distribution configuration"""

    # Extension source: local files, gitea, or OCI registry
    source: "local" | "gitea" | "oci" | "mixed"

    # Local path for extensions (for local source)
    local_path?: str

    # Gitea configuration (for gitea source)
    gitea_config?: GiteaConfig

    # OCI registry configuration (for oci source)
    oci_registry?: OCIExtensionConfig

    # Allow mixed sources
    allow_mixed: bool = False

    check:
        source == "local" and local_path != Undefined or
        source == "gitea" and gitea_config != Undefined or
        source == "oci" and oci_registry != Undefined or
        source == "mixed", "Extension config must match source type"

schema GiteaConfig:
    """Gitea extension repository configuration"""

    url: str
    organization: str = "provisioning"
    username?: str
    token_path?: str
    verify_ssl: bool = True

    check:
        len(url) > 0, "Gitea URL required"

schema OCIExtensionConfig:
    """OCI registry extension configuration"""

    enabled: bool = True
    endpoint: str
    namespace: str = "provisioning-extensions"
    auth_token_path?: str
    tls_enabled: bool = True
    verify_ssl: bool = True
    cache_dir: str = "~/.provisioning/oci-cache"

    check:
        len(endpoint) > 0, "OCI endpoint required"
        len(namespace) > 0, "OCI namespace required"

schema WorkspacePolicy:
    """Workspace management policies"""

    # Workspace locking
    locking: "disabled" | "enabled" | "required"

    # Lock provider (if locking enabled)
    lock_provider?: "gitea" | "etcd" | "redis" | "filesystem"

    # Git integration requirement
    git_integration: "disabled" | "optional" | "required"

    # Workspace isolation
    isolation: "none" | "user" | "strict" = "user"

    # Maximum concurrent workspaces per user
    max_workspaces_per_user?: int

    check:
        locking == "disabled" or lock_provider != Undefined, \
            "Lock provider required when locking enabled"
        git_integration in ["disabled", "optional", "required"], \
            "Invalid git integration setting"

schema SecurityConfig:
    """Security policies for mode"""

    # Encryption requirements
    encryption_at_rest: bool = False
    encryption_in_transit: bool = False

    # Secret management
    secret_provider: cfg.SecretProvider = cfg.SecretProvider {}

    # DNS modification policy
    dns_modification: "none" | "coredns" | "system" = "none"

    # Audit logging
    audit_logging: bool = False
    audit_log_path?: str

    # Network policies
    network_isolation: bool = False

    check:
        not audit_logging or audit_log_path != Undefined, \
            "Audit log path required when audit logging enabled"

schema ResourceLimits:
    """Resource limits for multi-user/enterprise modes"""

    # Per-user limits
    max_servers_per_user: int = 10
    max_cpu_cores_per_user: int = 32
    max_memory_gb_per_user: int = 128
    max_storage_gb_per_user: int = 500

    # Global limits
    max_total_servers?: int
    max_total_cpu_cores?: int
    max_total_memory_gb?: int

    check:
        max_servers_per_user > 0, "Max servers must be positive"
        max_cpu_cores_per_user > 0, "Max CPU must be positive"
        max_memory_gb_per_user > 0, "Max memory must be positive"

# ============================================================================
# Concrete Mode Schemas
# ============================================================================

schema SoloMode(ExecutionMode):
    """
    Solo mode: Single developer local development

    Characteristics:
      - No authentication required
      - Local service deployment
      - Optional OCI registry for extension testing
      - No workspace locking
      - Minimal security constraints

    Example:
        SoloMode {
            mode_name = "solo"
            description = "Local development environment"
        }
    """

    mode_name: "solo" = "solo"
    description: str = "Single developer local development mode"

    authentication: AuthenticationStrategy = AuthenticationStrategy {
        auth_type = "none"
        ssh_key_storage = "local"
    }

    services: ServiceDeployments = ServiceDeployments {
        orchestrator = ServiceConfig {
            deployment = "local"
            auto_start = True
            local_config = LocalServiceConfig {
                data_dir = "~/.provisioning/orchestrator"
                port = 8080
            }
        }
        control_center = ServiceConfig {
            deployment = "disabled"
        }
        coredns = ServiceConfig {
            deployment = "disabled"
        }
        gitea = ServiceConfig {
            deployment = "disabled"
        }
        oci_registry = oci.OCIRegistryConfig {
            deployment = "local"
            type = "zot"
            endpoint = "localhost"
            port = 5000
            tls_enabled = False
            auth_required = False
            local = oci.LocalOCIConfig {
                data_dir = "~/.provisioning/oci-registry"
                config_path = "~/.provisioning/oci-registry/config.json"
                auto_start = False
            }
            namespaces = oci.OCINamespaces {
                extensions = "dev-extensions"
                kcl_packages = "dev-kcl"
                platform_images = "dev-platform"
                test_images = "dev-test"
            }
        }
    }

    extensions: ExtensionConfig = ExtensionConfig {
        source = "local"
        local_path = "./provisioning/extensions"
        allow_mixed = True
    }

    workspaces: WorkspacePolicy = WorkspacePolicy {
        locking = "disabled"
        git_integration = "optional"
        isolation = "none"
    }

    security: SecurityConfig = SecurityConfig {
        encryption_at_rest = False
        encryption_in_transit = False
        dns_modification = "none"
        audit_logging = False
        network_isolation = False
    }

schema MultiUserMode(ExecutionMode):
    """
    Multi-user mode: Team collaboration with shared services

    Characteristics:
      - Token-based authentication
      - Remote shared services
      - OCI registry for extension distribution
      - Workspace locking enabled
      - Git integration required
      - User resource limits

    Example:
        MultiUserMode {
            mode_name = "multi-user"
            description = "Team collaboration environment"
        }
    """

    mode_name: "multi-user" = "multi-user"
    description: str = "Team collaboration with shared services"

    authentication: AuthenticationStrategy = AuthenticationStrategy {
        auth_type = "token"
        token_config = TokenConfig {
            token_path = "~/.provisioning/tokens/auth"
            token_format = "jwt"
            expiry_seconds = 86400
            refresh_enabled = True
        }
        ssh_key_storage = "local"
    }

    services: ServiceDeployments = ServiceDeployments {
        orchestrator = ServiceConfig {
            deployment = "remote"
            remote_config = RemoteServiceConfig {
                endpoint = "orchestrator.company.local"
                port = 8080
                tls_enabled = True
                verify_ssl = True
                timeout = 30
                retries = 3
            }
        }
        control_center = ServiceConfig {
            deployment = "remote"
            remote_config = RemoteServiceConfig {
                endpoint = "control.company.local"
                port = 8081
                tls_enabled = True
            }
        }
        coredns = ServiceConfig {
            deployment = "remote"
            remote_config = RemoteServiceConfig {
                endpoint = "dns.company.local"
                port = 53
                tls_enabled = False
            }
        }
        gitea = ServiceConfig {
            deployment = "remote"
            remote_config = RemoteServiceConfig {
                endpoint = "git.company.local"
                port = 443
                tls_enabled = True
            }
        }
        oci_registry = oci.OCIRegistryConfig {
            deployment = "remote"
            type = "harbor"
            endpoint = "harbor.company.local"
            tls_enabled = True
            auth_required = True
            remote = oci.RemoteOCIConfig {
                timeout = 30
                retries = 3
                verify_ssl = True
            }
            namespaces = oci.OCINamespaces {
                extensions = "provisioning-extensions"
                kcl_packages = "provisioning-kcl"
                platform_images = "provisioning-platform"
                test_images = "provisioning-test"
            }
        }
    }

    extensions: ExtensionConfig = ExtensionConfig {
        source = "oci"
        oci_registry = OCIExtensionConfig {
            enabled = True
            endpoint = "harbor.company.local"
            namespace = "provisioning-extensions"
            auth_token_path = "~/.provisioning/tokens/oci"
            tls_enabled = True
            verify_ssl = True
            cache_dir = "~/.provisioning/oci-cache"
        }
    }

    workspaces: WorkspacePolicy = WorkspacePolicy {
        locking = "enabled"
        lock_provider = "gitea"
        git_integration = "required"
        isolation = "user"
        max_workspaces_per_user = 5
    }

    security: SecurityConfig = SecurityConfig {
        encryption_at_rest = False
        encryption_in_transit = True
        dns_modification = "coredns"
        audit_logging = True
        audit_log_path = "/var/log/provisioning/audit.log"
        network_isolation = False
    }

    resource_limits: ResourceLimits = ResourceLimits {
        max_servers_per_user = 10
        max_cpu_cores_per_user = 32
        max_memory_gb_per_user = 128
        max_storage_gb_per_user = 500
        max_total_servers = 100
        max_total_cpu_cores = 320
        max_total_memory_gb = 1024
    }

schema CICDMode(ExecutionMode):
    """
    CI/CD mode: Automated pipeline execution

    Characteristics:
      - Token or mTLS authentication
      - Remote service endpoints
      - OCI registry for artifacts
      - No workspace locking (stateless)
      - Git integration required
      - Ephemeral workspaces

    Example:
        CICDMode {
            mode_name = "cicd"
            description = "CI/CD pipeline environment"
        }
    """

    mode_name: "cicd" = "cicd"
    description: str = "CI/CD pipeline automated execution"

    authentication: AuthenticationStrategy = AuthenticationStrategy {
        auth_type = "token"
        token_config = TokenConfig {
            token_path = "/var/run/secrets/provisioning/token"
            token_format = "jwt"
            expiry_seconds = 3600  # 1 hour
            refresh_enabled = False
        }
        ssh_key_storage = "kms"
    }

    services: ServiceDeployments = ServiceDeployments {
        orchestrator = ServiceConfig {
            deployment = "remote"
            remote_config = RemoteServiceConfig {
                endpoint = "orchestrator.cicd.local"
                port = 8080
                tls_enabled = True
                verify_ssl = True
                timeout = 60
                retries = 5
            }
        }
        control_center = ServiceConfig {
            deployment = "disabled"
        }
        coredns = ServiceConfig {
            deployment = "remote"
            remote_config = RemoteServiceConfig {
                endpoint = "dns.cicd.local"
                port = 53
            }
        }
        gitea = ServiceConfig {
            deployment = "remote"
            remote_config = RemoteServiceConfig {
                endpoint = "git.cicd.local"
                port = 443
                tls_enabled = True
            }
        }
        oci_registry = oci.OCIRegistryConfig {
            deployment = "remote"
            type = "harbor"
            endpoint = "registry.cicd.local"
            tls_enabled = True
            auth_required = True
            remote = oci.RemoteOCIConfig {
                timeout = 60
                retries = 5
                verify_ssl = True
            }
            namespaces = oci.OCINamespaces {
                extensions = "cicd-extensions"
                kcl_packages = "cicd-kcl"
                platform_images = "cicd-platform"
                test_images = "cicd-test"
            }
        }
    }

    extensions: ExtensionConfig = ExtensionConfig {
        source = "oci"
        oci_registry = OCIExtensionConfig {
            enabled = True
            endpoint = "registry.cicd.local"
            namespace = "cicd-extensions"
            auth_token_path = "/var/run/secrets/provisioning/oci-token"
            tls_enabled = True
            verify_ssl = True
            cache_dir = "/tmp/provisioning-oci-cache"
        }
    }

    workspaces: WorkspacePolicy = WorkspacePolicy {
        locking = "disabled"
        git_integration = "required"
        isolation = "strict"
        max_workspaces_per_user = 1
    }

    security: SecurityConfig = SecurityConfig {
        encryption_at_rest = True
        encryption_in_transit = True
        dns_modification = "coredns"
        audit_logging = True
        audit_log_path = "/var/log/provisioning/cicd-audit.log"
        network_isolation = True
    }

    resource_limits: ResourceLimits = ResourceLimits {
        max_servers_per_user = 5
        max_cpu_cores_per_user = 16
        max_memory_gb_per_user = 64
        max_storage_gb_per_user = 200
    }

schema EnterpriseMode(ExecutionMode):
    """
    Enterprise mode: Production enterprise deployment

    Characteristics:
      - mTLS or OAuth authentication
      - Kubernetes-deployed services
      - Enterprise OCI registry (Harbor HA)
      - Workspace locking required
      - Git integration required
      - Full encryption and auditing
      - Strict resource limits

    Example:
        EnterpriseMode {
            mode_name = "enterprise"
            description = "Production enterprise environment"
        }
    """

    mode_name: "enterprise" = "enterprise"
    description: str = "Production enterprise deployment with full security"

    authentication: AuthenticationStrategy = AuthenticationStrategy {
        auth_type = "mtls"
        mtls_config = MTLSConfig {
            client_cert_path = "/etc/provisioning/certs/client.crt"
            client_key_path = "/etc/provisioning/certs/client.key"
            ca_cert_path = "/etc/provisioning/certs/ca.crt"
            verify_server = True
        }
        ssh_key_storage = "kms"
    }

    services: ServiceDeployments = ServiceDeployments {
        orchestrator = ServiceConfig {
            deployment = "k8s"
            k8s_config = K8sServiceConfig {
                namespace = "provisioning-system"
                deployment_name = "orchestrator"
                service_name = "orchestrator-svc"
                replicas = 3
                image = "harbor.enterprise.local/provisioning/orchestrator:latest"
                resources = K8sResources {
                    cpu_request = "500m"
                    cpu_limit = "2000m"
                    memory_request = "1Gi"
                    memory_limit = "4Gi"
                }
            }
        }
        control_center = ServiceConfig {
            deployment = "k8s"
            k8s_config = K8sServiceConfig {
                namespace = "provisioning-system"
                deployment_name = "control-center"
                service_name = "control-center-svc"
                replicas = 2
                image = "harbor.enterprise.local/provisioning/control-center:latest"
            }
        }
        coredns = ServiceConfig {
            deployment = "k8s"
            k8s_config = K8sServiceConfig {
                namespace = "kube-system"
                deployment_name = "coredns"
                service_name = "kube-dns"
                replicas = 2
                image = "registry.k8s.io/coredns/coredns:latest"
            }
        }
        gitea = ServiceConfig {
            deployment = "k8s"
            k8s_config = K8sServiceConfig {
                namespace = "provisioning-system"
                deployment_name = "gitea"
                service_name = "gitea-svc"
                replicas = 2
                image = "gitea/gitea:latest"
            }
        }
        oci_registry = oci.OCIRegistryConfig {
            deployment = "remote"
            type = "harbor"
            endpoint = "harbor.enterprise.local"
            tls_enabled = True
            auth_required = True
            remote = oci.RemoteOCIConfig {
                timeout = 60
                retries = 5
                verify_ssl = True
            }
            namespaces = oci.OCINamespaces {
                extensions = "prod-extensions"
                kcl_packages = "prod-kcl"
                platform_images = "prod-platform"
                test_images = "test-images"
            }
        }
    }

    extensions: ExtensionConfig = ExtensionConfig {
        source = "oci"
        oci_registry = OCIExtensionConfig {
            enabled = True
            endpoint = "harbor.enterprise.local"
            namespace = "prod-extensions"
            auth_token_path = "/etc/provisioning/tokens/oci"
            tls_enabled = True
            verify_ssl = True
            cache_dir = "/var/cache/provisioning/oci"
        }
    }

    workspaces: WorkspacePolicy = WorkspacePolicy {
        locking = "required"
        lock_provider = "etcd"
        git_integration = "required"
        isolation = "strict"
        max_workspaces_per_user = 3
    }

    security: SecurityConfig = SecurityConfig {
        encryption_at_rest = True
        encryption_in_transit = True
        secret_provider = cfg.SecretProvider {
            provider = "kms"
            kms_config = cfg.KmsConfig {
                server_url = "https://kms.enterprise.local"
                auth_method = "certificate"
                client_cert_path = "/etc/provisioning/certs/kms-client.crt"
                client_key_path = "/etc/provisioning/certs/kms-client.key"
                ca_cert_path = "/etc/provisioning/certs/kms-ca.crt"
                verify_ssl = True
            }
        }
        dns_modification = "system"
        audit_logging = True
        audit_log_path = "/var/log/provisioning/enterprise-audit.log"
        network_isolation = True
    }

    resource_limits: ResourceLimits = ResourceLimits {
        max_servers_per_user = 20
        max_cpu_cores_per_user = 64
        max_memory_gb_per_user = 256
        max_storage_gb_per_user = 1000
        max_total_servers = 500
        max_total_cpu_cores = 2000
        max_total_memory_gb = 8192
    }