proxy

Documentation

Index

• Constants
• Variables
• func StreamNetworkData(ctx context.Context, east, west DeadlineReaderWriter) (*NetworkStreamResult, *NetworkStreamResult)
• type DeadlineReader
• type DeadlineReaderWriter
• type DeadlineWriter
• type Endpoint
• type NetworkStreamResult
  • func (nsr *NetworkStreamResult) LogProperties() map[string]string
• type Proxy
  • func NewRuntimeProxy(mode apiv1.PortProtocol, listenAddress string, listenPort int32, ...) Proxy
• type ProxyConfig
  • func (pc *ProxyConfig) Clone() ProxyConfig
  • func (pc *ProxyConfig) String() string
• type ProxyConn
• type ProxyFactory
• type ProxyState
  • func (s ProxyState) String() string

Constants

const (
	// Timeouts used for the read operation. When the read request times out, it gives us the opportunity
	// to check for pending write requests and whether the proxy connection should be shut down.
	// Reads are interruptible by writes (meaning arriving write will cancel the read operation),
	// so the read timeout can be relatively long.
	DefaultReadTimeout = 3 * time.Second

	// Timeout used for the write operation.
	DefaultWriteTimeout = 5 * time.Second

	// The default connection timeout for establishing a TCP connections.
	DefaultConnectionTimeout = 5 * time.Second

	// The maximum number of UDP packets that will be cached for a single client.
	MaxCachedUdpPackets = 20

	// Even though the maximum UDP packet size is 64 kB, most networks have a maximum transmission unit (MTU)
	// that is much lower. E.g. Ethernet MTU is only 1500 bytes. And packet fragmentation is something
	// that every UDP client must be prepared to deal with.
	// That is why we use a buffer of 4kB for UDP packet data.
	UdpPacketBufferSize = 4 * 1024

	// The size of the TCP data buffer, used for single read between two TCP connections (32 kB).
	TcpDataBufferSize = 32 * 1024

	// The time after which a UDP stream will be shut down if it has not been used.
	UdpStreamInactivityTimeout = 2 * time.Minute

	// The maximum number of parked TCP connections allowed.
	// If exceeded, the oldest parked connection will be closed.
	MaxParkedConnections = 20

	// The maximum buffer size for a parked connection (1 MB).
	ParkedConnectionMaxBufferSize = 1024 * 1024
)

Variables

var ErrWriteQueueFull = errors.New("write queue is full")

var (
	Never = time.Time{}
)

var SilenceTcpStreamCompletionErrors = &atomic.Bool{}

If set, the proxy will not log TCP stream execution errors upon stream completion. This is useful for handling application shutdown, when TCP stream abrupt terminations are expected.

Functions

func StreamNetworkData

func StreamNetworkData(
	ctx context.Context,
	east, west DeadlineReaderWriter,
) (*NetworkStreamResult, *NetworkStreamResult)

Streams data between two network connections, both ways, until an error occurs with either connection. Returns the NetworkStreamResult for each connection.

Types

type DeadlineReader

type DeadlineReader interface {
	io.Reader
	SetReadDeadline(t time.Time) error
}

type DeadlineReaderWriter

type DeadlineReaderWriter interface {
	DeadlineReader
	DeadlineWriter
	SetDeadline(t time.Time) error
	Close() error
}

type DeadlineWriter

type DeadlineWriter interface {
	io.Writer
	SetWriteDeadline(t time.Time) error
}

type Endpoint

type Endpoint struct {
	Address string `yaml:"address"`
	Port    int32  `yaml:"port"`
}

type NetworkStreamResult

type NetworkStreamResult struct {
	BytesRead                    int64
	BytesWritten                 int64
	LastSuccessfulReadTimestamp  time.Time
	LastSuccessfulWriteTimestamp time.Time
	ReadError                    error
	WriteError                   error
	ReadErrorTimestamp           time.Time
	WriteErrorTimestamp          time.Time
}

func (*NetworkStreamResult) LogProperties

func (nsr *NetworkStreamResult) LogProperties() map[string]string

type Proxy

type Proxy interface {
	Start() error
	Configure(ProxyConfig) error
	State() ProxyState
	ListenAddress() string
	ListenPort() int32
	EffectiveAddress() string
	EffectivePort() int32
}

Represents a reverse proxy.

After Start() method is called, the proxy will listen on the specified address and port (which cannot be changed after the proxy is created), and forward incoming connections to the endpoints specified by the configuration (supplied via Configure() method). The proxy will stop when the lifetime context is cancelled (passed via ProxyFactory.CreateProxy()).

func NewRuntimeProxy

func NewRuntimeProxy(mode apiv1.PortProtocol, listenAddress string, listenPort int32, lifetimeCtx context.Context, log logr.Logger) Proxy

type ProxyConfig

type ProxyConfig struct {
	Endpoints []Endpoint
}

func (*ProxyConfig) Clone

func (pc *ProxyConfig) Clone() ProxyConfig

func (*ProxyConfig) String

func (pc *ProxyConfig) String() string

type ProxyConn

type ProxyConn interface {
	// Queues a write of the given data to the connection.
	// The error returned (if any) indicates the failure to queue the write.
	// The actual write operation may fail asynchronously, and the error will be reported via Result().
	// If the returned error is ErrWriteQueueFull, the client should wait a bit and retry.
	QueueWrite(data []byte) error

	// Returns the channel that lets the client check whether the run loop has finished.
	Done() <-chan struct{}

	// Returns the connection-terminating result, if available.
	// Typically it is either an I/O error (e.g. the other side closed the connection,
	// represented by io.EOF), or the context associated with the connection was cancelled.
	Result() *NetworkStreamResult

	// Runs the connection's main loop (for reading and writing data).
	// The goroutine that calls Run() is the only goroutine that interacts with the underlying net.TCPConn connection.
	// The connections always work in pairs, and the main loop will stop when either connection fails or is closed by the client.
	Run(ProxyConn, logr.Logger)

	// Stops reading data from the connection, but writes any pending data to the connection,
	// then stops the main loop.
	// DrainAndStop() is a blocking operation that is goroutine-safe and idempotent.
	DrainAndStop()
}

ProxyConn defines an interface a network connection wrapper that helps the proxy use a network connection in a goroutine-safe, asynchronous way. All operations are goroutine-safe, except for Run().

ProxyConn does not do any network connection management (e.g. dialing, closing), It only reads and writes data to the connection, and sets read/write deadlines.

type ProxyFactory

type ProxyFactory func(
	mode apiv1.PortProtocol,
	listenAddress string,
	listenPort int32,
	lifetimeCtx context.Context,
	log logr.Logger,
) Proxy

Creates a reverse proxy.

If the listenAddress is empty, the proxy will listen on localhost. The Proxy.EffectiveAddress() returns the actual IPv4 or IPv6 address used for listening. If the port is 0, the proxy will listen on a random port. Proxy.EffectivePort() will return the actual listened-on port.

type ProxyState

type ProxyState uint32

const (
	ProxyStateInitial  ProxyState = 0x1
	ProxyStateRunning  ProxyState = 0x2
	ProxyStateFailed   ProxyState = 0x4
	ProxyStateFinished ProxyState = 0x8
	ProxyStateAny      ProxyState = 0xFFFFFFFF
)

func (ProxyState) String

func (s ProxyState) String() string