addrkit: deterministic address resolution service (Go)

- domain: address normalization/parsing, matching with explicit statuses
- adapters: SQLite registry store, ArcGIS outages client, optional LLM rewriter, HTTP API
- seed pipeline with duplicate handling and unparsed reporting
- CLI (seed/verify/resolve), systemd unit, OpenAPI contract, tests

cmd/addrkitd/main.go

@@ -0,0 +1,120 @@
+// Command addrkitd runs the address resolution service.
+//
+// It loads the canonical registry into memory, wires the optional adapters
+// (ArcGIS portal, LLM rewriter) and serves the versioned JSON API. The process
+// fails closed: if the registry cannot be loaded it exits rather than serving
+// an empty index.
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"git.totmin.ru/en2zmax/addrkit/internal/adapters/arcgis"
+	"git.totmin.ru/en2zmax/addrkit/internal/adapters/httpapi"
+	"git.totmin.ru/en2zmax/addrkit/internal/adapters/llm"
+	"git.totmin.ru/en2zmax/addrkit/internal/adapters/registrystore"
+	"git.totmin.ru/en2zmax/addrkit/internal/config"
+	"git.totmin.ru/en2zmax/addrkit/internal/domain/match"
+)
+
+func main() {
+	cfgPath := flag.String("config", "config.json", "path to the JSON config file")
+	flag.Parse()
+
+	cfg, err := config.Load(*cfgPath)
+	if err != nil {
+		slog.Error("config", "error", err)
+		os.Exit(1)
+	}
+
+	logger := newLogger(cfg.LogLevel)
+
+	version, entries, err := registrystore.Load(cfg.DataPath)
+	if err != nil {
+		// Fail closed: no registry, no service.
+		logger.Error("load registry", "error", err, "path", cfg.DataPath)
+		os.Exit(1)
+	}
+	logger.Info("registry loaded", "version", version, "entries", len(entries))
+
+	index := match.NewIndex(version, entries, match.Options{
+		FuzzyThreshold:  cfg.Resolve.FuzzyThreshold,
+		AmbiguityMargin: cfg.Resolve.AmbiguityMargin,
+		MaxCandidates:   cfg.Resolve.MaxCandidates,
+	})
+
+	var rewriter match.Rewriter
+	if cfg.LLM.Enabled {
+		rewriter = llm.New(cfg.LLM)
+		logger.Info("llm rewriter enabled", "url", cfg.LLM.URL, "model", cfg.LLM.Model)
+	}
+	resolver := match.NewResolver(index, rewriter)
+
+	portal := arcgis.New(
+		cfg.Portal.URL,
+		time.Duration(cfg.Portal.TimeoutSeconds)*time.Second,
+		cfg.Portal.Retries,
+	)
+
+	loc := operationalLocation()
+	srv := httpapi.New(resolver, portal, logger, loc)
+
+	httpServer := &http.Server{
+		Addr:              cfg.Addr,
+		Handler:           srv.Handler(),
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	go func() {
+		logger.Info("listening", "addr", cfg.Addr, "tz", loc.String())
+		if err := httpServer.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			logger.Error("serve", "error", err)
+			stop()
+		}
+	}()
+
+	<-ctx.Done()
+	logger.Info("shutting down")
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if err := httpServer.Shutdown(shutdownCtx); err != nil {
+		logger.Error("shutdown", "error", err)
+	}
+}
+
+func newLogger(level string) *slog.Logger {
+	var lvl slog.Level
+	switch level {
+	case "debug":
+		lvl = slog.LevelDebug
+	case "warn":
+		lvl = slog.LevelWarn
+	case "error":
+		lvl = slog.LevelError
+	default:
+		lvl = slog.LevelInfo
+	}
+	return slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: lvl}))
+}
+
+// operationalLocation returns Asia/Novosibirsk when the tz database is
+// available and falls back to a fixed UTC+7 offset otherwise (containers
+// without tzdata).
+func operationalLocation() *time.Location {
+	if loc, err := time.LoadLocation("Asia/Novosibirsk"); err == nil {
+		return loc
+	}
+	return time.FixedZone("Asia/Novosibirsk", 7*3600)
+}