Introspection support: add schema, interfaces, data provider system

host/host.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/libp2p/go-libp2p-core/connmgr"
 	"github.com/libp2p/go-libp2p-core/event"
+	"github.com/libp2p/go-libp2p-core/introspection"
 	"github.com/libp2p/go-libp2p-core/network"
 	"github.com/libp2p/go-libp2p-core/peer"
 	"github.com/libp2p/go-libp2p-core/peerstore"
@@ -73,3 +74,16 @@ type Host interface {
 	// EventBus returns the hosts eventbus
 	EventBus() event.Bus
 }
+
+// IntrospectableHost is implemented by Host implementations that are
+// introspectable, that is, that may have introspection capability.
+type IntrospectableHost interface {
+	// Introspector returns the introspector, or nil if one hasn't been
+	// registered. With it, the call can register data providers, and can fetch
+	// introspection data.
+	Introspector() introspection.Introspector
+
+	// IntrospectionEndpoint returns the introspection endpoint, or nil if one
+	// hasn't been registered.
+	IntrospectionEndpoint() introspection.Endpoint
+}

introspection/doc.go

@@ -0,0 +1,7 @@
+// Package introspection is EXPERIMENTAL. It is subject to heavy change, and it
+// WILL change. For now, it is the simplest implementation to power the
+// proof-of-concept of the libp2p introspection framework.
+//
+// Package introspect contains the abstract skeleton of the introspection system
+// of go-libp2p, and holds the introspection data schema.
+package introspection

introspection/endpoint.go

@@ -0,0 +1,30 @@
+package introspection
+
+// Endpoint is the interface to be implemented by introspection endpoints.
+//
+// An introspection endpoint makes introspection data accessible to external
+// consumers, over, for example, WebSockets, or TCP, or libp2p itself.
+//
+// Experimental.
+type Endpoint interface {
+	// Start starts the introspection endpoint. It must only be called once, and
+	// once the server is started, subsequent calls made without first calling
+	// Close will error.
+	Start() error
+
+	// Close stops the introspection endpoint. Calls to Close on an already
+	// closed endpoint (or an unstarted endpoint) must noop.
+	Close() error
+
+	// ListenAddrs returns the listen addresses of this endpoint.
+	ListenAddrs() []string
+
+	// Sessions returns the ongoing sessions of this endpoint.
+	Sessions() []*Session
+}
+
+// Session represents an introspection session.
+type Session struct {
+	// RemoteAddr is the remote address of the session.
+	RemoteAddr string
+}

introspection/introspector.go

@@ -0,0 +1,39 @@
+package introspection
+
+import (
+	"io"
+
+	"github.com/libp2p/go-libp2p-core/introspection/pb"
+)
+
+// Introspector is the interface to be satisfied by components that are capable
+// of spelunking the state of the system, and representing in accordance with
+// the introspection schema.
+//
+// It's very rare to build a custom implementation of this interface;
+// it exists mostly for mocking. In most cases, you'll end up using the
+// default introspector.
+//
+// Introspector implementations are usually injected in introspection endpoints
+// to serve the data to clients, but they can also be used separately for
+// embedding or testing.
+//
+// Experimental.
+type Introspector interface {
+	io.Closer
+
+	// FetchRuntime returns the runtime information of the system.
+	FetchRuntime() (*pb.Runtime, error)
+
+	// FetchFullState returns the full state cross-cut of the running system.
+	FetchFullState() (*pb.State, error)
+
+	// EventChan returns the channel where all eventbus events are dumped,
+	// decorated with their corresponding event metadata, ready to send over
+	// the wire.
+	EventChan() <-chan *pb.Event
+
+	// EventMetadata returns the metadata of all events known to the
+	// Introspector.
+	EventMetadata() []*pb.EventType
+}

introspection/pb/Makefile

@@ -0,0 +1,11 @@
+PB = $(wildcard *.proto)
+GO = $(PB:.proto=.pb.go)
+
+all: $(GO)
+
+%.pb.go: %.proto
+	protoc --proto_path=$(PWD):$(PWD)/../..:$(GOPATH)/src --gogofaster_out=Mgoogle/protobuf/timestamp.proto=github.com/gogo/protobuf/types:. $<
+
+clean:
+	rm -f *.pb.go
+	rm -f *.go

introspection/pb/doc.go

@@ -0,0 +1,3 @@
+// Package introspection/pb contains the protobuf definitions and objects for
+// that form the libp2p introspection protocol.
+package pb