HTTPRole is the string representation of HTTP role.
const HTTPRole = "HTTP"
MaxMessageSize max size of a message before split - 10MB in bytes
const MaxMessageSize = 10000000
MaxPacketSize The max size of mesh message in bytes.
const MaxPacketSize = 1400
MaxSize The threshold of packet size to split - if a packet is greater than this value, it will split
const MaxSize = 1300
Shrink The number of deletes until we shrink msgmap size
const Shrink = 10
TCPRole is the string representation of TCP role.
const TCPRole = "TCP"
UDPRole is the string representation of UDP role.
const UDPRole = "UDP"
Update Event name before update
const Update = "update"
Updated Event name after update
const Updated = "updated"
func Command(commandID uint16, callback func(map[string]interface{}) (map[string]interface{}, error))
Command defines a handling function for a mesh network message as a command.
This function has been deprecated and will be removed in the future version without a warning. Use HandleCommand instead.
Command is replaced by HandleCommand - Command messages are sent by SendRequest, SendMany, USend, USendMany
func CreateRequestData() *util.Parcel
CreateRequestData returns an instance of util.Parcel to be used for SendRequest, SendMany, USendMany, Send, and USend.
func CreateReturnBytes(data interface{}) ([]byte, error)
CreateReturnBytes converts a map into a byte array for HandleCommand handler's return value
func CreateSendBytes(data interface{}) ([]byte, error)
CreateSendBytes converts a map into a byte array for Send, USend, SendMany, USendMany, and SendRequest
func GetBool(data map[string]interface{}, name string) bool
GetBool returns a bool from the mesh network request/response data
func GetBytes(data map[string]interface{}, name string) []byte
GetBytes returns a byte array from the mesh network request/response data
func GetFloat64(data map[string]interface{}, name string) float64
GetFloat64 returns a float64 from the mesh network request/response data
func GetInt(data map[string]interface{}, name string) int
GetInt returns an int from the mesh network request/response data
func GetInt16(data map[string]interface{}, name string) int16
GetInt16 returns an int16 from the mesh network request/response data
func GetInt32(data map[string]interface{}, name string) int32
GetInt32 returns an int32 from the mesh network request/response data
func GetInt64(data map[string]interface{}, name string) int64
GetInt64 returns an int64 from the mesh network request/response data
func GetInt8(data map[string]interface{}, name string) int8
GetInt8 returns an int8 from the mesh network request/response data
func GetMyEndPoint() string
GetMyEndPoint Returns its own mesh network endpoint that is used for internal server-to-server communication.
[IMPORTANT] Send, USend, SendMany, USendMany, and SendRequest needs this mesh network endpoint.
The returned address is external address for clients.
[NOTE] Uses mutex lock internally.
func GetMyNodeEndPoint() string
GetMyNodeEndPoint returns the server endpoint (internet) its own node
The returned address is external address for clients.
[NOTE] Uses mutex lock internally.
func GetMyNodeType() string
GetMyNodeType Returns the node type of itself
func GetMyNodeValue(name string) interface{}
GetMyNodeValue returns a metadata value of the node
[NOTE] Uses mutex lock internally.
func GetNodeAddresses(ignoreList []string) []string
GetNodeAddresses Returns all internal server-to-server communication node addresses.
[NOTE] Uses mutex lock internally.
func GetNodeAddressesByRole(nRole string) []string
GetNodeAddressesByRole return the mesh network endpoints for internal server-to-server communication of nodes by server role (role is based on network protocol).
[IMPORTANT] Send, USend, SendMany, USendMany, and SendRequest needs this mesh network endpoint. [NOTE] Uses mutex lock internally.
func GetNodeAddressesByType(nType string) []string
GetNodeAddressesByType Return the mesh network endpoints for internal server-to-server communication of nodes by type.
[IMPORTANT] Send, USend, SendMany, USendMany, and SendRequest needs this mesh network endpoint.
Server type can be changed by the application.
The returned list of addresses contain offline and taken nodes as well.
[NOTE] Uses mutex lock internally.
func GetNodeEndPoint(nodeAddr string) string
GetNodeEndPoint returns the public server endpoint (internet) of a node by its mesh node address - only TCP, UDP, and HTTP
[IMPORTANT] Endpoint that is used to communicate with the clients over internet.
The returned address is external address for clients.
[NOTE] Uses mutex lock internally.
func GetNodeRole() string
GetNodeRole returns the server role of the server.
func GetNodeRoleByAddress(addr string) string
GetNodeRoleByAddress returns the server role of the given mesh address (internal address).
[IMPORTANT] Send, USend, SendMany, USendMany, and SendRequest needs this mesh network endpoint.
func GetNodeRoleByType(nType string) string
GetNodeRoleByType Returns node role by node type.
[NOTE] Uses mutex lock internally.
Possible values for nType:
func GetNodeType() string
GetNodeType returns the server type of the server
func GetNodeTypeByAddress(addr string) string
GetNodeTypeByAddress returns the server type of the given mesh address (internal address)
[IMPORTANT] Send, USend, SendMany, USendMany, and SendRequest needs this mesh network endpoint. [NOTE] Uses mutex lock internally.
func GetNodeTypes() []string
GetNodeTypes returns all node types currently in the Diarkis cluster
[NOTE] Uses mutex lock internally.
func GetNodeValue(nodeAddr string, name string) interface{}
GetNodeValue Returns a metadata value of a node by its address
[NOTE] Uses mutex lock internally.
Parameter
nodeAddr - External address (address for clients) of the node. name - Name of the value.
func GetNodeValues(nodeAddr string) map[string]interface{}
GetNodeValues Returns all metadata values of a node by its address
[NOTE] Uses mutex lock internally.
Parameter
nodeAddr - External address (address for clients) of the node.
func GetNodesWithDifferentPublicAddr() (meshAddrs []string)
GetNodesWithDifferentPublicAddr returns an array of mesh addresses which have different public address from the current node
[NOTE] Uses mutex lock internally.
func GetSharedData(key string) (int16, bool)
GetSharedData returns synchronized shared data by its key.
func GetString(data map[string]interface{}, name string) string
GetString returns a string from the mesh network request/response data
func GetUint16(data map[string]interface{}, name string) uint16
GetUint16 returns a uint16 from the mesh network request/response data
func GetUint32(data map[string]interface{}, name string) uint32
GetUint32 returns a uint32 from the mesh network request/response data
func GetUint64(data map[string]interface{}, name string) uint64
GetUint64 returns a uint64 from the mesh network request/response data
func GetUint8(data map[string]interface{}, name string) uint8
GetUint8 returns a uint8 from the mesh network request/response data
func Guest(confpath string)
Guest starts mesh network as a guest meaning that the process can only send and receive messages but does not become part of the mesh node
func HandleCommand(cmd uint16, cb func(requestData map[string]interface{}) ([]byte, error))
HandleCommand defines a handling function for a mesh network message as a command
Parameters
cmd - Internal message command ID. cb - Callback associated to the command ID.
func HandleRPC(cmd uint16, handler func(data []byte, senderAddr string) (response []byte, err error)) bool
HandleRPC defines a handling function for a mesh network RPC command sent by SendRPC.
Parameters
cmd - RPC command ID.
handler - Callback associated to the RPC ID.
The handler callback will be passed two parameters:
- data []byte - The byte array sent from another server node.
The byte array can be encoded by mesh.TransportData.
If mesh.TransPortData is used,
you may decode data using mesh.TransportData.
- senderAddr string - The private address of the sender server node.
In order to use TransportData, we must define each data structure of TransportData.
// We define the structure of the transport data once
var exampleTransportData = td.DefineTransportData([]td.Property{
td.Property{ Name: "name", Type: td.String },
td.Property{ Name: "counter", Type: td.Int },
td.Property{ Name: "list", Type: td.Uint32Array },
td.Property{ Name: "data", Type: td.Bytes },
td.Property{ Name: "users", Type: td.BytesArray },
})
var userTransportData = td.DefineTransportData([]td.Property{
td.Property{ Name: "UID", Type: td.String },
td.Property{ Name: "SID", Type: td.String },
})
// We first create an instance of already defined mesh.TransportData.
// You must create the correct instance that corresponds with what SendRPC used to send the data.
td := exampleTransportData.New()
// We then pass the byte array the callback received.
td.Unpack(receivedBytes)
name, nameFound := td.GetAsString("name")
counter, counterFound := td.GetAsInt("counter")
list, listFound := td.GetAsUint32Array("list")
data, dataFound := td.GetAsBytes("data")
usersBytesList, usersBytesFound := td.GetAsBytesArray("users")
// We can reuse the same userTransportData instance here
ud := userTransportData.New()
for _, userBytes := range userBytesList {
ud.Unpack(userBytes)
// We handle each user UID and SID
uid, uidFound := ud.GetAsString("uid")
sid, sidFound := ud.GetAsString("sid")
}
func IsCommandDuplicate(commandID uint16) bool
IsCommandDuplicate returns true if command ID is used elsewhere
func IsMyNodeOffline() bool
IsMyNodeOffline returns true if the node is offline (received SIGTERM)
[NOTE] Uses mutex lock internally.
When the node is offline, the connected clients will be raising OnOffline event
func IsMyNodeOnline() bool
IsMyNodeOnline returns false if the node is offline (received SIGTERM)
[NOTE] Uses mutex lock internally.
When the node is offline, the connected clients will be raising OnOffline event
func IsMyNodeTaken() bool
IsMyNodeTaken returns true if the node is marked as taken
[NOTE] Uses mutex lock internally.
When the node is taken, the server will not accept new client connections, but allows the connected clients to stay connected.
func IsNodeOffline(nodeAddr string) bool
IsNodeOffline Returns true if the given node is offline
[NOTE] Uses mutex lock internally.
When the node is offline, the connected clients will be raising OnOffline event
func IsNodeOnline(nodeAddr string) bool
IsNodeOnline Returns true if the given node is online
[NOTE] Uses mutex lock internally.
When the node is offline, the connected clients will be raising OnOffline event
func IsNodeTaken(nodeAddr string) bool
IsNodeTaken returns false if the node is taken (mesh.SetStatus(util.MeshStatusTaken))
[NOTE] Uses mutex lock internally.
When a node is taken, the taken node will not be returned by HTTP server as available server.
func IsPartOfCluster() bool
IsPartOfCluster returns true if the server has communicated with MARS within the accepted time span
func IsRequestError(err error) bool
IsRequestError returns true if the given error is or contains a SendRequest error.
func IsRequestTimeoutError(err error) bool
IsRequestTimeoutError returns true if the given error is or contains a SendRequest time out error.
func IsSendError(err error) bool
IsSendError returns bool if the given error is or contains Send error.
The Send error is used by Send, USend, SendMany, USendMany.
func IsUnhealthyError(err error) bool
IsUnhealthyError returns true if the given error is or contains mesh health check error.
func OnInitialSync(cb func())
OnInitialSync assigns a callback on the first sync with MARS
func OnSharedDataRemove(cb func(string))
OnSharedDataRemove assigns a callback on shared data removal
func OnSharedDataUpdate(cb func(string, int16))
OnSharedDataUpdate assigns a callback on shared data update
func OnUpdate(handler func())
OnUpdate Registers a callback on announcer update event
[NOTE] Uses mutex lock internally.
func OnUpdated(handler func())
OnUpdated Registers a callback on announcer updated event
[NOTE] Uses mutex lock internally.
func RemoveOnSharedDataRemove(cb func(string))
RemoveOnSharedDataRemove removes a callback that has been assigned.
[IMPORTANT] This function uses mutex lock internally.
func RemoveOnSharedDataUpdate(cb func(string, int16))
RemoveOnSharedDataUpdate removes a callback that has been assigned.
[IMPORTANT] This function uses mutex lock internally.
func RemoveSharedData(key string) bool
RemoveSharedData removes the given shared key and propagates the removal to all server nodes in the cluster.
The propagation of the shared data may take some time.
[IMPORTANT] Updated value may suffer from race condition.
if multiple server nodes attempt to update the same key.
func Send(commandID uint16, addr string, data interface{}) error
Send Sends a mesh network message to a given node - addr = <address>:<port>
func SendMany(commandID uint16, addrs []string, data interface{}, limit int) error
SendMany Sends a mesh network message to multiple nodes
commandID - Mesh message command ID addrs - A list of mesh node addresses to send the message to data - Data to be sent limit - Maximum number of node to send the message at a time
SendMany propagates data to multiple servers.
The diagram below show how SendMany works with limit=2 and send data to 6 servers:
With the example below, SendMany can reach all servers with 2 jumps.
┌──────────┐
┌────▶︎│ Server D │
│ └──────────┘
┌──────────┐ <2> Send │
┌──▶︎│ Server B │──────────┤ ┌──────────┐
│ └──────────┘ └────▶︎│ Server E │
┌──────────┐ <1> Send │ └──────────┘
│ Server A │ ──────────────┤ ┌──────────┐
└──────────┘ │ ┌──────────┐ ┌────▶︎│ Server F │
└──▶︎│ Server C │──────────┤ └──────────┘
└──────────┘ │
│ ┌──────────┐
└────▶︎│ Server G │
└──────────┘
func SendRPC(cmd uint16, addr string, data []byte) ([]byte, error)
SendRPC sends a mesh network request to another node - addr = <address>:<port> and expects a response back from it
Parameters
cmd - Pre-defined command ID that corresponds with user defined custom handler function(s).
You may define multiple handler functions for a command ID.
addr - Target node address (internal) to send the request to.
data - Request data as a byte array to be sent to the handler function(s).
You may use td.DefineTransportData to create a data structure for RPC.
TransportData Example
// We define the structure of the transport data once
var exampleTransportData = td.DefineTransportData([]td.Property{
td.Property{ Name: "name", Type: td.String },
td.Property{ Name: "counter", Type: td.Int },
td.Property{ Name: "list", Type: td.Uint32Array },
td.Property{ Name: "data", Type: td.Bytes },
td.Property{ Name: "users", Type: td.BytesArray },
})
var userTransportData = td.DefineTransportData([]td.Property{
td.Property{ Name: "UID", Type: td.String },
td.Property{ Name: "SID", Type: td.String },
})
// We then create an instance of already defined transport data
// when we need it
td := exampleTransportData.New()
// We set values
td.SetAsString("name", "John")
td.SetAsInt("counter", 0)
td.SetAsUint32Array("list", []uint32{ 10, 20, 2 })
td.SetAsBytes("data", []byte{ 0xff, 0xee, 0xdd, 0xcc })
users := make([]*userTransportData, len(users))
ud := userTransportData.New()
for i, userData := range users {
ud.SetAsString("UID", userData.ID)
ud.SetAsString("SID", userData.SID)
users[i] = ud.Pack()
}
td.SetAsBytes("users", users)
// We then create the byte array for SendRPC
packed := td.Pack()
Returned Values
response - Response data returned from another server. error - Error.
SendRPC allows you to execute a pre-defined callback function using HandleRPC on another server and expects a response back from the server.
Error Cases
┌───────────────────┬─────────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ╞═══════════════════╪═════════════════════════════════════════════════════════════════════════╡ │ Handler error │ Handler function of the request returned an error. │ │ Network error │ Mesh network error. Failed to send or receive server-to-server message. │ ╘═══════════════════╧═════════════════════════════════════════════════════════════════════════╛
The diagram below show how SendRequest works:
┌──────────┐ <1> RPC Request ┌──────────┐ │ Server A │ ─────────────────▶︎│ Server B │ │ │ ◀︎──────────────── │ │ └──────────┘ <2> RPC Response └──────────┘
func SendRequest(commandID uint16, addr string, data interface{}, callback func(err error, responseData map[string]interface{}))
SendRequest Sends a mesh network request to another node - addr = <address>:<port> and expects a response back from it
Parameters
commandID - Pre-defined command ID that corresponds with user defined custom handler function(s).
You may define multiple handler functions for a command ID.
addr - Target node address (internal) to send the request to.
data - Request data to be sent to the handler function(s).
The valid data type of data must be the following two types only:
1. map[string]interface{}
2. struct
callback - The callback function to be invoked when the response comes back.
SendRequest allows you to execute a pre-defined function on another server and expects a response back from the server.
Error Cases
┌───────────────────┬─────────────────────────────────────────────────────────────────────────┐
│ Error │ Reason │
╞═══════════════════╪═════════════════════════════════════════════════════════════════════════╡
│ Invalid data type │ Input data type must be either a struct or map[string]interface{}. │
│ Handler error │ Handler function of the request returned an error. │
│ Network error │ Mesh network error. Failed to send or receive server-to-server message. │
╘═══════════════════╧═════════════════════════════════════════════════════════════════════════╛
The diagram below show how SendRequest works:
┌──────────┐ <1> Send request ┌──────────┐ │ Server A │ ─────────────────▶︎│ Server B │ │ │ ◀︎──────────────── │ │ └──────────┘ <2> Send Response └──────────┘
func SetAppName(name string)
SetAppName creates a name space within the mars-server in order to have multiple diarkis clusters
func SetCheckForShutdownReadiness(cb func() bool)
SetCheckForShutdownReadiness USED INTERNALLY ONLY.
func SetCommandHandler(cmd uint16, cb func(payload []byte, senderAddress string) ([]byte, error))
SetCommandHandler assigns a handler callback to the given command ID.
Parameters
cmd - Internal message command ID. cb - Callback associated to the command ID.
func SetEndPoint(endPoint string)
SetEndPoint Sets its own end point
[NOTE] Uses mutex lock internally.
func SetNodeRole(role string)
SetNodeRole [INTERNAL USE ONLY]
func SetNodeType(_nodeType string)
SetNodeType replaces the default server type with the given custom server type.
Default Server Types - HTTP, UDP, TCP
func SetNodeValue(name string, val interface{})
SetNodeValue Sets a metadata value to a node
[NOTE] Uses mutex lock internally.
func SetSharedData(key string, value int16) bool
SetSharedData updates a shared data to be propagated to all server nodes in the cluster.
The propagation of the shared data may take some time.
[IMPORTANT] Updated value may suffer from race condition.
if multiple server nodes attempt to update the same key.
key - Key of the shared data to set.
The length of the key must not exceed 54 characters.
value - Value of the shared data.
func SetStatus(status int)
SetStatus Sets its status
func Setup(confpath string)
Setup Loads a configuration file into memory - pass an empty string to load nothing
func StartAsMARS(confpath string)
StartAsMARS Starts the server as MARS server - For now this is meant to be used for mars-server ONLY
func TestPackPacket() bool
TestPackPacket used for testing ONLY
func USend(commandID uint16, addr string, data interface{}) error
USend Sends an unreliable message to a given node - addr = <address>:<port>
func USendMany(command uint16, addrs []string, data interface{}, limit int) error
USendMany Sends an unreliable mesh network message to multiple nodes
commandID - Mesh message command ID addrs - A list of mesh node addresses to send the message to data - Data map to be sent limit - Maximum number of node to send the message at a time
USendMany propagates data to multiple servers.
The diagram below show how USendMany works with limit=2 and send data to 6 servers:
With the example below, USendMany can reach all servers with 2 jumps.
┌──────────┐
┌────▶︎│ Server D │
│ └──────────┘
┌──────────┐ <2> Send │
┌──▶︎│ Server B │──────────┤ ┌──────────┐
│ └──────────┘ └────▶︎│ Server E │
┌──────────┐ <1> Send │ └──────────┘
│ Server A │ ──────────────┤ ┌──────────┐
└──────────┘ │ ┌──────────┐ ┌────▶︎│ Server F │
└──▶︎│ Server C │──────────┤ └──────────┘
└──────────┘ │
│ ┌──────────┐
└────▶︎│ Server G │
└──────────┘
func ValidateDataType(data interface{}) bool
ValidateDataType returns true if the given data type is either a pointer to a struct or map[string]interface {}
Msg Data structure of Msg
type Msg struct {
UUID []byte
Packet []byte
AddedSize int
TTL int64
sync.RWMutex
}
Node a mesh network node data structure
type Node struct {
Addr string
Type string
Role string
Values map[string]interface{}
Self bool
}
func GetNode(nodeAddr string) *Node
GetNode Returns a node by its address
[NOTE] Uses mutex lock internally.
Parameters
nodeAddr - External address (address for clients) of the node.
The returned *Node contains internal node address as *Node.Addr.
func GetNodeByEndPoint(endPoint string) *Node
GetNodeByEndPoint Returns a node by its server end point - only TCP, UDP, and HTTP
[NOTE] Uses mutex lock internally.
SendData represents internally used data for mesh communication
type SendData struct {
Payload interface{} `json:"payload"`
Cmd uint16 `json:"cmd"`
Limit int `json:"limit"`
Branch []string `json:"branch"`
UBranch []string `json:"ubranch"`
}