tuicubserver 0.1.0

Back-end for tuicub - online multiplayer board game in your terminal.

Back-end for tuicub - online multiplayer board game in your terminal.

API Documentation · Events Documentation

Features

• Fully typed code (PEP-484),
• Testable, clean layered architecture,
• 100% tests coverage,
• All public interfaces documented with Google style docstrings,
• Detailed API documentation using the OpenAPI 3.1.0 specification.

Overview

1. The Client connects to the Events Server to receive real-time notifications about events that occur in the user's game or gameroom,
2. The Client queries and issues commands to the API Server via REST API,
3. The API Server notifies the Messaging about the Client's actions, such as ending a turn,
4. The Messaging then notifies the Events Server that an event has occured and it needs to be sent to affected Clients ,
5. The Events Server sends the event that occurred to all affected Clients .

Installation

Using pip

Tuicubserver is available as tuicubserver on PyPI:

pip install tuicubserver

Manually

Start by cloning the repository:

git clone https://github.com/tom-bartk/tuicub-server.git
cd tuicub-server

Then, install the project's dependencies:

python -m pip install -e .

You can now launch the server using the following commands:

$ python -m src.tuicubserver

Usage: python -m src.tuicubserver [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  api     Start the API server.
  events  Start the events and messages server.

Configuration

Prerequisites

A PostgreSQL database is needed for persistence. Some of tuicub's models utilize the ARRAY data type, hence the need for the PostgreSQL backend.

config.toml

Configuration is done via a toml file with a following structure and default values:

[db]
# Connection string to the database.
url ="postgresql+psycopg2://postgres:postgres@localhost:5432/tuicub"

[logging]
# Path to a file to write logs to.
logfile = "/tmp/tuicubserver.log"

[messages]
# Host of the messages server to connect to.
host = "api.tuicub.com"

# Port of the messages server.
port = 23433

# Secret to use when sending messages.
secret = "changeme"

[events]
# Secret to use when authorizing disconnect callbacks from the events server.
secret = "changeme"

To use a custom configuration, set the TUICUBSERV_CONF environment variable to the path of your config file.

For example:

TUICUBSERV_CONF=~/mytuicub/myconfig.toml tuicubserver api

If the TUICUBSERV_CONF environment variable is not set or the file does not exist, the app will try to read a config.toml file from the current working directory.

Launching

API Server

The tuicubserver api command

Use the api command to start the API server, for example:

TUICUBSERV_CONF=./config.toml tuicubserver api --host 0.0.0.0 --port 8080

This will run the underlying Flask application on all available interfaces and port 8080 using the Werkzeug's development server.

[!WARNING] This method is suitable only for local use. For production deployment, follow the Using a WSGI HTTP server instructions below.

Using a WSGI HTTP server

Since the API server is a WSGI application (PEP-3333), you can use any WSGI HTTP server of your choice. The application factory named create_app is defined in the src.tuicubserver.tuicubserver module.

To start the api server using gunicorn on all interfaces and port 8080 run:

TUICUBSERV_CONF=./config.toml gunicorn \
  --bind 0.0.0.0:8080 \
  "src.tuicubserver.tuicubserver:create_app()"

Events Server

Both the Messaging and the Events Server run in the same process. To start it, use the tuicubserver events command:

Usage: tuicubserver events [OPTIONS]

  Start the events and messages server.

Options:
  --events-port PORT    Port to bind events server to.  [default: 23432]
  --events-host HOST    Host to bind events server to.  [default: 0.0.0.0]
  --messages-port PORT  Port to bind messages server to.  [default: 23433]
  --messages-host HOST  Host to bind messages server to.  [default: 0.0.0.0]
  --api-url URL         Base URL of the API for disconnect callbacks.
                        [default: https://api.tuicub.com]
  --help                Show this message and exit.

Following example uses the default host and ports, and a custom API Server:

TUICUBSERV_CONF=./config.toml tuicubserver events --api-url http://localhost:8080

Documentation

API Docs

Visit the API Documentation for a detailed description of all API endpoints.

Screenshot

Events Docs

tuicub gameplay is driven by asynchronous events delivered over TCP sockets.

Every event is fully documented in the Events Documentation.

Screenshot

License

Copyright (C) 2023 tombartk 

This program is free software: you can redistribute it and/or modify it under the terms
of the GNU Affero General Public License as published by the Free Software Foundation,
either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program.
If not, see https://www.gnu.org/licenses/.