# terraform-provider-dynu

A standalone Terraform provider for Dynu DNS.

> Status: **read-only milestone**. This provider currently implements provider configuration and data sources only.

## Feature scope

Implemented:
- Provider authentication using `api_key` or `DYNU_API_KEY`
- Optional provider `base_url` override for local test/dev setups
- Data sources:
  - `dynu_domains`
  - `dynu_domain`
  - `dynu_dns_records`

Not implemented yet:
- Terraform resources (no create/update/delete)
- Any write API operations

## Provider source and module path

- Terraform provider source address: `dynu/dynu`
- Go module path: `github.com/dynu/terraform-provider-dynu`

The repository can be hosted elsewhere during development, but module and provider source naming are kept aligned with planned public registry publishing.

## Requirements

- Terraform `>= 1.5`
- Go `>= 1.23`
- Dynu API key for live API usage

## Authentication

Option 1: Terraform configuration.

```hcl
provider "dynu" {
  api_key = var.dynu_api_key
}

variable "dynu_api_key" {
  type      = string
  sensitive = true
}
```

Option 2: Environment variable.

```bash
export DYNU_API_KEY="your-dynu-api-key"
```

## Data source examples

See the `examples/` directory:
- `examples/provider/provider.tf`
- `examples/data-sources/dynu_domains/data-source.tf`
- `examples/data-sources/dynu_domain/data-source.tf`
- `examples/data-sources/dynu_dns_records/data-source.tf`

## Developer workflow

- `./scripts/setup-dev.sh` - validate local Go/Terraform toolchains and environment health (no changes)
- `./scripts/setup-dev.sh --fix` - attempt safe remediation with installed version managers (`mise`, `asdf`, `tfenv`, `tenv`)
- `./scripts/setup-dev.sh --strict` - require Terraform to be installed
- `./scripts/check.sh` - formatting, vet, and unit tests (Tier A)
- `./scripts/test-integration.sh` - local mock-backed provider integration tests (Tier B)
- `./scripts/testacc.sh` - default: Tier B; live mode available with `--live` (Tier C)

### setup-dev behavior

`scripts/setup-dev.sh` now performs robust validation and troubleshooting checks:

- Always reports resolved paths for `bash`, `git`, `go`, and `terraform` (Terraform is warning-only unless `--strict` is used).
- Enforces minimum versions:
  - Go `>= 1.23` (error if missing or too old)
  - Terraform `>= 1.5` (warning if missing by default, error if present but too old)
- Detects common broken Go setups:
  - manual `GOROOT` conflicting with `go env GOROOT`
  - stale stdlib tree mismatches (for example missing `slices`, `maps`, `math/rand/v2`)
- Detects malformed `GOPROXY` and prints the recommended non-destructive fix:
  - `go env -w GOPROXY=https://proxy.golang.org,direct`
- Supports optional safe auto-fix mode:
  - only uses already-installed user-space managers
  - does **not** run distro package managers, `sudo`, or shell-profile edits
  - re-validates tools after attempted remediation

The script is safe for both normal shells and VS Code integrated terminals, and includes guidance when terminal/session restart may be needed after changing versions.

### Standalone repository guarantee

This repository is intentionally self-contained:
- no dependency on sibling repositories
- no dependency on external helper scripts (for example `services-up.sh`)
- no hardcoded local paths (for example `/workspace/...` or `/home/...`)

### setup-dev troubleshooting quick reference

- **Malformed GOPROXY**
  - Symptom: warning that GOPROXY has no valid entries.
  - Fix: `go env -w GOPROXY=https://proxy.golang.org,direct`

- **Broken GOROOT**
  - Symptom: `GOROOT` environment value differs from `go env GOROOT`, or stdlib package checks fail.
  - Fix: usually remove manual override with `unset GOROOT`, then ensure the intended `go` binary is first in `PATH`.

- **Go version / stdlib path mismatch**
  - Symptom: `go version` looks modern but build errors mention missing stdlib packages (for example `slices`, `maps`, `math/rand/v2`).
  - Cause: stale or mismatched Go installation path.
  - Fix: re-select/install Go via your version manager and re-run `./scripts/setup-dev.sh`.

- **VS Code integrated terminal stale environment**
  - Symptom: command paths or versions do not match your expected shell setup.
  - Fix: restart the integrated terminal (or reload the VS Code window) and run `./scripts/setup-dev.sh` again.

### Build

```bash
go build ./...
```

## Testing model

The provider now has three explicit test tiers:

### Tier A: unit tests (fast, no network)

Covers focused package behavior (client parsing, mappers, provider helper logic).

```bash
./scripts/check.sh
go test ./...
```

### Tier B: local integration tests (mock Dynu API, no real credentials)

These tests use an `httptest` fake Dynu API server and run the Terraform provider end-to-end against deterministic fixtures.

- No Dynu account required
- Dummy API key is used in test provider configuration
- Exercises provider wiring, schema/state mapping, hostname resolution flow, and diagnostic behavior

```bash
./scripts/test-integration.sh
./scripts/testacc.sh
```

### Tier C: live acceptance tests (opt-in)

These tests call the real Dynu API and are read-only.

Required environment variables:
- `TF_ACC=1`
- `DYNU_API_KEY`

Optional:
- `DYNU_DOMAIN` (required for domain-specific acceptance tests such as `dynu_domain` and `dynu_dns_records`)

```bash
TF_ACC=1 DYNU_API_KEY="your-dynu-api-key" DYNU_DOMAIN="www.example.com" ./scripts/testacc.sh --live
# or
LIVE=1 TF_ACC=1 DYNU_API_KEY="your-dynu-api-key" ./scripts/testacc.sh
```

If `DYNU_DOMAIN` is omitted, domain-specific live tests skip cleanly.

## CI

GitHub Actions CI runs on push and pull requests and executes:
- gofmt verification
- `go vet ./...`
- `go test ./...`

Live acceptance tests are intentionally excluded from default CI.

## Documentation

Registry-style markdown docs are stored in `docs/`.

## Limitations

- Dynu timestamps are currently exposed as strings exactly as returned by Dynu API.
- Data returned from Dynu is sorted in provider state for Terraform stability.
- Read-only operations only.

## Roadmap

Next planned milestone after this testing foundation:
- first writable resource (`dynu_dns_record`) with strict schema validation, import support, mock-first integration tests, and then live acceptance coverage.