# infra
**Import:** `forge.lthn.ai/core/go-infra`
**Files:** 5

## Types

### `RetryConfig`
Controls exponential backoff retry behaviour for `APIClient`.
- `MaxRetries int`: Maximum number of retry attempts after the initial request. `0` disables retries.
- `InitialBackoff time.Duration`: Delay before the first retry.
- `MaxBackoff time.Duration`: Upper bound for the computed backoff delay.

### `APIClient`
Shared HTTP client with retry handling, shared rate-limit blocking, pluggable authentication, and configurable error prefixes. All struct fields are unexported.
- `func (a *APIClient) Do(req *http.Request, result any) error`: Applies authentication, honours the shared rate-limit window, retries transport failures plus `429` and `5xx` responses, and JSON-decodes into `result` when `result` is non-nil.
- `func (a *APIClient) DoRaw(req *http.Request) ([]byte, error)`: Runs the same request pipeline as `Do` but returns the raw response body instead of decoding JSON.

### `APIClientOption`
`type APIClientOption func(*APIClient)`

Functional option consumed by `NewAPIClient` to mutate a newly created `APIClient`.

### `CloudNSClient`
HTTP client for the CloudNS DNS API. Authentication details, base URL, and delegated `APIClient` state are stored in unexported fields.
- `func (c *CloudNSClient) ListZones(ctx context.Context) ([]CloudNSZone, error)`: Fetches all zones visible to the configured CloudNS sub-user.
- `func (c *CloudNSClient) ListRecords(ctx context.Context, domain string) (map[string]CloudNSRecord, error)`: Fetches all records for a zone and returns them keyed by CloudNS record ID.
- `func (c *CloudNSClient) CreateRecord(ctx context.Context, domain, host, recordType, value string, ttl int) (string, error)`: Creates a record and returns the created record ID.
- `func (c *CloudNSClient) UpdateRecord(ctx context.Context, domain, recordID, host, recordType, value string, ttl int) error`: Replaces an existing CloudNS record with the supplied values.
- `func (c *CloudNSClient) DeleteRecord(ctx context.Context, domain, recordID string) error`: Deletes a record by CloudNS record ID.
- `func (c *CloudNSClient) EnsureRecord(ctx context.Context, domain, host, recordType, value string, ttl int) (bool, error)`: Idempotently creates or updates a record and reports whether a change was applied.
- `func (c *CloudNSClient) SetACMEChallenge(ctx context.Context, domain, value string) (string, error)`: Creates the `_acme-challenge` TXT record used for DNS-01 validation.
- `func (c *CloudNSClient) ClearACMEChallenge(ctx context.Context, domain string) error`: Deletes all `_acme-challenge` TXT records in the zone.

### `CloudNSZone`
CloudNS zone metadata returned by `ListZones`.
- `Name string`: Zone name as returned by CloudNS.
- `Type string`: Zone type reported by the API.
- `Zone string`: Zone domain name or zone identifier.
- `Status string`: Current CloudNS status string for the zone.

### `CloudNSRecord`
CloudNS DNS record model returned by `ListRecords`.
- `ID string`: CloudNS record ID.
- `Type string`: DNS record type such as `A`, `CNAME`, or `TXT`.
- `Host string`: Relative host label stored in the zone.
- `Record string`: Record payload or answer value.
- `TTL string`: TTL reported by CloudNS. The API returns it as a string.
- `Priority string`: Optional priority value for record types that support it.
- `Status int`: CloudNS numeric status flag for the record.

