package dgs

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

Package dgs ▷

Enable dedicated servers to participate within the Diarkis cluster and mesh network without sacrificing customizability nor scalability.

The DGS framework is divided into four main components, each requiring separate setup to implement Diarkis DGS:

1. Diarkis UDP Server Application
2. Diarkis UDP
3. Diarkis DGS
4. DGS Application

At its core, Diarkis DGS serves as an abstract interface facilitating participation in the Diarkis mesh network. It functions as a pipeline for data transmission between the Diarkis UDP application and the Diarkis DGS application. The DGS Application SDK acts as a sidecar, integrating the DGS application into the Diarkis mesh network. During data transmission, all data sent from the server to the DGS application is treated as a black box. Handling RPC calls, including their creation and response, is managed entirely by the DGS application. Data is transferred as serialized []byte payloads during RPC calls.

To provide flexibility, the framework supports custom DGS allocation node selection backends. Depending on your backend solution (e.g., Agones), you may select a DGS node and perform RPC calls between your Diarkis server and the DGS via the Diarkis network.

                    ╔═════════════════════════════════════════════════════════════════════════════════╗
                    ║   △ Diarkis Cluster                                                             ║
                    ║ ┌─────────────────────────────────────────────┐       ┌───────────────────────┐ ║
                    ║ │ △ Diarkis DGS Module                        │       │ ▽ Application CPP     │ ║
 ┌───────────────┐  ║ │   ┌───────────────┐     ┌───────────────┐   │       │   ┌───────────────┐   │ ║
 │Server-side App│  ║ │   │  Diarkis UDP  │     │  Diarkis DGS  │   │       │   │DGS Application│   │ ║
 └───────────────┘  ║ │   └───────────────┘     └───────────────┘   │       │   └───────────────┘   │ ║
         ╎          ║ │           ╎                     ╎           │       │           ╎           │ ║
         ╎          ║ │           ╎                     ╎  Initialization, & Start [1]  ╎           │ ║
         ╎          ║ │           ╎                     ╎◀︎──────────────────────────────╎           │ ║
         ╎          ║ │           ╎ Join Node Mesh [2]  ╎           │       │           ╎           │ ║
         ╎          ║ │           ╎          ○──────────╎           │       │           ╎           │ ║
         ╎    Allocate DGS Node   ╎                     ╎           │       │           ╎           │ ║
         ╎───────────────────────▶︎╎                     ╎           │       │           ╎           │ ║
         ╎          ║ │           ╎ Forward Alloc Req.  ╎           │       │           ╎           │ ║
         ╎          ║ │           ╎────────────────────▶︎╎           │       │           ╎           │ ║
         ╎          ║ │           ╎                     ╎ Trigger app.onInstanceCreate ╭───────────────────────────╮╮╮
         ╎          ║ │           ╎                     ╎─────────────────────────────▶│ • Instance Initialization │││
         ╎          ║ │           ╎                     ╎     Send DGS Init Response   │   ◦ APP_DEFINED_LOGIC [3] │││
         ╎          ║ │           ╎                     ╎◀︎─────────────────────────────│ • ...                     │││
         ╎          ║ │           ╎   Forward Response  ╎           │       │          ╰───────────────────────────╯╯╯
         ╎          ║ │           ╎◀────────────────────︎╎           │       │           ╎           │ ║
         ╎    DGS Init Response   ╎                     ╎           │       │           ╎           │ ║
         ╎◀───────────────────────︎╎                     ╎           │       │           ╎           │ ║
         ╎      Send DGS RPC      ╎                     ╎           │       │           ╎           │ ║
         ╎───────────────────────▶︎╎                     ╎           │       │           ╎           │ ║
         ╎          ║ │           ╎     Forward RPC     ╎           │       │           ╎           │ ║
         ╎          ║ │           ╎────────────────────▶︎╎           │       │           ╎           │ ║
         ╎          ║ │           ╎                     ╎  Trigger app.onInstanceRPC   ╭───────────────────────────╮╮╮
         ╎          ║ │           ╎                     ╎─────────────────────────────▶│ • Handle Instance RPC     │││
         ╎          ║ │           ╎                     ╎        Send RPC Reponse      │   ◦ APP_DEFINED_LOGIC [4] │││
         ╎          ║ │           ╎                     ╎◀︎─────────────────────────────│ • ...                     │││
         ╎          ║ │           ╎   Forward Response  ╎           │       │          ╰───────────────────────────╯╯╯
         ╎          ║ │           ╎◀────────────────────︎╎           │       │           ╎           │ ║
         ╎    DGS RPC Response    ╎                     ╎           │       │           ╎           │ ║
         ╎◀───────────────────────︎╎                     ╎           │       │           ╎           │ ║
 ╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮
 ╎                                    Life-Span of DGS Instance [5]                                       ╎
 ╰╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╯
         ╎          ║ │           ╎                     ╎   DGS app.InstanceFinish [6]  ╎           │ ║
         ╎          ║ │           ╎                     ╎◀︎──────────────────────────────╎           │ ║
         ╎          ║ │           ╎                     ╎           │       │           ╎           │ ║
 ┌───────────────┐  ║ │   ┌───────────────┐     ┌───────────────┐   │       │   ┌───────────────┐   │ ║
 │Server-side App│  ║ │   │  Diarkis UDP  │     │  Diarkis DGS  │   │       │   │DGS Application│   │ ║
 └───────────────┘  ║ │   └───────────────┘     └───────────────┘   │       │   └───────────────┘   │ ║
                    ║ └─────────────────────────────────────────────┘       └───────────────────────┘ ║
                    ╚═════════════════════════════════════════════════════════════════════════════════╝

