Prepare KarlDNS production deployment

karldns/store/__init__.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from sqlite3 import Connection
+from time import monotonic
+
+from .accounts import AccountsMixin
+from .metrics import MetricsMixin
+from .rate_limit import RateLimitCleanupMixin
+from .records import RecordsEventsMixin
+from .scheduler import SchedulerMixin
+from .schema import connect_database, initialize_schema
+
+
+class DdnsStore(AccountsMixin, MetricsMixin, RecordsEventsMixin, RateLimitCleanupMixin, SchedulerMixin):
+    def __init__(self, database_path: Path) -> None:
+        self.database_path = database_path
+        self._connections = threading.local()
+        self._connection_lock = threading.Lock()
+        self._tracked_connections: list[Connection] = []
+        self._closed_connection_ids: set[int] = set()
+        self._rate_limit_prune_lock = threading.Lock()
+        self._rate_limit_lock = threading.Lock()
+        self._rate_limit_buckets: dict[str, dict[str, float | int]] = {}
+        self._rate_limit_dirty_counts: dict[tuple[str, int], int] = {}
+        self._last_rate_limit_flush = monotonic()
+        self._last_rate_limit_prune_window = -1
+        self.database_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    @contextmanager
+    def connect(self):
+        conn = self._thread_connection()
+        try:
+            yield conn
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+
+    def _init_db(self) -> None:
+        with self.connect() as conn:
+            initialize_schema(conn)
+
+    def optimize(self) -> None:
+        with self.connect() as conn:
+            conn.execute("PRAGMA optimize")
+
+    def checkpoint_wal(self) -> None:
+        if str(self.database_path) == ":memory:":
+            return
+        with self.connect() as conn:
+            conn.execute("PRAGMA wal_checkpoint(PASSIVE)")
+
+    def _thread_connection(self) -> Connection:
+        conn = getattr(self._connections, "conn", None)
+        if conn is None or id(conn) in self._closed_connection_ids:
+            conn = connect_database(self.database_path)
+            self._connections.conn = conn
+            with self._connection_lock:
+                self._tracked_connections.append(conn)
+                self._closed_connection_ids.discard(id(conn))
+        return conn
+
+    def close_connections(self) -> None:
+        with self._connection_lock:
+            connections = list(self._tracked_connections)
+            self._tracked_connections.clear()
+            self._closed_connection_ids.update(id(conn) for conn in connections)
+        for conn in connections:
+            conn.close()
+        if getattr(self._connections, "conn", None) in connections:
+            self._connections.conn = None
+
+    close = close_connections
+
+
+__all__ = ["DdnsStore"]

