Pitaya Game Server Framework

Pitaya uses ephemeral session instances associated with every client connection. Sessions enable asynchronous communication and state management. Key capabilities include:

• ID binding: Bind a session to a user ID so messages can be sent to a user without knowing their specific server or connection.
• Data storage: Store and retrieve data between requests.
• Message passing: Send messages to users via sessions without managing underlying connection protocols.
• Request access: Access sessions via the context instance during handler requests.
• Kick: Disconnect users using the Kick method.

The handshake is the first operation performed when a client connects.

1. Client Initiation: The client sends information such as platform, client library version, and custom user data.
2. Data Storage: Any user data sent during the handshake is stored in the client's session and can be accessed in subsequent requests.
3. Server Response: The server replies with the heartbeat interval, the name of the serializer, and the dictionary of compressed routes.
4. Validation: You can perform validations on the data submitted by the client to ensure they comply with server rules. If validation fails, access to server capabilities can be restricted. Detailed validation logic can be implemented using handshake validators.

To run the provided example scenario, follow these steps to set up dependencies, start the Pitaya cluster components, and execute the k6 test.

# spin up pitaya dependencies
make ensure-testing-deps

# run pitaya server, backend and frontend
make run-cluster-example-backend
make run-cluster-example-frontend

# run k6 scenario
./k6 run ./examples/scenario1.js

Frontend sessions are associated with a connection on a specific frontend server.

Capabilities & Limitations:

• Can be retrieved by session ID or bound user ID only on the server where the connection was established.
• Cannot be retrieved from a different server.
• Supports lifecycle callbacks.

Lifecycle Callbacks:

• Per-session callbacks: Use s.OnClose for individual session logic.
• Global callbacks: Use OnSessionClose, OnSessionBind, and OnAfterSessionBind for logic applied to every session.

In cluster mode, Pitaya servers are categorized into two types:

• Frontend servers: Must specify listeners to receive incoming client connections. They handle routing and forwarding messages to the appropriate backend servers.
• Backend servers: Do not listen for client connections. They only receive RPCs, which are either forwarded client messages (sys rpc) or RPCs from other servers (user rpc).

To run the custom metrics demonstration, use the provided Makefile command. This will start the Pitaya server configured with the custom metrics implementation.

make run-custom-metrics-example

Acceptor Wrappers can be applied to listeners (like TCP or Websocket) to read and modify incoming data before message forwarding.

To create a custom wrapper:

1. Implement the Wrapper interface (or inherit from BaseWrapper).
2. Add the wrapper to your acceptor using the WithWrappers method.

When a request is forwarded to a remote server (a _Sys_ RPC call), the remote server uses a short-lived remote agent to handle the request.

Important: Changes made to the session on a backend server do not automatically reflect in the associated frontend session. If a backend server needs to modify the session, it must explicitly commit those changes by pushing the modifications to the frontend server.

Message Forwarding

When a server receives a client message, it automatically checks the target server type via the route. If the target type differs from the current server type, Pitaya forwards the message to an appropriate instance. By default, routing chooses a target instance at random, but custom routing functions can be defined.

Message Push

Messages can be pushed to users without needing prior knowledge of their session or connection status. A push message requires:

• A route (for client identification)
• The message payload
• target ids
• The expected server type the client is connected to.