prvng_kcl/dependencies.k

"""
KCL Dependency Management Schema for Provisioning System
Provides type-safe dependency declarations with resource requirements and health checks
"""

schema ResourceRequirement:
    """Resource requirements for taskserv installation and operation"""
    # CPU requirement (K8s format)
    cpu?: str = "100m"
    # Memory requirement (K8s format)
    memory?: str = "128Mi"
    # Disk space requirement
    disk?: str = "1Gi"
    # Requires network connectivity
    network?: bool = True
    # Requires privileged access
    privileged?: bool = False

    check:
        len(cpu) > 0, "CPU requirement cannot be empty"
        len(memory) > 0, "Memory requirement cannot be empty"
        len(disk) > 0, "Disk requirement cannot be empty"

schema HealthCheck:
    """Health check definition for taskserv validation"""
    # Command to execute for health check
    command: str
    # Check interval in seconds
    interval?: int = 30
    # Command timeout in seconds
    timeout?: int = 10
    # Number of retry attempts
    retries?: int = 3
    # Consecutive successes needed
    success_threshold?: int = 1
    # Consecutive failures to mark unhealthy
    failure_threshold?: int = 3

    check:
        len(command) > 0, "Health check command cannot be empty"
        interval > 0, "Health check interval must be positive"
        timeout > 0, "Health check timeout must be positive"
        retries >= 0, "Health check retries cannot be negative"

schema InstallationPhase:
    """Installation phase definition for ordered deployment"""
    # Phase name (e.g., "pre-install", "install", "post-install")
    name: str
    # Execution order within phase (lower first)
    order: int
    # Can run in parallel with same order
    parallel?: bool = False
    # Phase is required for successful installation
    required?: bool = True

    check:
        len(name) > 0, "Installation phase name cannot be empty"
        order >= 0, "Installation phase order cannot be negative"
        name in ["pre-install", "install", "post-install", "validate", "cleanup"], "Phase name must be one of: pre-install, install, post-install, validate, cleanup"

schema TaskservDependencies:
    """Complete dependency configuration for a taskserv"""
    # Taskserv name (must match directory)
    name: str

    # Dependency relationships
    # Required taskservs (must be installed first)
    requires?: [str]
    # Conflicting taskservs (cannot coexist)
    conflicts?: [str]
    # Optional taskservs (install if available)
    optional?: [str]
    # Services this taskserv provides
    provides?: [str]
    # Resource requirements
    # Resource requirements for installation
    resources: ResourceRequirement

    # Health and validation
    # Health check definitions
    health_checks?: [HealthCheck]
    # Readiness check for installation completion
    readiness_probe?: HealthCheck
    # Installation control
    # Installation phase definitions
    phases?: [InstallationPhase]
    # Installation timeout in seconds
    timeout?: int = 600
    # Number of installation retry attempts
    retry_count?: int = 3
    # Compatibility
    # Supported operating systems
    os_support?: [str] = ["linux"]
    # Supported CPU architectures
    arch_support?: [str] = ["amd64"]
    # Compatible Kubernetes versions
    k8s_versions?: [str]

    check:
        len(name) > 0, "Taskserv name cannot be empty"
        name == name.lower(), "Taskserv name must be lowercase"
        timeout > 0, "Installation timeout must be positive"
        retry_count >= 0, "Retry count cannot be negative"
        len(os_support) > 0, "Must specify at least one supported OS"
        len(arch_support) > 0, "Must specify at least one supported architecture"

# Re-export for taskserv use
schema TaskservDependency(TaskservDependencies):
    """Alias for TaskservDependencies - provides the same functionality"""

# OCI Registry Integration Schemas

schema OCISource:
    """OCI registry configuration for extension distribution"""
    # OCI registry endpoint (localhost:5000, harbor.company.com)
    registry: str
    # Namespace in registry (provisioning-extensions, provisioning-platform)
    namespace: str
    # Path to authentication token file
    auth_token_path?: str
    # Enable TLS for registry connection
    tls_enabled: bool = False
    # Skip TLS certificate verification (insecure, dev only)
    insecure_skip_verify: bool = False
    # OCI platform architecture
    platform: str = "linux/amd64"
    # Media type for KCL packages
    media_type: str = "application/vnd.kcl.package.v1+tar"

    check:
        len(registry) > 0, "OCI registry endpoint required"
        len(namespace) > 0, "OCI namespace required"
        not (insecure_skip_verify and tls_enabled), \
            "insecure_skip_verify should only be used without TLS"
        platform in ["linux/amd64", "linux/arm64", "darwin/amd64", "darwin/arm64"], \
            "Platform must be one of: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64"

schema GiteaSource:
    """Gitea repository configuration for extension distribution"""
    # Gitea server URL
    url: str
    # Organization/namespace containing repositories
    organization: str
    # Path to authentication token file
    auth_token_path?: str
    # Use SSH instead of HTTPS
    use_ssh: bool = False
    # Branch to use for extensions
    branch: str = "main"

    check:
        len(url) > 0, "Gitea URL required"
        len(organization) > 0, "Gitea organization required"
        url.startswith("http://") or url.startswith("https://"), \
            "Gitea URL must start with http:// or https://"

schema LocalSource:
    """Local filesystem configuration for extension distribution"""
    # Absolute path to extensions directory
    path: str
    # Watch for changes and auto-reload
    watch: bool = False

    check:
        len(path) > 0, "Local source path required"
        path.startswith("/") or path.startswith("~"), \
            "Local source path must be absolute"

schema HTTPSource:
    """Generic HTTP/HTTPS configuration for extension distribution"""
    # HTTP/HTTPS URL
    url: str
    # Authentication header (e.g., "Bearer token123")
    auth_header?: str
    # Use HTTP basic auth
    basic_auth?: bool = False
    # Username for basic auth
    username?: str
    # Password for basic auth
    password?: str

    check:
        len(url) > 0, "HTTP URL required"
        url.startswith("http://") or url.startswith("https://"), \
            "URL must start with http:// or https://"
        not basic_auth or (username and password), \
            "Basic auth requires username and password"

schema ExtensionSource:
    """Extension source configuration with multi-backend support"""
    # Source type
    type: "oci" | "gitea" | "local" | "http"

    # OCI registry source configuration
    oci?: OCISource
    # Gitea source configuration
    gitea?: GiteaSource
    # Local filesystem source configuration
    local?: LocalSource
    # HTTP source configuration
    http?: HTTPSource

    check:
        (type == "oci" and oci != None) or \
        (type == "gitea" and gitea != None) or \
        (type == "local" and local != None) or \
        (type == "http" and http != None), \
            "Source configuration must match selected type"

schema ExtensionManifest:
    """Extension package manifest for OCI distribution"""
    # Extension name (must match directory name)
    name: str
    # Extension type
    type: "provider" | "taskserv" | "cluster"
    # Semantic version
    version: str
    # Extension description
    description?: str
    # Extension author/maintainer
    author?: str
    # License identifier (SPDX)
    license?: str = "MIT"
    # Extension homepage URL
    homepage?: str
    # Repository URL
    repository?: str
    # Extension dependencies
    dependencies?: {str: str}
    # Extension tags/keywords
    tags?: [str]
    # Supported platforms
    platforms?: [str] = ["linux/amd64"]
    # Minimum provisioning core version
    min_provisioning_version?: str

    check:
        len(name) > 0, "Extension name required"
        name == name.lower(), "Extension name must be lowercase"
        len(version) > 0, "Extension version required"
        # Semantic version format (basic check)
        version.count(".") >= 2, "Version must be semantic (x.y.z)"

schema RepositoryConfig:
    """Multi-repository configuration for dependency management"""
    # Repository name
    name: str
    # Repository type
    type: "core" | "extensions" | "platform" | "workspace"
    # Source configuration
    source: ExtensionSource
    # Repository version/tag
    version?: str
    # Enable repository
    enabled: bool = True
    # Repository priority (higher = more priority)
    priority: int = 100
    # Cache TTL in seconds
    cache_ttl: int = 3600

    check:
        len(name) > 0, "Repository name required"
        priority >= 0, "Repository priority cannot be negative"
        cache_ttl > 0, "Cache TTL must be positive"

schema DependencyResolution:
    """Dependency resolution configuration"""
    # Resolution strategy
    strategy: "strict" | "latest" | "minimal"
    # Allow pre-release versions
    allow_prerelease: bool = False
    # Enable version pinning
    pin_versions: bool = True
    # Maximum dependency depth
    max_depth: int = 10
    # Conflict resolution strategy
    conflict_strategy: "error" | "latest" | "highest_priority"

    check:
        max_depth > 0 and max_depth <= 100, \
            "Max depth must be between 1 and 100"