package diarkisexec

import "github.com/Diarkis/diarkis/diarkisexec"

Package diarkisexec ▷

Diarkis Server DiarkisExec

This package helps you to setup Diarkis server with ease.

Setting Up Redundant MARS

You may configure your Diarkis cluster with MARS auto-redundancy when deploying it in environments where server nodes are more prone to failure and restarting them is challenging, such as non-cloud or unstable infrastructures.

In order to setup redundant MARS, you must add the following setup on the HTTP servers and add the configuration for Mesh module. If your Diarkis cluster is running in a cloud environment, you most likely won’t need this setup. Redundancy failover is triggered after 10 seconds of inactivity. If MARS recovers within that window, normal operation resumes without initiating failover.

diarkisexec.SetupDiarkis(logConfigPath, meshConfigPath, &diarkisexec.Modules{
	... // Modules configurations here
	MARS: &diarkisexec.Options{ ConfigPath: "path/to/config/file/mars.json" },
})

Mesh Module Configuration for Redundant MARS

In order for redundant MARS to work properly, you must add the host name of the HTTP endpoint of your Diarkis cluster. this host name is the one that is used to call /endpoint/type/$(server_type)/user/$(user_id) and metrics endpoints.

Setting Up Diarkis Server (HTTP, UDP, or TCP) With Environment Variable

DiarkisExec allows you to setup Diarkis server with a specific network protocol by giving an environment variable instead of calling SetupDiarkisHTTPServer, SetupDiarkisUDPServer, or SetupDiarkisTCPServer.

Example:

# Start the server as Diarkis HTTP server
DIARKIS_HTTP_SERVER_CONFIG_PATH=configs/http/main.json ./remote_bin/http

Valid Environment Variables For the Server

Custom configuration root directory

If the environment variable DIARKIS_CONFIG_ROOT_PATH is set, the process will resolve the configuration path using it instead of using the current working directory.

Example:

# Start the http server from anywhere while the project code is located at /home/user/diarkis
DIARKIS_CONFIG_ROOT_PATH=/home/user/diarkis /home/user/diarkis/remote_bin/http

Index

• Constants
• func CreateReturnBytes(data map[string]interface{}) ([]byte, error)
• func GetMeshAddress() string
• func GetMeshAddressByPublicEndpoint(publicEndpoint string) string
• func GetMeshAddressByServerRole(serverRole string) string
• func GetMeshAddressByServerType(serverType string) string
• func GetMeshAddressesByServerRole(serverRole string) []string
• func GetMeshAddressesByServerType(serverType string) []string
• func GetPublicEndpoint() string
• func GetPublicEndpointByMeshAddress(meshAddress string) string
• func GetServerRole() string
• func GetServerRoleByMeshAddress(meshAddress string) string
• func GetServerType() string
• func GetServerTypeByMeshAddress(meshAddress string) string
• func GetSharedData(key string) (int16, bool)
• func IsOffline() bool
• func IsOfflineByMeshAddress(meshAddress string) bool
• func IsServerRoleHTTP() bool
• func IsServerRoleTCP() bool
• func IsServerRoleUDP() bool
• func IsTaken() bool
• func IsTakenByMeshAddress(meshAddress string) bool
• func MarkServerAsOffline()
• func MarkServerAsOnline()
• func MarkServerAsTaken()
• func MarkServerAsTakenIf(callback func() bool)
• func NewLogger(name string) *log.Logger
• func OnKeepAlive(handler func(userData *user.User, next func(error)))
• func RemoveOnSharedDataRemove(cb func(key string, updated int64))
• func RemoveOnSharedDataUpdate(cb func(key string, value int16, updated int64))
• func RemoveSharedData(key string) bool
• func ResponseStatusBad() uint8
• func ResponseStatusErr() uint8
• func ResponseStatusOK() uint8
• func SendMeshCommand(cmd uint16, addresses []string, data interface{}, reliable bool) error
• func SendMeshRPC(cmd uint16, address string, data []byte) (response []byte, err error)
• func SendMeshRequest(cmd uint16, address string, data interface{}, ...)
• func SetMeshCommandHandler(cmd uint16, handler MeshCommandHandler)
• func SetMeshRPCHandler(cmd uint16, handler MeshRPCHandler)
• func SetOnSharedDataRemove(cb func(key string, updated int64))
• func SetOnSharedDataUpdate(cb func(key string, value int16, updated int64))
• func SetServerCommandHandler(ver uint8, cmd uint16, handler CommandHandler)
• func SetSharedData(key string, value int16) bool
• func SetupDiarkis(logConfigPath, meshConfigPath string, m *Modules)
• func SetupDiarkisHTTPServer(config string)
• func SetupDiarkisTCPServer(config string)
• func SetupDiarkisUDPServer(config string)
• func SetupNotificationService(name string, interval int64, callback func() (*Notification, error))
• func SetupNotificationServiceBySharedData(name string, sharedDataName string, ...)
• func StartDiarkis()
• type CommandHandler
• type MeshCommandHandler
• type MeshRPCHandler
• type Modules
• type Notification
• type Options

