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
2026-10-09 20:05:32 +07:00
commit 3be331bb65
34 changed files with 3446 additions and 0 deletions
@@ -0,0 +1,146 @@
+// Command addrkit is the operator CLI: it seeds the canonical registry from a
+// registry dump, verifies a built database and resolves a single address for
+// quick checks.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+
+	"git.totmin.ru/en2zmax/addrkit/internal/adapters/registrystore"
+	"git.totmin.ru/en2zmax/addrkit/internal/domain/match"
+	"git.totmin.ru/en2zmax/addrkit/internal/seed"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		usage()
+		os.Exit(2)
+	}
+	switch os.Args[1] {
+	case "seed":
+		os.Exit(runSeed(os.Args[2:]))
+	case "verify":
+		os.Exit(runVerify(os.Args[2:]))
+	case "resolve":
+		os.Exit(runResolve(os.Args[2:]))
+	case "help", "-h", "--help":
+		usage()
+		os.Exit(0)
+	default:
+		fmt.Fprintf(os.Stderr, "unknown command %q\n", os.Args[1])
+		usage()
+		os.Exit(2)
+	}
+}
+
+func usage() {
+	fmt.Fprint(os.Stderr, `addrkit — address registry toolkit
+
+Usage:
+  addrkit seed    -in registry.ndjson -out registry.db [-version 2026-10-09]
+  addrkit verify  -db registry.db
+  addrkit resolve -db registry.db "2-я Станционная улица 1/1 стр."
+`)
+}
+
+func runSeed(args []string) int {
+	fs := flag.NewFlagSet("seed", flag.ExitOnError)
+	in := fs.String("in", "", "input registry dump (Bulk NDJSON or JSONL)")
+	out := fs.String("out", "", "output SQLite database")
+	version := fs.String("version", "", "data version (defaults to input file mtime)")
+	_ = fs.Parse(args)
+
+	if *in == "" || *out == "" {
+		fmt.Fprintln(os.Stderr, "seed: -in and -out are required")
+		return 2
+	}
+	if *version == "" {
+		if fi, err := os.Stat(*in); err == nil {
+			*version = fi.ModTime().UTC().Format("20060102T150405Z")
+		}
+	}
+
+	f, err := os.Open(*in)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "seed: open input: %v\n", err)
+		return 1
+	}
+	defer f.Close()
+
+	sources, err := seed.ReadBulkNDJSON(f)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "seed: read: %v\n", err)
+		return 1
+	}
+	entries, stats := seed.Build(sources)
+	if stats.Parsed == 0 {
+		fmt.Fprintln(os.Stderr, "seed: no parseable entries; refusing to write empty index")
+		return 1
+	}
+	if err := registrystore.Save(*out, *version, entries); err != nil {
+		fmt.Fprintf(os.Stderr, "seed: save: %v\n", err)
+		return 1
+	}
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	_ = enc.Encode(map[string]any{
+		"output":  *out,
+		"version": *version,
+		"entries": len(entries),
+		"stats":   stats,
+	})
+	return 0
+}
+
+func runVerify(args []string) int {
+	fs := flag.NewFlagSet("verify", flag.ExitOnError)
+	db := fs.String("db", "", "SQLite database")
+	_ = fs.Parse(args)
+	if *db == "" {
+		fmt.Fprintln(os.Stderr, "verify: -db is required")
+		return 2
+	}
+	version, entries, err := registrystore.Load(*db)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "verify: %v\n", err)
+		return 1
+	}
+	streets := make(map[string]struct{})
+	for _, e := range entries {
+		streets[e.StreetKey] = struct{}{}
+	}
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	_ = enc.Encode(map[string]any{
+		"version":          version,
+		"entries":          len(entries),
+		"distinct_streets": len(streets),
+	})
+	return 0
+}
+
+func runResolve(args []string) int {
+	fs := flag.NewFlagSet("resolve", flag.ExitOnError)
+	db := fs.String("db", "", "SQLite database")
+	_ = fs.Parse(args)
+	rest := fs.Args()
+	if *db == "" || len(rest) == 0 {
+		fmt.Fprintln(os.Stderr, `resolve: -db and an address are required`)
+		return 2
+	}
+	version, entries, err := registrystore.Load(*db)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "resolve: %v\n", err)
+		return 1
+	}
+	resolver := match.NewResolver(match.NewIndex(version, entries, match.DefaultOptions()), nil)
+	res := resolver.Resolve(context.Background(), rest[0])
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	_ = enc.Encode(res)
+	return 0
+}
@@ -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)
+}