libp2phttp

package

v0.0.0-...-06db429 Latest Latest Go to latest Published: Jan 20, 2024 License: MIT Imports: 21 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/genovatix/genovatix-go-pkg

Links

Open Source Insights

Documentation ¶

Overview ¶

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

Index ¶

Constants
Variables
func PreferHTTPTransport(o roundTripperOpts) roundTripperOpts
func ServerMustAuthenticatePeerID(o roundTripperOpts) roundTripperOpts
type Host
type PeerMeta
type PeerMetadataGetter
type ProtocolMeta
type RoundTripperOption
type WellKnownHandler

Constants ¶

View Source

const ProtocolIDForMultistreamSelect = "/http/1.1"

Variables ¶

View Source

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 libp2p 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/libp2p/specs/pull/564).

Types ¶

type Host ¶

type Host struct {
	// StreamHost is a stream based libp2p host used to do HTTP over libp2p 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/libp2p`
	// 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 libp2p 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.

Example (ListenOnHTTPTransportAndStreams) ¶

serverStreamHost, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/udp/50124/quic-v1"))
if err != nil {
	log.Fatal(err)
}
server := libp2phttp.Host{
	InsecureAllowHTTP: true, // For our example, we'll allow insecure HTTP
	ListenAddrs:       []ma.Multiaddr{ma.StringCast("/ip4/127.0.0.1/tcp/50124/http")},
	StreamHost:        serverStreamHost,
}
go server.Serve()
defer server.Close()

fmt.Println("Server listening on:", server.Addrs())

Output:

Server listening on: [/ip4/127.0.0.1/udp/50124/quic-v1 /ip4/127.0.0.1/tcp/50124/http]

Example (OverLibp2pStreams) ¶

serverStreamHost, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/udp/0/quic-v1"))
if err != nil {
	log.Fatal(err)
}

server := libp2phttp.Host{
	StreamHost: serverStreamHost,
}

// A server with a simple echo protocol
server.SetHTTPHandler("/echo/1.0.0", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.Header().Add("Content-Type", "application/octet-stream")
	io.Copy(w, r.Body)
}))
go server.Serve()
defer server.Close()

clientStreamHost, err := libp2p.New(libp2p.NoListenAddrs)
if err != nil {
	log.Fatal(err)
}

client := libp2phttp.Host{StreamHost: clientStreamHost}

// Make an HTTP request using the Go standard library, but over libp2p
// streams. If the server were listening on an HTTP transport, this could
// also make the request over the HTTP transport.
httpClient, err := client.NamespacedClient("/echo/1.0.0", peer.AddrInfo{ID: server.PeerID(), Addrs: server.Addrs()})

// Only need to Post to "/" because this client is namespaced to the "/echo/1.0.0" protocol.
resp, err := httpClient.Post("/", "application/octet-stream", strings.NewReader("Hello HTTP"))
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()

body, err := io.ReadAll(resp.Body)
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(body))

Output:

Hello HTTP

Example (WithAStockGoHTTPClient) ¶

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"strings"

	libp2phttp "github.com/libp2p/go-libp2p/p2p/http"

	ma "github.com/multiformats/go-multiaddr"
)

func main() {
	server := libp2phttp.Host{
		InsecureAllowHTTP: true, // For our example, we'll allow insecure HTTP
		ListenAddrs:       []ma.Multiaddr{ma.StringCast("/ip4/127.0.0.1/tcp/0/http")},
	}

	// A server with a simple echo protocol
	server.SetHTTPHandler("/echo/1.0.0", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Add("Content-Type", "application/octet-stream")
		io.Copy(w, r.Body)
	}))
	go server.Serve()
	defer server.Close()

	var serverHTTPPort string
	var err error
	for _, a := range server.Addrs() {
		serverHTTPPort, err = a.ValueForProtocol(ma.P_TCP)
		if err == nil {
			break
		}
	}
	if err != nil {
		log.Fatal(err)
	}

	// Make an HTTP request using the Go standard library.
	resp, err := http.Post("http://127.0.0.1:"+serverHTTPPort+"/echo/1.0.0/", "application/octet-stream", strings.NewReader("Hello HTTP"))
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(body))

}

Output:

Hello HTTP

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.

Example ¶

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"

	"github.com/libp2p/go-libp2p/core/peer"

	libp2phttp "github.com/libp2p/go-libp2p/p2p/http"

	ma "github.com/multiformats/go-multiaddr"
)

func main() {
	var client libp2phttp.Host

	// Create the server
	server := libp2phttp.Host{
		InsecureAllowHTTP: true, // For our example, we'll allow insecure HTTP
		ListenAddrs:       []ma.Multiaddr{ma.StringCast("/ip4/127.0.0.1/tcp/50223/http")},
	}

	server.SetHTTPHandler("/hello/1", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Add("Content-Type", "text/plain")
		w.Write([]byte("Hello World"))
	}))

	go server.Serve()
	defer server.Close()

	// Create an http.Roundtripper for the server
	rt, err := client.NewConstrainedRoundTripper(peer.AddrInfo{ID: server.PeerID(), Addrs: server.Addrs()})
	if err != nil {
		log.Fatal(err)
	}

	// Namespace this roundtripper to a specific protocol
	rt, err = client.NamespaceRoundTripper(rt, "/hello/1", server.PeerID())
	if err != nil {
		log.Fatal(err)
	}

	resp, err := (&http.Client{Transport: rt}).Get("/")
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(respBody))

}

Output:

Hello World

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.

Example ¶

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"

	"github.com/libp2p/go-libp2p/core/peer"

	libp2phttp "github.com/libp2p/go-libp2p/p2p/http"

	ma "github.com/multiformats/go-multiaddr"
)