Constants

const CommandResponseBad uint8 = server.Bad

CommandResponseBad represents the server response status code for UDP/TCP server command.

The status indicates the command execution failed due to the client operation: invalid parameters etc..

const CommandResponseErr uint8 = server.Err

CommandResponseErr represents the server response status code for UDP/TCP server command.

The status indicates the command execution failed due to the server internal error.

const CommandResponseOK uint8 = server.Ok

CommandResponseOK represents the server response status code for UDP/TCP server command.

The status indicates the command execution was successful.

Functions

func CreateReturnBytes

func CreateReturnBytes(data map[string]interface{}) ([]byte, error)

CreateReturnBytes converts the given map[string]interface{} into a byte error for MeshCommandHandler return value.

func GetMeshAddress

func GetMeshAddress() string

GetMeshAddress returns the server's internal mesh address.

func GetMeshAddressByPublicEndpoint

func GetMeshAddressByPublicEndpoint(publicEndpoint string) string

GetMeshAddressByPublicEndpoint returns the remote/local server's internal mesh address by its public endpoint.

func GetMeshAddressByServerRole

func GetMeshAddressByServerRole(serverRole string) string

GetMeshAddressByServerRole returns a randomly selected internal mesh address of the given server role.

func GetMeshAddressByServerType

func GetMeshAddressByServerType(serverType string) string

GetMeshAddressByServerType returns a randomly selected internal mesh address of the given server type.

func GetMeshAddressesByServerRole

func GetMeshAddressesByServerRole(serverRole string) []string

GetMeshAddressesByServerRole returns an array of internal mesh addresses of the given server role.

func GetMeshAddressesByServerType

func GetMeshAddressesByServerType(serverType string) []string

GetMeshAddressesByServerType returns an array of internal mesh addresses of the given server type.

func GetPublicEndpoint

func GetPublicEndpoint() string

GetPublicEndpoint returns the server's public endpoint.

func GetPublicEndpointByMeshAddress

func GetPublicEndpointByMeshAddress(meshAddress string) string

GetPublicEndpointByMeshAddress returns the remote/local server's public endpoint by its internal mesh address.

func GetServerRole

func GetServerRole() string

GetServerRole returns the server role of itself.

func GetServerRoleByMeshAddress

func GetServerRoleByMeshAddress(meshAddress string) string

GetServerRoleByMeshAddress returns the server role of a remote server by its internal mesh address.

func GetServerType

func GetServerType() string

GetServerType returns the server type of itself.

func GetServerTypeByMeshAddress

func GetServerTypeByMeshAddress(meshAddress string) string

GetServerTypeByMeshAddress returns the server type of a remote server by its internal mesh address.

func GetSharedData

func GetSharedData(key string) (int16, bool)

GetSharedData returns synchronized shared data by its key.

func IsOffline

func IsOffline() bool

IsOffline returns true if the server is marked to be shutdown.

func IsOfflineByMeshAddress

func IsOfflineByMeshAddress(meshAddress string) bool

IsOfflineByMeshAddress returns true if the remote server of the given mesh address is marked to be shutdown.

func IsServerRoleHTTP

func IsServerRoleHTTP() bool

IsServerRoleHTTP returns true if the server role is HTTP.

func IsServerRoleTCP

func IsServerRoleTCP() bool

IsServerRoleTCP returns true if the server role is UDP.

func IsServerRoleUDP

func IsServerRoleUDP() bool

IsServerRoleUDP returns true if the server role is UDP.

func IsTaken

func IsTaken() bool

IsTaken returns true if the server is in taken state.

func IsTakenByMeshAddress

func IsTakenByMeshAddress(meshAddress string) bool

IsTakenByMeshAddress returns true if the remote server of the given mesh address is in taken state.

func MarkServerAsOffline

func MarkServerAsOffline()

MarkServerAsOffline flags the server as "OFFLINE".

func MarkServerAsOnline

