dep2phttp

Documentation

Overview

HTTP semantics with dep2p. Can use a dep2p stream transport or stock HTTP transports. This API is experimental and will likely change soon. Implements [dep2p spec #508](https://github.com/dep2p/specs/pull/508).

Index

• Constants
• Variables
• func PreferHTTPTransport(o roundTripperOpts) roundTripperOpts
• func ServerMustAuthenticatePeerID(o roundTripperOpts) roundTripperOpts
• type Host
  • func (h *Host) AddPeerMetadata(server peer.ID, meta PeerMeta)
  • func (h *Host) Addrs() []ma.Multiaddr
  • func (h *Host) Close() error
  • func (h *Host) GetPeerMetadata(server peer.ID) (PeerMeta, bool)
  • func (h *Host) NamespaceRoundTripper(roundtripper http.RoundTripper, p protocol.ID, server peer.ID) (*namespacedRoundTripper, error)
  • func (h *Host) NamespacedClient(p protocol.ID, server peer.AddrInfo, opts ...RoundTripperOption) (http.Client, error)
  • func (h *Host) NewConstrainedRoundTripper(server peer.AddrInfo, opts ...RoundTripperOption) (http.RoundTripper, error)
  • func (h *Host) PeerID() peer.ID
  • func (h *Host) RemovePeerMetadata(server peer.ID)
  • func (h *Host) Serve() error
  • func (h *Host) SetHTTPHandler(p protocol.ID, handler http.Handler)
  • func (h *Host) SetHTTPHandlerAtPath(p protocol.ID, path string, handler http.Handler)
  • func (h *Host) SetPeerMetadata(server peer.ID, meta PeerMeta)
• type PeerMeta
• type PeerMetadataGetter
• type ProtocolMeta
• type RoundTripperOption
• type WellKnownHandler
  • func (h *WellKnownHandler) AddProtocolMeta(p protocol.ID, protocolMeta ProtocolMeta)
  • func (h *WellKnownHandler) RemoveProtocolMeta(p protocol.ID)
  • func (h *WellKnownHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

Constants

const ProtocolIDForMultistreamSelect = "/http/1.1"

Variables

var ErrNoListeners = errors.New("nothing to listen on")

Functions

func PreferHTTPTransport

func PreferHTTPTransport(o roundTripperOpts) roundTripperOpts

PreferHTTPTransport tells the roundtripper constructor to prefer using an HTTP transport (as opposed to a dep2p stream transport). Useful, for example, if you want to attempt to leverage HTTP caching.

func ServerMustAuthenticatePeerID

func ServerMustAuthenticatePeerID(o roundTripperOpts) roundTripperOpts

ServerMustAuthenticatePeerID tells the roundtripper constructor that we MUST authenticate the Server's PeerID. Note: this currently means we can not use a native HTTP transport (HTTP peer id authentication is not yet implemented: https://github.com/dep2p/specs/pull/564).

Types

type Host

type Host struct {
	// StreamHost is a stream based dep2p host used to do HTTP over dep2p streams. May be nil
	StreamHost host.Host
	// ListenAddrs are the requested addresses to listen on. Multiaddrs must be
	// valid HTTP(s) multiaddr. Only multiaddrs for an HTTP transport are
	// supported (must end with /http or /https).
	ListenAddrs []ma.Multiaddr
	// TLSConfig is the TLS config for the server to use
	TLSConfig *tls.Config
	// InsecureAllowHTTP indicates if the server is allowed to serve unencrypted
	// HTTP requests over TCP.
	InsecureAllowHTTP bool
	// ServeMux is the http.ServeMux used by the server to serve requests. If
	// nil, a new serve mux will be created. Users may manually add handlers to
	// this mux instead of using `SetHTTPHandler`, but if they do, they should
	// also update the WellKnownHandler's protocol mapping.
	ServeMux *http.ServeMux

	// DefaultClientRoundTripper is the default http.RoundTripper for clients to
	// use when making requests over an HTTP transport. This must be an
	// `*http.Transport` type so that the transport can be cloned and the
	// `TLSClientConfig` field can be configured. If unset, it will create a new
	// `http.Transport` on first use.
	DefaultClientRoundTripper *http.Transport

	// WellKnownHandler is the http handler for the `.well-known/dep2p`
	// resource. It is responsible for sharing this node's protocol metadata
	// with other nodes. Users only care about this if they set their own
	// ServeMux with pre-existing routes. By default, new protocols are added
	// here when a user calls `SetHTTPHandler` or `SetHTTPHandlerAtPath`.
	WellKnownHandler WellKnownHandler
	// contains filtered or unexported fields
}

Host is a dep2p host for request/responses with HTTP semantics. This is in contrast to a stream-oriented host like the core host.Host interface. Its zero-value (&Host{}) is usable. Do not copy by value. See examples for usage.

Warning, this is experimental. The API will likely change.

func (*Host) AddPeerMetadata

func (h *Host) AddPeerMetadata(server peer.ID, meta PeerMeta)

AddPeerMetadata merges the given peer's protocol metadata to the http host. Useful if you have out-of-band knowledge of a peer's protocol mapping.

func (*Host) Addrs

func (h *Host) Addrs() []ma.Multiaddr

func (*Host) Close

func (h *Host) Close() error

func (*Host) GetPeerMetadata

func (h *Host) GetPeerMetadata(server peer.ID) (PeerMeta, bool)

GetPeerMetadata gets a peer's cached protocol metadata from the http host.

func (*Host) NamespaceRoundTripper

func (h *Host) NamespaceRoundTripper(roundtripper http.RoundTripper, p protocol.ID, server peer.ID) (*namespacedRoundTripper, error)

NamespaceRoundTripper returns an http.RoundTripper that are scoped to the given protocol on the given server.

func (*Host) NamespacedClient

func (h *Host) NamespacedClient(p protocol.ID, server peer.AddrInfo, opts ...RoundTripperOption) (http.Client, error)

NamespacedClient returns an http.Client that is scoped to the given protocol on the given server. It creates a new RoundTripper for each call. If you are creating many namespaced clients, consider creating a round tripper directly and namespacing the roundripper yourself, then creating clients from the namespace round tripper.

func (*Host) NewConstrainedRoundTripper

func (h *Host) NewConstrainedRoundTripper(server peer.AddrInfo, opts ...RoundTripperOption) (http.RoundTripper, error)

NewConstrainedRoundTripper returns an http.RoundTripper that can fulfill and HTTP request to the given server. It may use an HTTP transport or a stream based transport. It is valid to pass an empty server.ID. If there are multiple addresses for the server, it will pick the best transport (stream vs standard HTTP) using the following rules:

• If PreferHTTPTransport is set, use the HTTP transport.
• If ServerMustAuthenticatePeerID is set, use the stream transport, as the HTTP transport does not do peer id auth yet.
• If we already have a connection on a stream transport, use that.
• Otherwise, if we have both, use the HTTP transport.

func (*Host) PeerID

func (h *Host) PeerID() peer.ID

ID returns the peer ID of the underlying stream host, or the zero value if there is no stream host.

func (*Host) RemovePeerMetadata

func (h *Host) RemovePeerMetadata(server peer.ID)

RemovePeerMetadata removes a peer's protocol metadata from the http host

func (*Host) Serve

func (h *Host) Serve() error

Serve starts the HTTP transport listeners. Always returns a non-nil error. If there are no listeners, returns ErrNoListeners.

func (*Host) SetHTTPHandler

func (h *Host) SetHTTPHandler(p protocol.ID, handler http.Handler)

SetHTTPHandler sets the HTTP handler for a given protocol. Automatically manages the .well-known/dep2p mapping. http.StripPrefix is called on the handler, so the handler will be unaware of its prefix path.

func (*Host) SetHTTPHandlerAtPath

func (h *Host) SetHTTPHandlerAtPath(p protocol.ID, path string, handler http.Handler)

SetHTTPHandlerAtPath sets the HTTP handler for a given protocol using the given path. Automatically manages the .well-known/dep2p mapping. http.StripPrefix is called on the handler, so the handler will be unaware of its prefix path.

func (*Host) SetPeerMetadata

func (h *Host) SetPeerMetadata(server peer.ID, meta PeerMeta)

SetPeerMetadata adds a peer's protocol metadata to the http host. Useful if you have out-of-band knowledge of a peer's protocol mapping.

type PeerMeta

type PeerMeta map[protocol.ID]ProtocolMeta

type PeerMetadataGetter

type PeerMetadataGetter interface {
	GetPeerMetadata() (PeerMeta, error)
}

PeerMetadataGetter lets RoundTrippers implement a specific way of caching a peer's protocol mapping.

type ProtocolMeta

type ProtocolMeta struct {
	// Path defines the HTTP Path prefix used for this protocol
	Path string `json:"path"`
}

ProtocolMeta is metadata about a protocol.

type RoundTripperOption

type RoundTripperOption func(o roundTripperOpts) roundTripperOpts

type WellKnownHandler

type WellKnownHandler struct {
	// contains filtered or unexported fields
}

WellKnownHandler is an http.Handler that serves the .well-known/dep2p resource

func (*WellKnownHandler) AddProtocolMeta

func (h *WellKnownHandler) AddProtocolMeta(p protocol.ID, protocolMeta ProtocolMeta)

func (*WellKnownHandler) RemoveProtocolMeta

func (h *WellKnownHandler) RemoveProtocolMeta(p protocol.ID)

func (*WellKnownHandler) ServeHTTP

func (h *WellKnownHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)