diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..04ffa1a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,203 @@ +# Contributing + +This page provide technical information to facilitate future maintenance of the project. + +- [Contributing](#contributing) + - [Building from sources](#building-from-sources) + - [Deployments methods](#deployments-methods) + - [Use CLI in console mode](#use-cli-in-console-mode) + - [Deploy the game for Web based access](#deploy-the-game-for-web-based-access) + - [Information for developers](#information-for-developers) + - [Client console](#client-console) + - [Server](#server) + - [High level design](#high-level-design) + - [Low level design](#low-level-design) + - [Debug log](#debug-log) + - [Ideas for the future](#ideas-for-the-future) + +## Building from sources + +Prerequisites: + +- internet access +- recent go version (tested with 1.19.x) + +Get the sources and build the `poker` binary: + +```bash +git clone https://github.com/fc92/poker +cd poker +go build -o poker cmd/poker.go +``` + +This binary contains can be used to start a server or a client process. It needs a terminal to run properly. + +Other common go checks and tests can be run with: + +```bash +go vet -v ./... +go test -v ./... +``` + +## Deployments methods + +The are different ways of deploying this client/server game: + +- using CLI in console mode (recommended for development or native client on a wide range of platforms), +- with Web based access for better user experience (recommended for end users). + +### Use CLI in console mode + +The same binary file is used to start the server and console clients. Various platform are supported. See [latest release page](https://github.com/fc92/poker/releases/latest) for more details. For example to use the Windows terminal natively without Docker use the corresponding binary file. + +Start a single server instance (dedicated for one team): + +- using default websocket: + +```bash +./poker server +subcommand 'server' + websocket: localhost:8080 +``` + +- or specifying the websocket to open: + +```bash +./poker server -websocket 127.0.0.1:7878 +subcommand 'server' + websocket: 127.0.0.1:7878 +``` + +When the server is started, start a client for each player. It must be able to communicate with the server. + +- example of client specifying a player name and the websocket value: + +```bash +./poker client -name Player1 -websocket 127.0.0.1:7878 +subcommand 'client' + name: Player1 + server websocket: 127.0.0.1:7878 +``` + +- example of client using a generated name and default websocket: + +```bash +./poker client +subcommand 'client' + name: snowy-cloud + server websocket: localhost:8080 +``` + +Each player can navigate the client console and send commands using keyboard and mouse. + +NB: in mobaXterm mouse events are not always correctly handled + +This binary file is located in `/poker` in the docker image and can be used with `docker run` on a limited number of supported platforms. + +### Deploy the game for Web based access + +In production the docker image is used to provide both server and client processes. This is described in the [README page](/README.md). + +For development outside of docker the manual steps to work with the `poker` binary are described here. This binary is the result of the `go build -o poker cmd/poker.go` command and can also be found in `/poker` of the docker image. + +Prerequisite: server with docker and [tty2web](https://github.com/kost/tty2web) binary (tested on Linux x86_64). + +To simplify the user experience it is recommended to: + +- start the server in a docker container: + +```bash +docker run -p 192.168.0.1:8080:8080/tcp ghcr.io/fc92/poker:main /poker server -websocket 8080 +``` + +to expose the server on address 192.168.0.1 port TCP 8080 + +- provide user access in a web browser using [tty2web](https://github.com/kost/tty2web): + +```bash +tty2web --title-format Poker --permit-arguments -a 192.168.0.1 -p 8081 -w docker run -it --rm ghcr.io/fc92/poker:main /poker client -websocket 192.168.0.1:8080 +``` + +so that users can connect to to join the game in a browser with player name *Mary*. + +There are multiple benefits with this tty2web deployment method: + +- users only need a web browser with proper network access to play the game, +- users can play on platforms that are not natively supported like iOS or Android, +- the server and each player process run inside a restricted container for security. + +## Information for developers + +This section provides technical information for developers. + +### Client console + +Each player starts a console client to join the team server and play the game. + +Client main features: + +- [X] display available commands +- [X] allow mouse and keyboard user inputs +- [X] user defined or generated player name +- [X] commands: quit game, start new vote, send vote, modify vote, close the vote session +- [X] display vote progress during vote session +- [X] display distribution of votes when vote session is closed +- [X] content is driven by the server to maintain consistency between players + +### Server + +The server broadcasts a shared vision to all clients in real time. + +Server main features: + +- [X] start single game to host client players +- [X] share vote and available commands to all users +- [X] add newly connected user +- [X] remove disconnected user +- [X] broadcast vote status per user during vote session +- [X] broadcast votes when all votes are available or vote is manually closed +- [X] reset vote values when a new vote starts +- [X] close vote when all players have voted + +### High level design + +HTTP websocket is used for "real-time" communication between clients and the server. Messages are in JSON format and contain `Room` and `Participant` information. + +A server instance maintains a single `Room` that contains: + +- a `Participant` for each player, +- the status of the game: vote open or closed. + +The `Room` content changes when a client sends a command or is disconnected. Each change is broadcasted to all clients. + +Each `Participant` contains information about a player: + +- player name, +- commands available to the user, +- vote value. + +A `Participant` can be updated by local user actions or updates sent from the server. + +### Low level design + +Server and console client are written in pure Go language. + +The software is packaged as a single binary file for each supported platform. The same file is used with different parameters to start a server or a client instance from a text console. + +It should be possible to write other client implementations using other languages supporting websocket and JSON. The focus of this project is pure GO so far. + +## Debug log + +Server debug logs can be activated using the `-debug` flag + +## Ideas for the future + +- [ ] [WebAssembly.sh](https://webassembly.sh) support: tinygo WASI support is not yes sufficient + +```bash +tinygo build -wasm-abi=generic -target=wasi -o poker.wasm cmd/poker.go +# golang.org/x/sys/unix +../.go/pkg/mod/golang.org/x/sys@v0.0.0-20220722155257-8c9f86f7a55f/unix/syscall_unix.go:526:17: Exec not declared by package syscall +``` + +- [ ] server part on ESP32: [tinygo support for ESP32](https://tinygo.org/docs/reference/microcontrollers/esp32-coreboard-v2) is not sufficient diff --git a/README.md b/README.md index 02ae729..93ff1e7 100644 --- a/README.md +++ b/README.md @@ -10,17 +10,8 @@ - [poker](#poker) - [Game description](#game-description) - [Install](#install) - - [Deploy the game for Web based access (recommended)](#deploy-the-game-for-web-based-access-recommended) - - [Use CLI in console mode (advanced)](#use-cli-in-console-mode-advanced) - - [Binary](#binary) - - [Docker image](#docker-image) - - [Information for developers](#information-for-developers) - - [Client console](#client-console) - - [Server](#server) - - [High level design](#high-level-design) - - [Low level design](#low-level-design) - - [Debug log](#debug-log) - - [Ideas for the future](#ideas-for-the-future) + - [Standard deployment](#standard-deployment) + - [Custom HTTP port deployment](#custom-http-port-deployment) ## Game description @@ -34,183 +25,31 @@ ## Install -The are different ways of deploying this client/server game: +The most common usage is to deploy: -- with Web based access for better user experience (recommended), -- using CLI in console mode (advanced). +- deploy a container for one poker room on server side, +- use a modern browser on client side to join the room for the game. -### Deploy the game for Web based access (recommended) +### Standard deployment -Prerequisite: server with docker and [tty2web](https://github.com/kost/tty2web) binary (tested on Linux x86_64). - -To simplify the user experience it is recommended to: - -- start the server in a docker container: - -```bash -docker run -p 192.168.0.1:8080:8080/tcp ghcr.io/fc92/poker:main -``` - -to expose the server on address 192.168.0.1 port TCP 8080 - -- provide user access in a web browser using [tty2web](https://github.com/kost/tty2web): - -```bash -tty2web --title-format Poker --permit-arguments -a 192.168.0.1 -p 8081 -w docker run -it --rm ghcr.io/fc92/poker:main /poker client -websocket 192.168.0.1:8080 -``` - -so that users can connect to to join the game in a browser with player name *Mary*. - -There are multiple benefits with this tty2web deployment method: - -- users only need a web browser with proper network access to play the game, -- users can play on platforms that are not natively supported like iOS or Android, -- the server and each player process run inside a restricted container for security. - -### Use CLI in console mode (advanced) - -Binary or docker image version can be used to start the server or a client. - -#### Binary - -The same binary file is used to start the server and console clients. Various platform are supported. See [latest release page](https://github.com/fc92/poker/releases/latest) for more details. - -Start a single server instance (dedicated for one team): - -- using default websocket: - -```bash -./poker server -subcommand 'server' - websocket: localhost:8080 -``` - -- or specifying the websocket to open: - -```bash -./poker server -websocket 127.0.0.1:7878 -subcommand 'server' - websocket: 127.0.0.1:7878 -``` - -When the server is started, start a client for each player. It must be able to communicate with the server. - -- example of client specifying a player name and the websocket value: - -```bash -./poker client -name Player1 -websocket 127.0.0.1:7878 -subcommand 'client' - name: Player1 - server websocket: 127.0.0.1:7878 -``` - -- example of client using a generated name and default websocket: - -```bash -./poker client -subcommand 'client' - name: snowy-cloud - server websocket: localhost:8080 -``` - -Each player can navigate the client console and send commands using keyboard and mouse. - -NB: in mobaXterm mouse events are not always correctly handled - -#### Docker image - -By default the docker image runs a server listening on 0.0.0.0:8080. - -Using the docker command line it is possible to expose that port outside of the container and to modify the IP and port of the server. - -Server: +- Server using default HTTP port 8081: ```bash -docker run -p 8080:8080 ghcr.io/fc92/poker:main -subcommand 'server' - websocket: 0.0.0.0:8080` +docker run -p 8081:8081 -td ghcr.io/fc92/poker:main ``` -Client with IP *192.168.0.10*: - -It is also possible to start a client instance. - -```bash -docker run -it ghcr.io/fc92/poker:main /poker client -name PlayerName -websocket 192.168.0.10:8080 -``` - -## Information for developers - -This section provides technical information for developers. - -### Client console - -Each player starts a console client to join the team server and play the game. - -Client main features: - -- [X] display available commands -- [X] allow mouse and keyboard user inputs -- [X] user defined or generated player name -- [X] commands: quit game, start new vote, send vote, modify vote, close the vote session -- [X] display vote progress during vote session -- [X] display distribution of votes when vote session is closed -- [X] content is driven by the server to maintain consistency between players - -### Server - -The server broadcasts a shared vision to all clients in real time. - -Server main features: - -- [X] start single game to host client players -- [X] share vote and available commands to all users -- [X] add newly connected user -- [X] remove disconnected user -- [X] broadcast vote status per user during vote session -- [X] broadcast votes when all votes are available or vote is manually closed -- [X] reset vote values when a new vote starts -- [X] close vote when all players have voted - -### High level design - -HTTP websocket is used for "real-time" communication between clients and the server. Messages are in JSON format and contain `Room` and `Participant` information. - -A server instance maintains a single `Room` that contains: - -- a `Participant` for each player, -- the status of the game: vote open or closed. - -The `Room` content changes when a client sends a command or is disconnected. Each change is broadcasted to all clients. - -Each `Participant` contains information about a player: - -- player name, -- commands available to the user, -- vote value. - -A `Participant` can be updated by local user actions or updates sent from the server. - -### Low level design - -Server and console client are written in pure Go language. - -The software is packaged as a single binary file for each supported platform. The same file is used with different parameters to start a server or a client instance from a text console. - -It should be possible to write other client implementations using other languages supporting websocket and JSON. The focus of this project is pure GO so far. - -### Debug log +- Browser URL to connect as player *Mary*: +`http://server_ip:8081/?arg=-name&arg=Mary` -Server debug logs can be activated using the `-debug` flag +### Custom HTTP port deployment -### Ideas for the future +The port can be modified, to add a second poker room for example: -- [ ] [WebAssembly.sh](https://webassembly.sh) support: tinygo WASI support is not yes sufficient +- Server using non default HTTP port 8083: ```bash -tinygo build -wasm-abi=generic -target=wasi -o poker.wasm cmd/poker.go -# golang.org/x/sys/unix -../.go/pkg/mod/golang.org/x/sys@v0.0.0-20220722155257-8c9f86f7a55f/unix/syscall_unix.go:526:17: Exec not declared by package syscall +docker run -p 8083:8083 -td ghcr.io/fc92/poker:main ./clients.sh 8083 ``` -- [ ] server part on ESP32: [tinygo support for ESP32](https://tinygo.org/docs/reference/microcontrollers/esp32-coreboard-v2) is not sufficient +- Browser URL to connect as player *Mary*: +`http://server_ip:8083/?arg=-name&arg=Mary`