[1] You must perform the following steps as a part of the DGS application initialization:
    • Execute SetupDiarkisServer(), set the callback OnDiarkisTerminate(), and SetDiarkisServerType() to DGS node-type.
    • Set DGS application callbacks via SetOnInstanceCreate() and SetOnInstanceRPC() and then invoke SetupAsDiarkisDGSServer().
    • Invoke StartDiarkisServer() and change node-status to ONLINE via SetDiarkisAsOnline().
[2] Once the initialization is complete, the DGS application will join the Diarkis mesh network as the target node-type
    selected via SetDiarkisServerType(). It will be made discoverable by other nodes after invoking SetDiarkisAsOnline().
[3] You MUST define the handler response for InstanceCreate RPC. We recommend a response with endpoint information of the DGS.
[4] You MUST define the handler response for InstanceRPC. We reccomend setting a command code within the RPC payload.
[5] Once a game as been finished, the DGS's state will be set back allocatable. In the case where the game state is UNABLE
    to be reset, we recommend killing and restarting the DGS node and allowing it to re-join the mesh network.
[6] The game application MUST call app.InstanceFinish before termninating the session so the DGS state can be reset.

Setup

Setup of a DGS application requires (2) main sections:

1. Setting up the dgs package (server-side)
2. Setting up the app package (DGS-side)

1. dgs Package (Server-side)

1. First execute Setup(confpath) containing the absolute path to the Diarkis DGS configuration file.

   [NOTE] Within the configuration there must be a property defined: {"backend: $NAME"}. Otherwise the default Diarkis 'DEBUG' backend will be selected (NOT to be used in production).

2. Any configurations nested under the name of the backend will be passed as configurations to the registered custom backend defined by the "backend" property.

3. Once your backend which implements the Diarkis types.DGSSDK interface has been registered, invocation of InstanceCreate will select an available DGS node to host your DGS session upon.

Example Default 'DEBUG' Backend Configuration

Below we provide an example of the default 'DEBUG' backend setup:

{
    "backend": "debugAllocator",
    "debugAllocator": {
       "targetNodeType": "CUSTOM_UDP"
    }
}

[NOTE] When using the default 'debugAllocator' backend, the configuration MUST at least provide: {"targetNodeType": $TYPE}.

Example Custom Backend Configuration

Here too, is an example, in the case of some provisioned custom backend:

{
    "backend": "myCustomBackend",
    "myCustomBackend": {
       "property-1": "some string",
       "property-2": 12
    }
}

2. app Package (DGS-side)

1. Make sure to set callbacks via all the following callback assignment functions: app.SetOnInstanceStart & app.SetOnInstanceRPC

2. Once all of the callbacks have been set accordingly, execute app.Setup.

   [NOTE] On the DGS Application-side, you MUST make sure that an API call to app.InstanceFinished is performed upon DGS instance finish.

Creating a DGS Instance

Diarkis DGS helpfully abstracts the processes of the allocation of a new DGS instance. Invocation of DGS InstanceCreate will find an available DGS node in the Diarkis cluster network which is available to host a DGS instance. The method for which nodes are selected is delegated to the DGS allocation of the provided types.DGSSDK interface implementation to provide flexibility.

[NOTE] A timeout period must be assigned to reset the state of the DGS node in the event that the DGS instance is not able to be created in time.

The node will return both the DGS endpoint information, and a serialized identifier token which allows for subsequent communications with the DGS via instance RPC. The endpoint information may be used by the registered types.DGSSDK allocation backend to initiate the creation of a new server "session" on the DGS. Several solutions for DGS instance creation (and management) exist, such as Agones. In order to handle the creation of an instance, a receiver which implements the types.DGSSDK interface must be provided.

Registering an Allocation Backend

In order to create a new DGS instance, you must first implement an allocation backend receiver which implements the types.DGSSDK interface. The DGS allocation backend struct must AT LEAST implement the following:

type DGSSDK interface {
	// Returns the name of the current backend
	Name() string
	// Sets up the backend with the corresponding backend config map (NOTE: targetNodeType MUST be defined)
	Setup(config map[string]any) error
	// Specifies (with context-timeout) the instansiation of the DGS server, and returns the public address as a types.AllocateResult struct
	AllocateDGS(ctx context.Context, params map[string]string, config map[string]string) (AllocateResult, error)
}