karldns/store/accounts.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import secrets
+from datetime import UTC, datetime
+
+from ..security import hash_lookup_token, hash_secret, verify_secret
+from .types import AccountRow
+
+
+class AccountsMixin:
+    def create_account(self, hostname: str, username: str | None = None, *, accepted: bool = True) -> AccountRow:
+        now = datetime.now(UTC).isoformat()
+        update_slug = secrets.token_urlsafe(32)
+        management_slug = secrets.token_urlsafe(32)
+        management_hash = hash_lookup_token(management_slug)
+        accepted_at = now if accepted else None
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO accounts(hostname, update_slug, management_hash, created_at, accepted_at, disabled)
+                VALUES (?, ?, ?, ?, ?, 0)
+                """,
+                (hostname, update_slug, management_hash, now, accepted_at),
+            )
+        return {
+            "hostname": hostname,
+            "update_slug": update_slug,
+            "management_slug": management_slug,
+            "accepted_at": accepted_at,
+        }
+
+    def list_accounts(self, limit: int = 100, offset: int = 0) -> list[AccountRow]:
+        with self.connect() as conn:
+            rows = conn.execute(
+                """
+            SELECT accounts.hostname, accounts.update_slug,
+                   accounts.created_at, accounts.accepted_at, accounts.disabled, records.ipv4, records.ipv6, records.updated_at
+            FROM accounts
+            LEFT JOIN records ON records.hostname = accounts.hostname
+            ORDER BY accounts.hostname
+            LIMIT ? OFFSET ?
+            """,
+                (limit, offset),
+            ).fetchall()
+        return [dict(row) for row in rows]
+
+    def count_accounts(self) -> int:
+        with self.connect() as conn:
+            row = conn.execute("SELECT COUNT(*) FROM accounts").fetchone()
+        return int(row[0])
+
+    def get_account_by_hostname(self, hostname: str) -> AccountRow | None:
+        with self.connect() as conn:
+            account = conn.execute(
+                """
+                SELECT accounts.hostname, accounts.update_slug, accounts.dashboard_password_hash,
+                       accounts.created_at, accounts.accepted_at, accounts.disabled, records.ipv4, records.ipv6, records.updated_at
+                FROM accounts
+                LEFT JOIN records ON records.hostname = accounts.hostname
+                WHERE accounts.hostname = ?
+                """,
+                (hostname,),
+            ).fetchone()
+        return dict(account) if account else None
+
+    def get_account_by_slug(self, update_slug: str) -> AccountRow | None:
+        with self.connect() as conn:
+            account = conn.execute(
+                """
+                SELECT hostname, update_slug, accepted_at, disabled FROM accounts
+                WHERE update_slug = ?
+                """,
+                (update_slug,),
+            ).fetchone()
+        return dict(account) if account else None
+
+    def get_account_by_management_slug(self, management_slug: str) -> AccountRow | None:
+        with self.connect() as conn:
+            account = conn.execute(
+                """
+                SELECT accounts.hostname, accounts.update_slug, accounts.dashboard_password_hash,
+                       accounts.created_at, accounts.accepted_at, accounts.disabled, records.ipv4, records.ipv6, records.updated_at
+                FROM accounts
+                LEFT JOIN records ON records.hostname = accounts.hostname
+                WHERE accounts.management_hash = ?
+                """,
+                (hash_lookup_token(management_slug),),
+            ).fetchone()
+        return dict(account) if account else None
+
+    def activate_account(self, hostname: str) -> AccountRow | None:
+        now = datetime.now(UTC).isoformat()
+        with self.connect() as conn:
+            conn.execute(
+                "UPDATE accounts SET accepted_at = COALESCE(accepted_at, ?) WHERE hostname = ?",
+                (now, hostname),
+            )
+        return self.get_account_by_hostname(hostname)
+
+    def delete_account(self, hostname: str) -> None:
+        with self.connect() as conn:
+            conn.execute("DELETE FROM accounts WHERE hostname = ?", (hostname,))
+            conn.execute("DELETE FROM records WHERE hostname = ?", (hostname,))
+
+    def rotate_update_slug(self, hostname: str) -> AccountRow | None:
+        update_slug = secrets.token_urlsafe(32)
+        with self.connect() as conn:
+            conn.execute("UPDATE accounts SET update_slug = ? WHERE hostname = ?", (update_slug, hostname))
+        return self.get_account_by_hostname(hostname)
+
+    def rotate_management_slug(self, hostname: str) -> AccountRow | None:
+        management_slug = secrets.token_urlsafe(32)
+        management_hash = hash_lookup_token(management_slug)
+        with self.connect() as conn:
+            conn.execute("UPDATE accounts SET management_hash = ? WHERE hostname = ?", (management_hash, hostname))
+        account = self.get_account_by_hostname(hostname)
+        if account:
+            account["management_slug"] = management_slug
+        return account
+
+    def set_dashboard_password(self, hostname: str, password: str) -> AccountRow | None:
+        password_hash = hash_secret(password)
+        with self.connect() as conn:
+            conn.execute(
+                "UPDATE accounts SET dashboard_password_hash = ? WHERE hostname = ?",
+                (password_hash, hostname),
+            )
+        return self.get_account_by_hostname(hostname)
+
+    def clear_dashboard_password(self, hostname: str) -> AccountRow | None:
+        with self.connect() as conn:
+            conn.execute("UPDATE accounts SET dashboard_password_hash = NULL WHERE hostname = ?", (hostname,))
+        return self.get_account_by_hostname(hostname)
+
+    def verify_dashboard_password(self, hostname: str, password: str | None) -> bool:
+        if not password:
+            return False
+        with self.connect() as conn:
+            account = conn.execute(
+                """
+                SELECT dashboard_password_hash, disabled FROM accounts
+                WHERE hostname = ?
+                """,
+                (hostname,),
+            ).fetchone()
+        if not account or account["disabled"] or not account["dashboard_password_hash"]:
+            return False
+        return verify_secret(password, account["dashboard_password_hash"])

karldns/store/metrics.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+class MetricsMixin:
+    def increment_metric(self, name: str, amount: float = 1.0) -> None:
+        now = datetime.now(UTC).isoformat()
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO service_metrics(name, value, updated_at)
+                VALUES (?, ?, ?)
+                ON CONFLICT(name) DO UPDATE SET
+                  value=value + excluded.value,
+                  updated_at=excluded.updated_at
+                """,
+                (name, amount, now),
+            )
+
+    def set_metric(self, name: str, value: float) -> None:
+        now = datetime.now(UTC).isoformat()
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO service_metrics(name, value, updated_at)
+                VALUES (?, ?, ?)
+                ON CONFLICT(name) DO UPDATE SET
+                  value=excluded.value,
+                  updated_at=excluded.updated_at
+                """,
+                (name, value, now),
+            )
+
+    def get_service_metrics(self) -> dict[str, float]:
+        with self.connect() as conn:
+            rows = conn.execute("SELECT name, value FROM service_metrics").fetchall()
+        return {str(row["name"]): float(row["value"]) for row in rows}
+
+    def record_update_metrics(
+        self,
+        latency_ms: float,
+        *,
+        is_success: bool = False,
+        is_dns_failure: bool = False,
+        is_reconcile_failure: bool = False,
+        is_bad_ip: bool = False,
+    ) -> None:
+        increments = {
+            "update_requests_total": 1,
+            "update_latency_ms_total": latency_ms,
+            "update_latency_samples_total": 1,
+        }
+        if is_success:
+            increments["update_success_total"] = 1
+        if is_dns_failure:
+            increments["dns_failures_total"] = 1
+        if is_reconcile_failure:
+            increments["dns_reconcile_failures_total"] = 1
+        if is_bad_ip:
+            increments["bad_ip_total"] = 1
+
+        now = datetime.now(UTC).isoformat()
+        with self.connect() as conn:
+            conn.executemany(
+                """
+                INSERT INTO service_metrics(name, value, updated_at)
+                VALUES (?, ?, ?)
+                ON CONFLICT(name) DO UPDATE SET
+                  value=value + excluded.value,
+                  updated_at=excluded.updated_at
+                """,
+                [(name, value, now) for name, value in increments.items()],
+            )
+            conn.execute(
+                """
+                INSERT INTO service_metrics(name, value, updated_at)
+                VALUES ('last_update_latency_ms', ?, ?)
+                ON CONFLICT(name) DO UPDATE SET
+                  value=excluded.value,
+                  updated_at=excluded.updated_at
+                """,
+                (latency_ms, now),
+            )

karldns/store/rate_limit.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import time
+from datetime import UTC, datetime, timedelta
+
+from .types import CleanupRunRow
+
+RATE_LIMIT_FLUSH_SECONDS = 10.0
+
+
+class RateLimitCleanupMixin:
+    def list_cleanup_runs(self, limit: int = 20, offset: int = 0) -> list[CleanupRunRow]:
+        with self.connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT created_at, unused_accounts_deleted
+                FROM cleanup_runs
+                ORDER BY created_at DESC
+                LIMIT ? OFFSET ?
+                """,
+                (limit, offset),
+            ).fetchall()
+        return [CleanupRunRow(**dict(row)) for row in rows]
+
+    def count_cleanup_runs(self) -> int:
+        with self.connect() as conn:
+            row = conn.execute("SELECT COUNT(*) FROM cleanup_runs").fetchone()
+        return int(row[0])
+
+    def allow_rate_limit(self, key: str, limit: int) -> bool:
+        if limit <= 0:
+            return False
+
+        now = time.time()
+        window = int(now) // 60
+        refill_rate = limit / 60.0
+        with self._rate_limit_lock:
+            bucket = self._rate_limit_buckets.get(key)
+            if bucket is None:
+                bucket = {"tokens": float(limit), "updated_at": now, "window": window}
+            else:
+                elapsed_seconds = max(0.0, now - float(bucket["updated_at"]))
+                bucket["tokens"] = min(float(limit), float(bucket["tokens"]) + elapsed_seconds * refill_rate)
+                bucket["updated_at"] = now
+                bucket["window"] = window
+
+            if float(bucket["tokens"]) < 1.0:
+                self._rate_limit_buckets[key] = bucket
+                return False
+
+            bucket["tokens"] = float(bucket["tokens"]) - 1.0
+            self._rate_limit_buckets[key] = bucket
+            dirty_key = (key, window)
+            self._rate_limit_dirty_counts[dirty_key] = self._rate_limit_dirty_counts.get(dirty_key, 0) + 1
+            self._prune_memory_rate_limits(now)
+
+        self._flush_rate_limits_if_due()
+        return True
+
+    def flush_rate_limits(self) -> None:
+        with self._rate_limit_lock:
+            dirty_counts = self._rate_limit_dirty_counts
+            self._rate_limit_dirty_counts = {}
+            self._last_rate_limit_flush = time.monotonic()
+
+        if not dirty_counts:
+            return
+
+        try:
+            with self.connect() as conn:
+                conn.executemany(
+                    """
+                    INSERT INTO rate_limits(key, window, count)
+                    VALUES (?, ?, ?)
+                    ON CONFLICT(key, window) DO UPDATE SET count=count + excluded.count
+                    """,
+                    [(key, window, count) for (key, window), count in dirty_counts.items()],
+                )
+        except Exception:
+            with self._rate_limit_lock:
+                for dirty_key, count in dirty_counts.items():
+                    self._rate_limit_dirty_counts[dirty_key] = self._rate_limit_dirty_counts.get(dirty_key, 0) + count
+            raise
+
+    def _flush_rate_limits_if_due(self) -> None:
+        if time.monotonic() - self._last_rate_limit_flush < RATE_LIMIT_FLUSH_SECONDS:
+            return
+        self.flush_rate_limits()
+
+    def _prune_memory_rate_limits(self, now: float) -> None:
+        stale_before = now - 120
+        stale_keys = [
+            key
+            for key, bucket in self._rate_limit_buckets.items()
+            if float(bucket["updated_at"]) < stale_before and float(bucket["tokens"]) >= 1.0
+        ]
+        for key in stale_keys:
+            del self._rate_limit_buckets[key]
+
+    def prune_rate_limit_storage(self) -> None:
+        current_window = int(time.time()) // 60
+        should_prune = self._should_prune_rate_limits(current_window)
+        if not should_prune:
+            return
+        with self.connect() as conn:
+            conn.execute("DELETE FROM rate_limits WHERE window < ?", (current_window - 2,))
+
+    def _should_prune_rate_limits(self, window: int) -> bool:
+        if self._last_rate_limit_prune_window == window:
+            return False
+        with self._rate_limit_prune_lock:
+            if self._last_rate_limit_prune_window == window:
+                return False
+            self._last_rate_limit_prune_window = window
+            return True
+
+    def cleanup(
+        self,
+        unused_account_hours: int,
+        event_history_hours: int = 24 * 180,
+        pending_account_hours: int = 24,
+    ) -> dict[str, int]:
+        self.flush_rate_limits()
+        unused_account_cutoff = (datetime.now(UTC) - timedelta(hours=unused_account_hours)).isoformat()
+        pending_account_cutoff = (datetime.now(UTC) - timedelta(hours=pending_account_hours)).isoformat()
+        event_history_cutoff = (datetime.now(UTC) - timedelta(hours=event_history_hours)).isoformat()
+        with self.connect() as conn:
+            account_cursor = conn.execute(
+                """
+                DELETE FROM accounts
+                WHERE (
+                    accepted_at IS NULL
+                    AND created_at < ?
+                  )
+                  OR (
+                    accepted_at IS NOT NULL
+                    AND created_at < ?
+                    AND NOT EXISTS (
+                      SELECT 1 FROM records WHERE records.hostname = accounts.hostname
+                    )
+                  )
+                """,
+                (pending_account_cutoff, unused_account_cutoff),
+            )
+            rollup_cursor = conn.execute(
+                "DELETE FROM update_event_rollups WHERE last_seen_at < ?",
+                (unused_account_cutoff,),
+            )
+            event_cursor = conn.execute(
+                "DELETE FROM update_events WHERE created_at < ?",
+                (event_history_cutoff,),
+            )
+            current_window = int(time.time()) // 60
+            conn.execute("DELETE FROM rate_limits WHERE window < ?", (current_window - 60,))
+            conn.execute(
+                """
+                INSERT INTO cleanup_runs(created_at, unused_accounts_deleted)
+                VALUES (?, ?)
+                """,
+                (datetime.now(UTC).isoformat(), account_cursor.rowcount),
+            )
+        return {
+            "unused_accounts": account_cursor.rowcount,
+            "event_rollups": rollup_cursor.rowcount,
+            "update_events": event_cursor.rowcount,
+        }

