Add SQLite persistence and write-through gRPC mutations

Database (internal/db) stores listeners, routes, and firewall rules with
WAL mode, foreign keys, and idempotent migrations. First run seeds from
TOML config; subsequent runs load from DB as source of truth.

gRPC admin API now writes to the database before updating in-memory state
(write-through cache pattern). Adds snapshot command for VACUUM INTO
backups. Refactors firewall.New to accept raw rule slices instead of
config struct for flexibility.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

internal/db/db.go

@@ -0,0 +1,63 @@
+package db
+
+import (
+	"database/sql"
+	"fmt"
+	"os"
+
+	_ "modernc.org/sqlite"
+)
+
+// Store wraps a SQLite database connection for mc-proxy persistence.
+type Store struct {
+	db *sql.DB
+}
+
+// Open opens (or creates) the SQLite database at path with WAL mode,
+// foreign keys, and a busy timeout. The file is created with 0600 permissions.
+func Open(path string) (*Store, error) {
+	// Ensure the file has restrictive permissions if it doesn't exist.
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0600)
+		if err != nil {
+			return nil, fmt.Errorf("creating database file: %w", err)
+		}
+		f.Close()
+	}
+
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		return nil, fmt.Errorf("opening database: %w", err)
+	}
+
+	// Apply connection pragmas.
+	pragmas := []string{
+		"PRAGMA journal_mode = WAL",
+		"PRAGMA foreign_keys = ON",
+		"PRAGMA busy_timeout = 5000",
+	}
+	for _, p := range pragmas {
+		if _, err := db.Exec(p); err != nil {
+			db.Close()
+			return nil, fmt.Errorf("setting pragma %q: %w", p, err)
+		}
+	}
+
+	return &Store{db: db}, nil
+}
+
+// Close closes the database connection.
+func (s *Store) Close() error {
+	return s.db.Close()
+}
+
+// IsEmpty returns true if the listeners table has no rows.
+// Used to determine if the database needs seeding from config.
+func (s *Store) IsEmpty() (bool, error) {
+	var count int
+	err := s.db.QueryRow("SELECT COUNT(*) FROM listeners").Scan(&count)
+	if err != nil {
+		return false, err
+	}
+	return count == 0, nil
+}

internal/db/db_test.go

