core

Documentation

Index

• Constants
• Variables
• type Bridge
  • func CreateBridge(ctx context.Context, clientID string, w http.ResponseWriter, r *http.Request) (Bridge, error)
• type BridgeCreateParams
• type BridgeDatabase
• type BridgeDoc
• type BridgeIdentityInfo
• type BridgeManager
• type BridgeMessage
• type BridgeStatus
• type CodeAndReason
  • func (c *CodeAndReason) Error() string
• type DiscoveryAddressResolver
• type IncomingMessageReq
• type IntercomService
• type OutgoingMessageInternalReq
• type OutgoingMessageInternalRes
  • func SendMessageInternal(ctx context.Context, req *OutgoingMessageInternalReq) (*OutgoingMessageInternalRes, error)
• type OutgoingMessageReq
• type OutgoingMessageRes
  • func SendMessage(ctx context.Context, request *OutgoingMessageReq) (*OutgoingMessageRes, error)

Constants

const (
	// MessageIncomingReq is the type for an incoming message request.
	MessageIncomingReq string = "INCOMING_MESSAGE_REQ"
	// MessageOutgoingReq is the type for an outgoing message request.
	MessageOutgoingReq string = "OUTGOING_MESSAGE_REQ"
	// MessageOutgoingRes is the type for an outgoing message response.
	MessageOutgoingRes string = "OUTGOING_MESSAGE_RES"
	// MessageErrorRes is the type for all error messages.
	MessageErrorRes string = "ERROR_RES"
)

Message types.

const (
	// CodeOK is the success code for all scenarios.
	CodeOK = "OK"
	// CodeOffline indicates that the concerned client is offline.
	CodeOffline = "OFFLINE"
	// CodeBridgeNotFound is sent when the required bridge does not exist.
	CodeBridgeNotFound = "BRIDGE_NOT_FOUND"
	// CodeUnknown indicates that an unknown error occurred.
	CodeUnknown = "UNKNOWN"
)

Variables

var (
	BridgeMG BridgeManager
	BridgeDB BridgeDatabase
	Discover DiscoveryAddressResolver
	Intercom IntercomService
)

These dependencies must be assigned before using the core.

Types

type Bridge

type Bridge interface {
	// Identify provides the bridge's identity information.
	Identify() *BridgeIdentityInfo
	// SendMessage sends a new message over the bridge.
	SendMessage(ctx context.Context, message *BridgeMessage) error

	// SetMessageHandler sets the message handler for the bridge.
	// All messages that arrive at this bridge will be handled by this function.
	SetMessageHandler(handler func(message *BridgeMessage))
	// SetCloseHandler sets the connection closure handler for the bridge.
	// It is called whenever the underlying connection of the bridge is closed.
	SetCloseHandler(handler func(err error))
	// SetErrorHandler sets the error handler for the bridge.
	// It is called whenever there's an error in the bridge, except for connection closure.
	SetErrorHandler(handler func(err error))

	// Close disconnects the bridge.
	Close() error
}

Bridge represents a connection between a client and Rosenbridge.

func CreateBridge

func CreateBridge(ctx context.Context, clientID string, w http.ResponseWriter, r *http.Request) (Bridge, error)

CreateBridge creates a new bridge as per the provided params.

It accepts a clientID, which is the ID of the client for whom the bridge is to be created. "w" and "r" are required to upgrade the connection to websocket.

Once the bridge is created for the specified client, they are considered online and receives messages that are sent to them using the SendMessage core function.

type BridgeCreateParams

type BridgeCreateParams struct {
	*BridgeIdentityInfo

	// Writer is required to upgrade the connection to websocket.
	Writer http.ResponseWriter
	// Request is required to upgrade the connection to websocket.
	Request *http.Request

	// ResponseHeaders are the headers that should be included in the websocket response.
	ResponseHeaders http.Header
}

BridgeCreateParams are the params required to create a new bridge through the BridgeManager.

type BridgeDatabase

type BridgeDatabase interface {
	// InsertBridge inserts a new bridge document into the database.
	InsertBridge(ctx context.Context, doc *BridgeDoc) error
	// GetBridgesByClientIDs gets all bridges that belong to any of the provided clients.
	GetBridgesByClientIDs(ctx context.Context, clientIDs []string) ([]*BridgeDoc, error)
	// DeleteBridgeForNode deletes the specified bridge for the specified node.
	DeleteBridgeForNode(ctx context.Context, bridgeID string, nodeAddr string) error
	// DeleteBridgesForNode deletes all specified bridges for the specified node.
	DeleteBridgesForNode(ctx context.Context, bridgeIDs []string, nodeAddr string) error
}

BridgeDatabase provides access to the database of all bridges hosted by the cluster.

type BridgeDoc

type BridgeDoc struct {
	// ClientID is the ID of the client to which the bridge belongs.
	ClientID string `json:"client_id" bson:"client_id"`
	// BridgeID is unique ID for a bridge. It is unique at the cluster level.
	BridgeID string `json:"bridge_id" bson:"bridge_id"`

	// NodeAddr is the address of the node hosting the connection.
	NodeAddr string `json:"node_addr" bson:"node_addr"`
	// ConnectedAt is the time at which connection was established.
	ConnectedAt time.Time `json:"connected_at" bson:"connected_at"`
}

BridgeDoc is the schema for the document of the bridge in the database.

type BridgeIdentityInfo

type BridgeIdentityInfo struct {
	// ClientID is the ID of the client to whom the bridge belongs.
	ClientID string `json:"client_id,omitempty"`
	// BridgeID is the unique ID of the bridge.
	BridgeID string `json:"bridge_id,omitempty"`
}