karldns/store/records.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import sqlite3
+from datetime import UTC, datetime
+
+from ..models import UpdateResult
+from .types import UpdateEventRow
+
+
+class RecordsEventsMixin:
+    def upsert(
+        self,
+        hostname: str,
+        ipv4: str | None,
+        ipv6: str | None,
+        update_ipv4: bool = True,
+        update_ipv6: bool = True,
+    ) -> UpdateResult:
+        now = datetime.now(UTC).isoformat()
+        with self.connect() as conn:
+            existing = conn.execute("SELECT ipv4, ipv6 FROM records WHERE hostname = ?", (hostname,)).fetchone()
+            current_ipv4 = existing["ipv4"] if existing else None
+            current_ipv6 = existing["ipv6"] if existing else None
+            effective_ipv4 = ipv4 if update_ipv4 else current_ipv4
+            effective_ipv6 = ipv6 if update_ipv6 else current_ipv6
+            changed = existing is None or current_ipv4 != effective_ipv4 or current_ipv6 != effective_ipv6
+            conn.execute(
+                """
+                INSERT INTO records(hostname, ipv4, ipv6, updated_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(hostname) DO UPDATE SET
+                  ipv4=excluded.ipv4,
+                  ipv6=excluded.ipv6,
+                  updated_at=excluded.updated_at
+                """,
+                (hostname, effective_ipv4, effective_ipv6, now),
+            )
+        return UpdateResult(
+            hostname=hostname,
+            ipv4=effective_ipv4,
+            ipv6=effective_ipv6,
+            changed=changed,
+            update_ipv4=update_ipv4,
+            update_ipv6=update_ipv6,
+        )
+
+    def commit_update_result(self, result: UpdateResult) -> UpdateResult:
+        now = datetime.now(UTC).isoformat()
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO records(hostname, ipv4, ipv6, updated_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(hostname) DO UPDATE SET
+                  ipv4=excluded.ipv4,
+                  ipv6=excluded.ipv6,
+                  updated_at=excluded.updated_at
+                """,
+                (result.hostname, result.ipv4, result.ipv6, now),
+            )
+        return result
+
+    def preview_update(
+        self,
+        hostname: str,
+        ipv4: str | None,
+        ipv6: str | None,
+        update_ipv4: bool = True,
+        update_ipv6: bool = True,
+    ) -> UpdateResult:
+        with self.connect() as conn:
+            existing = conn.execute("SELECT ipv4, ipv6 FROM records WHERE hostname = ?", (hostname,)).fetchone()
+        current_ipv4 = existing["ipv4"] if existing else None
+        current_ipv6 = existing["ipv6"] if existing else None
+        effective_ipv4 = ipv4 if update_ipv4 else current_ipv4
+        effective_ipv6 = ipv6 if update_ipv6 else current_ipv6
+        changed = existing is None or current_ipv4 != effective_ipv4 or current_ipv6 != effective_ipv6
+        return UpdateResult(
+            hostname=hostname,
+            ipv4=effective_ipv4,
+            ipv6=effective_ipv6,
+            changed=changed,
+            update_ipv4=update_ipv4,
+            update_ipv6=update_ipv6,
+        )
+
+    def list_records(self) -> list[dict[str, str | None]]:
+        return self.list_records_page(limit=10_000, offset=0)
+
+    def list_records_page(self, limit: int = 100, offset: int = 0) -> list[dict[str, str | None]]:
+        with self.connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT hostname, ipv4, ipv6, updated_at
+                FROM records
+                ORDER BY hostname
+                LIMIT ? OFFSET ?
+                """,
+                (limit, offset),
+            ).fetchall()
+        return [dict(row) for row in rows]
+
+    def count_records(self) -> int:
+        with self.connect() as conn:
+            row = conn.execute("SELECT COUNT(*) FROM records").fetchone()
+        return int(row[0])
+
+    def log_update_event(
+        self,
+        hostname: str,
+        ipv4: str | None,
+        ipv6: str | None,
+        status: str,
+        detail: str,
+        source_ip: str,
+    ) -> None:
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO update_events(hostname, ipv4, ipv6, status, detail, source_ip, created_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (hostname, ipv4, ipv6, status, detail[:500], source_ip, datetime.now(UTC).isoformat()),
+            )
+
+    def log_update_rollup(
+        self,
+        hostname: str,
+        ipv4: str | None,
+        ipv6: str | None,
+        status: str,
+        detail: str,
+        source_ip: str,
+    ) -> None:
+        now = datetime.now(UTC).isoformat()
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO update_event_rollups(
+                  hostname, ipv4, ipv6, status, detail, source_ip, first_seen_at, last_seen_at, count
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1)
+                ON CONFLICT(hostname, ipv4, ipv6, status, detail, source_ip) DO UPDATE SET
+                  last_seen_at=excluded.last_seen_at,
+                  count=count + 1
+                """,
+                (hostname, ipv4 or "", ipv6 or "", status, detail[:500], source_ip, now, now),
+            )
+
+    def list_update_events(self, limit: int = 100, offset: int = 0) -> list[UpdateEventRow]:
+        return self.list_update_events_page(limit=limit, offset=offset)
+
+    def list_update_events_page(self, limit: int = 100, offset: int = 0) -> list[UpdateEventRow]:
+        with self.connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT hostname, ipv4, ipv6, status, detail, source_ip, created_at, count
+                FROM (
+                    SELECT hostname, ipv4, ipv6, status, detail, source_ip, created_at, 1 AS count
+                    FROM update_events
+                    UNION ALL
+                    SELECT hostname, ipv4, ipv6, status, detail, source_ip, last_seen_at AS created_at, count
+                    FROM update_event_rollups
+                )
+                ORDER BY created_at DESC
+                LIMIT ? OFFSET ?
+                """,
+                (limit, offset),
+            ).fetchall()
+        return [dict(row) for row in rows]
+
+    def list_update_events_before(self, limit: int = 100, before: str | None = None) -> list[UpdateEventRow]:
+        where_clause = "WHERE created_at < ?" if before else ""
+        params: tuple[object, ...] = (before, limit) if before else (limit,)
+        with self.connect() as conn:
+            rows = conn.execute(
+                f"""
+                SELECT hostname, ipv4, ipv6, status, detail, source_ip, created_at, count
+                FROM (
+                    SELECT hostname, ipv4, ipv6, status, detail, source_ip, created_at, 1 AS count
+                    FROM update_events
+                    UNION ALL
+                    SELECT hostname, ipv4, ipv6, status, detail, source_ip, last_seen_at AS created_at, count
+                    FROM update_event_rollups
+                )
+                {where_clause}
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                params,
+            ).fetchall()
+        return [dict(row) for row in rows]
+
+    def count_update_events(self) -> int:
+        with self.connect() as conn:
+            event_count = conn.execute("SELECT COUNT(*) FROM update_events").fetchone()[0]
+            rollup_count = conn.execute("SELECT COUNT(*) FROM update_event_rollups").fetchone()[0]
+        return int(event_count) + int(rollup_count)
+
+    def list_update_events_for_hostname(self, hostname: str, limit: int = 25) -> list[UpdateEventRow]:
+        with self.connect() as conn:
+            event_rows = conn.execute(
+                """
+                SELECT hostname, ipv4, ipv6, status, detail, source_ip, created_at, 1 AS count
+                FROM update_events
+                WHERE hostname = ?
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                (hostname, limit),
+            ).fetchall()
+            rollup_rows = conn.execute(
+                """
+                SELECT hostname, ipv4, ipv6, status, detail, source_ip, last_seen_at AS created_at, count
+                FROM update_event_rollups
+                WHERE hostname = ?
+                ORDER BY last_seen_at DESC
+                LIMIT ?
+                """,
+                (hostname, limit),
+            ).fetchall()
+        return _merge_event_rows(event_rows, rollup_rows, limit, 0)
+
+
+def _merge_event_rows(
+    event_rows: list[sqlite3.Row],
+    rollup_rows: list[sqlite3.Row],
+    limit: int,
+    offset: int,
+) -> list[UpdateEventRow]:
+    rows = [dict(row) for row in event_rows]
+    rows.extend(dict(row) for row in rollup_rows)
+    rows.sort(key=lambda row: str(row["created_at"]), reverse=True)
+    return rows[offset : offset + limit]