func MarkServerAsOnline()

MarkServerAsOnline flags the server as "ONLINE".

func MarkServerAsTaken

func MarkServerAsTaken()

MarkServerAsTaken flags the server as "TAKEN".

func MarkServerAsTakenIf

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".

TAKEN - When the server is marked as "TAKEN", the server will NOT accept new user connections.

func NewLogger

func NewLogger(name string) *log.Logger

NewLogger creates a new instance of log.Logger.

func OnKeepAlive

func OnKeepAlive(handler func(userData *user.User, next func(error)))

OnKeepAlive assigns a callback to be invoked on every echo (UDP) or heartbeat (TCP).

func RemoveOnSharedDataRemove

func RemoveOnSharedDataRemove(cb func(key string, updated int64))

RemoveOnSharedDataRemove removes the given callback that has been assigned by SetOnSharedDataRemove.

func RemoveOnSharedDataUpdate

func RemoveOnSharedDataUpdate(cb func(key string, value int16, updated int64))

RemoveOnSharedDataUpdate removes the given callback that has been assigned by SetOnSharedDataUpdate.

func RemoveSharedData

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.

func ResponseStatusBad

func ResponseStatusBad() uint8

ResponseStatusBad returns UDP or TCP server response status code for invalid command invocation.

func ResponseStatusErr

func ResponseStatusErr() uint8

ResponseStatusErr returns UDP or TCP server response status code for server error while handling command.

func ResponseStatusOK

func ResponseStatusOK() uint8

ResponseStatusOK returns UDP or TCP server response status code for successfully handled command.

func SendMeshCommand

func SendMeshCommand(cmd uint16, addresses []string, data interface{}, reliable bool) error

SendMeshCommand sends a mesh command of the given cmd to the given internal mesh address.

The server of the given address will invoke the command handler of the given cmd.

Parameters

cmd       - Mesh command ID.
addresses - Internal mesh address of the server to send the command to.
data      - Data to be sent to the handler.
            The valid data type of data must be the following two types only:
            1. map[string]interface{}
            2. struct
reliable  - If true, UDP will be RUDP.

The diagram below show how command is sent to multiple servers when you give multiple addresses:

                                                           ┌──────────┐
                                                     ┌────▶︎│ Server D │
                                                     │     └──────────┘
                               ┌──────────┐ <2> Send │
                           ┌──▶︎│ Server B │──────────┤     ┌──────────┐
                           │   └──────────┘          └────▶︎│ Server E │
┌──────────┐ <1> Send      │                               └──────────┘
│ Server A │ ──────────────┤                               ┌──────────┐
└──────────┘               │   ┌──────────┐          ┌────▶︎│ Server F │
                           └──▶︎│ Server C │──────────┤     └──────────┘
                               └──────────┘          │
                                                     │     ┌──────────┐
                                                     └────▶︎│ Server G │
                                                           └──────────┘

func SendMeshRPC

func SendMeshRPC(cmd uint16, address string, data []byte) (response []byte, err error)

SendMeshRPC sends a mesh RPC of the given cmd to the given internal mesh address and expects a response back from the server.

The server of the given address will invoke the command handler of the given cmd and sends back a response.

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 SendMeshRequest works:

┌──────────┐ <1> Send request  ┌──────────┐
│ Server A │ ─────────────────▶︎│ Server B │
│          │ ◀︎──────────────── │          │
└──────────┘ <2> Send Response └──────────┘

Parameters

cmd       - Mesh command ID.
address   - Internal mesh address of the server to send the command to.
data      - Data to be sent to the handler.
            You may use td.DefineTransportData to create a data structure for RPC.

Returned Values

response  - The RPC handler on a remote server's response to the RPC sent.
err       - If the RPC operation fails, an error is sent.

func SendMeshRequest

func SendMeshRequest(cmd uint16, address string, data interface{}, callback func(err error, response map[string]interface{}))

SendMeshRequest sends a mesh command of the given cmd to the given internal mesh address and expects a response back from the server.

The server of the given address will invoke the command handler of the given cmd and sends back a response.

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 SendMeshRequest works:

┌──────────┐ <1> Send request  ┌──────────┐
│ Server A │ ─────────────────▶︎│ Server B │
│          │ ◀︎──────────────── │          │
└──────────┘ <2> Send Response └──────────┘

Parameters

cmd       - Mesh command ID.
address   - Internal mesh address of the server to send the command to.
data      - Data to be sent to the handler.
            The valid data type of data must be the following two types only:
            1. map[string]interface{}
            2. struct
