webwire

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

type ClientInfo struct {
	ConnectionTime time.Time
	UserAgent      string
	RemoteAddr     net.Addr
}

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

type ConnUpgrader interface {
	Upgrade(resp http.ResponseWriter, req *http.Request) (Socket, error)
}

type DefaultSessionKeyGenerator struct{}

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

type DisconnectedErr struct {
	Cause error
}

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

type JSONEncodedSession struct {
	Key        string                 `json:"k"`
	Creation   time.Time              `json:"c"`
	LastLookup time.Time              `json:"l"`
	Info       map[string]interface{} `json:"i,omitempty"`
}

type MaxSessConnsReachedErr struct{}

type Message struct {
	Name    string
	Payload Payload
	// contains filtered or unexported fields
}

type OptionValue = int32

type Payload struct {
	Encoding PayloadEncoding
	Data     []byte
}

type PayloadEncoding int

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

type ReqErr struct {
	Code    string
	Message string
}

type ReqInternalErr struct{}

type ReqSrvShutdownErr struct{}

type ReqTimeoutErr struct {
	Target time.Duration
}

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

type Server interface {
	// ServeHTTP implements the HTTP handler interface
	ServeHTTP(resp http.ResponseWriter, req *http.Request)

	// Run will luanch the webwire server blocking the calling goroutine
	// until the server is either gracefully shut down
	// or crashes returning an error
	Run() error

	// Addr returns the address the webwire server is listening on
	Addr() net.Addr

	// Shutdown appoints a server shutdown and blocks the calling goroutine
	// until the server is gracefully stopped awaiting all currently processed
	// signal and request handlers to return.
	// During the shutdown incoming connections are rejected
	// with 503 service unavailable.
	// Incoming requests are rejected with an error while incoming signals
	// are just ignored
	Shutdown() error

	// ActiveSessionsNum returns the number of currently active sessions
	ActiveSessionsNum() int

	// SessionConnectionsNum implements the SessionRegistry interface
	SessionConnectionsNum(sessionKey string) int

	// SessionConnections implements the SessionRegistry interface
	SessionConnections(sessionKey string) []*Client

	// CloseSession closes the session identified by the given key
	// and returns the number of closed connections.
	// If there was no session found -1 is returned
	CloseSession(sessionKey string) int
}

type ServerImplementation interface {
	// OnOptions is invoked when the websocket endpoint is examined by the client
	// using the HTTP OPTION method.
	OnOptions(resp http.ResponseWriter)

	// BeforeUpgrade is invoked right before the upgrade of an incoming HTTP connection request to
	// a WebSocket connection and can be used to intercept or prevent connection attempts.
	// If true is returned then the connection is normally established, though if false is returned
	// then the connection won't be established and will be canceled immediately
	BeforeUpgrade(resp http.ResponseWriter, req *http.Request) bool

	// OnClientConnected is invoked when a new client successfully established a connection
	// to the server.
	//
	// This hook will be invoked by the goroutine serving the client and thus will block the
	// initialization process, detaining the client from starting to listen for incoming messages.
	// To prevent blocking the initialization process it is advised to move any time consuming work
	// to a separate goroutine
	OnClientConnected(client *Client)

	// OnClientDisconnected is invoked when a client closes the connection to the server
	//
	// This hook will be invoked by the goroutine serving the calling client before it's suspended
	OnClientDisconnected(client *Client)

	// OnSignal is invoked when the webwire server receives a signal from a client.
	//
	// This hook will be invoked by the goroutine serving the calling client and will block any
	// other interactions with this client while executing
	OnSignal(ctx context.Context, client *Client, message *Message)

	// OnRequest is invoked when the webwire server receives a request from a client.
	// It must return either a response payload or an error.
	//
	// A webwire.ReqErr error can be returned to reply with an error code and an error message,
	// this is useful when the clients user code needs to be able to understand the error
	// and react accordingly.
	// If a non-webwire error type is returned such as an error created by fmt.Errorf(),
	// a special kind of error (internal server error) is returned to the client as a reply,
	// in this case the error will be logged and the error message will not be sent to the client
	// for security reasons as this might accidentally leak sensitive information to the client.
	//
	// This hook will be invoked by the goroutine serving the calling client and will block any
	// other interactions with this client while executing
	OnRequest(
		ctx context.Context,
		client *Client,
		message *Message,
	) (response Payload, err error)
}

