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
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 ¶
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) GetPeerMetadata ¶
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 ¶
ID returns the peer ID of the underlying stream host, or the zero value if there is no stream host.
func (*Host) RemovePeerMetadata ¶
RemovePeerMetadata removes a peer's protocol metadata from the http host
func (*Host) Serve ¶
Serve starts the HTTP transport listeners. Always returns a non-nil error. If there are no listeners, returns ErrNoListeners.
func (*Host) SetHTTPHandler ¶
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 ¶
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.
type PeerMeta ¶
type PeerMeta map[protocol.ID]ProtocolMeta
type PeerMetadataGetter ¶
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)
Source Files
Directories