### `Config`
Top-level `infra.yaml` model loaded by `Load` and `Discover`.
- `Hosts map[string]*Host`: Named infrastructure hosts keyed by logical host name.
- `LoadBalancer LoadBalancer`: Managed load balancer definition.
- `Network Network`: Shared private network definition.
- `DNS DNS`: DNS provider configuration and desired zone state.
- `SSL SSL`: Certificate and TLS settings.
- `Database Database`: Database cluster settings.
- `Cache Cache`: Cache or session cluster settings.
- `Containers map[string]*Container`: Named container deployment definitions.
- `S3 S3Config`: Object storage configuration.
- `CDN CDN`: CDN provider configuration.
- `CICD CICD`: CI/CD service configuration.
- `Monitoring Monitoring`: Health-check and alert thresholds.
- `Backups Backups`: Backup job schedules.
- `func (c *Config) HostsByRole(role string) map[string]*Host`: Returns the subset of `Hosts` whose `Role` matches `role`.
- `func (c *Config) AppServers() map[string]*Host`: Convenience wrapper around `HostsByRole("app")`.

### `Host`
Infrastructure host definition loaded from `infra.yaml`.
- `FQDN string`: Public hostname for the machine.
- `IP string`: Primary public IP address.
- `PrivateIP string`: Optional private network IP.
- `Type string`: Provider class, such as `hcloud` or `hrobot`.
- `Role string`: Functional role such as `bastion`, `app`, or `builder`.
- `SSH SSHConf`: SSH connection settings for the host.
- `Services []string`: Services expected to run on the host.

### `SSHConf`
SSH connection settings associated with a `Host`.
- `User string`: SSH username.
- `Key string`: Path to the private key file. `Load` expands `~` and defaults are applied before use.
- `Port int`: SSH port. `Load` defaults this to `22` when omitted.

### `LoadBalancer`
Desired Hetzner managed load balancer configuration loaded from `infra.yaml`.
- `Name string`: Hetzner load balancer name.
- `FQDN string`: DNS name expected to point at the load balancer.
- `Provider string`: Provider identifier for the managed load balancer service.
- `Type string`: Hetzner load balancer type name.
- `Location string`: Hetzner location or datacenter slug.
- `Algorithm string`: Load-balancing algorithm name.
- `Backends []Backend`: Backend targets referenced by host name and port.
- `Health HealthCheck`: Health-check policy applied to listeners.
- `Listeners []Listener`: Frontend-to-backend listener mappings.
- `SSL LBCert`: TLS certificate settings for the load balancer.

### `Backend`
Load balancer backend target declared in `infra.yaml`.
- `Host string`: Host key in `Config.Hosts` to use as the backend target.
- `Port int`: Backend port to route traffic to.

### `HealthCheck`
Load balancer health-check settings.
- `Protocol string`: Protocol used for checks.
- `Path string`: HTTP path for health checks when the protocol is HTTP-based.
- `Interval int`: Probe interval in seconds.

### `Listener`
Frontend listener mapping for the managed load balancer.
- `Frontend int`: Exposed listener port.
- `Backend int`: Destination backend port.
- `Protocol string`: Listener protocol.
- `ProxyProtocol bool`: Whether the Hetzner listener should enable PROXY protocol forwarding.

### `LBCert`
TLS certificate settings for the load balancer.
- `Certificate string`: Certificate identifier or path.
- `SAN []string`: Subject alternative names covered by the certificate.

### `Network`
Private network definition from `infra.yaml`.
- `CIDR string`: Network CIDR block.
- `Name string`: Logical network name.

### `DNS`
DNS provider settings and desired zone contents.
- `Provider string`: DNS provider identifier.
- `Nameservers []string`: Authoritative nameservers for the managed domains.
- `Zones map[string]*Zone`: Desired DNS zones keyed by zone name.

### `Zone`
Desired DNS zone contents.
- `Records []DNSRecord`: Desired records for the zone.

### `DNSRecord`
Desired DNS record entry in `infra.yaml`.
- `Name string`: Record name or host label.
- `Type string`: DNS record type.
- `Value string`: Record value.
- `TTL int`: Record TTL in seconds.

### `SSL`
Top-level TLS configuration.
- `Wildcard WildcardCert`: Wildcard certificate settings.

### `WildcardCert`
Wildcard certificate request and deployment settings.
- `Domains []string`: Domain names covered by the wildcard certificate.
- `Method string`: Certificate issuance method.
- `DNSProvider string`: DNS provider used for validation.
- `Termination string`: Termination point for the certificate.