karldns/store/scheduler.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from .types import ScheduledTaskRow
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _iso(value: datetime) -> str:
+    return value.isoformat()
+
+
+class SchedulerMixin:
+    def ensure_scheduled_task(self, name: str, interval_seconds: int) -> None:
+        now = _now()
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO scheduled_tasks(name, interval_seconds, next_run_at, updated_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(name) DO UPDATE SET
+                  interval_seconds=excluded.interval_seconds,
+                  updated_at=excluded.updated_at
+                """,
+                (name, interval_seconds, _iso(now), _iso(now)),
+            )
+
+    def acquire_due_task(self, name: str, lease_owner: str, lease_seconds: int) -> bool:
+        now = _now()
+        lease_expires_at = now + timedelta(seconds=lease_seconds)
+        with self.connect() as conn:
+            cursor = conn.execute(
+                """
+                UPDATE scheduled_tasks
+                SET lease_owner = ?,
+                    lease_expires_at = ?,
+                    last_started_at = ?,
+                    last_status = 'running',
+                    last_error = '',
+                    updated_at = ?
+                WHERE name = ?
+                  AND next_run_at <= ?
+                  AND (lease_expires_at IS NULL OR lease_expires_at <= ?)
+                """,
+                (
+                    lease_owner,
+                    _iso(lease_expires_at),
+                    _iso(now),
+                    _iso(now),
+                    name,
+                    _iso(now),
+                    _iso(now),
+                ),
+            )
+        return cursor.rowcount == 1
+
+    def complete_scheduled_task(
+        self,
+        name: str,
+        interval_seconds: int,
+        success: bool,
+        error: str = "",
+    ) -> None:
+        now = _now()
+        next_run_at = now + timedelta(seconds=interval_seconds)
+        status = "ok" if success else "error"
+        with self.connect() as conn:
+            conn.execute(
+                """
+                UPDATE scheduled_tasks
+                SET next_run_at = ?,
+                    lease_owner = NULL,
+                    lease_expires_at = NULL,
+                    last_finished_at = ?,
+                    last_status = ?,
+                    last_error = ?,
+                    interval_seconds = ?,
+                    updated_at = ?
+                WHERE name = ?
+                """,
+                (_iso(next_run_at), _iso(now), status, error[:500], interval_seconds, _iso(now), name),
+            )
+
+    def list_scheduled_tasks(self) -> list[ScheduledTaskRow]:
+        with self.connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT name, interval_seconds, next_run_at, lease_owner, lease_expires_at,
+                       last_started_at, last_finished_at, last_status, last_error, updated_at
+                FROM scheduled_tasks
+                ORDER BY name
+                """
+            ).fetchall()
+        return [ScheduledTaskRow(**dict(row)) for row in rows]