callback  - The callback to be invoked when the response is received from the remote server.

func SetMeshCommandHandler

func SetMeshCommandHandler(cmd uint16, handler MeshCommandHandler)

SetMeshCommandHandler assigns a callback to the given mesh command handler to the given cmd.

func SetMeshRPCHandler

func SetMeshRPCHandler(cmd uint16, handler MeshRPCHandler)

SetMeshRPCHandler assigns a callback to the given mesh RPC handler to the given cmd.

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.

func SetOnSharedDataRemove

func SetOnSharedDataRemove(cb func(key string, updated int64))

SetOnSharedDataRemove assigns a callback to be invoked when a shared data is deleted.

func SetOnSharedDataUpdate

func SetOnSharedDataUpdate(cb func(key string, value int16, updated int64))

SetOnSharedDataUpdate assigns a callback to be invoked when a shared data is updated.

func SetServerCommandHandler

func SetServerCommandHandler(ver uint8, cmd uint16, handler CommandHandler)

SetServerCommandHandler assigns a callback to the given command ver and cmd.

func SetSharedData

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.

func SetupDiarkis

func SetupDiarkis(logConfigPath, meshConfigPath string, m *Modules)

SetupDiarkis initializes core and optional modules.

func SetupDiarkisHTTPServer

func SetupDiarkisHTTPServer(config string)

SetupDiarkisHTTPServer declares the server to be HTTP server.

func SetupDiarkisTCPServer

func SetupDiarkisTCPServer(config string)

SetupDiarkisTCPServer declares the server to be TCP server.

func SetupDiarkisUDPServer

func SetupDiarkisUDPServer(config string)

SetupDiarkisUDPServer declares the server to be UDP server.

func SetupNotificationService

func SetupNotificationService(name string, interval int64, callback func() (*Notification, error))

SetupNotificationService starts a notification service loop on the server.

The notification loop will execute the given callback at the given interval in seconds.

If the callback returns, *diarkisexec.Notification, the server will send the notification message along with ver and cmd to all the clients connected to the server.

Parameters

name     - A name of the notification service.
interval - Notification delivery cycle interval in milliseconds
callback - A callback to be invoked on each notification service loop tick. The returned values will be the notification.
           If the callback returns a nil, notification will not be sent to the clients.

func SetupNotificationServiceBySharedData

func SetupNotificationServiceBySharedData(name string, sharedDataName string, cb func(sharedDataValue int16) (*Notification, error))

SetupNotificationServiceBySharedData starts a goroutine that listens to a shared data change for the given shared data name and value. When the shared data that matches the given name changes its value, the NotificationLoader callback is invoked to handle notifications.

If the callback returns, *diarkisexec.Notification, the server will send the notification message along with ver and cmd to all the clients connected to the server.

Parameters

name            - A name of the notification service.
sharedDataName  - A shared data name that the notification service listens to.
cb              - A callback to be invoked on each notification service loop tick. The returned values will be the notification.
                  If the callback returns a nil, notification will not be sent to the clients.

func StartDiarkis

func StartDiarkis()

StartDiarkis starts the Diarkis server.

Types

type CommandHandler

type CommandHandler func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error))

CommandHandler callback for a UDP/TCP server command.

type MeshCommandHandler

type MeshCommandHandler func(req map[string]interface{}) (response []byte, err error)

MeshCommandHandler callback for a mesh command.

type MeshRPCHandler

type MeshRPCHandler func(req []byte, senderAddr string) (response []byte, err error)

MeshRPCHandler callback for a mesh command.

type Modules

type Modules struct {
	DGS        *Options
	Dive       *Options
	DM         *Options
	Field      *Options
	Group      *Options
	Room       *Options
	MatchMaker *Options
	Session    *Options
	Metrics    *Options
	Notifier   *Options
	MARS       *Options
	// In order to use P2P module properly, you must provide enableP2P:true config to Diarkis UDP server.
	// P2P module is only compatible with Diarkis UDP server.
	P2P *Options
}

Modules represents module declarations.

type Notification

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
}

Notification represents the notification data to be propagated to all connected Diarkis clients.

type Options

type Options struct {
	// Configuration file path for the module that needs configuration JSON file provided.
	// The path to configuration JSON file must be a relative to the server executable binary file location.
	ConfigPath string
	// If true, Diarkis server will expose built-in commands of the modules to the client.
	// There are modules that do not have built-in commands.
	ExposeCommands bool
}

Options represents module configurations.