@@ -0,0 +1,331 @@
+package db
+
+import (
+	"path/filepath"
+	"testing"
+
+	"git.wntrmute.dev/kyle/mc-proxy/internal/config"
+)
+
+func openTestDB(t *testing.T) *Store {
+	t.Helper()
+	dir := t.TempDir()
+	store, err := Open(filepath.Join(dir, "test.db"))
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if err := store.Migrate(); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	t.Cleanup(func() { store.Close() })
+	return store
+}
+
+func TestMigrate(t *testing.T) {
+	store := openTestDB(t)
+
+	// Running migrate again should be idempotent.
+	if err := store.Migrate(); err != nil {
+		t.Fatalf("second migrate: %v", err)
+	}
+}
+
+func TestIsEmpty(t *testing.T) {
+	store := openTestDB(t)
+
+	empty, err := store.IsEmpty()
+	if err != nil {
+		t.Fatalf("is empty: %v", err)
+	}
+	if !empty {
+		t.Fatal("expected empty database")
+	}
+
+	if _, err := store.CreateListener(":443"); err != nil {
+		t.Fatalf("create listener: %v", err)
+	}
+
+	empty, err = store.IsEmpty()
+	if err != nil {
+		t.Fatalf("is empty: %v", err)
+	}
+	if empty {
+		t.Fatal("expected non-empty database")
+	}
+}
+
+func TestListenerCRUD(t *testing.T) {
+	store := openTestDB(t)
+
+	id, err := store.CreateListener(":443")
+	if err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if id == 0 {
+		t.Fatal("expected non-zero ID")
+	}
+
+	listeners, err := store.ListListeners()
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(listeners) != 1 {
+		t.Fatalf("got %d listeners, want 1", len(listeners))
+	}
+	if listeners[0].Addr != ":443" {
+		t.Fatalf("got addr %q, want %q", listeners[0].Addr, ":443")
+	}
+
+	l, err := store.GetListenerByAddr(":443")
+	if err != nil {
+		t.Fatalf("get by addr: %v", err)
+	}
+	if l.ID != id {
+		t.Fatalf("got ID %d, want %d", l.ID, id)
+	}
+
+	if err := store.DeleteListener(id); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+
+	listeners, err = store.ListListeners()
+	if err != nil {
+		t.Fatalf("list after delete: %v", err)
+	}
+	if len(listeners) != 0 {
+		t.Fatalf("got %d listeners after delete, want 0", len(listeners))
+	}
+}
+
+func TestListenerDuplicateAddr(t *testing.T) {
+	store := openTestDB(t)
+
+	if _, err := store.CreateListener(":443"); err != nil {
+		t.Fatalf("first create: %v", err)
+	}
+	if _, err := store.CreateListener(":443"); err == nil {
+		t.Fatal("expected error for duplicate addr")
+	}
+}
+
+func TestRouteCRUD(t *testing.T) {
+	store := openTestDB(t)
+
+	listenerID, err := store.CreateListener(":443")
+	if err != nil {
+		t.Fatalf("create listener: %v", err)
+	}
+
+	routeID, err := store.CreateRoute(listenerID, "example.com", "127.0.0.1:8443")
+	if err != nil {
+		t.Fatalf("create route: %v", err)
+	}
+	if routeID == 0 {
+		t.Fatal("expected non-zero route ID")
+	}
+
+	routes, err := store.ListRoutes(listenerID)
+	if err != nil {
+		t.Fatalf("list routes: %v", err)
+	}
+	if len(routes) != 1 {
+		t.Fatalf("got %d routes, want 1", len(routes))
+	}
+	if routes[0].Hostname != "example.com" {
+		t.Fatalf("got hostname %q, want %q", routes[0].Hostname, "example.com")
+	}
+
+	if err := store.DeleteRoute(listenerID, "example.com"); err != nil {
+		t.Fatalf("delete route: %v", err)
+	}
+
+	routes, err = store.ListRoutes(listenerID)
+	if err != nil {
+		t.Fatalf("list after delete: %v", err)
+	}
+	if len(routes) != 0 {
+		t.Fatalf("got %d routes after delete, want 0", len(routes))
+	}
+}
+
+func TestRouteDuplicateHostname(t *testing.T) {
+	store := openTestDB(t)
+
+	listenerID, _ := store.CreateListener(":443")
+	if _, err := store.CreateRoute(listenerID, "example.com", "127.0.0.1:8443"); err != nil {
+		t.Fatalf("first create: %v", err)
+	}
+	if _, err := store.CreateRoute(listenerID, "example.com", "127.0.0.1:9443"); err == nil {
+		t.Fatal("expected error for duplicate hostname on same listener")
+	}
+}
+
+func TestRouteCascadeDelete(t *testing.T) {
+	store := openTestDB(t)
+
+	listenerID, _ := store.CreateListener(":443")
+	store.CreateRoute(listenerID, "a.example.com", "127.0.0.1:8443")
+	store.CreateRoute(listenerID, "b.example.com", "127.0.0.1:9443")
+
+	if err := store.DeleteListener(listenerID); err != nil {
+		t.Fatalf("delete listener: %v", err)
+	}
+
+	routes, err := store.ListRoutes(listenerID)
+	if err != nil {
+		t.Fatalf("list routes: %v", err)
+	}
+	if len(routes) != 0 {
+		t.Fatalf("got %d routes after cascade delete, want 0", len(routes))
+	}
+}
+
+func TestFirewallRuleCRUD(t *testing.T) {
+	store := openTestDB(t)
+
+	id, err := store.CreateFirewallRule("ip", "192.0.2.1")
+	if err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if id == 0 {
+		t.Fatal("expected non-zero ID")
+	}
+
+	if _, err := store.CreateFirewallRule("cidr", "198.51.100.0/24"); err != nil {
+		t.Fatalf("create cidr: %v", err)
+	}
+	if _, err := store.CreateFirewallRule("country", "CN"); err != nil {
+		t.Fatalf("create country: %v", err)
+	}
+
+	rules, err := store.ListFirewallRules()
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(rules) != 3 {
+		t.Fatalf("got %d rules, want 3", len(rules))
+	}
+
+	if err := store.DeleteFirewallRule("ip", "192.0.2.1"); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+
+	rules, err = store.ListFirewallRules()
+	if err != nil {
+		t.Fatalf("list after delete: %v", err)
+	}
+	if len(rules) != 2 {
+		t.Fatalf("got %d rules after delete, want 2", len(rules))
+	}
+}
+
+func TestFirewallRuleDuplicate(t *testing.T) {
+	store := openTestDB(t)
+
+	if _, err := store.CreateFirewallRule("ip", "192.0.2.1"); err != nil {
+		t.Fatalf("first create: %v", err)
+	}
+	if _, err := store.CreateFirewallRule("ip", "192.0.2.1"); err == nil {
+		t.Fatal("expected error for duplicate rule")
+	}
+}
+
+func TestSeed(t *testing.T) {
+	store := openTestDB(t)
+
+	listeners := []config.Listener{
+		{
+			Addr: ":443",
+			Routes: []config.Route{
+				{Hostname: "a.example.com", Backend: "127.0.0.1:8443"},
+				{Hostname: "b.example.com", Backend: "127.0.0.1:9443"},
+			},
+		},
+		{
+			Addr: ":8443",
+			Routes: []config.Route{
+				{Hostname: "c.example.com", Backend: "127.0.0.1:18443"},
+			},
+		},
+	}
+
+	fw := config.Firewall{
+		BlockedIPs:       []string{"192.0.2.1"},
+		BlockedCIDRs:     []string{"198.51.100.0/24"},
+		BlockedCountries: []string{"cn", "KP"},
+	}
+
+	if err := store.Seed(listeners, fw); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	dbListeners, err := store.ListListeners()
+	if err != nil {
+		t.Fatalf("list listeners: %v", err)
+	}
+	if len(dbListeners) != 2 {
+		t.Fatalf("got %d listeners, want 2", len(dbListeners))
+	}
+
+	routes, err := store.ListRoutes(dbListeners[0].ID)
+	if err != nil {
+		t.Fatalf("list routes: %v", err)
+	}
+	if len(routes) != 2 {
+		t.Fatalf("got %d routes for listener 0, want 2", len(routes))
+	}
+
+	rules, err := store.ListFirewallRules()
+	if err != nil {
+		t.Fatalf("list firewall rules: %v", err)
+	}
+	if len(rules) != 4 {
+		t.Fatalf("got %d firewall rules, want 4", len(rules))
+	}
+}
+
+func TestSnapshot(t *testing.T) {
+	store := openTestDB(t)
+
+	store.CreateListener(":443")
+
+	dest := filepath.Join(t.TempDir(), "backup.db")
+	if err := store.Snapshot(dest); err != nil {
+		t.Fatalf("snapshot: %v", err)
+	}
+
+	// Open the snapshot and verify.
+	backup, err := Open(dest)
+	if err != nil {
+		t.Fatalf("open backup: %v", err)
+	}
+	defer backup.Close()
+
+	if err := backup.Migrate(); err != nil {
+		t.Fatalf("migrate backup: %v", err)
+	}
+
+	listeners, err := backup.ListListeners()
+	if err != nil {
+		t.Fatalf("list from backup: %v", err)
+	}
+	if len(listeners) != 1 {
+		t.Fatalf("backup has %d listeners, want 1", len(listeners))
+	}
+}
+
+func TestDeleteNonexistent(t *testing.T) {
+	store := openTestDB(t)
+
+	if err := store.DeleteListener(999); err == nil {
+		t.Fatal("expected error deleting nonexistent listener")
+	}
+
+	if err := store.DeleteRoute(999, "example.com"); err == nil {
+		t.Fatal("expected error deleting nonexistent route")
+	}
+
+	if err := store.DeleteFirewallRule("ip", "1.2.3.4"); err == nil {
+		t.Fatal("expected error deleting nonexistent firewall rule")
+	}
+}

