# Hetzner Cloud Provider Contracts - Type Definitions
# Migrated from: provisioning/extensions/providers/hetzner/kcl/

{
  # Delete/rebuild protection flags — applicable to servers, networks, volumes, and floating IPs.
  # Hetzner applies protection as a post-creation step; this contract validates the intent fields.
  # Servers support both delete and rebuild; networks, volumes, and FIPs support delete only.
  Protection = {
    delete  | Bool | optional,
    rebuild | Bool | optional,
  },

  # Volume (Block Storage) for Hetzner Cloud
  Volume = {
    name | String,
    size | Number,
    location | String | optional,
    format | String | optional,
    automount | Bool | optional,
    delete_on_termination | Bool | optional,
    protection | Protection | optional,
  },

  # Storage Box Subaccount — a scoped (optionally read-only) SFTP/Samba/WebDAV
  # access path under a home directory. Used to give restic its own credential
  # scope without exposing the primary account.
  StorageBoxSubaccount = {
    home_directory   | String,                 # e.g. restic (NO leading slash — Hetzner API rejects it)
    name             | String | optional,      # friendly name in `hcloud storage-box subaccount list`; defaults to home_directory
    password_env_key | String,                 # SOPS key suffix: STORAGEBOX_SUB_PASSWORD_<key>, injected at render time
    readonly         | Bool | optional,
    enable_ssh       | Bool | optional,
    enable_samba     | Bool | optional,
    enable_webdav    | Bool | optional,
    reachable_externally | Bool | optional,    # access from outside the Hetzner network
    description      | String | optional,
  },

  # Storage Box (BX series) — external SFTP/Samba/WebDAV/BorgBackup storage,
  # created via `hcloud storage-box`. The --password is a secret injected from
  # SOPS at render time (STORAGEBOX_PASSWORD), never declared here.
  StorageBox = {
    name                 | String,
    type                 | String | optional,  # bx11 | bx21 | bx31 | bx41
    location             | String | optional,
    enable_ssh           | Bool | optional,
    enable_samba         | Bool | optional,
    enable_webdav        | Bool | optional,
    enable_zfs           | Bool | optional,
    reachable_externally | Bool | optional,    # access from outside the Hetzner network
    ssh_keys             | Array String | optional,  # OpenSSH public keys or existing key names
    labels               | { _ | String } | optional,
    subaccounts          | Array StorageBoxSubaccount | optional,
    protection           | Protection | optional,
  },

  # Private Network configuration
  Network = {
    name | String | optional,
    ip | String | optional,
    alias_ips,  # Bare field: array of strings
    protection | Protection | optional,
  },

  # Floating IP configuration
  FipAssignment = {
    mode     | [| 'pinned, 'floating |],
    node     | String | optional,       # required when mode = 'pinned
    selector | { .. } | optional,       # label key=value pairs ALL must match (floating only)
    exclude  | Array String | optional, # hostname exceptions even when labels match (floating only)
  },

  FloatingIp = {
    name | String,
    type | String,               # "ipv4" | "ipv6"
    home_location | String | optional,
    description | String | optional,
    dns_ptr | String | optional,
    assignment | FipAssignment | optional,
    labels,                      # Bare field: record of string keys/values
    protection | Protection | optional,
  },

  # Firewall configuration
  Firewall = {
    name | String | optional,
    apply_to,  # Bare field: array of strings
    rules,     # Bare field: array of rule objects
  },

  # Hetzner Cloud server defaults schema
  ServerDefaults_hetzner = {
    provider | String,
    location | String,
    server_type | String,
    image | String,
    ssh_keys,           # Bare field: array of strings
    user_data | String | optional,
    volumes,            # Bare field: array of Volume
    networks,           # Bare field: array of Network
    firewalls,          # Bare field: array of Firewall
    labels,             # Bare field: record of string keys/values
    placement_group | String | optional,
    backups | Bool | optional,
    automount | Bool | optional,
    protection | Protection | optional,
  },

  # Hetzner server configuration (extends defaults)
  ServerHetzner = {
    hostname | String,
    title | String | optional,
    network_private_ip | String | optional,
    extra_hostnames,  # Bare field: array of strings
    taskservs,        # Bare field: array of taskserv defs
    clusters,         # Bare field: array of cluster defs
    provider | String,
    location | String,
    server_type | String,
    image | String,
    ssh_keys,         # Bare field: array of strings
    user_data | String | optional,
    volumes,          # Bare field: array of Volume
    networks,         # Bare field: array of Network
    firewalls,        # Bare field: array of Firewall
    labels,           # Bare field: record
    placement_group | String | optional,
    backups | Bool | optional,
    automount | Bool | optional,
    protection | Protection | optional,
    os_type | String | optional,              # "debian" | "nixos"
    nixos_anywhere_enabled | Bool | optional, # Use nixos-anywhere for NixOS install
    flake_path | String | optional,           # Path to flake.nix for nixos-anywhere
    target_host | String | optional,          # Target for nixos-anywhere SSH (root@ip)
    kexec_tarball_url | String | optional,    # Optional custom kexec tarball URL
  },

  # Hetzner provisioning configuration
  ProvisionHetzner = {
    api_url | String,
    api_timeout | Number,
    api_retries | Number,
    default_location | String,
    default_server_type | String,
    default_os_type | String,                           # "debian" | "ubuntu" | "nixos"
    default_image | String,                             # Resolved from os_type
    enable_backups | Bool,
    enable_private_networks | Bool,
    enable_volumes | Bool,
    enable_firewalls | Bool,
    enable_nixos_anywhere | Bool,                       # Auto-enabled for os_type="nixos"
    nixos_anywhere_bootstrap_image | String | optional, # Bootstrap image for NixOS (default: ubuntu-24.04)
  },
}