README
¶
go-libp2p-http
HTTP on top of libp2p
Package p2phttp allows to serve HTTP endpoints and make HTTP requests through libp2p using Go's standard "http" and "net" stack.
Instead of the regular "host:port" addressing, p2phttp uses a Peer ID and lets libp2p take care of the routing, thus taking advantage of features like multi-routes, NAT transversal and stream multiplexing over a single connection.
Table of Contents
Install
This package is a library that uses Go modules for dependency management.
Usage
Full documentation can be read at Godoc. The important bits follow.
A simple http.Server on libp2p works as:
listener, _ := gostream.Listen(host1, p2phttp.DefaultP2PProtocol)
defer listener.Close()
go func() {
http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hi!"))
})
server := &http.Server{}
server.Serve(listener)
}
The listener is provided by https://github.com/libp2p/go-libp2p-gostream .
A client just needs to be initialized with a custom libp2p host-based transport to perform requests to such server:
tr := &http.Transport{}
tr.RegisterProtocol("libp2p", p2phttp.NewTransport(clientHost))
client := &http.Client{Transport: tr}
res, err := client.Get("libp2p://Qmaoi4isbcTbFfohQyn28EiYM5CDWQx9QRCjDh3CTeiY7P/hello")
Contribute
PRs accepted.
License
MIT © Protocol Labs, Inc.
Documentation
¶
Overview ¶
Package p2phttp allows to serve HTTP endpoints and make HTTP requests through LibP2P (https://github.com/libp2p/libp2p) using Go's standard "http" and "net" stacks.
Instead of the regular "host:port" addressing, `p2phttp` uses a Peer ID and lets LibP2P take care of the routing, thus taking advantage of features like multi-routes, NAT transversal and stream multiplexing over a single connection.
When already running a LibP2P facility, this package allows to expose existing HTTP-based services (like REST APIs) through LibP2P and to use those services with minimal changes to the code-base.
For example, a simple http.Server on LibP2P works as:
listener, _ := gostream.Listen(host1, p2phttp.DefaultP2PProtocol)
defer listener.Close()
go func() {
http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hi!"))
})
server := &http.Server{}
server.Serve(listener)
}
...
As shown above, a Server only needs a "github.com/libp2p/go-libp2p-gostream" listener. This listener will use a libP2P host to watch for stream tagged with our Protocol.
On the other side, a client just needs to be initialized with a custom LibP2P host-based transport to perform requests to such server:
tr := &http.Transport{}
tr.RegisterProtocol("libp2p", p2phttp.NewTransport(clientHost))
client := &http.Client{Transport: tr}
res, err := client.Get("libp2p://Qmaoi4isbcTbFfohQyn28EiYM5CDWQx9QRCjDh3CTeiY7P/hello")
...
In the example above, the client registers a "libp2p" protocol for which the custom transport is used. It can still perform regular "http" requests. The protocol name used is arbitraty and non standard.
Note that LibP2P hosts cannot dial to themselves, so there is no possibility of using the same host as server and as client.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultP2PProtocol protocol.ID = "/libp2p-http"
DefaultP2PProtocol is used to tag and identify streams handled by go-libp2p-http
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(o *options)
Option allows to set the libp2p transport options.
func ProtocolOption ¶
ProtocolOption sets the Protocol Tag associated to the libp2p roundtripper.
type RoundTripper ¶
type RoundTripper struct {
// contains filtered or unexported fields
}
RoundTripper implemenets http.RoundTrip and can be used as custom transport with Go http.Client.
func NewTransport ¶
func NewTransport(h host.Host, opts ...Option) *RoundTripper
NewTransport returns a new RoundTripper which uses the provided libP2P host to perform an http request and obtain the response.
The typical use case for NewTransport is to register the "libp2p" protocol with a Transport, as in:
t := &http.Transport{}
t.RegisterProtocol("libp2p", p2phttp.NewTransport(host, ProtocolOption(DefaultP2PProtocol)))
c := &http.Client{Transport: t}
res, err := c.Get("libp2p://Qmaoi4isbcTbFfohQyn28EiYM5CDWQx9QRCjDh3CTeiY7P/index.html")
...
Source Files