refactor!: make addrkit a multi-city address normalizer

- remove the events/outages module, ArcGIS adapter, portal config and event statuses
- add a configurable city dictionary/parser and make City part of StreetKey
- seed: read city/city_name, namespace IDs by city, keep structures distinct
- fix reliability: schema v2 with fail-closed load, deterministic ordering,
  input limits, config validation, atomic DB publish, LLM response caps
- add read-only shadow mode comparing the old ES path with addrkit
- breaking: registry.db must be re-seeded; config has no portal section

internal/adapters/httpapi/middleware.go

@@ -14,10 +14,13 @@ type ctxKey int
 const requestIDKey ctxKey = 0
 
 // requestIDMW assigns a request id (for correlation in logs) and echoes it.
+// A client-supplied id is accepted only when it is short and well-formed; the
+// header ends up in logs, so accepting arbitrary bytes would be an injection
+// and log-flooding vector.
 func requestIDMW(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		id := r.Header.Get("X-Request-Id")
-		if id == "" {
+		if !validRequestID(id) {
 			id = newRequestID()
 		}
 		w.Header().Set("X-Request-Id", id)
@@ -26,6 +29,23 @@ func requestIDMW(next http.Handler) http.Handler {
 	})
 }
 
+const maxRequestIDLen = 128
+
+func validRequestID(id string) bool {
+	if id == "" || len(id) > maxRequestIDLen {
+		return false
+	}
+	for _, r := range id {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9':
+		case r == '-', r == '_', r == '.':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
 // loggingMW logs one line per request with method, path, status and duration.
 // It records no addresses (PII) — only routing metadata.
 func loggingMW(log *slog.Logger) func(http.Handler) http.Handler {
@@ -45,8 +65,10 @@ func loggingMW(log *slog.Logger) func(http.Handler) http.Handler {
 	}
 }
 
-// timeoutMW bounds the whole request, so a slow portal cannot tie up a
-// goroutine indefinitely.
+// timeoutMW bounds the whole request by setting a context deadline. Handlers
+// and adapters that talk to the network honour it; purely CPU-bound handlers
+// are additionally bounded by input limits and the HTTP server's read/write
+// timeouts in cmd/addrkitd.
 func timeoutMW(d time.Duration) func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

internal/adapters/httpapi/server.go

@@ -1,52 +1,54 @@
 // Package httpapi exposes the addrkit domain over a small, versioned JSON API.
 //
 // It contains no business logic: handlers decode requests, call the resolver
-// and the outages source, and encode responses. Cross-cutting concerns
-// (timeouts, recovery, request ids, logging) live in middleware.
+// and encode responses. Cross-cutting concerns (timeouts, recovery, request
+// ids, logging) live in middleware.
 package httpapi
 
 import (
 	"context"
 	"encoding/json"
-	"errors"
-	"log/slog"
 	"net/http"
 	"time"
+	"unicode/utf8"
+
+	"log/slog"
 
-	"git.totmin.ru/en2zmax/addrkit/internal/domain/address"
 	"git.totmin.ru/en2zmax/addrkit/internal/domain/match"
-	"git.totmin.ru/en2zmax/addrkit/internal/domain/outages"
 )
 
 // Resolver is the read side of the domain (implemented by *match.Resolver).
 type Resolver interface {
 	Resolve(ctx context.Context, raw string) match.Result
+	ResolveInCity(ctx context.Context, raw, city string) match.Result
+	MatchCity(query string) (string, bool)
 	Version() string
 	Ready() bool
+	Cities() []string
 }
 
+// maxAddressRunes bounds user input. A real address is far shorter; the limit
+// keeps a pathological string from turning into a CPU-bound fuzzy scan.
+const maxAddressRunes = 512
+
+// maxCityQueryRunes bounds the separate city-only endpoint.
+const maxCityQueryRunes = 128
+
 // Server wires the domain to HTTP.
 type Server struct {
 	resolver Resolver
-	outages  outages.Source
 	log      *slog.Logger
-	now      func() time.Time
-	loc      *time.Location
 	timeout  time.Duration
 }
 
-// New builds a server. loc controls how outage dates are interpreted; it
-// should be the operational timezone (Asia/Novosibirsk).
-func New(resolver Resolver, src outages.Source, log *slog.Logger, loc *time.Location) *Server {
-	if loc == nil {
-		loc = time.UTC
+// New builds a server.
+func New(resolver Resolver, log *slog.Logger) *Server {
+	if log == nil {
+		log = slog.Default()
 	}
 	return &Server{
 		resolver: resolver,
-		outages:  src,
 		log:      log,
-		now:      time.Now,
-		loc:      loc,
 		timeout:  10 * time.Second,
 	}
 }
@@ -55,16 +57,21 @@ func New(resolver Resolver, src outages.Source, log *slog.Logger, loc *time.Loca
 func (s *Server) Handler() http.Handler {
 	mux := http.NewServeMux()
 	mux.HandleFunc("POST /v1/resolve", s.handleResolve)
-	mux.HandleFunc("POST /v1/outages", s.handleOutages)
+	mux.HandleFunc("POST /v1/city", s.handleCity)
+	mux.HandleFunc("GET /v1/cities", s.handleCities)
 	mux.HandleFunc("GET /v1/healthz", s.handleHealthz)
 	mux.HandleFunc("GET /v1/readyz", s.handleReadyz)
 	mux.HandleFunc("GET /v1/version", s.handleVersion)
 
-	return recoverMW(s.log)(requestIDMW(loggingMW(s.log)(timeoutMW(s.timeout)(mux))))
+	// Logging sits outside recovery so a panic is still recorded as a 500.
+	return requestIDMW(loggingMW(s.log)(recoverMW(s.log)(timeoutMW(s.timeout)(mux))))
 }
 
 type resolveRequest struct {
 	Address string `json:"address"`
+	// City is an optional hint for clients that keep the city separate from
+	// the street line. It overrides a city found in the address text.
+	City string `json:"city"`
 }
 
 func (s *Server) handleResolve(w http.ResponseWriter, r *http.Request) {
@@ -72,64 +79,49 @@ func (s *Server) handleResolve(w http.ResponseWriter, r *http.Request) {
 	if !ok {
 		return
 	}
-	writeJSON(w, http.StatusOK, s.resolver.Resolve(r.Context(), req.Address))
+	writeJSON(w, http.StatusOK, s.resolver.ResolveInCity(r.Context(), req.Address, req.City))
 }
 
-type outagesResponse struct {
-	Status      address.Status   `json:"status"`
-	Address     string           `json:"address,omitempty"`
-	District    string           `json:"district,omitempty"`
-	Outages     []outages.Outage `json:"outages"`
-	AsOf        string           `json:"as_of,omitempty"`
-	DataVersion string           `json:"data_version,omitempty"`
-	Detail      string           `json:"detail,omitempty"`
+type cityRequest struct {
+	Query string `json:"query"`
 }
 
-func (s *Server) handleOutages(w http.ResponseWriter, r *http.Request) {
-	req, ok := s.decode(w, r)
-	if !ok {
-		return
-	}
-	ctx := r.Context()
-	res := s.resolver.Resolve(ctx, req.Address)
+type cityResponse struct {
+	Status string `json:"status"`
+	City   string `json:"city,omitempty"`
+}
 
-	out := outagesResponse{
-		Status:      res.Status,
-		Address:     res.Address,
-		District:    res.District,
-		DataVersion: res.DataVersion,
-		Outages:     []outages.Outage{},
-	}
-	if res.Status != address.StatusFound {
-		// No canonical address => nothing to query. Return the resolver's
-		// verdict so the caller can ask for clarification.
-		writeJSON(w, http.StatusOK, out)
+// handleCity normalizes a city-only query ("нск", "г. Новосибирск",
+// "Новосибирская область"). It is the small, separate use case for projects
+// that need city names but not streets.
+func (s *Server) handleCity(w http.ResponseWriter, r *http.Request) {
+	var req cityRequest
+	r.Body = http.MaxBytesReader(w, r.Body, 16*1024)
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid json body")
 		return
 	}
-	if s.outages == nil {
-		// The events module is optional and off when portal.url is empty.
-		out.Status = address.StatusInfra
-		out.Detail = "outages source is not configured"
-		writeJSON(w, http.StatusOK, out)
+	if req.Query == "" {
+		writeError(w, http.StatusBadRequest, "query is required")
 		return
 	}
+	if utf8.RuneCountInString(req.Query) > maxCityQueryRunes {
+		writeError(w, http.StatusBadRequest, "query is too long")
+		return
+	}
+	if city, ok := s.resolver.MatchCity(req.Query); ok {
+		writeJSON(w, http.StatusOK, cityResponse{Status: "found", City: city})
+		return
+	}
+	writeJSON(w, http.StatusOK, cityResponse{Status: "not_found"})
+}
 
-	raw, err := s.outages.Query(ctx, res.Address)
-	if err != nil {
-		if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
-			out.Status = address.StatusPortalTimeout
-		} else {
-			out.Status = address.StatusInfra
-		}
-		writeJSON(w, http.StatusOK, out)
-		return
+func (s *Server) handleCities(w http.ResponseWriter, _ *http.Request) {
+	cities := s.resolver.Cities()
+	if cities == nil {
+		cities = []string{}
 	}
-
-	parsed := address.Parse(res.Address)
-	current := outages.Current(raw, s.now(), s.loc)
-	out.Outages = outages.MatchingHouse(current, parsed)
-	out.AsOf = s.now().In(s.loc).Format(time.RFC3339)
-	writeJSON(w, http.StatusOK, out)
+	writeJSON(w, http.StatusOK, map[string][]string{"cities": cities})
 }
 
 func (s *Server) handleHealthz(w http.ResponseWriter, _ *http.Request) {
@@ -160,6 +152,14 @@ func (s *Server) decode(w http.ResponseWriter, r *http.Request) (resolveRequest,
 		writeError(w, http.StatusBadRequest, "address is required")
 		return resolveRequest{}, false
 	}
+	if utf8.RuneCountInString(req.Address) > maxAddressRunes {
+		writeError(w, http.StatusBadRequest, "address is too long")
+		return resolveRequest{}, false
+	}
+	if utf8.RuneCountInString(req.City) > 128 {
+		writeError(w, http.StatusBadRequest, "city is too long")
+		return resolveRequest{}, false
+	}
 	return req, true
 }
 

internal/adapters/httpapi/server_test.go

@@ -2,46 +2,51 @@ package httpapi
 
 import (
 	"bytes"
-	"context"
 	"encoding/json"
 	"io"
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
-	"time"
 
 	"git.totmin.ru/en2zmax/addrkit/internal/domain/address"
 	"git.totmin.ru/en2zmax/addrkit/internal/domain/match"
-	"git.totmin.ru/en2zmax/addrkit/internal/domain/outages"
 )
 
+func entry(t *testing.T, city, raw string) address.Entry {
+	t.Helper()
+	p := address.NewParser(address.NewDictionary(cityDictionary()), "").ParseInCity(raw, city)
+	return address.Entry{
+		ID: raw, Address: raw, District: "Тестовый",
+		City: p.City, CityKey: p.CityKey,
+		Ordinal: p.Ordinal, NameKey: p.NameKey, NameDisplay: p.NameDisplay,
+		StreetType: p.StreetType, StreetKey: p.StreetKey,
+		House: p.House, HouseFrac: p.HouseFrac, HouseLetter: p.HouseLetter,
+		Building: p.Building, BuildingFrac: p.BuildingFrac, BuildingLetter: p.BuildingLetter,
+		Structure: p.Structure,
+	}
+}
+
+func cityDictionary() []address.City {
+	return []address.City{
+		{Name: "Новосибирск", Aliases: []string{"нск", "новосиб", "новосибирская область"}},
+		{Name: "Бердск"},
+	}
+}
+
 func testResolver(t *testing.T) *match.Resolver {
 	t.Helper()
 	var entries []address.Entry
 	for _, a := range []string{"Станционная улица 1/1", "2-я Станционная улица 1/1", "Искитимская улица 5"} {
-		p := address.Parse(a)
-		entries = append(entries, address.Entry{
-			ID: a, Address: a, District: "Тестовый",
-			Ordinal: p.Ordinal, NameKey: p.NameKey, StreetType: p.StreetType, StreetKey: p.StreetKey,
-			House: p.House, HouseFrac: p.HouseFrac, HouseLetter: p.HouseLetter,
-		})
+		entries = append(entries, entry(t, "", a))
 	}
 	return match.NewResolver(match.NewIndex("test-version", entries, match.DefaultOptions()), nil)
 }
 
-type fakeSource struct {
-	list []outages.Outage
-	err  error
-}
-
-func (f fakeSource) Query(context.Context, string) ([]outages.Outage, error) {
-	return f.list, f.err
-}
-
-func newServer(t *testing.T, src fakeSource) *httptest.Server {
+func newServer(t *testing.T, resolver Resolver) *httptest.Server {
 	t.Helper()
-	srv := New(testResolver(t), src, slog.New(slog.NewTextHandler(io.Discard, nil)), time.UTC)
+	srv := New(resolver, slog.New(slog.NewTextHandler(io.Discard, nil)))
 	ts := httptest.NewServer(srv.Handler())
 	t.Cleanup(ts.Close)
 	return ts
@@ -57,7 +62,7 @@ func postJSON(t *testing.T, url, body string) *http.Response {
 }
 
 func TestResolveEndpoint(t *testing.T) {
-	ts := newServer(t, fakeSource{})
+	ts := newServer(t, testResolver(t))
 	resp := postJSON(t, ts.URL+"/v1/resolve", `{"address":"2-я Станционная 1/1"}`)
 	defer resp.Body.Close()
 
@@ -73,38 +78,120 @@ func TestResolveEndpoint(t *testing.T) {
 	}
 }
 
-func TestOutagesEndpointFiltersHouse(t *testing.T) {
-	src := fakeSource{list: []outages.Outage{
-		{Address: "Станционная улица 1/1", System: "Теплоснабжение"},
-		{Address: "Станционная улица 1/2", System: "Теплоснабжение"},
-	}}
-	ts := newServer(t, src)
-	resp := postJSON(t, ts.URL+"/v1/outages", `{"address":"станционная 1/1"}`)
-	defer resp.Body.Close()
-
-	var out outagesResponse
-	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
-		t.Fatalf("decode: %v", err)
-	}
-	if out.Status != address.StatusFound {
-		t.Fatalf("status = %q, want found", out.Status)
-	}
-	if len(out.Outages) != 1 || out.Outages[0].Address != "Станционная улица 1/1" {
-		t.Fatalf("house filter failed: %+v", out.Outages)
+func TestResolveValidation(t *testing.T) {
+	ts := newServer(t, testResolver(t))
+	for _, body := range []string{`{}`, `{"address":""}`, `not json`} {
+		resp := postJSON(t, ts.URL+"/v1/resolve", body)
+		resp.Body.Close()
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Errorf("body %q: status = %d, want 400", body, resp.StatusCode)
+		}
 	}
 }
 
-func TestResolveValidation(t *testing.T) {
-	ts := newServer(t, fakeSource{})
-	resp := postJSON(t, ts.URL+"/v1/resolve", `{}`)
-	defer resp.Body.Close()
+func TestResolveRejectsOversizedAddress(t *testing.T) {
+	ts := newServer(t, testResolver(t))
+	body, _ := json.Marshal(map[string]string{"address": strings.Repeat("а", maxAddressRunes+1)})
+	resp := postJSON(t, ts.URL+"/v1/resolve", string(body))
+	resp.Body.Close()
 	if resp.StatusCode != http.StatusBadRequest {
 		t.Fatalf("status = %d, want 400", resp.StatusCode)
 	}
 }
 
+func TestResolveCityHint(t *testing.T) {
+	entries := []address.Entry{
+		entry(t, "Новосибирск", "Ленина улица 5"),
+		entry(t, "Бердск", "Ленина улица 5"),
+	}
+	resolver := match.NewResolver(
+		match.NewIndex("test", entries, match.DefaultOptions()),
+		nil,
+	)
+	ts := newServer(t, resolver)
+
+	resp := postJSON(t, ts.URL+"/v1/resolve", `{"address":"Ленина 5","city":"Бердск"}`)
+	defer resp.Body.Close()
+	var res match.Result
+	if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if res.Status != address.StatusFound || res.City != "Бердск" || res.Address != "Ленина улица 5" {
+		t.Fatalf("unexpected result: %+v", res)
+	}
+}
+
+func TestCitiesEndpoint(t *testing.T) {
+	entries := []address.Entry{
+		entry(t, "Новосибирск", "Ленина улица 5"),
+		entry(t, "Бердск", "Ленина улица 5"),
+	}
+	resolver := match.NewResolver(match.NewIndex("test", entries, match.DefaultOptions()), nil)
+	ts := newServer(t, resolver)
+
+	resp, err := http.Get(ts.URL + "/v1/cities")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	defer resp.Body.Close()
+	var body struct {
+		Cities []string `json:"cities"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(body.Cities) != 2 || body.Cities[0] != "Бердск" || body.Cities[1] != "Новосибирск" {
+		t.Fatalf("cities = %v", body.Cities)
+	}
+}
+
+func TestCityEndpoint(t *testing.T) {
+	parser := address.NewParser(address.NewDictionary(cityDictionary()), "")
+	resolver := match.NewResolverWithOptions(
+		match.NewIndex("test", nil, match.DefaultOptions()),
+		nil,
+		match.ResolverOptions{Parser: parser},
+	)
+	ts := newServer(t, resolver)
+
+	for _, tt := range []struct {
+		query string
+		city  string
+	}{
+		{"нск", "Новосибирск"},
+		{"г. Новосибирск", "Новосибирск"},
+		{"Новосибирская область", "Новосибирск"},
+		{"Бердск", "Бердск"},
+		{"Томск", ""},
+	} {
+		body, _ := json.Marshal(map[string]string{"query": tt.query})
+		resp := postJSON(t, ts.URL+"/v1/city", string(body))
+		var got cityResponse
+		if err := json.NewDecoder(resp.Body).Decode(&got); err != nil {
+			resp.Body.Close()
+			t.Fatalf("%q: decode: %v", tt.query, err)
+		}
+		resp.Body.Close()
+		if tt.city == "" {
+			if got.Status != "not_found" {
+				t.Errorf("%q: status = %q, want not_found", tt.query, got.Status)
+			}
+			continue
+		}
+		if got.Status != "found" || got.City != tt.city {
+			t.Errorf("%q: %+v", tt.query, got)
+		}
+	}
+
+	resp := postJSON(t, ts.URL+"/v1/city", `{}`)
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Errorf("empty query status = %d, want 400", resp.StatusCode)
+	}
+}
+
 func TestReadyzAndVersion(t *testing.T) {
-	ts := newServer(t, fakeSource{})
+	ts := newServer(t, testResolver(t))
 
 	resp, err := http.Get(ts.URL + "/v1/readyz")
 	if err != nil {
@@ -120,9 +207,11 @@ func TestReadyzAndVersion(t *testing.T) {
 		t.Fatalf("version: %v", err)
 	}
 	defer resp.Body.Close()
-	var v map[string]string
-	_ = json.NewDecoder(resp.Body).Decode(&v)
-	if v["data_version"] != "test-version" {
-		t.Fatalf("version = %q", v["data_version"])
+	var body map[string]string
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if body["data_version"] != "test-version" {
+		t.Fatalf("data_version = %q", body["data_version"])
 	}
 }