Bad Send status for server response.
const Bad = 4
Err Send status for server response.
const Err = 5
Ok Send status for server response.
const Ok = 1
TCPType a type of TCP server used by mesh module
const TCPType = tcp.Type
UDPType a type of UDP server used by mesh module
const UDPType = udp.Type
func Command(ver uint8, cmd uint16, handler func(userData *user.User, next func(error)))
Command has been deprecated: Use HandleCommand instead for other servers.
This function has been deprecated and will be removed in the future version without a warning.
ver uint8 - Command version of the handler. cmd uint16 - Command ID of the handler. handler func(userData *user.User, next func(error))
Returns an error if it fails to assign a handler.
NOTE: If you assign multiple handles with the same ver and cmd, all handlers will be executed in the order of assignment.
func DeleteNotification(id string)
DeleteNotification deletes an existing Notification message struct data.
func EnableNotifications()
EnableNotifications initializes notifier. It must be called before diarkis.Start is called to setup notifier properly. In order for notifications to be sent out to the clients, you must use Notify and/or NotificationService.
func ExposeDebugCommands()
ExposeDebugCommands exposes debug commands to the client. Server package comes with debug-only commands for tests and debugging.
Available Debug Commands:
▷ Set Server State Online
Sets the server to "ONLINE" state.
ONLINE State - The server accepts new client connections execute all diarkis functions.
version: 0 command: 900 Required payload: empty byte array Response: none
▷ Set Server State Taken
Sets the server to "TAKEN" state.
TAKEN State - The server does **NOT** accept new client connections, but able to execute all diarkis functions.
version: 0 command: 901 Required payload: empty byte array Response: none
▷ Set Server State Offline
Sets the server to "OFFLINE" state.
OFFLINE State - The server does **NOT** accept new client connections, and can **NOT** create new rooms, but able to join rooms and execute all other diarkis functions.
version: 0 command: 902 Required payload: empty byte array Response: none
▷ Server Terminate
Stops the server. Diarkis server waits for the connected clients
version: 0 command: 903 Required payload: empty byte array Response: none
▷ Room Data Dump
Dumps the room data to the client.
version: 0 command: 904 Required payload: empty byte array Response: byte array encoded room data dump as JSON
func GetEndPoint() string
GetEndPoint returns the end point address the server is bound with
func HandleCommand(ver uint8, cmd uint16, handler func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error))) error
HandleCommand registers a command handler function for TCP and UDP/RUDP server.
Returns an error if it fails to assign a handler.
[NOTE] If you assign multiple handles with the same ver and cmd,
all handlers will be executed in the order of assignment.
Handler callback's next function:
The next function that the handler callback receives must be invoked at the end of all operations within the handler.
This ensures the handling of a command is completed and Diarkis server proceeds to the next handler of the same command ID or another command ID.
By blocking or not invoking the next function, Diarkis server will pause the handling of all commands for the user and eventually the user client will disconnect because it cannot handle echo (keep alive) command that every user client needs to stay connected to the server.
Parameters
ver - Command version of the handler.
cmd - Command ID of the handler.
handler - Handler function to be executed when the server receives the command.
func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error))
Handler Callback Parameters
ver - Command ver sent from the client.
cmd - Command ID sent from the client.
payload - Command payload sent from the client.
userData - User data representing the client that sent the command.
next - The function to signal the command to move on to the next operation of the same ver and command ID.
This function must be called at the end of all operations in the callback.
If you pass an error, it will not proceed to the next operations of the same command ver and ID.
func HookAllCommands(handler func(userData *user.User, next func(error)))
HookAllCommands Registers a packet handler as a hook to all commands
handler func(userData *user.User, next func(error)) - Function to be invoked on command hook.
NOTE: The second argument next func(error) must be called at the end of handler to move the operation to next.
func IsCommandDuplicate(ver uint8, commandID uint16) bool
IsCommandDuplicate returns true if ver and command ID are used elsewhere when this function is invoked
ver uint8 - Command version to be checked for duplication. cmd uint16 - Command ID to be checked for duplication.
func IsDebugCommandsEnabled() bool
IsDebugCommandsEnabled returns true if debug commands are enabled
func IsP2PEnabled() bool
IsP2PEnabled returns true if UDP server enabled P2P by its configuration
func IsTCP() bool
IsTCP Returns true if the server is setup as TCP server
func IsUDP() bool
IsUDP Returns true if the server is setup as UDP server
func MarkServerAsTakenIf(callback func() bool)
MarkServerAsTakenIf flags the server as "TAKEN" if the callback returns true. The callback is invoked every 2 second and if the callback returns true, the server will be marked as "ONLINE".
[IMPORTANT] If the server is marked as "OFFLINE", this function will be ignored. [NOTE] This function is executed every 2 seconds so there will be race condition and it is not precise.
TAKEN - When the server is marked as "TAKEN", the server will NOT accept new user connections.
Example: The example code below uses CCU of the node to control TAKEN <==> ONLINE
server.MarkServerAsTakenIf(func() bool {
// user package can tell you the CCU of the node
ccu := user.GetCCU()
if ccu >= maxAllowedCCU {
// this will mark the server as TAKEN
return true
}
// this will mark the server as ONLINE
return false
})
func NotificationService(name string, cb NotificationLoader, interval int64)
NotificationService starts a goroutine loop that invokes the given callback at the interval that is given. Every iteration of the goroutine loop triggers a notification message being sent.
[NOTE] The returned value of the callback will be sent as a notification.
[IMPORTANT] In order to deliver notifications, all server process must start the same notification service.
[IMPORTANT] This function does NOT guarantee the delivery of notification message to all user clients.
The possible failure of notification message delivery may include the following:
- Duplicate message ID will cause the message to be sent or ignored.
- User clients that are not connected at the time of this function's execution.
- User clients that are connected to non-responsive server process.
- TTL expiration.
Parameters
name - A name of the notification service. cb - A callback to be invoked on each notification service loop tick. The returned values will be the notification. interval - Notification delivery cycle interval in milliseconds
Example:
The code example blow demonstrates server.NotificationService fetches a notification data from a database every 10,000ms and sets it up to be delivered to all connected users.
interval := int64(5000)
server.EnableNotifications()
server.NotificationService("Test", func() (notification *server.Notification, err error) {
// Retrieve notification data from a database by the current time
notificationData := someDatabase.GetNotificationDataByCurrentTime(year, month, date)
if notificationData == nil {
// No notification data to send out
return nil, nil
}
n := new(server.Notification)
n.ID = notificationData.ID
n.Name = notificationData.Name
// Ver is used by the client to identify the message when received.
n.Ver = notificationData.Ver
// Cmd is used by the client to identify the message when received.
n.Cmd = notificationData.Cmd
n.Message = []byte("Notification message says 'Hello from the server'")
// TTL is in seconds to indicate the availability of the notification data.
// The notification will be available for the not-connected-clients for the duration of TTL and
// will be sent to the clients when they connect before TTL expires.
n.TTL = int64(60)
return n, nil
}, interval)
func Notify(m *Notification, local bool) error
Notify sends out a notification message for all user clients.
[IMPORTANT] This function does NOT guarantee the delivery of notification message to all user clients.
The possible failure of notification message delivery may include the following:
- Duplicate message ID will cause the message to be sent or ignored.
- User clients that are not connected at the time of this function's execution.
- User clients that are connected to non-responsive server process.
- TTL expiration.
Parameters
name - A notification name used to assign NotificationHandler. m - Message struct that represents a notification message. local - If true, the notification message will be sent to the user clients on the same server ONLY.
Returns an error if it fails to send out the notification.
func Offline()
Offline flags the server to be offline (will be shutdown) and will not accept new users
func OnDisconnect(callback func(string, *user.User))
OnDisconnect Registers a callback on connection termination for TCP/UDP
func OnKeepAlive(handler func(userData *user.User, next func(error)))
OnKeepAlive assigns a callback function on TCP heartbeat or UDP echo
handler - Function to be invoked on keep alive message from the clients. [NOTE] next func(error) must be called at the end of handler's operation.
func Online()
Online flags the server to be online and will accept new users
func SendPM(nodeAddr string, sid string, ver uint8, cmd uint16, message []byte)
SendPM sends a direct message to another user - The sent private message is a reliable delivery.
This function has been deprecated and will be removed in the future version without a warning. Use DM module instead.
nodeAddr string - This is the node (server) internal address of the target user. sid string - This is the sid (session ID) of the target user. ver uint8 - This is the command version to be used with the message sent. cmd uint16 - This is the command version to be used with the message sent. message []byte - This is the message data byte array.
func SetDebugCommandCallback(cmd uint16, cb func(*user.User, []byte, func(error, []byte)))
SetDebugCommandCallback assigns a callback for a debug command with the given debug command ID
func SetOnNotification(name string, cb NotificationHandler)
SetOnNotification assigns a callback function to notifications with the matching name. The callback is invoked on every notification with the same name before it is sent to a client and decides who receives the notification by returning true/false. If the callback returns true, the target user will receive the notification.
[CRITICALLY IMPORTANT] Using pointer variables that are defined outside of the callback closure
in the callback closure will cause those pointers to be not garbage collected leading to memory leak.
func SetPublicEndPoint(addr string)
SetPublicEndPoint sets public end point to be sent to the client to be used to connect
addr string - This is the public endpoint for the server to be registered and used by the clients.
This is usually used internally.
func SetupAsConnector(path string)
SetupAsConnector Initialize the server as a Connector server for an external real-time server. This is meant to be used with an external real-time server such as Unreal Engine Dedicated server etc. Diarkis itself will not communicate wit the clients, but focuses on auto-scaling and horizontal scaling on K8s.
path string - This is the absolute path of the configuration file to read.
func SetupAsTCPServer(path string)
SetupAsTCPServer Initialize as a TCP server. Load configurations from the file path given. Pass an empty string, if there is no need for configurations.
path string - This is the absolute path of the configuration file to read.
func SetupAsUDPServer(path string)
SetupAsUDPServer Initialize as a UDP server. Load configurations from the file path given. Pass an empty string, if there is no need for configurations.
path string - This is the absolute path of the configuration file to read.
func SetupGenericCloudServer() error
SetupGenericCloudServer sets public endpoint in a generic way Must be called in diarkis.OnReady() as a callback
func SetupServerForAWS() error
SetupServerForAWS sets public endpoint in AWS environment Must be called in diarkis.OnReady() as a callback
func SetupServerForAlibaba() error
SetupServerForAlibaba sets public endpoint in Alibaba Cloud environment Must be called in diarkis.OnReady() as a callback
func SetupServerForAzure() error
SetupServerForAzure sets public endpoint in Microsoft Azure environment Must be called in diarkis.OnReady() as a callback
func SetupServerForGCP() error
SetupServerForGCP sets public endpoint in GCP environment Must be called in diarkis.OnReady() as a callback
func SetupServerForLinode() error
SetupServerForLinode sets public endpoint in Linode environment Must be called in diarkis.OnReady() as a callback
func SetupServerForTencent() error
SetupServerForTencent sets public endpoint in Tencent Cloud environment Must be called in diarkis.OnReady() as a callback
func Taken()
Taken flags the server to be taken and will not accept new users.
Notification is a data structure that represents a notification message.
ID - Unique Identifier for the server notification. This ID must not overlap. Ver - Command version of the notification. If ver = 0 and cmd = 400, the client raises OnNotification event. Cmd - Command ID of the notification. If ver = 0 and cmd = 400, the client raises OnNotification event. Message - Notification message TTL - Notification TTL in milliseconds.
type Notification struct {
// Message ID
ID string
// Name is used to associate the notification with a handler callback
Name string
// Message command ver to be sent to the user clients
Ver uint8
// Message command ID to be sent to the user clients
Cmd uint16
// Message to be sent to the user clients
Message []byte
// TTL of the message
TTL int64
}
NotificationHandler is invoked on every Notify. If it returns true, the user client receives the notification, but if it returns false, the client user does not receive the notification.
type NotificationHandler func(userData *user.User, notification *Notification) bool
NotificationLoader is a callback to used by NotificationService to generate a notification message.
type NotificationLoader func() (notification *Notification, err error)
UserDataDump implies a payload format for the dump user data command
type UserDataDump struct {
ID string `json:"ID"`
SID string `json:"SID"`
Data map[string]interface{} `json:"Data"`
Latency int64 `json:"Latency"`
}