karldns/store/schema.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import secrets
+import sqlite3
+from pathlib import Path
+
+from ..security import hash_lookup_token
+
+BUSY_TIMEOUT_MS = 10_000
+CACHE_SIZE_KIB = 20_000
+MMAP_SIZE_BYTES = 256 * 1024 * 1024
+WAL_AUTOCHECKPOINT_PAGES = 1_000
+SCHEMA_VERSION = 3
+
+
+def connect_database(database_path: Path) -> sqlite3.Connection:
+    if str(database_path) != ":memory:":
+        database_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(database_path, check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    configure_connection(conn)
+    return conn
+
+
+def configure_connection(conn: sqlite3.Connection) -> None:
+    conn.execute("PRAGMA foreign_keys = ON")
+    conn.execute(f"PRAGMA busy_timeout = {BUSY_TIMEOUT_MS}")
+    conn.execute("PRAGMA temp_store = MEMORY")
+    conn.execute(f"PRAGMA cache_size = -{CACHE_SIZE_KIB}")
+    conn.execute(f"PRAGMA mmap_size = {MMAP_SIZE_BYTES}")
+    conn.execute("PRAGMA synchronous = NORMAL")
+    conn.execute(f"PRAGMA wal_autocheckpoint = {WAL_AUTOCHECKPOINT_PAGES}")
+
+
+def initialize_schema(conn: sqlite3.Connection) -> None:
+    configure_connection(conn)
+    schema_version = conn.execute("PRAGMA user_version").fetchone()[0]
+    conn.execute("PRAGMA journal_mode = WAL")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS records (
+          hostname TEXT PRIMARY KEY,
+          ipv4 TEXT,
+          ipv6 TEXT,
+          updated_at TEXT NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS update_events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          hostname TEXT NOT NULL,
+          ipv4 TEXT,
+          ipv6 TEXT,
+          status TEXT NOT NULL,
+          detail TEXT NOT NULL,
+          source_ip TEXT NOT NULL,
+          created_at TEXT NOT NULL
+        )
+        """
+    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_update_events_created_at ON update_events(created_at)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_update_events_hostname_created_at ON update_events(hostname, created_at DESC)")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS update_event_rollups (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          hostname TEXT NOT NULL,
+          ipv4 TEXT,
+          ipv6 TEXT,
+          status TEXT NOT NULL,
+          detail TEXT NOT NULL,
+          source_ip TEXT NOT NULL,
+          first_seen_at TEXT NOT NULL,
+          last_seen_at TEXT NOT NULL,
+          count INTEGER NOT NULL,
+          UNIQUE(hostname, ipv4, ipv6, status, detail, source_ip)
+        )
+        """
+    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_update_event_rollups_last_seen_at ON update_event_rollups(last_seen_at)")
+    conn.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_update_event_rollups_hostname_last_seen_at
+        ON update_event_rollups(hostname, last_seen_at DESC)
+        """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS cleanup_runs (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          created_at TEXT NOT NULL,
+          unused_accounts_deleted INTEGER NOT NULL
+        )
+        """
+    )
+    _migrate_cleanup_runs_schema(conn)
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_cleanup_runs_created_at ON cleanup_runs(created_at)")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS scheduled_tasks (
+          name TEXT PRIMARY KEY,
+          interval_seconds INTEGER NOT NULL,
+          next_run_at TEXT NOT NULL,
+          lease_owner TEXT,
+          lease_expires_at TEXT,
+          last_started_at TEXT,
+          last_finished_at TEXT,
+          last_status TEXT NOT NULL DEFAULT 'pending',
+          last_error TEXT NOT NULL DEFAULT '',
+          updated_at TEXT NOT NULL
+        )
+        """
+    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_scheduled_tasks_next_run_at ON scheduled_tasks(next_run_at)")
+    conn.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_scheduled_tasks_due
+        ON scheduled_tasks(next_run_at, lease_expires_at)
+        """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS rate_limits (
+          key TEXT NOT NULL,
+          window INTEGER NOT NULL,
+          count INTEGER NOT NULL,
+          PRIMARY KEY(key, window)
+        )
+        """
+    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_rate_limits_window ON rate_limits(window)")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS service_metrics (
+          name TEXT PRIMARY KEY,
+          value REAL NOT NULL,
+          updated_at TEXT NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS accounts (
+          hostname TEXT PRIMARY KEY,
+          update_slug TEXT NOT NULL UNIQUE,
+          management_hash TEXT UNIQUE,
+          dashboard_password_hash TEXT,
+          created_at TEXT NOT NULL,
+          accepted_at TEXT,
+          disabled INTEGER NOT NULL DEFAULT 0
+        )
+        """
+    )
+    _ensure_column(conn, "accounts", "update_slug", "TEXT")
+    _ensure_column(conn, "accounts", "management_hash", "TEXT")
+    _ensure_column(conn, "accounts", "dashboard_password_hash", "TEXT")
+    _ensure_column(conn, "accounts", "accepted_at", "TEXT")
+    if schema_version < 2:
+        conn.execute("UPDATE accounts SET accepted_at = created_at WHERE accepted_at IS NULL")
+    for row in conn.execute("SELECT hostname FROM accounts WHERE update_slug IS NULL OR update_slug = ''"):
+        conn.execute("UPDATE accounts SET update_slug = ? WHERE hostname = ?", (secrets.token_urlsafe(32), row[0]))
+    for row in conn.execute("SELECT hostname FROM accounts WHERE management_hash IS NULL OR management_hash = ''"):
+        conn.execute(
+            "UPDATE accounts SET management_hash = ? WHERE hostname = ?",
+            (hash_lookup_token(secrets.token_urlsafe(32)), row[0]),
+        )
+    _migrate_accounts_schema(conn)
+    conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_accounts_update_slug ON accounts(update_slug)")
+    conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_accounts_management_hash ON accounts(management_hash)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_accounts_accepted_at ON accounts(accepted_at)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_accounts_created_at ON accounts(created_at)")
+    if schema_version < SCHEMA_VERSION:
+        conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+    conn.execute("PRAGMA optimize")
+
+
+def _ensure_column(conn: sqlite3.Connection, table: str, column: str, definition: str) -> None:
+    columns = {row[1] for row in conn.execute(f"PRAGMA table_info({table})")}
+    if column not in columns:
+        conn.execute(f"ALTER TABLE {table} ADD COLUMN {column} {definition}")
+
+
+def _migrate_accounts_schema(conn: sqlite3.Connection) -> None:
+    columns = {row[1] for row in conn.execute("PRAGMA table_info(accounts)")}
+    if "username" not in columns and "token_hash" not in columns:
+        return
+    conn.execute("DROP INDEX IF EXISTS idx_accounts_update_slug")
+    conn.execute("DROP INDEX IF EXISTS idx_accounts_management_hash")
+    conn.execute("DROP INDEX IF EXISTS idx_accounts_accepted_at")
+    conn.execute("DROP INDEX IF EXISTS idx_accounts_created_at")
+    conn.execute("DROP INDEX IF EXISTS idx_accounts_hostname_username")
+    conn.execute(
+        """
+        CREATE TABLE accounts_new (
+          hostname TEXT PRIMARY KEY,
+          update_slug TEXT NOT NULL UNIQUE,
+          management_hash TEXT UNIQUE,
+          dashboard_password_hash TEXT,
+          created_at TEXT NOT NULL,
+          accepted_at TEXT,
+          disabled INTEGER NOT NULL DEFAULT 0
+        )
+        """
+    )
+    conn.execute(
+        """
+        INSERT INTO accounts_new(hostname, update_slug, management_hash, dashboard_password_hash, created_at, accepted_at, disabled)
+        SELECT hostname, update_slug, management_hash, dashboard_password_hash, created_at, accepted_at, disabled
+        FROM accounts
+        """
+    )
+    conn.execute("DROP TABLE accounts")
+    conn.execute("ALTER TABLE accounts_new RENAME TO accounts")
+
+
+def _migrate_cleanup_runs_schema(conn: sqlite3.Connection) -> None:
+    columns = {row[1] for row in conn.execute("PRAGMA table_info(cleanup_runs)")}
+    if columns <= {"id", "created_at", "unused_accounts_deleted"}:
+        return
+    conn.execute("DROP INDEX IF EXISTS idx_cleanup_runs_created_at")
+    conn.execute(
+        """
+        CREATE TABLE cleanup_runs_new (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          created_at TEXT NOT NULL,
+          unused_accounts_deleted INTEGER NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        """
+        INSERT INTO cleanup_runs_new(id, created_at, unused_accounts_deleted)
+        SELECT id, created_at, unused_accounts_deleted
+        FROM cleanup_runs
+        """
+    )
+    conn.execute("DROP TABLE cleanup_runs")
+    conn.execute("ALTER TABLE cleanup_runs_new RENAME TO cleanup_runs")

karldns/store/types.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class AccountRow(TypedDict, total=False):
+    hostname: str
+    update_slug: str
+    management_slug: str
+    dashboard_password_hash: str | None
+    created_at: str
+    accepted_at: str | None
+    disabled: int
+    ipv4: str | None
+    ipv6: str | None
+    updated_at: str | None
+
+
+class UpdateEventRow(TypedDict, total=False):
+    hostname: str
+    ipv4: str | None
+    ipv6: str | None
+    status: str
+    detail: str
+    source_ip: str
+    created_at: str
+    count: int
+
+
+class CleanupRunRow(TypedDict):
+    created_at: str
+    unused_accounts_deleted: int
+
+
+class ScheduledTaskRow(TypedDict, total=False):
+    name: str
+    interval_seconds: int
+    next_run_at: str
+    lease_owner: str | None
+    lease_expires_at: str | None
+    last_started_at: str | None
+    last_finished_at: str | None
+    last_status: str
+    last_error: str
+    updated_at: str