func main() {
	var client libp2phttp.Host

	// Create the server
	server := libp2phttp.Host{
		InsecureAllowHTTP: true, // For our example, we'll allow insecure HTTP
		ListenAddrs:       []ma.Multiaddr{ma.StringCast("/ip4/127.0.0.1/tcp/50221/http")},
	}

	server.SetHTTPHandlerAtPath("/hello/1", "/other-place/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Add("Content-Type", "text/plain")
		w.Write([]byte("Hello World"))
	}))

	go server.Serve()
	defer server.Close()

	// Create an http.Client that is namespaced to this protocol.
	httpClient, err := client.NamespacedClient("/hello/1", peer.AddrInfo{ID: server.PeerID(), Addrs: server.Addrs()})
	if err != nil {
		log.Fatal(err)
	}

	resp, err := httpClient.Get("/")
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(respBody))

}

Output:

Hello World

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.

Example ¶

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"

	"github.com/libp2p/go-libp2p/core/peer"

	libp2phttp "github.com/libp2p/go-libp2p/p2p/http"

	ma "github.com/multiformats/go-multiaddr"
)

func main() {
	var client libp2phttp.Host

	// Create the server
	server := libp2phttp.Host{
		InsecureAllowHTTP: true, // For our example, we'll allow insecure HTTP
		ListenAddrs:       []ma.Multiaddr{ma.StringCast("/ip4/127.0.0.1/tcp/50225/http")},
	}

	server.SetHTTPHandler("/hello/1", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Add("Content-Type", "text/plain")
		w.Write([]byte("Hello World"))
	}))

	go server.Serve()
	defer server.Close()

	// Create an http.Roundtripper for the server
	rt, err := client.NewConstrainedRoundTripper(peer.AddrInfo{ID: server.PeerID(), Addrs: server.Addrs()})
	if err != nil {
		log.Fatal(err)
	}

	resp, err := (&http.Client{Transport: rt}).Get("/hello/1")
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(respBody))

}

Output:

Hello World

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.

Example ¶

package main

import (
	"fmt"

	libp2phttp "github.com/libp2p/go-libp2p/p2p/http"

	ma "github.com/multiformats/go-multiaddr"
)

func main() {
	server := libp2phttp.Host{
		InsecureAllowHTTP: true, // For our example, we'll allow insecure HTTP
		ListenAddrs:       []ma.Multiaddr{ma.StringCast("/ip4/127.0.0.1/tcp/50221/http")},
	}

	go server.Serve()
	defer server.Close()

	fmt.Println(server.Addrs())

}

Output:

[/ip4/127.0.0.1/tcp/50221/http]

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/libp2p mapping. http.StripPrefix is called on the handler, so the handler will be unaware of its prefix path.

Example ¶

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"

	libp2phttp "github.com/libp2p/go-libp2p/p2p/http"

	ma "github.com/multiformats/go-multiaddr"
)

func main() {
	server := libp2phttp.Host{
		InsecureAllowHTTP: true, // For our example, we'll allow insecure HTTP
		ListenAddrs:       []ma.Multiaddr{ma.StringCast("/ip4/127.0.0.1/tcp/50222/http")},
	}

	server.SetHTTPHandler("/hello/1", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Add("Content-Type", "text/plain")
		w.Write([]byte("Hello World"))
	}))

	go server.Serve()
	defer server.Close()

	port, err := server.Addrs()[0].ValueForProtocol(ma.P_TCP)
	if err != nil {
		log.Fatal(err)
	}

	resp, err := http.Get("http://127.0.0.1:" + port + "/hello/1/")
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(respBody))

}

Output:

Hello World

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/libp2p mapping. http.StripPrefix is called on the handler, so the handler will be unaware of its prefix path.

Example ¶

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"

	libp2phttp "github.com/libp2p/go-libp2p/p2p/http"

	ma "github.com/multiformats/go-multiaddr"
)

func main() {
	server := libp2phttp.Host{
		InsecureAllowHTTP: true, // For our example, we'll allow insecure HTTP
		ListenAddrs:       []ma.Multiaddr{ma.StringCast("/ip4/127.0.0.1/tcp/50224/http")},
	}

	server.SetHTTPHandlerAtPath("/hello/1", "/other-place/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Add("Content-Type", "text/plain")
		w.Write([]byte("Hello World"))
	}))

	go server.Serve()
	defer server.Close()

	port, err := server.Addrs()[0].ValueForProtocol(ma.P_TCP)
	if err != nil {
		log.Fatal(err)
	}

	resp, err := http.Get("http://127.0.0.1:" + port + "/other-place/")
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(respBody))

}

Output:

Hello World

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/libp2p resource

Example ¶

package main

import (
	"fmt"
	"io"
	"log"
	"net"
	"net/http"

	libp2phttp "github.com/libp2p/go-libp2p/p2p/http"
)

func main() {
	var h libp2phttp.WellKnownHandler
	h.AddProtocolMeta("/hello/1", libp2phttp.ProtocolMeta{
		Path: "/hello-path/",
	})

	listener, err := net.Listen("tcp", "127.0.0.1:0")
	if err != nil {
		log.Fatal(err)
	}

	defer listener.Close()
	// Serve `.well-known/libp2p`. Note, this is handled automatically if you use the libp2phttp.Host.
	go http.Serve(listener, &h)

	// Get the `.well-known/libp2p` resource
	resp, err := http.Get("http://" + listener.Addr().String() + "/.well-known/libp2p")
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(respBody))
}

Output:

{"/hello/1":{"path":"/hello-path/"}}

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 ¶

View all Source files

Directories ¶

Path	Synopsis
ping

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL