updns/development-plan.md

Development Plan for UpDNS

A step-by-step roadmap to build, test, and evolve the Go‑based DynDNS proxy—including support for both exact hostnames and wildcard domains.

---

Phase 1: Project Setup (Week 1)

1. Repository Initialization

   • go mod init git.cloonar.com/cloonar/updns
   • Create directory structure:

     cmd/updns
     internal/config
     internal/server
     internal/provider
     test/
     

2. Configuration Loader

   • Use [spf13/viper] to parse YAML/JSON/TOML.
   • Define Config struct with:

     type ClientConfig struct {
       Secret   string   `mapstructure:"secret"`
       Exact    []string `mapstructure:"exact"`
       Wildcard []string `mapstructure:"wildcard"`
     }
     
     type Config struct {
       Server   ServerConfig             `mapstructure:"server"`
       Upstream UpstreamConfig           `mapstructure:"upstream"`
       Clients  map[string]ClientConfig  `mapstructure:"clients"`
     }
     

   • Validate that at least one of Exact or Wildcard is set per client.

3. Main & CLI

   • Parse --config flag.
   • Load config, handle errors, and pass into server setup.

---

Phase 2: HTTP API & Authentication (Week 2)

1. Server Implementation

   • Choose router: net/http or gin-gonic/gin.
   • Define route POST /update.

2. Authentication & Authorization

   • Middleware to:
     • Lookup client by key.
     • Verify secret matches stored token.
     • Check that requested host is allowed by matching either:
       • An entry in Exact (full string equality), or
       • A wildcard base domain in Wildcard, e.g. example.com matches foo.example.com and example.com.
   • Reject requests with clear error if host not authorized.

3. Request Validation

   • Validate JSON payload: key, secret, host, optional ip.
   • Default ip to requestor’s IP if omitted.

---

Phase 3: Hetzner Provider Integration (Week 3)

1. Provider Interface

   type Provider interface {
     UpdateRecord(ctx context.Context, domain, ip string) error
   }
   

2. Hetzner Implementation

   • On startup, fetch or cache record IDs by domain.
   • Use Hetzner’s DDNS API to PATCH IP on update.

3. Error Handling & Retries

   • Retry transient errors with exponential backoff.
   • Surface permanent errors in response.

---

Phase 4: Testing & CI (Week 4)

1. Unit Tests

   • Config parsing, ensuring Exact and Wildcard fields load correctly.
   • Authorization logic: hosts matching exact list vs. wildcard list.
   • Secret validation.

2. Integration Tests

   • Use httptest.Server to simulate upstream.
   • Test success and failure for:
     • Exact hostname updates.
     • Subdomain updates via wildcard rules.
     • Unauthorized host attempts.

3. CI Pipeline

   • GitHub Actions to run go fmt, go vet, go test.
   • Build artifacts for Linux/macOS.

---

Phase 5: TLS, Logging & Metrics (Week 5)

1. TLS Support

   • Enable HTTPS when tls.enabled in config.
   • Load cert/key files.

2. Structured Logging

   • Integrate uber/zap or sirupsen/logrus.
   • Log requests, responses, errors, and authorization decisions (with no secrets).

3. Metrics

   • Expose Prometheus /metrics endpoint.
   • Track:
     • Total updates.
     • Successes vs. failures.
     • Requests authorized via exact vs. wildcard.

---

Phase 6: Extensibility & Additional Providers (Week 6)

1. Provider Factory

   • Map upstream.provider string to constructor.

2. Cloudflare & AWS Stubs

   • Scaffold cloudflare and aws provider packages.
   • Document config for each.

3. Documentation Update

   • Update README to reflect exact + wildcard support and new provider instructions.

---

Phase 7: Deployment & Release (Week 7)

1. Dockerization

   • Write Dockerfile and example docker-compose.yml.

2. Optional Helm Chart

   • Package for Kubernetes.

3. Release v1.0.0

   • Tag in GitHub, attach binaries, update changelog.