Documentation
¶
Index ¶
- type Client
- func (c *Client) Context() context.Context
- func (c *Client) Credentials(ctx context.Context) (*nethernet.Credentials, error)
- func (c *Client) DisableTrickleICE() bool
- func (c *Client) NetworkID() string
- func (c *Client) Notify(n nethernet.Notifier) (stop func())
- func (c *Client) PongData([]byte)
- func (c *Client) Signal(ctx context.Context, signal *nethernet.Signal) error
- type ClientConfig
- type Handler
- func (h *Handler) Close() error
- func (h *Handler) Context() context.Context
- func (h *Handler) Credentials(ctx context.Context) (*nethernet.Credentials, error)
- func (h *Handler) DisableTrickleICE() bool
- func (h *Handler) NetworkID() string
- func (h *Handler) Notify(n nethernet.Notifier) (stop func())
- func (h *Handler) PongData([]byte)
- func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
- func (h *Handler) Signal(ctx context.Context, signal *nethernet.Signal) error
- type HandlerConfig
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client implements nethernet.Signaling using the HTTP endpoints exposed by a NetherNet server.
Example ¶
ExampleClient demonstrates how to connect to a NetherNet server using HTTP signaling.
// Create a signaling client.
// This client is responsible for exchanging WebRTC connection details with the server over HTTP.
client := NewClient()
// Establish a NetherNet connection using the client for the signaling.
var d nethernet.Dialer
conn, err := d.DialContext(context.TODO(), "https://localhost:19132", client)
if err != nil {
panic(fmt.Sprintf("error connecting to server: %s", err))
}
defer conn.Close()
fmt.Printf("connected, latency: %s", conn.Latency())
func NewClient ¶
func NewClient() *Client
NewClient creates a new Client with the default ClientConfig. It is equivalent to calling ClientConfig{}.New().
func (*Client) Context ¶
Context always returns context.Background.
func (*Client) Credentials ¶
Credentials returns a nethernet.Credentials using the ClientConfig.Credentials if possible. Otherwise, it returns an empty nethernet.Credentials. It is optimal for the caller to provide ClientConfig.Credentials containing STUN/TURN servers in order to stabilize WebRTC peer negotiations.
func (*Client) DisableTrickleICE ¶
DisableTrickleICE always returns true as it is not supported because the HTTP request-response model requires the full SDP exchange to complete within a single round trip. A peer connection should wait for all local ICE candidates to be gathered and include them as SDP attributes in the initial offer.
func (*Client) NetworkID ¶
NetworkID returns a network ID assigned for this Client. It is included to the URL path of requests sent to servers. Callers can specify this value from ClientConfig.NetworkID.
type ClientConfig ¶
type ClientConfig struct {
// HTTPClient is the HTTP client used for making HTTP requests to the remote servers.
// If nil, [http.DefaultClient] will be used instead.
HTTPClient *http.Client
// Credentials is an optional function that supplies ICE credentials
// to the ICE gatherer used by the peer connection.
// When nil, [Handler.Credentials] returns an empty [nethernet.Credentials]
// with no STUN/TURN servers, which may reduce NAT traversal reliability.
Credentials func(ctx context.Context) (*nethernet.Credentials, error)
// Logger is used to log messages produced when handling requests.
// If nil, it will be set from [slog.Default].
Logger *slog.Logger
// NetworkID is the identifier assigned to this Handler.
// It is included to the URL path of requests sent to servers.
// If empty, a random uint64 is generated and used.
NetworkID string
}
ClientConfig represents a configuration for creating a Client.
func (ClientConfig) New ¶
func (conf ClientConfig) New() *Client
New returns a new Client from the configuration. The resulting Client can be passed to nethernet.Dialer.DialContext.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler is an http.Handler that negotiates incoming NetherNet connections over HTTP. Callers can create a Handler from NewHandler or HandlerConfig.New, then pass it to http.ListenAndServeTLS or assign to http.Server.Handler.
Currently, Handler implements the following endpoints:
- GET /v1/join (ping)
- POST /v1/join/{networkID} (WebRTC negotiation)
func NewHandler ¶
func NewHandler() *Handler
NewHandler creates a new Handler with default HandlerConfig values and returns it. It is equivalent to calling HandlerConfig{}.New().
func ServeTLS ¶ added in v1.0.16
ServeTLS is a utility method that set-ups an HTTP/TLS server on the specified address using the TLS certificate and key file. It is equivalent of calling HandlerConfig{}.ServeTLS().
func (*Handler) Close ¶ added in v1.0.16
Close closes the underlying HTTP server, if one is bound. Otherwise, Close is no-op.
func (*Handler) Context ¶
Context returns the background context of the underlying HTTP server, if one is bound to this Handler. Otherwise, Context always returns context.Background.
func (*Handler) Credentials ¶
Credentials returns a nethernet.Credentials using the HandlerConfig.Credentials if possible. Otherwise, it returns an empty nethernet.Credentials. It is optimal for the caller to provide HandlerConfig.Credentials containing STUN/TURN servers in order to stabilize WebRTC peer negotiations.
func (*Handler) DisableTrickleICE ¶
DisableTrickleICE always returns true as it is not supported because the HTTP request-response model requires the full SDP exchange to complete within a single round trip. A peer connection should wait for all local ICE candidates to be gathered and include them as SDP attributes in the initial offer.
func (*Handler) NetworkID ¶
NetworkID returns a network ID assigned for this Handler. This is never transmitted to clients and is currently only used for locally identifying this Handler.
func (*Handler) PongData ¶
PongData is a no-op implementation of nethernet.Signaling.PongData. It may become meaningful in the future if Mojang introduces an HTTP endpoint for serving MOTDs.
func (*Handler) ServeHTTP ¶
func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP implements http.Handler by delegating the given response writer and the request to the internal http.ServeMux.
func (*Handler) Signal ¶
Signal delivers a signal to the pending negotiation identified by the nethernet.Signal.NetworkID and nethernet.Signal.ConnectionID.
type HandlerConfig ¶
type HandlerConfig struct {
// Logger is used to log messages produced when handling requests.
// If nil, it will be set from [slog.Default].
Logger *slog.Logger
// NegotiationContext returns the [context.Context] that controls how long
// the Handler waits for the listener to produce an SDP answer.
// The resulting [context.Context] must be derived from the parent context.
// If nil, a context with a 15-second timeout will be returned.
NegotiationContext func(parent context.Context) (context.Context, context.CancelFunc)
// Credentials is an optional function that supplies ICE credentials
// to the ICE gatherer used by the peer connection.
// When nil, [Handler.Credentials] returns an empty [nethernet.Credentials]
// with no STUN/TURN servers, which may reduce NAT traversal reliability.
Credentials func(ctx context.Context) (*nethernet.Credentials, error)
// NetworkID is the identifier assigned to this Handler.
// It is used only for identifying Handler and is never transmitted to clients.
// If empty, a random uint64 is generated and used.
NetworkID string
}
HandlerConfig represents a configuration for creating a Handler.
func (HandlerConfig) New ¶
func (conf HandlerConfig) New() *Handler
New returns a new Handler from the configuration. The resulting Handler can be passed directly to http.ListenAndServeTLS or assigned to http.Server.Handler.
Source Files