provisioning/schemas/platform/docker-build.ncl

# Docker Build Configuration Schema
# Defines build-time configuration for multi-stage Docker builds with cargo-chef
# Supports BuildKit caching, sccache, cross-compilation, and feature flags

let constraints = import "schemas/platform/common/constraints.ncl" in

{
  # Cache mode for BuildKit layer caching
  CacheMode = [|
    'local,    # Local cache (solo development)
    'registry, # Registry-based cache (CI/CD, enterprise)
    'inline,   # Inline cache metadata (minimal overhead)
  |],

  # Docker build configuration for Rust services
  DockerBuildConfig = {
    # Cargo package name (from workspace Cargo.toml)
    package
      | doc "Cargo workspace package name"
      | String,

    # Binary name (output executable name)
    binary
      | doc "Binary executable name"
      | String,

    # Base image for build stage
    base_image
      | doc "Rust base image for build stage"
      | String
      | default = "rust:1.82-trixie",

    # Runtime image for final stage
    runtime_image
      | doc "Minimal runtime image for final stage"
      | String
      | default = "debian:trixie-slim",

    # Cargo feature flags
    features
      | doc "Cargo features to enable during build"
      | Array String
      | default = [],

    # Enable cargo-chef for dependency caching
    chef_enabled
      | doc "Use cargo-chef for layer caching"
      | Bool
      | default = true,

    # Cross-compilation target (optional)
    target
      | doc "Rust target triple for cross-compilation"
      | String
      | optional,

    # sccache configuration for distributed caching
    sccache
      | doc "Distributed build cache configuration"
      | {
        enabled
          | doc "Enable sccache for build caching"
          | Bool
          | default = false,

        endpoint
          | doc "S3-compatible endpoint for cache storage"
          | String
          | optional,

        bucket
          | doc "S3 bucket name for cache artifacts"
          | String
          | default = "rust-cache",

        region
          | doc "S3 region for cache bucket"
          | String
          | default = "",
      }
      | default = { enabled = false, bucket = "rust-cache", region = "" },

    # Service port (must match server.port from runtime config)
    port
      | doc "HTTP port for service (must be 9000-65535)"
      | Number
      | constraints.port_high,

    # Health check endpoint path
    health_path
      | doc "Health check endpoint path"
      | String
      | default = "/health",

    # Additional runtime packages (apt packages for runtime stage)
    extra_runtime_pkgs
      | doc "Additional apt packages for runtime image"
      | Array String
      | default = [],

    # User ID for non-root user in container
    user_id
      | doc "UID for non-root container user"
      | Number
      | default = 1000,

    # Configuration file to copy (null if none)
    config_file
      | doc "Config file to copy from crate (relative path)"
      | String
      | default = "",

    # BuildKit-specific configuration
    buildkit
      | doc "BuildKit advanced build options"
      | {
        # Cache mode strategy
        cache_mode
          | doc "BuildKit cache storage mode"
          | CacheMode
          | default = 'registry,

        # Parallel build jobs
        parallel_jobs
          | doc "Number of parallel cargo build jobs"
          | Number
          | constraints.server_workers
          | default = 4,

        # Enable BuildKit inline cache
        inline_cache
          | doc "Include cache metadata in image"
          | Bool
          | default = false,

        # Cache registry URL (for registry cache mode)
        cache_registry
          | doc "Container registry for build cache"
          | String
          | optional,
      }
      | default = { cache_mode = 'registry, parallel_jobs = 4, inline_cache = false },
  },
}