common

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 6, 2020 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ResultSuccess indicates successful completion of requested admin action.
	ResultSuccess = 1
	// ResultNoActionReqd indicates that Requested operation didn't need any action.
	// The system is already in requested state.
	ResultNoActionReqd = 3
	// ResultFailed indicates Requested operation failure
	ResultFailed = 4
)

Following constants define values which are expected to be returned from various methods in BackendAdministrator interface.

View Source 
const (
	// RemoteConnectionNormalClosure indicates a proper, i.e. graceful, closure
	// of a connection to other end of a session. frontend can send this message
	// to backend on receipt of proper closure message in which case the backend
	// connection should terminate itself gracefully (with close code
	// CloseNormalClosure).
	//
	// When sent from backend to frontend, the frontend treats this message as
	// an indication that backend wants to close the frontend connection as well
	// and in this case frontend will gracefully close the connection with
	// remote client (with close code CloseNormalClosure).
	//
	// This message type is also used when an administrative request is made to
	// failover an active connection. The frontend will send this message to
	// backend which will result in backend connection terminating itself while
	// frontend attempt a new backend connection and starts sending data to this
	// new backend connection.
	RemoteConnectionNormalClosure = 32

	// RemoteConnectionAbnormalClosure indicate abnormal closure of the remote
	// end. When sent from backend to frontend, frontend treats as abnormal
	// backend error and attempts to initiate a new backend connection WITHOUT
	// terminating the frontend client connection. If a new backend connection
	// is obtained, current frontend connection is proxied to this new backend
	// connection. As far as the remote frontend connection is concerned, it
	// does not see any disruption.
	//
	// This message is NEVER sent by frontend to backend. Even an abnormal
	// frontend connection is indicated as RemoteConnectionNormalClosure by
	// frontend to backend. This is by design since backend can not initiate a
	// new connection to frontend remote end.
	RemoteConnectionAbnormalClosure = 64
)

Additional control message types which are used by balancer for state communication between frontend and backend connections. These are NOT standard message types and as such they will never appear on wire on either end of a session. These are used internally by balancer.

View Source 
const (
	// SubprotocolHeader Header name for websocket subprotocol, i.e. Sec-WebSocket-Protocol
	SubprotocolHeader = "Sec-WebSocket-Protocol"
	// ForwardedForHeader forwarded for header , i.e. X-Forwarded-For
	ForwardedForHeader = "X-Forwarded-For"
)

Constants which are commonly used across the balancer subsystem and as such it is expected that these will be useful across other packages as well which are trying to integrate with balancer in any shape or form.

Variables

This section is empty.

Functions

This section is empty.

Types

type BackendAdministrator 

type BackendAdministrator interface {
	BackendDialer

	// Prepares a list of backends and return as string. Returned string is
	// completely opaque to frontend and this is sent AS-IS over the
	// administrative API interface. The only assumption made by this interface
	// is that this data is JSON. Implementations are free to choose any
	// structure of this JSON as they seem appropriate. For best usage, it is
	// expected that the returned data at least contains the id of the backend
	// that can be further utilized in subsequent administrative calls. This is
	// further advised that the list also contains circuit status of the backend
	// if it supports one. This way it'll be possible for admin API consumers to
	// know if a specific backend is tripped due to which no new connection is
	// being sent to the backend.
	ListBackends() string

	// Add a new backend to the system. The data is completely opaque to
	// frontend and the data received over administrative endpoint will be
	// passed on AS-IS to this method. Decoding/Un-Marshalling this data
	// appropriately and bulding backend definition is the responsibility of the
	// implementation. The result, success or failure, shall be returned as a
	// JSON message by the implementation in any structure as they find
	// appropriate.
	AddBackend(data []byte) string

	// Returns the current configuration of backend with given id. Apart from
	// assuming that returned data is JSON, frontend do not expect any structure
	// of the JSON and pass it AS-IS to caller over the administrative API
	// interface.
	BackendConfig(id string) string

	// Disables the backend with given id. A disabled backend is retained in the
	// system but do not participate in any new connection attempt. All existing
	// connections to a disabled backend shall continue to work AS-IS without
	// any trouble. A disabled backend can be enabled again. This is typically
	// required while debugging specific issues with a backend OR while
	// switching from one backend to new backend. The returned status must be
	// one of the ResultXXX constant as defined in this package.
	DisableBackend(id string) (int, error)

	// Enables the backend with the given id. A disabled backend can be enabled
	// so that it starts participating in new connection requests normally. The
	// returned status must be one of the ResultXXX constant as defined in this
	// package.
	EnableBackend(id string) (int, error)

	// Deletes the backend with given id. A deleted backend practically do not
	// exists in the system any longer. The implementation must NOT terminate
	// any existing connection during the delete operation. Frontend will take
	// care of terminating respective connections once this API returns
	// successful response. The returned status must be one of the ResultXXX
	// constant as defined in this package.
	DeleteBackend(id string) (int, error)

	// Resets a tripped backend. A backend goes into tripped state the moment
	// consecutive number of failures go beyond configured threshold.The
	// returned status must be one of the ResultXXX constant as defined in this
	// package.
	ResetBackend(id string) (int, error)
}