BridgeIdentityInfo encapsulates all identity parameters associated with a bridge.

type BridgeManager

type BridgeManager interface {
	// CreateBridge creates a new bridge and makes it available for other CRUD operations.
	CreateBridge(ctx context.Context, params *BridgeCreateParams) (Bridge, error)
	// GetBridgeByID fetches the bridge that matches the provided ID. It returns nil if the bridge is not found.
	GetBridgeByID(ctx context.Context, bridgeID string) Bridge
	// GetBridgesByClientID fetches all bridges for the provided client ID.
	GetBridgesByClientID(ctx context.Context, clientID string) []Bridge
	// DeleteBridgeByID disconnects and deletes the specified bridge.
	DeleteBridgeByID(ctx context.Context, bridgeID string)
}

BridgeManager manages all the bridges hosted by this node. It involves CRUD operations on these bridges on the basis of their clientID and bridgeID.

type BridgeMessage

type BridgeMessage struct {
	// Type of the message. It can be used to differentiate and route various kinds of messages.
	Type string `json:"type"`
	// RequestID is used to correlate an outgoing-message-request with its corresponding response.
	RequestID string `json:"request_id"`
	// Body is the main content of this message.
	Body interface{} `json:"body"`
}

BridgeMessage is the general schema of all messages that are sent over a bridge.

type BridgeStatus

type BridgeStatus struct {
	// Identification of the bridge.
	*BridgeIdentityInfo
	// Response code and reason.
	*CodeAndReason
}

BridgeStatus tells about the status of an operation on a bridge. For example a SendMessage operation.

It encapsulates the identity attributes of a bridge and the response code and reason.

type CodeAndReason

type CodeAndReason struct {
	// Code is the response code. For example: OK, CONFLICT etc.
	Code string `json:"code"`
	// Reason is the human-readable error reason.
	Reason string `json:"reason"`
}

CodeAndReason represent the response of an operation.

func (*CodeAndReason) Error

func (c *CodeAndReason) Error() string

Error makes CodeAndReason a valid error type.

type DiscoveryAddressResolver

type DiscoveryAddressResolver interface {
	// Read returns the discovery address of the service.
	Read(ctx context.Context) (string, error)
}

DiscoveryAddressResolver resolves the discovery address of this service.

type IncomingMessageReq

type IncomingMessageReq struct {
	// SenderID is the ID of the client who sent the message.
	SenderID string `json:"sender_id"`
	// Message is the main message content.
	Message string `json:"message"`
}

IncomingMessageReq represents an incoming message for a client.

It is called "incoming message request" because the naming is done from the client's perspective.

type IntercomService

type IntercomService interface {
	// SendMessageInternal invokes the specified node to deliver a message through its hosted bridges.
	SendMessageInternal(ctx context.Context, nodeAddr string, request *OutgoingMessageInternalReq,
	) (*OutgoingMessageInternalRes, error)
}

IntercomService allows intra-cluster communication.

type OutgoingMessageInternalReq

type OutgoingMessageInternalReq struct {
	// SenderID is the ID of client who sent this message.
	SenderID string `json:"sender_id"`
	// BridgeIIs is the identity info of the bridges that are intended to receive this message.
	BridgeIIs []*BridgeIdentityInfo `json:"bridge_iis"`
	// Message is the main message content that needs to be delivered.
	Message string `json:"message"`
	// contains filtered or unexported fields
}

OutgoingMessageInternalReq represents an internal request (from one cluster node to the other) to send a message.

type OutgoingMessageInternalRes

type OutgoingMessageInternalRes struct {
	// The primary code and reason.
	*CodeAndReason
	// Report is the slice of statuses for all the relevant bridges.
	Report []*BridgeStatus `json:"report"`
}

OutgoingMessageInternalRes is the response of an OutgoingMessageInternalReq.

It encapsulates a primary code and reason, and a slice of bridge statuses. If the primary code and reason indicate failure, it means the request failed completely (and not partially). If the primary code and reason are positive, it is possible that some or all of the bridges received the intended message.

func SendMessageInternal

func SendMessageInternal(ctx context.Context, req *OutgoingMessageInternalReq) (*OutgoingMessageInternalRes, error)

SendMessageInternal is invoked by another cluster node. Its role is to send messages to the bridges that are hosted under this node.

type OutgoingMessageReq

type OutgoingMessageReq struct {
	// SenderID is the ID of client who sent this message.
	SenderID string `json:"sender_id"`
	// Receivers is the list of client IDs that are intended to receive this message.
	ReceiverIDs []string `json:"receiver_ids"`
	// Message is the main message content that needs to be delivered.
	Message string `json:"message"`
	// contains filtered or unexported fields
}

OutgoingMessageReq represents a request from a client to send a message.

It is called "outgoing message request" because the naming is done from the client's perspective.

type OutgoingMessageRes

type OutgoingMessageRes struct {
	// The primary code and reason.
	*CodeAndReason
	// Report is the mapping of clientIDs to their bridge statuses.
	// It shows detailed info on success/failure of message deliveries.
	Report map[string][]*BridgeStatus `json:"report"`
}

OutgoingMessageRes is the response of an OutgoingMessageReq from a client.

It is called "outgoing message response" because the naming is done from the client's perspective.

It encapsulates a primary code and reason, and a slice of bridge statuses. If the primary code and reason indicate failure, it means the request failed completely (and not partially). If the primary code and reason are positive, it is possible that some or all of the bridges received the intended message.

func SendMessage

func SendMessage(ctx context.Context, request *OutgoingMessageReq) (*OutgoingMessageRes, error)

SendMessage sends a new message to the specified receivers on the behalf of the specified client.

It provides detailed information on success/failure of message deliveries for every bridge.