internal/db/firewall.go

@@ -0,0 +1,57 @@
+package db
+
+import "fmt"
+
+// FirewallRule is a database firewall rule record.
+type FirewallRule struct {
+	ID    int64
+	Type  string // "ip", "cidr", "country"
+	Value string
+}
+
+// ListFirewallRules returns all firewall rules.
+func (s *Store) ListFirewallRules() ([]FirewallRule, error) {
+	rows, err := s.db.Query("SELECT id, type, value FROM firewall_rules ORDER BY type, value")
+	if err != nil {
+		return nil, fmt.Errorf("querying firewall rules: %w", err)
+	}
+	defer rows.Close()
+
+	var rules []FirewallRule
+	for rows.Next() {
+		var r FirewallRule
+		if err := rows.Scan(&r.ID, &r.Type, &r.Value); err != nil {
+			return nil, fmt.Errorf("scanning firewall rule: %w", err)
+		}
+		rules = append(rules, r)
+	}
+	return rules, rows.Err()
+}
+
+// CreateFirewallRule inserts a firewall rule and returns its ID.
+func (s *Store) CreateFirewallRule(ruleType, value string) (int64, error) {
+	result, err := s.db.Exec(
+		"INSERT INTO firewall_rules (type, value) VALUES (?, ?)",
+		ruleType, value,
+	)
+	if err != nil {
+		return 0, fmt.Errorf("inserting firewall rule: %w", err)
+	}
+	return result.LastInsertId()
+}
+
+// DeleteFirewallRule deletes a firewall rule by type and value.
+func (s *Store) DeleteFirewallRule(ruleType, value string) error {
+	result, err := s.db.Exec(
+		"DELETE FROM firewall_rules WHERE type = ? AND value = ?",
+		ruleType, value,
+	)
+	if err != nil {
+		return fmt.Errorf("deleting firewall rule: %w", err)
+	}
+	n, _ := result.RowsAffected()
+	if n == 0 {
+		return fmt.Errorf("firewall rule (%s, %s) not found", ruleType, value)
+	}
+	return nil
+}

