gchess-server

The gchess-server project is a backend server application designed to manage chess games and provide a platform for multiplayer matches. Built using the Go programming language, the server supports essential functionalities for hosting online chess matches, including player authentication, game state management, move validation, and real-time game updates

Features

Player Authentication

• Login/Registration: Users can create accounts and log in
• Session management: The server handles user sessions to maintain login states and manage active connections

Game Management

• Matchmaking: Players can enter matching queue and wait for another player to create a match. If players leave the match, they can come back later by rejoin the match.
• Game state: The server maintains the state of ongoing games, tracking each move and updating the board accordingly.
• Data persistence: After a game ended, its information is saved to database, ensuring that game states are preserved and can be retrieved later for user's analysis purposes.

Move Handling

• Move validation: The server validates each move to ensure they are legal according to chess rules.
• The server checks for conditions like check, checkmate, and stalemate after each move to determine the game's status.

Real-Time Updates

• WebSocket integration: The server uses WebSockets to provide real-time updates to connected clients, ensuring players see the latest game state without needing to refresh.

How to run

Client

For the client side, I made a CLI for testing purpose. After the server and database are up and running, you can run the client.go file in the test folder

$ cd test
$ go run test.go

Here is a video that showcase all the functionalities of the CLI

client.webm

Server

Docker

Clone the repository and run the command from the root of the project. This will automatically pull the Docker image for this project and the PostgreSQL database to set up the environment using Docker Compose.

$ docker compose up

You can also modify the docker-compose.yml to build from source instead

services:
  app:
    build: .
    container_name: go-chess-server
    ports:
      - "7202:7202"
      - "7201:7201"
    environment:
      - DATABASE_URL=postgresql://server:chessserver@db:5432/chess
    depends_on:
      - db

If you do it this way, you will also need a config file for the server to run

$ mkdir .go-server-chess
$ vim config.json

For example

{
  "host": {
    "address": "localhost",
    "game_server_port": "7201",
    "rest_server_port": "7202"
  },
  "database": {
    "name": "postgres",
    "host": "localhost",
    "user": "username",
    "password": "password"
  },
  "game": {
    "matching_timeout": 30
  }
}

API

REST

References

• POST /api/users: To register user
• POST /api/login: To log in to the server
• GET /api/sessions: Retrieve match records played by user
• GET /api/sessions/{sessionid}: Retrieve single match record based on ID

WebSocket

After login, user can now join a match by sending matching request

{
  "action": "matching",
  "data": {
    "playerId": "12345"
  }
}

If the action and data is valid, server pushes that user into the matching queue. When a match happens, the two connections are forwarded to game management module, where a game instance will be initialized and binded with the player pair. Then, a message is sent back to the user to notify about the match.

{
    "type": "matched",
    "session_id": "1232524",
    "game_state": {
        "status": "ACTIVE",
        "board": [[]]
        "is_white_turn": true,
    },
    "player_state": {
        "is_white_side": true
    }
}

On the contrary, if there are any errors in the process or the matching request is timeout, the server replies with

• Error (Note that this error json is universal for all the error response to users)

{
  "type": "error",
  "error": "<err_msg>"
}

• Timeout

{
  "type": "timeout",
  "error": "<err_msg>"
}

In a match, users can send move request with

{
  "action": "move",
  "data": {
    "playerId": "12345",
    "sessionId": "1719199808062498696",
    "move": "e2-e4"
  }
}

And get resonses as

{
    "type": "session",
    "game_state": {
        "status": "STALEMATE",
        "board": [[]]
        "is_white_turn": false,
    }
}

After the game reaches end state, the server notifies both players and close their connections.