The project allows Quibbble games to be run in a K8s cluster. Games are spun up as individual pods with their entire lifecycle handled by the Quibbble controller. This allows Quibbble to take advantage of the power of K8s, primarily the ability to scale as well as to seperate and self heal in the event of any single game failure.
This controller currently requires the usage of NGINX to allow for dynamic routing of games. Meaning that if a game with key tictactoe and id example is created, then NGINX will handle the routing to that game over path /game/tictactoe/example.
helm upgrade --install ingress-nginx ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx --create-namespacehelm upgrade --install quibbble-controller quibbble-controller \
--repo https://quibbble.github.io/quibbble-controller \
--namespace quibbble --create-namespaceAll contributions are welcome. To get started take a look at additional docs on setting up a local environment.
There are three main processes in this system.
controller- Processes game create and delete requests.watcher- Periodically searches for and cleans up stale games.server- Runs a game instance.
- Send
POST https://<host>/gamewith someqqnsuch as[key "tictactoe"][id "example"][teams "red, blue"]. controllerprocesses the request and, if valid, creates K8s ConfigMap, Pod, Service, and Ingress resources.- Game can now be accessed at
https://<host>/game/tictactoe/example.
- Join a game by connection to
wss://<host>/game/tictactoe/example?name=<name>with websockets. - Connection should be open to a
serverinstance and relevant game messages should be recieved.
watcherwill kick off everyXtimeperiod.- Job requests data from all live games by calling
GET https://<host>/game/<key>/<id>/activityfor each game. - If there are no connected players and no recent updates then all K8s related resources are deleted.
POST /game (create a game)
name type data type description None required QGN QGN descibing the game to create
http code content-type response 201text/plain;charset=UTF-8Created400text/plain;charset=UTF-8Bad Request409text/plain;charset=UTF-8Conflict500text/plain;charset=UTF-8Internal Server Error503text/plain;charset=UTF-8Service Unavailable
curl -X POST -H "Content-Type: application/qgn" --data @post.qgn https://api.quibbble.com/game
PUT /game (load a game from storage)
name type data type description key required string The name of the game i.e. tictactoeorconnect4id required string The unique id of the game instance to join
http code content-type response 200text/plain;charset=UTF-8OK400text/plain;charset=UTF-8Bad Request404text/plain;charset=UTF-8Not Found500text/plain;charset=UTF-8Internal Server Error503text/plain;charset=UTF-8Service Unavailable
curl -X PUT https://api.quibbble.com/game?key={key}&id={id}
DELETE /game?key={key}&id={id} (delete a game)
name type data type description key required string The name of the game i.e. tictactoeorconnect4id required string The unique id of the game instance to join
http code content-type response 200text/plain;charset=UTF-8OK400text/plain;charset=UTF-8Bad Request404text/plain;charset=UTF-8Not Found500text/plain;charset=UTF-8Internal Server Error
curl -X DELETE https://api.quibbble.com/game?key={key}&id={id}
WEBSOCKET /game/{key}/{id}?name={name} (connect to a game)
name type data type description key required string The name of the game i.e. tictactoeorconnect4id required string The unique id of the game instance to join name required string The name of the player connecting
None
wscat -c wss://api.quibbble.com/game/{key}/{id}
GET /game/{key}/{id}/snapshot?format={format} (get game snapshot)
name type data type description key required string The name of the game i.e. tictactoeorconnect4id required string The unique id of the game instance to join format required one of jsonorqgnThe type of data to return
http code content-type response 200application/jsonorapplication/qgnJSON or QGN 400text/plain;charset=UTF-8Bad Request404text/plain;charset=UTF-8Not Found500text/plain;charset=UTF-8Internal Server Error
curl -X GET https://api.quibbble.com/game/{key}/{id}/snapshot?format=json
GET /game/activity (get all games activity)
None
http code content-type response 200application/jsonActivity for all games 500text/plain;charset=UTF-8Internal Server Error
curl -X GET https://api.quibbble.com/game/activity
GET /game/{key}/{id}/activity (get game activity)
name type data type description key required string The name of the game i.e. tictactoeorconnect4id required string The unique id of the game instance to join
http code content-type response 200application/jsonJSON data describing player count and last update time 404text/plain;charset=UTF-8Not Found
curl -X GET https://api.quibbble.com/game/{key}/{id}/activity
snapshot (retrieve a snapshot of the game)
Message sent to all players on every game state change.
{
"type": "snapshot",
"details": {...}
}connection (retrieve player connection information)
Message sent to all players on every player connection, drop, or team change.
{
"type": "connection",
"details": {
"$NAME1": "$TEAM1",
"$NAME2": "$TEAM2",
"$NAME3": null
}
}chat (retrieve chat message)
Message sent to all players on every sent chat message.
{
"type": "chat",
"details": {
"name": "$NAME",
"team": "$TEAM",
"message": "$MESSAGE",
}
}