BackendAdministrator provides administrative capabilities over available backends. As such the entire implementation of this interface is OPTIONAL. If provided, the implementation will be used to expose administrative API endpoints for managing available backends.

The implementation of this interface should ONLY affect backends state and MUST NOT administer any existing established backend connections which has been handed over to frontend already. All established backend connections, once handed over to frontend, are administrated by frontend only. As an example - calling DeleteBackend should delete the backend thus system will no longer have knowledge of this backend and this backend will NOT participate in any new connection request. However, any existing established connections to this backend MUST NOT be terminated by the implementation. These connections will be appropriately terminated by frontend on delete request successful completion.

type BackendConnection 

type BackendConnection interface {
	StartCloseIdentifier
	BackendID() string
	Subprotocol() string
	AdditionalHeaders() http.Header
}

BackendConnection is the client connection created from one of the backend

type BackendDialContext 

type BackendDialContext struct {
	// URL onto which the incoming websocket connection was made on frontend
	URL url.URL

	// All headers received by frontend excluding ignored headers
	DestHeaders *http.Header

	// Channel which will be populated with incoming frontend websocket messages.
	// These messages shall be processed and sent to the backend by backend connection.
	// In addition to data messages, this channel will also contain control messages
	// to communicate frontend connection state to backend OR asking backend to
	// shut itself down should there be an administrative request.
	Receive <-chan *WsMessage

	// Channel onto which the backend shall write messages which it intends to send
	// to the frontend connection over a proxy session. In addition to the data
	// messages, this channel will also be used to transmit control messages to
	// communicate backend connection state to frontend.
	Send chan<- *WsMessage

	// If a connection request to backend is being made against an existing connection which
	// needs re-establishment (say due to existing backend connection gone bad) then
	// existing connection object will be sent across in the context. This object and it's
	// internal state is totally opaque to frontend and it assumes that backend will use it
	// if it needs to for any purpose. In current implementation, the existing old connection
	// is used to fetch any unsent messages which MUST be sent first on the newly established
	// backend connection.
	OldConnection BackendConnection
}

BackendDialContext - an encapsulated context type which contains all the information using which a backend connection shall be made to one of the available backend. This encapsulation is expected to grow as more and more features are added to the balancer.

type BackendDialer 

type BackendDialer interface {
	// Creates a new BackendConnection against given context and returns
	// the connection if successful.
	//
	// If, due to any reason, the Dialer is not able to establish a connection
	// than the returned error indicates what the error was, frontned will
	// decide appropriately what response to send to remote client based
	// on the error returned. Frontend decision is much more deterministic
	// if the error is an instance of RemoteSystemError or it's subtype.
	DialUpstream(dialContext *BackendDialContext) (BackendConnection, error)
}

