Adds a local service for decorating IPs with annotations. (#23)

* Adds a local service for decorating IPs with annotations. Does not (yet) hook it up to main.
* Missing: true now exists and is not an error
* all external methods now respect locking in asnannotator and geoannotator.
* Add tests for logging methods. TODO: consider moving these methods to a wider scope if we need them elsewhere.
* Better URL and better command-line arguments

Author: pboothe

annotator/annotator.go

@@ -43,6 +43,8 @@ type Geolocation struct {
 	Latitude         float64 `json:",omitempty"` // Latitude
 	Longitude        float64 `json:",omitempty"` // Longitude
 	AccuracyRadiusKm int64   `json:",omitempty"` // Geo2: Accuracy Radius (since 2018)
+
+	Missing bool `json:",omitempty"` // True when the Geolocation data is missing from MaxMind.
 }
 
 // We currently use CAIDA RouteView data to populate ASN annotations.

asnannotator/routeview.go

@@ -14,10 +14,11 @@ import (
 	"github.com/m-lab/uuid-annotator/routeview"
 )
 
-// ReloadingAnnotator is just a regular annotator with a Reload method.
-type ReloadingAnnotator interface {
+// ASNAnnotator is just a regular annotator with a Reload method and an AnnotateIP method.
+type ASNAnnotator interface {
 	annotator.Annotator
 	Reload(context.Context)
+	AnnotateIP(src string) *annotator.Network
 }
 
 // asnAnnotator is the central struct for this module.
@@ -32,7 +33,7 @@ type asnAnnotator struct {
 
 // New makes a new Annotator that uses IP addresses to lookup ASN metadata for
 // that IP based on the current copy of RouteViews data stored in the given providers.
-func New(ctx context.Context, as4 rawfile.Provider, as6 rawfile.Provider, localIPs []net.IP) ReloadingAnnotator {
+func New(ctx context.Context, as4 rawfile.Provider, as6 rawfile.Provider, localIPs []net.IP) ASNAnnotator {
 	a := &asnAnnotator{
 		as4:      as4,
 		as6:      as6,
@@ -59,14 +60,20 @@ func (a *asnAnnotator) Annotate(ID *inetdiag.SockID, annotations *annotator.Anno
 	// TODO: annotate the server IP with siteinfo data.
 	switch dir {
 	case annotator.DstIsServer:
-		annotations.Client.Network = a.annotate(ID.SrcIP)
+		annotations.Client.Network = a.annotateIPHoldingLock(ID.SrcIP)
 	case annotator.SrcIsServer:
-		annotations.Client.Network = a.annotate(ID.DstIP)
+		annotations.Client.Network = a.annotateIPHoldingLock(ID.DstIP)
 	}
 	return nil
 }
 
-func (a *asnAnnotator) annotate(src string) *annotator.Network {
+func (a *asnAnnotator) AnnotateIP(src string) *annotator.Network {
+	a.m.RLock()
+	defer a.m.RUnlock()
+	return a.annotateIPHoldingLock(src)
+}
+
+func (a *asnAnnotator) annotateIPHoldingLock(src string) *annotator.Network {
 	ann := &annotator.Network{}
 	// Check IPv4 first.
 	ipnet, err := a.asn4.Search(src)

asnannotator/routeview_test.go

@@ -166,6 +166,29 @@ func Test_asnAnnotator_Annotate(t *testing.T) {
 	}
 }
 
+func Test_asnAnnotator_AnnotateIP(t *testing.T) {
+
+	localV4 := "9.0.0.9"
+	localV6 := "2002::1"
+	localIPs = []net.IP{
+		net.ParseIP(localV4),
+		net.ParseIP(localV6),
+	}
+	ctx := context.Background()
+	a := New(ctx, local4Rawfile, local6Rawfile, localIPs)
+	got := a.AnnotateIP("2001:200::1")
+	want := annotator.Network{
+		CIDR:     "2001:200::/32",
+		ASNumber: 2500,
+		Systems: []annotator.System{
+			{ASNs: []uint32{2500}},
+		},
+	}
+	if diff := deep.Equal(*got, want); diff != nil {
+		log.Println("got!=want", diff)
+	}
+}
+
 type badProvider struct {
 	err error
 }

geoannotator/ipannotator.go

@@ -2,6 +2,7 @@ package geoannotator
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log"
 	"net"
@@ -15,10 +16,11 @@ import (
 	"github.com/m-lab/uuid-annotator/rawfile"
 )
 
-// ReloadingAnnotator is just a regular annotator with a Reload method.
-type ReloadingAnnotator interface {
+// GeoAnnotator is just a regular annotator with a Reload method and an AnnotateIP method.
+type GeoAnnotator interface {
 	annotator.Annotator
 	Reload(context.Context)
+	AnnotateIP(ip net.IP, geo **annotator.Geolocation) error
 }
 
 // geoannotator is the central struct for this module.
@@ -41,9 +43,9 @@ func (g *geoannotator) Annotate(ID *inetdiag.SockID, annotations *annotator.Anno
 
 	switch dir {
 	case annotator.DstIsServer:
-		err = g.annotate(ID.SrcIP, &annotations.Client.Geo)
+		err = g.annotateHoldingLock(ID.SrcIP, &annotations.Client.Geo)
 	case annotator.SrcIsServer:
-		err = g.annotate(ID.DstIP, &annotations.Client.Geo)
+		err = g.annotateHoldingLock(ID.DstIP, &annotations.Client.Geo)
 	}
 	if err != nil {
 		return annotator.ErrNoAnnotation
@@ -53,11 +55,24 @@ func (g *geoannotator) Annotate(ID *inetdiag.SockID, annotations *annotator.Anno
 
 var emptyResult = geoip2.City{}
 
-func (g *geoannotator) annotate(src string, geo **annotator.Geolocation) error {
+func (g *geoannotator) annotateHoldingLock(src string, geo **annotator.Geolocation) error {
 	ip := net.ParseIP(src)
 	if ip == nil {
 		return fmt.Errorf("failed to parse IP %q", src)
 	}
+	return g.annotateIPHoldingLock(ip, geo)
+}
+
+func (g *geoannotator) AnnotateIP(ip net.IP, geo **annotator.Geolocation) error {
+	g.mut.RLock()
+	defer g.mut.RUnlock()
+	return g.annotateIPHoldingLock(ip, geo)
+}
+
+func (g *geoannotator) annotateIPHoldingLock(ip net.IP, geo **annotator.Geolocation) error {
+	if ip == nil {
+		return errors.New("can't annotate nil IP")
+	}
 	record, err := g.maxmind.City(ip)
 	if err != nil {
 		return err
@@ -66,8 +81,14 @@ func (g *geoannotator) annotate(src string, geo **annotator.Geolocation) error {
 	// Check for empty results because "not found" is not an error. Instead the
 	// geoip2 package returns an empty result. May be fixed in a future version:
 	// https://github.com/oschwald/geoip2-golang/issues/32
+	//
+	// "Not found" in a well-functioning database should not be an error.
+	// Instead, it is an accurate reflection of data that is missing.
 	if isEmpty(record) {
-		return fmt.Errorf("not found %q", src)
+		*geo = &annotator.Geolocation{
+			Missing: true,
+		}
+		return nil
 	}
 
 	tmp := &annotator.Geolocation{
@@ -132,7 +153,7 @@ func (g *geoannotator) load(ctx context.Context) (*geoip2.Reader, error) {
 // New makes a new Annotator that uses IP addresses to generate geolocation and
 // ASNumber metadata for that IP based on the current copy of MaxMind data
 // stored in GCS.
-func New(ctx context.Context, geo rawfile.Provider, localIPs []net.IP) ReloadingAnnotator {
+func New(ctx context.Context, geo rawfile.Provider, localIPs []net.IP) GeoAnnotator {
 	g := &geoannotator{
 		backingDataSource: geo,
 		localIPs:          localIPs,

geoannotator/ipannotator_test.go

@@ -9,6 +9,7 @@ import (
 	"net/url"
 	"testing"
 
+	"github.com/go-test/deep"
 	"github.com/m-lab/go/pretty"
 	"github.com/m-lab/go/rtx"
 	"github.com/m-lab/tcp-info/inetdiag"
@@ -70,6 +71,13 @@ func TestIPAnnotationS2C(t *testing.T) {
 	if math.Abs(ann.Client.Geo.Latitude-51.75) > .01 {
 		t.Error("Bad Client latitude:", ann.Client.Geo.Latitude, "!~=", 51.75)
 	}
+
+	ann2 := &annotator.Annotations{}
+	g.AnnotateIP(net.ParseIP(remoteIP), &ann2.Client.Geo)
+
+	if diff := deep.Equal(ann, ann2); diff != nil {
+		log.Println("Annotate and AnnotateIP should do the same thing, but they differ:", diff)
+	}
 }
 
 func TestIPAnnotationC2S(t *testing.T) {
@@ -131,7 +139,7 @@ func TestIPAnnotationBadDst(t *testing.T) {
 	conn := &inetdiag.SockID{
 		SrcIP:  "1.0.0.1",
 		SPort:  1,
-		DstIP:  "0.0.0.0", // A local IP
+		DstIP:  "this is not an IP address",
 		DPort:  2,
 		Cookie: 4,
 	}
@@ -140,11 +148,11 @@ func TestIPAnnotationBadDst(t *testing.T) {
 	err := g.Annotate(conn, ann)
 
 	if err == nil {
-		t.Errorf("Annotate succeeded with a bad IP: %q", conn.SrcIP)
+		t.Errorf("Annotate succeeded with a bad IP: %q", conn.DstIP)
 	}
 }
 
-func TestIPAnnotationUknownDirection(t *testing.T) {
+func TestIPAnnotationUnknownDirection(t *testing.T) {
 	localaddrs := []net.IP{net.ParseIP("1.0.0.1")}
 	g := New(context.Background(), localRawfile, localaddrs)
 
@@ -179,9 +187,9 @@ func TestIPAnnotationUnknownIP(t *testing.T) {
 
 	ann := &annotator.Annotations{}
 	err := g.Annotate(conn, ann)
-	if !errors.Is(err, annotator.ErrNoAnnotation) {
+	if err != nil || ann.Client.Geo == nil || !ann.Client.Geo.Missing {
 		pretty.Print(ann)
-		t.Error("Should have had an ErrNoAnnotation error due to IP missing from our dataset, but got", err)
+		t.Error("Should have had a client annotation with everything set to Missing, but got", err)
 	}
 }
 

ipservice/client.go

@@ -0,0 +1,89 @@
+package ipservice
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io/ioutil"
+	"log"
+	"net"
+	"net/http"
+
+	"github.com/m-lab/uuid-annotator/annotator"
+	"github.com/m-lab/uuid-annotator/metrics"
+)
+
+// Client is the interface for all users who want an IP annotated from the
+// uuid-annotator service.
+//
+// Behind the scenes, the client is an http client and the server is an http
+// server, connecting to each other via unix-domain sockets. Except for the name
+// of the socket, all details of how the IPC is done should be considered
+// internal and subject to change without notice. In particular, if the overhead
+// of encoding and decoding lots of HTTP transactions ends up being too high, we
+// reserve the right to change away from HTTP without warning.
+type Client interface {
+	// Annotate gets the ClientAnnotations associated with a particular IP address.
+	Annotate(ctx context.Context, ip net.IP) (*annotator.ClientAnnotations, error)
+}
+
+// getter defines the subset of the interface of http.Client that we use, in an
+// effort to enable mocking and testing.
+type getter interface {
+	Get(url string) (resp *http.Response, err error)
+}
+
+type client struct {
+	sockfilename string
+	httpc        getter
+}
+
+func (c *client) Annotate(ctx context.Context, ip net.IP) (*annotator.ClientAnnotations, error) {
+	u := "http://unix/v1/annotate/ip?ip=" + ip.String()
+	resp, err := c.httpc.Get(u)
+	if err != nil {
+		metrics.ClientRPCCount.WithLabelValues("get_error").Inc()
+		return nil, err
+	}
+	if resp.StatusCode != 200 {
+		metrics.ClientRPCCount.WithLabelValues("http_status_error").Inc()
+		return nil, fmt.Errorf("Got HTTP %d, but wanted HTTP 200", resp.StatusCode)
+	}
+	ann := &annotator.ClientAnnotations{}
+	b, err := ioutil.ReadAll(resp.Body)
+	if err != nil {
+		metrics.ClientRPCCount.WithLabelValues("read_error").Inc()
+		return nil, err
+	}
+	err = json.Unmarshal(b, ann)
+	if err == nil {
+		metrics.ClientRPCCount.WithLabelValues("success").Inc()
+	} else {
+		metrics.ClientRPCCount.WithLabelValues("unmarshal_error").Inc()
+	}
+	return ann, err
+}
+
+// NewClient creates an RPC client for annotating IP addresses. The only RPC
+// that is performed should happen through objects returned from this function.
+// All other forms of RPC to the local IP annotation service have no long-term
+// compatibility guarantees.
+//
+// The recommended value to pass into this function is the value of the
+// command-line flag `--ipservice.SocketFilename`, which is pointed to by
+// `ipservice.SocketFilename`.
+func NewClient(sockfilename string) Client {
+	if sockfilename != *SocketFilename {
+		log.Printf("WARNING: socket filename of %q differs from command-line flag value of %q\n", sockfilename, *SocketFilename)
+	}
+	return &client{
+		sockfilename: sockfilename,
+		httpc: &http.Client{
+			Transport: &http.Transport{
+				DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+					return net.Dial("unix", sockfilename)
+				},
+			},
+		},
+	}
+}

ipservice/ipservice.go

@@ -0,0 +1,10 @@
+// Package ipservice sets up and queries and runs the RPC service for annotating IP addresses.
+package ipservice
+
+import "flag"
+
+// SocketFilename is a flag to allow both clients and servers to use the same command-line flag.
+var SocketFilename = flag.String(
+	"ipservice.sock",
+	"",
+	"The filename to use as a UNIX domain socket for the local annotation service.")