internal/db/listeners.go

@@ -0,0 +1,61 @@
+package db
+
+import "fmt"
+
+// Listener is a database listener record.
+type Listener struct {
+	ID   int64
+	Addr string
+}
+
+// ListListeners returns all listeners.
+func (s *Store) ListListeners() ([]Listener, error) {
+	rows, err := s.db.Query("SELECT id, addr FROM listeners ORDER BY id")
+	if err != nil {
+		return nil, fmt.Errorf("querying listeners: %w", err)
+	}
+	defer rows.Close()
+
+	var listeners []Listener
+	for rows.Next() {
+		var l Listener
+		if err := rows.Scan(&l.ID, &l.Addr); err != nil {
+			return nil, fmt.Errorf("scanning listener: %w", err)
+		}
+		listeners = append(listeners, l)
+	}
+	return listeners, rows.Err()
+}
+
+// CreateListener inserts a listener and returns its ID.
+func (s *Store) CreateListener(addr string) (int64, error) {
+	result, err := s.db.Exec("INSERT INTO listeners (addr) VALUES (?)", addr)
+	if err != nil {
+		return 0, fmt.Errorf("inserting listener: %w", err)
+	}
+	return result.LastInsertId()
+}
+
+// DeleteListener deletes a listener by ID. Routes are cascade-deleted.
+func (s *Store) DeleteListener(id int64) error {
+	result, err := s.db.Exec("DELETE FROM listeners WHERE id = ?", id)
+	if err != nil {
+		return fmt.Errorf("deleting listener: %w", err)
+	}
+	n, _ := result.RowsAffected()
+	if n == 0 {
+		return fmt.Errorf("listener %d not found", id)
+	}
+	return nil
+}
+
+// GetListenerByAddr returns a listener by its address.
+func (s *Store) GetListenerByAddr(addr string) (Listener, error) {
+	var l Listener
+	err := s.db.QueryRow("SELECT id, addr FROM listeners WHERE addr = ?", addr).
+		Scan(&l.ID, &l.Addr)
+	if err != nil {
+		return Listener{}, fmt.Errorf("querying listener by addr %q: %w", addr, err)
+	}
+	return l, nil
+}