BackendDialer is used for requesting a fresh connection to any of the available backend servers. It is up-to the dialer to decide which backend server to use for connection. Once the connection is established and returned, the BackendDialer no longer control the connection instead it is completely governed by the frontend during it's entire life cycle.

type ConnectionDeclinedError 

type ConnectionDeclinedError struct {
	RemoteSystemError
}

ConnectionDeclinedError indicates that remote system is available but when attempted to connect, the remote system purposefully declined the connection, this could be due to various reasons like authentication failure etc. Balancer frontend system will terminate the client connection as well in this case aborting the session altogether.

func NewConnectionDeclinedError 

func NewConnectionDeclinedError(id string, err string, code int) *ConnectionDeclinedError

NewConnectionDeclinedError create new error with provided code

type FrontendConnection 

type FrontendConnection interface {
	StartCloseIdentifier
	FrontendID() string
}

FrontendConnection is the client connection obtained from Frontend server against an incoming request.

type Identifier 

type Identifier interface {
	GetID() string
}

Identifier - provides a unique id for the object that can be used for general purpose admin management operations, reporting and logging

type MessageValve 

type MessageValve interface {
	BeforeTransmit(*WsMessage) (*WsMessage, error)
	AfterReceive(*WsMessage) (*WsMessage, error)
}

MessageValve - a valve acts as a filter through which the message is passed before it is sent to backend server and after it's received from backend server. A valve can potentially modify a message and return modified message. If the return message is nil OR if the error is not nil then the message is discarded and no message is sent to the destination.

type ProxySession 

type ProxySession struct {
	FEConnection FrontendConnection
	BEConnection BackendConnection
}

ProxySession is an established live session with an incoming frontend connection and respective backend connection.

type RemoteSystemError 

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

RemoteSystemError An error thrown by balancer indicating remote backend system is not able to accept a new connection

func (*RemoteSystemError) Code 

func (rsu *RemoteSystemError) Code() int

Code returns the error code against this error

func (*RemoteSystemError) Error 

func (rsu *RemoteSystemError) Error() string

Error - format the error for reporting and logging

func (*RemoteSystemError) GetID 

func (rsu *RemoteSystemError) GetID() string

GetID returns remote system unique identifier

type SessionListener 

type SessionListener interface {
	SessionCreated(*ProxySession)
	SessionTerminated(*ProxySession)
}

SessionListener is notified on creation and termination of every proxy sessions. A reconnect results into SessionTerminated followed by SessionCreated calls.

type StartCloseIdentifier 

type StartCloseIdentifier interface {
	StartCloser
	Identifier
}

StartCloseIdentifier - combination of Starter, Closer and Identifier

type StartCloser 

type StartCloser interface {
	Starter
	io.Closer
}

StartCloser - can be started as well as closed for reading/writing

type Starter 

type Starter interface {
	Start()
}

Starter - can start reading and writing loops

type SystemUnavailableError 

type SystemUnavailableError struct {
	RemoteSystemError
}

SystemUnavailableError indicate backend system unavailability. This could happen due to network error OR due to 5xx HTTP error during connection. balancer system will attempt next available backend in this case.

func NewSystemUnavailableError 

func NewSystemUnavailableError(id string, err string) *SystemUnavailableError

NewSystemUnavailableError create new error without code

func NewSystemUnavailableErrorWithCode 

func NewSystemUnavailableErrorWithCode(id string, err string, code int) *SystemUnavailableError

NewSystemUnavailableErrorWithCode create new error with provided code

type ValveProvider 

type ValveProvider interface {
	AddValves(session *ProxySession, currentValves []MessageValve) []MessageValve
}

ValveProvider - An interface that can be used to add 0 or more MessageValve for every new session.

type WsMessage 

type WsMessage struct {
	MessageType int
	Data        []byte
}

WsMessage - message being exchanged b/w frontend and backend connections

func (*WsMessage) IsControl 

func (wm *WsMessage) IsControl() bool

IsControl returns true if this is a control message, false otherwise.

func (*WsMessage) String 

func (wm *WsMessage) String() string

String returns a human readable form of the given message for logging purposes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.