type ServerOptions struct {
	Address               string
	Sessions              OptionValue
	SessionManager        SessionManager
	SessionKeyGenerator   SessionKeyGenerator
	SessionInfoParser     SessionInfoParser
	MaxSessionConnections uint
	WarnLog               *log.Logger
	ErrorLog              *log.Logger
}

type SessNotFoundErr struct{}

type Session struct {
	Key        string
	Creation   time.Time
	LastLookup time.Time
	Info       SessionInfo
}

type SessionFile struct {
	Creation   time.Time              `json:"c"`
	LastLookup time.Time              `json:"l"`
	Info       map[string]interface{} `json:"i"`
}

type SessionInfo interface {
	// Fields must return the exact names of all fields
	// of the session info object. This getter method must be idempotent,
	// which means that it must always return the same list of names
	Fields() []string

	// Value must return an exact deep copy of the value of a session info
	// object field identified by the given field name.
	//
	// Note that returning a shallow copy (such as shallow copies of
	// maps or slices for example) could lead to potentially dangerous
	// race conditions and undefined behavior
	Value(fieldName string) interface{}

	// Copy must return an exact deep copy of the entire session info object.
	//
	// Note that returning a shallow copy (such as shallow copies of
	// maps or slices for example) could lead to potentially dangerous
	// race conditions and undefined behavior
	Copy() SessionInfo
}

type SessionInfoParser func(map[string]interface{}) SessionInfo

type SessionKeyGenerator interface {
	// Generate is invoked when the webwire server creates a new session and requires
	// a new session key to be generated. This hook must not be used except the user
	// knows exactly what he/she does as it would compromise security if implemented improperly
	Generate() string
}

type SessionLookupResult struct {
	Creation   time.Time
	LastLookup time.Time
	Info       map[string]interface{}
}

type SessionManager interface {
	// OnSessionCreated is invoked after the synchronization of the new session
	// to the remote client.
	// The actual created session is retrieved from the provided client agent.
	// If OnSessionCreated returns an error then this error is logged
	// but the session will not be destroyed and will remain active!
	// The only consequence of OnSessionCreation failing is that the server
	// won't be able to restore the session after the client is disconnected.
	//
	// This hook will be invoked by the goroutine calling the
	// client.CreateSession client agent method
	OnSessionCreated(client *Client) error

	// OnSessionLookup is invoked when the server is looking for a specific
	// session given its key.
	// If the session wasn't found it must return a webwire.SessNotFoundErr,
	// otherwise it must first update the LastLookup field of the session
	// to ensure it's not garbage collected and then return
	// a webwire.SessionLookupResult object containing the time of the sessions
	// creation and the exact copy of the session info object.
	//
	// If an error (that's not a webwire.SessNotFoundErr) is returned then
	// it'll be logged and the session restoration will fail.
	//
	// This hook will be invoked by the goroutine serving the associated client
	// and will block any other interactions with this client while executing
	//
	// WARNING: if this hooks doesn't update the LastLookup field of the found
	// session object then the session garbage collection won't work properly
	OnSessionLookup(key string) (result SessionLookupResult, err error)

	// OnSessionClosed is invoked when the session associated with the given key
	// is closed (thus destroyed) either by the server or the client.
	// A closed session must be permanently deleted and must not be discoverable
	// in the OnSessionLookup hook any longer.
	// If an error is returned then the it is logged.
	//
	// This hook is invoked by either a goroutine calling the client.CloseSession()
	// client agent method, or the goroutine serving the associated client,
	// in the case of which it will block any other interactions with
	// this client while executing
	OnSessionClosed(sessionKey string) error
}

type SessionsDisabledErr struct{}

type SockReadErr interface {
	// IsAbnormalCloseErr must return true if the error represents an abnormal closure error
	IsAbnormalCloseErr() bool
}

type Socket interface {
	// Dial must connect the socket to the specified server
	Dial(serverAddr string) error

	// Write must send the given data to the other side of the socket
	// while protecting the connection from concurrent writes
	Write(data []byte) error

	// Read must block the calling goroutine and await an incoming message.
	// When a message arrives or an error occurs Read must return.
	Read() ([]byte, SockReadErr)

	// IsConnected must return true if the given socket maintains an open connection,
	// otherwise return false
	IsConnected() bool

	// RemoteAddr must return the address of the remote client
	// or nil if the client is not connected
	RemoteAddr() net.Addr

	// Close must close the socket
	Close() error
}