client

Documentation

Overview

package client

The client package contains the client-side types for interfacing with reverst tunnels. The client itself is a http Server implementation that dials out to a tunnel server, performs a handshake to identify and authenticate the relevant tunnel group to register with, and then it switches roles into that of the server.

Example

package main

import (
    "context"
    "crypto/tls"
    "net/http"

    "go.flipt.io/reverst/client"
)

func main() {
    server := &client.Server {
        TunnelGroup: "some-group",
        Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request {
            w.Write([]byte("Hello, World!"))
        })),
        TLSConfig: &tls.Config{InsecureSkipVerify: true}
    }

    server.DialAndServe(ctx, "some.reverst.tunnel:8443")
}

Index

• Variables
• type Authenticator
  • func BasicAuthenticator(username, password string, opts ...AuthorizationOption) Authenticator
  • func BearerAuthenticator(token string, opts ...AuthorizationOption) Authenticator
• type AuthenticatorFunc
  • func (a AuthenticatorFunc) Authenticate(ctx context.Context, r *protocol.RegisterListenerRequest) error
• type AuthenticatorOptions
• type AuthorizationOption
  • func WithScheme(scheme string) AuthorizationOption
• type Server
  • func (s *Server) DialAndServe(ctx context.Context, addr string) (err error)

Variables

var (
	// DefaultTLSConfig is the default configuration used for establishing
	// TLS over QUIC.
	DefaultTLSConfig = &tls.Config{
		NextProtos: []string{protocol.Name},
	}
	// DefaultQuicConfig is the default configuration used for establishing
	// QUIC connections.
	DefaultQuicConfig = &quic.Config{
		MaxIdleTimeout:  20 * time.Second,
		KeepAlivePeriod: 10 * time.Second,
	}

	// DefaultBackoff is the default backoff used when dialing and serving
	// a connection.
	DefaultBackoff = wait.Backoff{
		Steps:    5,
		Duration: 100 * time.Millisecond,
		Factor:   2.0,
		Jitter:   0.1,
	}

	// ErrNotFound is returned when a tunnel group is referenced that the
	// target reverst tunnel server does not known (CodeNotFound)
	ErrNotFound = errors.New("not found")
	// ErrBadRequest is returned when a tunnel registration request is rejected
	// due to an unexpected request payload (CodeBadRequest)
	ErrBadRequest = errors.New("bad request")
	// ErrUnauthorized is returned when the caller is not properly authenticated to
	// establish a tunnel on the request tunnel group (CodeUnauthorized)
	ErrUnauthorized = errors.New("unauthorized")
	// ErrServerError is returned when something unexplained went wrong on the
	// remote reverst tunnel server (CodeServerError)
	ErrServerError = errors.New("server error")
)

Types

type Authenticator

type Authenticator interface {
	Authenticate(context.Context, *protocol.RegisterListenerRequest) error
}

Authenticator is a type which adds authentication credentials to an outbound register listener request. It is called before the request is serialized and written to the stream.

func BasicAuthenticator

func BasicAuthenticator(username, password string, opts ...AuthorizationOption) Authenticator

BasicAuthenticator returns an instance of Authenticator which configures Basic authentication on requests passed to Authenticate using the provided username and password

func BearerAuthenticator

func BearerAuthenticator(token string, opts ...AuthorizationOption) Authenticator

BearerAuthenticator returns an instance of Authenticator which configures Bearer authentication on requests passed to Authenticate using the provided token string

type AuthenticatorFunc

type AuthenticatorFunc func(context.Context, *protocol.RegisterListenerRequest) error

AuthenticatorFunc is a function which implements the Authenticator interface

func (AuthenticatorFunc) Authenticate

func (a AuthenticatorFunc) Authenticate(ctx context.Context, r *protocol.RegisterListenerRequest) error

Authenticate delegates to the underlying AuthenticatorFunc

type AuthenticatorOptions

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

type AuthorizationOption

type AuthorizationOption func(*AuthenticatorOptions)

func WithScheme

func WithScheme(scheme string) AuthorizationOption

type Server

type Server struct {
	// TunnelGroup is an identifier for the group in which this server should
	// be registered against on the target tunnel server.
	TunnelGroup string

	// Handler is the root http.Handler of the server instance.
	Handler http.Handler

	// Logger allows the caller to configure a custome *slog.Logger instance.
	// If not defined then Server uses the default instance returned by slog.Default.
	Logger *slog.Logger

	// TLSConfig is used to configure TLS encryption over the Quic connection.
	// See DefaultTLSConfig for the parameters used which this is set to nil.
	TLSConfig *tls.Config

	// QuicConfig is used to configure Quic connections.
	// See DefaultQuicConfig for the parameters used which this is set to nil.
	QuicConfig *quic.Config

	// Authenticator is the Authenticator used to authenticate outbound
	// listener registration requests.
	Authenticator Authenticator

	// OnConnectionReady is called when the server has successfully
	// registered itself with the upstream tunnel server
	OnConnectionReady func(protocol.RegisterListenerResponse)
}

Server is an alternative HTTP server that dials to a reverst Tunnel server and attempts to remotely register itself as a listener. Given the connection is established and authorized as a valid listener the server switches into serving mode and handles HTTP/3 requests over the connection. The Tunnel should forward requests to this connection and any others in the same tunnel group. The group is identified via the TLSConfig.ServerName.

func (*Server) DialAndServe

func (s *Server) DialAndServe(ctx context.Context, addr string) (err error)

DialAndServe dials out to the provided address and attempts to register the server as a listener on the remote tunnel group.