### `Database`
Database cluster configuration.
- `Engine string`: Database engine name.
- `Version string`: Engine version.
- `Cluster string`: Cluster mode or cluster identifier.
- `Nodes []DBNode`: Database nodes in the cluster.
- `SSTMethod string`: State snapshot transfer method.
- `Backup BackupConfig`: Automated backup settings for the database cluster.

### `DBNode`
Single database node definition.
- `Host string`: Host identifier for the database node.
- `Port int`: Database port.

### `BackupConfig`
Backup settings attached to `Database`.
- `Schedule string`: Backup schedule expression.
- `Destination string`: Backup destination type or endpoint.
- `Bucket string`: Bucket name when backups target object storage.
- `Prefix string`: Object key prefix for stored backups.

### `Cache`
Cache or session cluster configuration.
- `Engine string`: Cache engine name.
- `Version string`: Engine version.
- `Sentinel bool`: Whether Redis Sentinel style high availability is enabled.
- `Nodes []CacheNode`: Cache nodes in the cluster.

### `CacheNode`
Single cache node definition.
- `Host string`: Host identifier for the cache node.
- `Port int`: Cache service port.

### `Container`
Named container deployment definition.
- `Image string`: Container image reference.
- `Port int`: Optional exposed service port.
- `Runtime string`: Optional container runtime identifier.
- `Command string`: Optional command override.
- `Replicas int`: Optional replica count.
- `DependsOn []string`: Optional dependency list naming other services or components.

### `S3Config`
Object storage configuration.
- `Endpoint string`: S3-compatible endpoint URL or host.
- `Buckets map[string]*S3Bucket`: Named bucket definitions keyed by logical bucket name.

### `S3Bucket`
Single S3 bucket definition.
- `Purpose string`: Intended bucket role or usage.
- `Paths []string`: Managed paths or prefixes within the bucket.

### `CDN`
CDN configuration.
- `Provider string`: CDN provider identifier.
- `Origin string`: Origin hostname or endpoint.
- `Zones []string`: Zones served through the CDN.

### `CICD`
CI/CD service configuration.
- `Provider string`: CI/CD provider identifier.
- `URL string`: Service URL.
- `Runner string`: Runner type or runner host reference.
- `Registry string`: Container registry endpoint.
- `DeployHook string`: Deploy hook URL or tokenized endpoint.

### `Monitoring`
Monitoring and alert configuration.
- `HealthEndpoints []HealthEndpoint`: Endpoints that should be polled for health.
- `Alerts map[string]int`: Numeric thresholds keyed by alert name.

### `HealthEndpoint`
Health endpoint monitored by the platform.
- `URL string`: Endpoint URL.
- `Interval int`: Polling interval in seconds.

### `Backups`
Backup schedules grouped by cadence.
- `Daily []BackupJob`: Jobs that run daily.
- `Weekly []BackupJob`: Jobs that run weekly.

### `BackupJob`
Scheduled backup job definition.
- `Name string`: Job name.
- `Type string`: Backup type or mechanism.
- `Destination string`: Optional destination override.
- `Hosts []string`: Optional host list associated with the job.

### `HCloudClient`
HTTP client for the Hetzner Cloud API. Token, base URL, and delegated `APIClient` state are stored in unexported fields.
- `func (c *HCloudClient) ListServers(ctx context.Context) ([]HCloudServer, error)`: Lists cloud servers.
- `func (c *HCloudClient) ListLoadBalancers(ctx context.Context) ([]HCloudLoadBalancer, error)`: Lists managed load balancers.
- `func (c *HCloudClient) GetLoadBalancer(ctx context.Context, id int) (*HCloudLoadBalancer, error)`: Fetches a load balancer by numeric ID.
- `func (c *HCloudClient) CreateLoadBalancer(ctx context.Context, req HCloudLBCreateRequest) (*HCloudLoadBalancer, error)`: Creates a load balancer from the supplied request payload.
- `func (c *HCloudClient) DeleteLoadBalancer(ctx context.Context, id int) error`: Deletes a load balancer by numeric ID.
- `func (c *HCloudClient) CreateSnapshot(ctx context.Context, serverID int, description string) error`: Creates a snapshot image for a server.

### `HCloudServer`
Hetzner Cloud server model returned by `ListServers`.
- `ID int`: Hetzner server ID.
- `Name string`: Server name.
- `Status string`: Provisioning or runtime status string.
- `PublicNet HCloudPublicNet`: Public networking information.
- `PrivateNet []HCloudPrivateNet`: Attached private network interfaces.
- `ServerType HCloudServerType`: Server flavour metadata.
- `Datacenter HCloudDatacenter`: Datacenter metadata.
- `Labels map[string]string`: Hetzner labels attached to the server.

### `HCloudPublicNet`
Hetzner Cloud public network metadata.
- `IPv4 HCloudIPv4`: Primary public IPv4 address.

### `HCloudIPv4`
Hetzner IPv4 model.
- `IP string`: IPv4 address string.

### `HCloudPrivateNet`
Hetzner private network attachment.
- `IP string`: Private IP assigned to the server on the network.
- `Network int`: Numeric network ID.

### `HCloudServerType`
Hetzner server flavour metadata.
- `Name string`: Server type name.
- `Description string`: Provider description for the server type.
- `Cores int`: Number of vCPUs.
- `Memory float64`: RAM size reported by the API.
- `Disk int`: Disk size reported by the API.

### `HCloudDatacenter`
Hetzner datacenter or location metadata.
- `Name string`: Datacenter or location name.
- `Description string`: Provider description.

### `HCloudLoadBalancer`
Hetzner managed load balancer model.
- `ID int`: Load balancer ID.
- `Name string`: Load balancer name.
- `PublicNet HCloudLBPublicNet`: Public network state, including the IPv4 address.
- `Algorithm HCloudLBAlgorithm`: Load-balancing algorithm.
- `Services []HCloudLBService`: Configured listeners and service definitions.
- `Targets []HCloudLBTarget`: Attached backend targets.
- `Location HCloudDatacenter`: Location metadata.
- `Labels map[string]string`: Hetzner labels attached to the load balancer.

### `HCloudLBPublicNet`
Public network state for a Hetzner load balancer.
- `Enabled bool`: Whether public networking is enabled.
- `IPv4 HCloudIPv4`: Assigned public IPv4 address.

### `HCloudLBAlgorithm`
Hetzner load-balancing algorithm descriptor.
- `Type string`: Algorithm name.

### `HCloudLBService`
Hetzner load balancer listener or service definition.
- `Protocol string`: Listener protocol.
- `ListenPort int`: Frontend port exposed by the load balancer.
- `DestinationPort int`: Backend port targeted by the service.
- `Proxyprotocol bool`: Whether PROXY protocol forwarding is enabled. The API field name is `proxyprotocol`.
- `HTTP *HCloudLBHTTP`: Optional HTTP-specific settings.
- `HealthCheck *HCloudLBHealthCheck`: Optional health-check configuration.

### `HCloudLBHTTP`
HTTP-specific load balancer service settings.
- `RedirectHTTP bool`: Whether plain HTTP requests should be redirected.

### `HCloudLBHealthCheck`
Hetzner load balancer health-check definition.
- `Protocol string`: Health-check protocol.
- `Port int`: Backend port to probe.
- `Interval int`: Probe interval.
- `Timeout int`: Probe timeout.
- `Retries int`: Failure threshold before a target is considered unhealthy.
- `HTTP *HCloudLBHCHTTP`: Optional HTTP-specific health-check options.

### `HCloudLBHCHTTP`
HTTP-specific Hetzner health-check options.
- `Path string`: HTTP path used for the probe.
- `StatusCode string`: Expected status code matcher serialized as `status_codes`.

### `HCloudLBTarget`
Backend target attached to a Hetzner load balancer.
- `Type string`: Target type, such as `ip` or `server`.
- `IP *HCloudLBTargetIP`: IP target metadata when the target type is IP-based.
- `Server *HCloudLBTargetServer`: Server reference when the target type is server-based.
- `HealthStatus []HCloudLBHealthStatus`: Health status entries for the target.

### `HCloudLBTargetIP`
IP-based load balancer target.
- `IP string`: Backend IP address.

### `HCloudLBTargetServer`
Server-based load balancer target reference.
- `ID int`: Hetzner server ID.

### `HCloudLBHealthStatus`
Health state for one listening port on a load balancer target.
- `ListenPort int`: Listener port associated with the status.
- `Status string`: Health status string such as `healthy`.

### `HCloudLBCreateRequest`
Request payload for `HCloudClient.CreateLoadBalancer`.
- `Name string`: New load balancer name.
- `LoadBalancerType string`: Hetzner load balancer type slug.
- `Location string`: Hetzner location or datacenter slug.
- `Algorithm HCloudLBAlgorithm`: Algorithm selection.
- `Services []HCloudLBService`: Listener definitions to create.
- `Targets []HCloudLBCreateTarget`: Backend targets to attach at creation time.
- `Labels map[string]string`: Labels to apply to the new load balancer.

### `HCloudLBCreateTarget`
Target entry used during load balancer creation.
- `Type string`: Target type.
- `IP *HCloudLBTargetIP`: IP target metadata when the target is IP-based.

### `HRobotClient`
HTTP client for the Hetzner Robot API. Credentials, base URL, and delegated `APIClient` state are stored in unexported fields.
- `func (c *HRobotClient) ListServers(ctx context.Context) ([]HRobotServer, error)`: Lists dedicated servers available from Robot.
- `func (c *HRobotClient) GetServer(ctx context.Context, ip string) (*HRobotServer, error)`: Fetches one Robot server by server IP.

### `HRobotServer`
Hetzner Robot dedicated server model.
- `ServerIP string`: Public server IP address.
- `ServerName string`: Server hostname.
- `Product string`: Product or hardware plan name.
- `Datacenter string`: Datacenter code returned by the API field `dc`.
- `Status string`: Robot status string.
- `Cancelled bool`: Whether the server is cancelled.
- `PaidUntil string`: Billing paid-through date string.

## Functions

### `func DefaultRetryConfig() RetryConfig`
Returns the library defaults used by `NewAPIClient`: three retries, `100ms` initial backoff, and `5s` maximum backoff.

### `func WithHTTPClient(c *http.Client) APIClientOption`
Injects a custom `http.Client` into an `APIClient`.

### `func WithRetry(cfg RetryConfig) APIClientOption`
Injects a retry policy into an `APIClient`.

### `func WithAuth(fn func(req *http.Request)) APIClientOption`
Registers a callback that mutates each outgoing request before it is sent.

### `func WithPrefix(p string) APIClientOption`
Sets the error prefix used when wrapping client errors.

### `func NewAPIClient(opts ...APIClientOption) *APIClient`
Builds an `APIClient` with a `30s` HTTP timeout, `DefaultRetryConfig`, default prefix `api`, and any supplied options.

### `func NewCloudNSClient(authID, password string) *CloudNSClient`
Builds a CloudNS client configured for `auth-id` and `auth-password` query-parameter authentication.

### `func Load(path string) (*Config, error)`
Reads and unmarshals `infra.yaml`, expands host SSH key paths, and defaults missing SSH ports to `22`.

### `func Discover(startDir string) (*Config, string, error)`
Searches `startDir` and its parents for `infra.yaml`, returning the parsed config together with the discovered file path.

### `func NewHCloudClient(token string) *HCloudClient`
Builds a Hetzner Cloud client that authenticates requests with a bearer token.

### `func NewHRobotClient(user, password string) *HRobotClient`
Builds a Hetzner Robot client that authenticates requests with HTTP basic auth.