internal/db/migrations.go

@@ -0,0 +1,93 @@
+package db
+
+import (
+	"database/sql"
+	"fmt"
+)
+
+type migration struct {
+	version int
+	name    string
+	fn      func(tx *sql.Tx) error
+}
+
+var migrations = []migration{
+	{1, "create_core_tables", migrate001CreateCoreTables},
+}
+
+// Migrate runs all unapplied migrations sequentially.
+func (s *Store) Migrate() error {
+	// Ensure the migration tracking table exists.
+	_, err := s.db.Exec(`
+		CREATE TABLE IF NOT EXISTS schema_migrations (
+			version INTEGER PRIMARY KEY,
+			applied TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+		)
+	`)
+	if err != nil {
+		return fmt.Errorf("creating schema_migrations table: %w", err)
+	}
+
+	var current int
+	err = s.db.QueryRow("SELECT COALESCE(MAX(version), 0) FROM schema_migrations").Scan(&current)
+	if err != nil {
+		return fmt.Errorf("querying current migration version: %w", err)
+	}
+
+	for _, m := range migrations {
+		if m.version <= current {
+			continue
+		}
+
+		tx, err := s.db.Begin()
+		if err != nil {
+			return fmt.Errorf("beginning migration %d (%s): %w", m.version, m.name, err)
+		}
+
+		if err := m.fn(tx); err != nil {
+			tx.Rollback()
+			return fmt.Errorf("running migration %d (%s): %w", m.version, m.name, err)
+		}
+
+		if _, err := tx.Exec("INSERT INTO schema_migrations (version) VALUES (?)", m.version); err != nil {
+			tx.Rollback()
+			return fmt.Errorf("recording migration %d (%s): %w", m.version, m.name, err)
+		}
+
+		if err := tx.Commit(); err != nil {
+			return fmt.Errorf("committing migration %d (%s): %w", m.version, m.name, err)
+		}
+	}
+
+	return nil
+}
+
+func migrate001CreateCoreTables(tx *sql.Tx) error {
+	stmts := []string{
+		`CREATE TABLE IF NOT EXISTS listeners (
+			id   INTEGER PRIMARY KEY,
+			addr TEXT NOT NULL UNIQUE
+		)`,
+		`CREATE TABLE IF NOT EXISTS routes (
+			id          INTEGER PRIMARY KEY,
+			listener_id INTEGER NOT NULL REFERENCES listeners(id) ON DELETE CASCADE,
+			hostname    TEXT NOT NULL,
+			backend     TEXT NOT NULL,
+			UNIQUE(listener_id, hostname)
+		)`,
+		`CREATE INDEX IF NOT EXISTS idx_routes_listener ON routes(listener_id)`,
+		`CREATE TABLE IF NOT EXISTS firewall_rules (
+			id    INTEGER PRIMARY KEY,
+			type  TEXT NOT NULL CHECK(type IN ('ip', 'cidr', 'country')),
+			value TEXT NOT NULL,
+			UNIQUE(type, value)
+		)`,
+	}
+
+	for _, stmt := range stmts {
+		if _, err := tx.Exec(stmt); err != nil {
+			return err
+		}
+	}
+	return nil
+}

internal/db/routes.go

