Report which public blocklists list an address in the IP lookup (closes #158)

A new package, internal/blocklist, downloads seven public lists on a
schedule: DShield, Feodo Tracker, FireHOL abusers and level 3, Spamhaus
DROP for IPv4 and IPv6, and the Tor exit list. It keeps the last good
copy of each in memory and in the state directory's blocklists
directory, and loads the copies at startup. Each list's interval follows
its publisher's page, cited in the code.

Each IP lookup result carries blocklists, one entry per list the address
is on. A successful lookup answer carries Cache-Control, private for the
caller's own address. The address sets come from go4.org/netipx.

Model: opus-5-5

internal/server/handlers.go

@@ -15,6 +15,7 @@ import (
 	"strings"
 	"time"
 
+	"git.eeqj.de/sneak/routewatch/internal/blocklist"
 	"git.eeqj.de/sneak/routewatch/internal/database"
 	"git.eeqj.de/sneak/routewatch/internal/metrics"
 	"git.eeqj.de/sneak/routewatch/internal/ristypes"
@@ -45,6 +46,15 @@ const (
 	ptrLookupTimeout = 2 * time.Second
 )
 
+// The Cache-Control header of an IP lookup answer, such as
+// "public, max-age=900".
+const (
+	cacheControlHeader  = "Cache-Control"
+	cacheControlPublic  = "public"
+	cacheControlPrivate = "private"
+	cacheControlMaxAge  = ", max-age="
+)
+
 // Keys of the JSON envelope the handlers and middleware write, and the status
 // value of an error answer.
 const (
@@ -693,9 +703,18 @@ func (s *Server) handleIPLookup() http.HandlerFunc {
 
 // IPLookupResponse is the standard response for IP/hostname lookups.
 type IPLookupResponse struct {
-	Query   string             `json:"query"`
-	Results []*database.IPInfo `json:"results"`
-	Errors  []string           `json:"errors,omitempty"`
+	Query   string           `json:"query"`
+	Results []IPLookupResult `json:"results"`
+	Errors  []string         `json:"errors,omitempty"`
+}
+
+// IPLookupResult is the answer for one address: its route and AS from the
+// database, and the blocklists that list it.
+type IPLookupResult struct {
+	*database.IPInfo
+
+	// Blocklists has one entry for each blocklist the address is on.
+	Blocklists []blocklist.Listing `json:"blocklists"`
 }
 
 // handleIPInfo returns a handler that provides comprehensive IP information.
@@ -704,7 +723,7 @@ type IPLookupResponse struct {
 // Always returns the same response structure with PTR records for each IP.
 func (s *Server) handleIPInfo() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		target := lookupTarget(r)
+		target, ownAddress := lookupTarget(r)
 		if target == "" {
 			s.writeJSONError(w, http.StatusBadRequest, "Could not determine IP address")
 
@@ -712,7 +731,7 @@ func (s *Server) handleIPInfo() http.HandlerFunc {
 		}
 
 		ctx := r.Context()
-		response := IPLookupResponse{Query: target, Results: make([]*database.IPInfo, 0)}
+		response := IPLookupResponse{Query: target, Results: make([]IPLookupResult, 0)}
 
 		// Collect all IPs to look up
 		ipsToLookup, resolveErrors, err := s.resolveLookupTargets(ctx, target)
@@ -772,7 +791,10 @@ func (s *Server) handleIPInfo() http.HandlerFunc {
 				ipInfo.PTR = ptrs
 			}
 
-			response.Results = append(response.Results, ipInfo)
+			response.Results = append(response.Results, IPLookupResult{
+				IPInfo:     ipInfo,
+				Blocklists: s.blocklistListings(ip),
+			})
 
 			if ipInfo.NeedsWHOISRefresh {
 				refreshASNs[ipInfo.ASN] = true
@@ -782,10 +804,40 @@ func (s *Server) handleIPInfo() http.HandlerFunc {
 		// Queue WHOIS refresh for stale ASNs (non-blocking)
 		s.queueWHOISRefresh(refreshASNs)
 
-		s.writeIPLookupAnswer(w, response)
+		s.writeIPLookupAnswer(w, response, ownAddress)
 	}
 }
 
+// blocklistListings returns the blocklists that list ip. It returns an empty
+// list, never nil, so that an answer's blocklists is [] rather than null.
+func (s *Server) blocklistListings(ip string) []blocklist.Listing {
+	addr, err := netip.ParseAddr(ip)
+	if s.blocklists == nil || err != nil {
+		return []blocklist.Listing{}
+	}
+
+	return s.blocklists.Lookup(addr)
+}
+
+// setIPLookupCacheControl lets caches keep an IP lookup answer for the
+// shortest blocklist interval, the soonest a blocklist copy can change. The
+// answer about the caller's own address is private, so that a shared cache
+// does not give it to another caller. Without blocklists it sets nothing.
+func (s *Server) setIPLookupCacheControl(w http.ResponseWriter, ownAddress bool) {
+	if s.blocklists == nil {
+		return
+	}
+
+	visibility := cacheControlPublic
+	if ownAddress {
+		visibility = cacheControlPrivate
+	}
+
+	maxAgeSeconds := int(s.blocklists.ShortestInterval().Seconds())
+	w.Header().Set(cacheControlHeader,
+		visibility+cacheControlMaxAge+strconv.Itoa(maxAgeSeconds))
+}
+
 // noTargetsMessage returns the message of the 400 an IP lookup answers when
 // no address is left to look up, followed by the first of resolveErrors, which
 // says why, when there is one.
@@ -800,9 +852,10 @@ func noTargetsMessage(resolveErrors []string) string {
 }
 
 // writeIPLookupAnswer sends response, or 404 with its first error when no
-// address had a route.
+// address had a route. ownAddress says the request asked about the caller's
+// own address.
 func (s *Server) writeIPLookupAnswer(
-	w http.ResponseWriter, response IPLookupResponse,
+	w http.ResponseWriter, response IPLookupResponse, ownAddress bool,
 ) {
 	if len(response.Results) == 0 && len(response.Errors) > 0 {
 		s.writeJSONError(w, http.StatusNotFound, "No routes found: "+response.Errors[0])
@@ -810,6 +863,8 @@ func (s *Server) writeIPLookupAnswer(
 		return
 	}
 
+	s.setIPLookupCacheControl(w, ownAddress)
+
 	err := writeJSONSuccess(w, response)
 	if err != nil {
 		s.logger.Error("Failed to encode IP lookup response", "error", err)
@@ -817,8 +872,9 @@ func (s *Server) writeIPLookupAnswer(
 }
 
 // lookupTarget returns what an IP lookup request asks for: the ip or addr URL
-// parameter, or else the client's own address.
-func lookupTarget(r *http.Request) string {
+// parameter, or else the client's own address. The bool is true for the
+// client's own address.
+func lookupTarget(r *http.Request) (string, bool) {
 	target := chi.URLParam(r, "ip")
 	if target == "" {
 		target = chi.URLParam(r, "addr")
@@ -826,10 +882,10 @@ func lookupTarget(r *http.Request) string {
 
 	if target == "" {
 		// Use client IP (RealIP middleware has already processed this)
-		target = extractClientIP(r)
+		return extractClientIP(r), true
 	}
 
-	return target
+	return target, false
 }
 
 // queueWHOISRefresh asks the WHOIS fetcher, when there is one, to refresh

internal/server/handlers_internal_test.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"html"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"net/netip"
@@ -16,6 +17,7 @@ import (
 	"testing"
 	"time"
 
+	"git.eeqj.de/sneak/routewatch/internal/blocklist"
 	"git.eeqj.de/sneak/routewatch/internal/config"
 	"git.eeqj.de/sneak/routewatch/internal/database"
 	"git.eeqj.de/sneak/routewatch/internal/logger"
@@ -1246,6 +1248,129 @@ func TestIPLookupKeepsRouteWhenPTRLookupDoesNotAnswer(t *testing.T) {
 	}
 }
 
+// addrInTestPrefixV6 is an address in testPrefixV6, which
+// newServerWithTestRoutes stores a route for.
+const addrInTestPrefixV6 = "2001:db8::1"
+
+// testBlocklistInterval is fakeBlocklists' shortest interval.
+const testBlocklistInterval = 15 * time.Minute
+
+// ownAddressPath is the IP lookup of the caller's own address.
+const ownAddressPath = "/ip/"
+
+// fakeBlocklists has one list, which lists addrInTestPrefixV4 and no other
+// address.
+type fakeBlocklists struct{}
+
+func testListing() blocklist.Listing {
+	return blocklist.Listing{
+		Name:        "test_list",
+		Description: "On the test list",
+		Updated:     time.Date(2026, 10, 27, 4, 0, 0, 0, time.UTC),
+	}
+}
+
+func (fakeBlocklists) Lookup(addr netip.Addr) []blocklist.Listing {
+	if addr == netip.MustParseAddr(addrInTestPrefixV4) {
+		return []blocklist.Listing{testListing()}
+	}
+
+	return []blocklist.Listing{}
+}
+
+func (fakeBlocklists) ShortestInterval() time.Duration {
+	return testBlocklistInterval
+}
+
+// TestIPLookupReportsBlocklists looks up two routed addresses, one of them on
+// a blocklist. The listed address's result names the list, says what it means
+// and when it was updated. The other's result has an empty list.
+func TestIPLookupReportsBlocklists(t *testing.T) {
+	t.Parallel()
+
+	s := newServerWithTestRoutes(t)
+	s.resolver = &fakeResolver{}
+	s.SetBlocklists(fakeBlocklists{})
+
+	rec := httptest.NewRecorder()
+	s.router.ServeHTTP(rec, httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet,
+		"/api/v1/ip/"+addrInTestPrefixV4+","+addrInTestPrefixV6, nil))
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status %d, want %d; body %s", rec.Code, http.StatusOK, rec.Body)
+	}
+
+	var body struct {
+		Data IPLookupResponse `json:"data"`
+	}
+
+	err := json.Unmarshal(rec.Body.Bytes(), &body)
+	if err != nil {
+		t.Fatalf("decoding the answer %q: %v", rec.Body, err)
+	}
+
+	results := body.Data.Results
+	if len(results) != 2 {
+		t.Fatalf("answer %s, want two results", rec.Body)
+	}
+
+	want := testListing()
+
+	listed := results[0].Blocklists
+	if len(listed) != 1 || listed[0].Name != want.Name ||
+		listed[0].Description != want.Description ||
+		!listed[0].Updated.Equal(want.Updated) {
+		t.Errorf("%s: blocklists %+v, want [%+v]", results[0].IP, listed, want)
+	}
+
+	if !strings.Contains(rec.Body.String(), `"blocklists":[]`) {
+		t.Errorf("answer %s, want an empty blocklists list for %s",
+			rec.Body, addrInTestPrefixV6)
+	}
+}
+
+// TestIPLookupAnswersMayBeCached checks the Cache-Control header of the IP
+// lookup answers. Caches may keep them for the blocklists' shortest interval,
+// and only the caller's own browser may keep the answer about the caller's
+// own address.
+func TestIPLookupAnswersMayBeCached(t *testing.T) {
+	t.Parallel()
+
+	s := newServerWithTestRoutes(t)
+	s.resolver = &fakeResolver{}
+	s.SetBlocklists(fakeBlocklists{})
+
+	tests := []struct {
+		path string
+		want string
+	}{
+		{"/api/v1/ip/" + addrInTestPrefixV4, "public, max-age=900"},
+		{ownAddressPath + addrInTestPrefixV4, "public, max-age=900"},
+		{ownAddressPath, "private, max-age=900"},
+	}
+
+	for _, tt := range tests {
+		req := httptest.NewRequestWithContext(t.Context(), http.MethodGet,
+			tt.path, nil)
+		req.RemoteAddr = net.JoinHostPort(addrInTestPrefixV4, "1234")
+
+		rec := httptest.NewRecorder()
+		s.router.ServeHTTP(rec, req)
+
+		if rec.Code != http.StatusOK {
+			t.Errorf("%s: status %d, want %d; body %s",
+				tt.path, rec.Code, http.StatusOK, rec.Body)
+
+			continue
+		}
+
+		if got := rec.Header().Get(cacheControlHeader); got != tt.want {
+			t.Errorf("%s: Cache-Control %q, want %q", tt.path, got, tt.want)
+		}
+	}
+}
+
 // The host name TestIPLookupHidesPrivateAddresses resolves to a private
 // address, and that address.
 const (

internal/server/server.go

@@ -15,6 +15,7 @@ import (
 	"strconv"
 	"time"
 
+	"git.eeqj.de/sneak/routewatch/internal/blocklist"
 	"git.eeqj.de/sneak/routewatch/internal/config"
 	"git.eeqj.de/sneak/routewatch/internal/database"
 	"git.eeqj.de/sneak/routewatch/internal/logger"
@@ -36,6 +37,13 @@ type ASNFetcher interface {
 	GetStats() ASNFetcherStats
 }
 
+// Blocklists tells which public blocklists list an address, from copies it
+// keeps in memory, as *blocklist.Blocklists does.
+type Blocklists interface {
+	Lookup(addr netip.Addr) []blocklist.Listing
+	ShortestInterval() time.Duration
+}
+
 // dnsResolver looks up the addresses of host names and the names of addresses
 // in DNS, as *net.Resolver does.
 type dnsResolver interface {
@@ -52,6 +60,7 @@ type Server struct {
 	port       int
 	srv        *http.Server
 	asnFetcher ASNFetcher
+	blocklists Blocklists
 
 	// trustedProxies are the reverse proxies whose X-Forwarded-For header
 	// RealIPMiddleware believes
@@ -148,3 +157,9 @@ func (s *Server) Stop(ctx context.Context) error {
 func (s *Server) SetASNFetcher(fetcher ASNFetcher) {
 	s.asnFetcher = fetcher
 }
+
+// SetBlocklists sets the blocklists the IP lookups report. Call it before
+// Start: the handlers read the blocklists without a lock.
+func (s *Server) SetBlocklists(blocklists Blocklists) {
+	s.blocklists = blocklists
+}