Once a allocation backend implementing has been types.DGSSDK interface has been defined, it must be registered BEFORE invoking Setup...! This can be accomplished by invoking RegisterBackend which registers a backend with a given name.

[NOTE] You may NOT register a backend by the same name "debugAllocator" as the default allocator.

[NOTE] The name by which you register your backend by MUST match the name of your backend within your DGS configuration.

All that is required to register your backend is the name, and a factory function which creates a new receiver struct which implements the types.DGSSDK interface.

Making an RPC to a DGS Instance

Diarkis DGS provides a simple interface to complete application RPC calls.

Below we provide an example of the implementation of a simple ping command between a Diarkis UDP server and a DGS written in Go.

Step 1. UDP server-side 'ping' function definition:

func dgsInstancePing(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error)) {
	res, err := dgs.InstanceRPC(payload, dgsIdentifier)
	if err != nil {
		next(err)
	}
	fmt.Printf("Received an RPC message: %s", string(res))
	next(nil)
}

Step 2. DGS-side RPC handler definition:

app.SetOnInstanceRPC(func(b []byte) ([]byte, error) {
	msg := []byte("pong")
	logger.Debug("Received the message: %q; replying: %q", b, msg)
	return []byte(msg), nil
})

Because Diarkis DGS Instance RPC simply delivers a byte payload between the UDP and DGS server, the ways in which, and the kind of data which is able to be sent is limitless. Although ping is a simple example, it illustrates well how the DGS server may communicate with to the Diarkis mesh. It is worth noting that the DGS instance RPC calls enable the sharing of any data or structures already present in the Diarkis cluster network.

Index

• func GetBackendName() string
• func InstanceCreate(ctx context.Context, payload []byte, params map[string]string, ...) (dgsResponse []byte, dgsIdentifier []byte, err error)
• func InstanceRPC(ctx context.Context, payload []byte, dgsIdentifer []byte) (rpcResponse []byte, err error)
• func NewBackend(name string) types.DGSSDK
• func RegisterBackend(name string, factory func() types.DGSSDK) error
• func Setup(confpath string)

Functions

func GetBackendName

func GetBackendName() string

GetBackendName return the backend name registered via DGS Setup.

[NOTE] You MUST call Setup() BEFORE invoking GetBackendName()!

func InstanceCreate

func InstanceCreate(ctx context.Context, payload []byte, params map[string]string, config map[string]string) (dgsResponse []byte, dgsIdentifier []byte, err error)

InstanceCreate allocates a new DGS instance, sends an RPC to initialize it, and returns the DGS endpoint's allocation response along with an identifier token for subsequent application RPCs.

[IMPORTANT] If the node type cannot be determined or the RPC call fails, appropriate errors are returned.
[NOTE] The returned DGS identifier can be used as an authentication token in subsequent RPCs to the DGS instance.
[NOTE] If the provided context does not have a deadline set, the default mesh.SendRPC() timeout will be used.
	   Additionally, the provided context MUST be non-nil.

Parameters:

• ctx: Context for instance creation timeout.
• payload: Data payload to initialize the DGS instance.
• params: Additional parameters for configuration.
• config: Additional configuration settings.

func InstanceRPC

func InstanceRPC(ctx context.Context, payload []byte, dgsIdentifer []byte) (rpcResponse []byte, err error)

InstanceRPC sends an RPC to the DGS endpoint held by the DGS identifier token and receives a response.

[IMPORTANT] DGS identifier tokens become invalid once the DGS instance it identifies has been
			unallocated. In this case, it will fail.
[IMPORTANT] It must be decided how to create the payload before passing it into InstanceRPC()
			and the payload must be handled as a response set by app.SetOnInstanceRPC().
[NOTE] If the provided context does not have a deadline set, the default mesh.SendRPC timeout will be used.
	   Additionally, the provided context MUST be non-nil.

Parameters:

• ctx: Context for instance creation timeout.
• payload: Byte payload to be delivered to the target identified by the DGS identifier token.
• dgsIdentifier: Identifier required for RPC with DGS endpoint returned by InstanceCreate.

func NewBackend

func NewBackend(name string) types.DGSSDK

NewBackend instanciate and return a new [DGSSDK] previously registered with the given name.

Parameters:

• name: Name of the registered backend for which to create a new [DGSSDK] backend.

func RegisterBackend

func RegisterBackend(name string, factory func() types.DGSSDK) error

RegisterBackend register a backend with the given name.

Parameters:

• name: Name of the DGS backend to register.
• factory: Factory function to create a new DGS backend struct which implements [DGSSDK].

func Setup

func Setup(confpath string)

Setup set up the DGS package.

[IMPORTANT] A backend name registered by RegisterBackend() MUST be provided, or
			the module setup will fail; and a valid DGS configuration must be provided.

Parameters:

• confpath: Absolute path to the location of the Diarkis DGS configuration file

Directories