@@ -0,0 +1,61 @@
+package db
+
+import "fmt"
+
+// Route is a database route record.
+type Route struct {
+	ID         int64
+	ListenerID int64
+	Hostname   string
+	Backend    string
+}
+
+// ListRoutes returns all routes for a listener.
+func (s *Store) ListRoutes(listenerID int64) ([]Route, error) {
+	rows, err := s.db.Query(
+		"SELECT id, listener_id, hostname, backend FROM routes WHERE listener_id = ? ORDER BY hostname",
+		listenerID,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("querying routes: %w", err)
+	}
+	defer rows.Close()
+
+	var routes []Route
+	for rows.Next() {
+		var r Route
+		if err := rows.Scan(&r.ID, &r.ListenerID, &r.Hostname, &r.Backend); err != nil {
+			return nil, fmt.Errorf("scanning route: %w", err)
+		}
+		routes = append(routes, r)
+	}
+	return routes, rows.Err()
+}
+
+// CreateRoute inserts a route and returns its ID.
+func (s *Store) CreateRoute(listenerID int64, hostname, backend string) (int64, error) {
+	result, err := s.db.Exec(
+		"INSERT INTO routes (listener_id, hostname, backend) VALUES (?, ?, ?)",
+		listenerID, hostname, backend,
+	)
+	if err != nil {
+		return 0, fmt.Errorf("inserting route: %w", err)
+	}
+	return result.LastInsertId()
+}
+
+// DeleteRoute deletes a route by listener ID and hostname.
+func (s *Store) DeleteRoute(listenerID int64, hostname string) error {
+	result, err := s.db.Exec(
+		"DELETE FROM routes WHERE listener_id = ? AND hostname = ?",
+		listenerID, hostname,
+	)
+	if err != nil {
+		return fmt.Errorf("deleting route: %w", err)
+	}
+	n, _ := result.RowsAffected()
+	if n == 0 {
+		return fmt.Errorf("route %q not found on listener %d", hostname, listenerID)
+	}
+	return nil
+}

internal/db/seed.go

@@ -0,0 +1,56 @@
+package db
+
+import (
+	"fmt"
+	"strings"
+
+	"git.wntrmute.dev/kyle/mc-proxy/internal/config"
+)
+
+// Seed populates the database from TOML config data. Only called when the
+// database is empty (first run).
+func (s *Store) Seed(listeners []config.Listener, fw config.Firewall) error {
+	tx, err := s.db.Begin()
+	if err != nil {
+		return fmt.Errorf("beginning seed transaction: %w", err)
+	}
+	defer tx.Rollback()
+
+	for _, l := range listeners {
+		result, err := tx.Exec("INSERT INTO listeners (addr) VALUES (?)", l.Addr)
+		if err != nil {
+			return fmt.Errorf("seeding listener %q: %w", l.Addr, err)
+		}
+		listenerID, _ := result.LastInsertId()
+
+		for _, r := range l.Routes {
+			_, err := tx.Exec(
+				"INSERT INTO routes (listener_id, hostname, backend) VALUES (?, ?, ?)",
+				listenerID, strings.ToLower(r.Hostname), r.Backend,
+			)
+			if err != nil {
+				return fmt.Errorf("seeding route %q on listener %q: %w", r.Hostname, l.Addr, err)
+			}
+		}
+	}
+
+	for _, ip := range fw.BlockedIPs {
+		if _, err := tx.Exec("INSERT INTO firewall_rules (type, value) VALUES ('ip', ?)", ip); err != nil {
+			return fmt.Errorf("seeding blocked IP %q: %w", ip, err)
+		}
+	}
+
+	for _, cidr := range fw.BlockedCIDRs {
+		if _, err := tx.Exec("INSERT INTO firewall_rules (type, value) VALUES ('cidr', ?)", cidr); err != nil {
+			return fmt.Errorf("seeding blocked CIDR %q: %w", cidr, err)
+		}
+	}
+
+	for _, code := range fw.BlockedCountries {
+		if _, err := tx.Exec("INSERT INTO firewall_rules (type, value) VALUES ('country', ?)", strings.ToUpper(code)); err != nil {
+			return fmt.Errorf("seeding blocked country %q: %w", code, err)
+		}
+	}
+
+	return tx.Commit()
+}

internal/db/snapshot.go

@@ -0,0 +1,12 @@
+package db
+
+import "fmt"
+
+// Snapshot creates a consistent backup of the database using VACUUM INTO.
+func (s *Store) Snapshot(destPath string) error {
+	_, err := s.db.Exec("VACUUM INTO ?", destPath)
+	if err != nil {
+		return fmt.Errorf("snapshot to %q: %w", destPath, err)
+	}
+	return nil
+}