Overview

Date: 2026-05-11

Time: 15:52

Overview

This module provides Cloudflare DNS management for FTL2 automation, specifically creating and updating A records via the Cloudflare v4 API. It's used in the ftl2-servercraft application to automatically point hostnames at provisioned game server IPs. It uses only stdlib (urllib.request) with no external HTTP dependencies.

Usage Patterns

The single public entry point is updatednsrecord:

from ftl2_servercraft.cloudflare import update_dns_record

update_dns_record(
    hostname="world1.servercraft2.com",
    ip="203.0.113.42",
    log=print,  # or any Callable[[str], None]
)

The log callback receives progress strings — callers typically pass a TUI logger or print. The function is idempotent: it creates the record if missing, updates it if the IP changed, and skips the API call entirely if the record already matches.

API and Configuration

| Parameter / Config | Description |

|---|---|

| CLOUDFLAREAPITOKEN | Required env var. Bearer token with DNS edit permissions for the target zone. Raises RuntimeError if missing. |

| hostname | FQDN for the A record (e.g. "world1.servercraft2.com") |

| ip | IPv4 address to point to |

| log | Callable[[str], None] — progress/status callback |

Records are created with TTL 300 seconds and proxied: False (DNS-only, no Cloudflare proxy).

Key Behaviors

• Idempotent: checks existing records before mutating. If the A record already has the target IP, no API write is made.
• Zone lookup: automatically extracts the root domain from the hostname (e.g. world1.servercraft2.com → zone lookup for servercraft2.com). Handles subdomains of any depth by taking the last two domain parts.
• Upsert logic: uses PUT (full replace) for existing records, POST for new ones. Only the first matching record is updated if duplicates exist.
• No retries or timeout handling: bare urllib.request.urlopen — network errors propagate as urllib.error.URLError. Callers should handle transient failures.
• Hardcoded settings: TTL (300s) and proxied (False) are not configurable via parameters.

Relationships

• Called by: ftl2-servercraft provisioning workflow — after a game server VM is created, this updates DNS to make it reachable.
• Dependencies: stdlib only (json, os, urllib.request). No FTL2 framework imports.
• External service: Cloudflare v4 REST API (api.cloudflare.com/client/v4).
• Pattern: follows the FTL2 application convention of injecting a log callback rather than using a global logger, consistent with TUI-integrated workflows.