ipservice

Documentation

Overview

Package ipservice sets up and queries and runs the RPC service for annotating IP addresses.

Index

• Variables
• type Client
  • func NewClient(sockfilename string) Client
• type Server
  • func NewServer(sockfilename string, asn asnannotator.ASNAnnotator, ...) (Server, error)

Examples

• Server (ForTesting)

Variables

var SocketFilename = flag.String(
	"ipservice.sock",
	"",
	"The filename to use as a UNIX domain socket for the local annotation service.")

SocketFilename is a flag to allow both clients and servers to use the same command-line flag.

Types

type Client

type Client interface {
	// Annotate gets the ClientAnnotations associated with each of the valid
	// passed-in IP addresses. Invalid IPs will not be present in the returned
	// map.
	Annotate(ctx context.Context, ips []string) (map[string]*annotator.ClientAnnotations, error)
}

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.

func NewClient

func NewClient(sockfilename string) Client

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`.

type Server

type Server interface {
	Close() error
	Serve() error
}

Server provides the http-over-unix-domain-socket service that serves up annotated IP addresses on request.

Example (ForTesting)

dir, err := ioutil.TempDir("", "ExampleFakeServerForTesting")
rtx.Must(err, "could not create tempdir")
defer os.RemoveAll(dir)

*SocketFilename = dir + "/ipservice.sock"
srv, err := NewServer(*SocketFilename, asnannotator.NewFake(), geoannotator.NewFake())
rtx.Must(err, "Could not create server")
defer warnonerror.Close(srv, "Could not stop the server")

go srv.Serve()
_, err = os.Stat(*SocketFilename)
for err != nil {
	time.Sleep(time.Millisecond)
	_, err = os.Stat(*SocketFilename)
}

// Now the server exists, and clients can connect to it via:
// c := NewClient(*SocketFilename)
// and then you can call c.Annotate() and use the returned values.

func NewServer

func NewServer(sockfilename string, asn asnannotator.ASNAnnotator, geo geoannotator.GeoAnnotator) (Server, error)

NewServer creates an RPC service for annotating IP addresses. The RPC service can be called by the returned objects from NewClient.

The returned object should have its Serve() method called, likely in a goroutine. To stop the server, call Close().

The recommended sockfilename value to pass into this function is the value of the command-line flag `--ipservice.SocketFilename`, which is pointed to by `ipservice.SocketFilename`.

If you would like to set up a server for use in unit tests outside this package, the easiest way of doing that is to pass in `nil` for `asn` and `geo`. The server will still work and run and exercise all its parsing an deserialization logic, but it will never fill in any data. If you need the server to contain dummy data for your test to work, then please file a bug in this repo asking the maintainer of this package to build a fake.