jhalitaksoy/mancala
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Release: Quarkus backend, Keycloak login, game history, clock, bot, tutorial and rematch #3

Merged
jhalitaksoy merged 88 commits from develop into main 2026-10-17 03:23:38 +03:00
Conversation 0 Commits 88 Files Changed 323 +18923 -5793
jhalitaksoy commented 2026-10-17 03:21:44 +03:00
Owner
Copy Link
No description provided.
jhalitaksoy added 88 commits 2026-10-17 03:21:45 +03:00 
- Custom authenticator creates and logs in a guest user when the
  authorization request has guest=true; other requests get the login form
- Scheduled task removes guests with no remaining sessions
- Realm export with mancala-web PKCE client, guest role and guest-aware
  browser flow (verify profile disabled so guests are not asked for details)
- Dockerfile building the extension into a Keycloak 26.7.5 image
- Keycloak and Postgres in compose; nginx proxies auth.playmancala.app
  and rate limits the auth endpoint
- Integration tests run the extension and realm in a Keycloak container
- New auth module verifies Keycloak access tokens offline against the
  realm's signing keys (issuer, RS256, typ=Bearer, allowed azp); guests
  are recognised by the guest realm role
- Clients send an auth message after connecting and get on_auth or
  on_auth_error; unauthenticated sockets are closed after 5 seconds and
  their messages ignored; a socket can refresh its token but not switch user
- A user can be connected from several sockets; a late close of an old
  socket no longer drops the new one
- Malformed messages are ignored instead of throwing
- Games store player names and guest flags and send them with the
  connection info
- Legacy ?userKey= clients and /register stay available behind
  LEGACY_USERKEY_AUTH; legacy keys must be UUIDs so they cannot take a
  Keycloak user's kc: id
- TypeScript target raised to es2020 for async/await
- Apps and @mancala/core depend on the packages in this repo through
  link: dependencies instead of the npm releases, so changes no longer
  need a publish
- Root package.json gets a build:packages script that installs and
  builds both packages
- Backend and frontend Docker images are built from the repo root so
  they can include the packages; compose builds them that way
- Metro watches the packages folder and resolves their imports from the
  app's node_modules
- First visit logs in as a new guest through Keycloak without a form;
  the session, including an offline refresh token, is kept in local storage
- Account menu on the home page: guests can log in or sign up, users can
  log out (which starts a new guest session)
- The WebSocket client in core authenticates with the access token after
  connecting, reports "connected" once the server accepts it, and re-sends
  renewed tokens on the open connection
- Game page shows player names; guests appear as "Guest 4F2A"
- Auth channels, AuthUser and player names in UserConnectionInfo move to
  core and the backend uses them from there
- Mobile keeps using userKey login for now
- postgres replaces keycloak-db and holds a keycloak and a mancala database,
  each with its own user, created by apps/postgres/init
- valkey with an append-only file for live game state and caches
- backend gets DATABASE_URL and VALKEY_URL
- PlayerSummary, MoveRecord, live and finished game summaries, GameRecord,
  timeout constants, startedAt/moveTimes on Game and offlineSince on
  UserConnectionInfo
- Channels for live game previews and for rejecting a new game while one
  is in progress
- getInitialBoard, getBoardAfterMove, describeMove and createGameAtMove,
  with tests against games played with the engine
- English and Turkish strings for the new screens
- Spectators are removed from games when they disconnect; the lookup
  iterated an iterator with for...in and never found anything
- Finished and left games are removed from memory, not only from the
  player mappings
- The connection info is sent once when a game starts
- Connection pool and a small migration runner (schema_migrations, one
  transaction per migration, advisory lock)
- games and game_players tables with indexes for a user's games and for
  popular games
- PostgresGameHistoryRepository: idempotent save, get, recent games of a
  user, popular games
- Integration tests against a real Postgres via testcontainers; a custom
  Jest environment gives tests Node's web globals, which Jest 27 leaves out
- GameRecord carries the number of distinct spectators
- Valkey client that fails commands at once while Valkey is down instead
  of queueing them, and logs connection errors once
- ValkeyLiveGameStore: live game snapshots and finished games waiting to
  be saved, loaded with SCAN on startup
- ValkeyCache: JSON values with a TTL; errors count as cache misses
- Integration tests against a real Valkey, including an unreachable one
- Games record start and move times, spectator peak and distinct count
- Games end as completed, left (the leaver loses), timeout (5 minutes
  offline on your turn while the opponent is online) or inactive (both
  offline for 30 minutes); everyone gets on_game_end
- Connection info carries offlineSince for the countdown
- A new game is rejected while the user has one in progress
- Live games are written to Valkey after every change and restored on
  startup; finished games are saved to Postgres with public ids, and
  saves that fail are kept and retried every 30 seconds
- Clients get a trimmed game without spectator ids
- Startup waits for Valkey, restores games, then accepts connections;
  migrations are retried while Postgres is unreachable
- GET /games/me/active and /games/me (Bearer token), /games/popular (live
  games, or the most spectated finished ones), and /game/:id now also
  returns saved records of finished games
- Lists are cached in Valkey for 10 seconds, cleared when a game is saved,
  and empty instead of failing while the database is down
- Live game previews over WebSocket: subscribers get the top 5 on
  subscribe and on change, at most once per second, without counting as
  spectators; ids are public ids
- RTMT supports several connection listeners
Board components size themselves from a --board-unit CSS variable instead
of vw. By default it is 1vw, so the game page looks the same; with the new
width prop the same board renders small, e.g. in previews.
- Banner for the user's game in progress with a Continue button
- Live games as cards with the real board, updated over WebSocket; the
  most watched finished games when nothing is live
- The user's last 3 games, from their side of the board, with the result
  as they would say it
- The lobby offers to continue the game in progress when a new one is
  refused
- Spectators register once connected and identified, and again after a
  reconnect, so they are counted
- The backend includes games that ended but are not saved yet in /game/:id
  and the lists
- Move list under the board with player, pit and what happened (extra
  turn, capture, stones to the store, game over); collapsed on phones
- Selecting a move or using the arrow keys shows that position with a
  banner and Back to live; pits are locked meanwhile and the banner says
  when it is your turn
- Countdown while the opponent is offline on their turn
- on_game_end is handled, so games that end by timeout or inactivity end
  on the page with the reason
- Opening a finished game shows its final position, result, score, date
  and duration, with Watch from start
- First / previous / play-pause / next / last, speed 1x, 2x, 4x, a
  timeline, the move list and arrow keys and space
- Stepping forward animates the move like a live game; jumps show the
  position directly
- ?move=n links to a move and follows the shown move
- Players see the board from their own side
- PitAnimator takes its step interval as a parameter
- Backend README: DATABASE_URL, VALKEY_URL, the new routes and how the
  backend behaves when Postgres or Valkey is down
- TODO: drop the fixed spectator and memory bugs, add game history on
  mobile, a page with all games, single-instance limits, backups and the
  new .env variables
- Spec marked as implemented, all tasks ticked
Requirements, design decisions and tasks for the Keycloak login, written
after the implementation; mobile login and turning off legacy userKey
login remain open.
The mancala login theme extends keycloak.v2 with one stylesheet: the game's
app bar and logo, the board's colors, pit-shaped inputs, pill buttons and a
board with stones on top of the card. Dark colors follow the system color
scheme. The realm turns the theme on and offers English and Turkish.

The test container now loads the theme and checks that the login page uses
it in the requested language.
Login and sign-up redirects pass the current language as ui_locales.
Each player has 5 minutes; the server keeps the time and a scheduled service ends games whose running clock reaches zero. Replaces the offline turn and inactivity rules.
GameClock and optional clock fields on live games, end messages, move records and finished games; getClockTimes, ClockSync, getClockAtMove and formatClock with tests.
Each player starts with GAME_CLOCK_MS (5 minutes). A move deducts the turn's time from the mover; a move that arrives after the time has run out is not played and the opponent wins on time. Every ending stops the clock, and clients get the clock and the server time with each game message.
GameClockScheduler checks every live game once a second and ends those whose running clock has reached zero, whether or not anyone is connected. The clock replaces the offline turn timeout and the inactivity rule, so both are removed with the offline times they used.
Live game snapshots become version 2 with the clock and each move's time left. On restore the running clock goes on from the start of the turn, so downtime is not charged; version 1 snapshots get a new clock. Saved games keep the initial time (migration 002_clock) and each move's time left.
Both clocks sit next to the players' names and count down in server time; the running one is highlighted and turns red under 30 seconds. They replace the offline countdown, so core drops TURN_TIMEOUT_MS, INACTIVE_TIMEOUT_MS, offlineSince and its text. Long info texts wrap on phones.
Each player's clock after the shown move, from the saved move times; games saved before the game clock show none.
Both clocks next to the players, counting down in server time with the same running and low-time styles as the web app. The game screen now handles on_game_end, so a game that ends on time ends on the phone too and says why.
Backend README (GAME_CLOCK_MS), AGENTS.md notes, TODO items for the open points and the mobile release order; game-history R3.3 and R3.4 marked as replaced. Checked end to end in Chrome: moves, a backend restart, a timeout and the replay.
The dialog's buttons were in the wrong order and its result was read inverted; leaving now needs Yes and returns to the home page.
Requirements, design and tasks for implementing the new web design
(themes, board, game, replay and home pages).
ThemeManager takes its list of themes, PitAnimator marks animated pits
with PitViewModel.highlight, getSowingPath lists the pits a move sows
into, and new texts in English and Turkish.
GET /games/popular?kind=finished returns the most watched finished
games even when games are being played, so the web app can show live
and popular games together.
ThemeManager called storage.set, which neither app's storage has, so
choosing a theme threw and the choice was lost on reload.
Ceviz, Gece and Yeşim themes as CSS variables on <html>, Bricolage
Grotesque, shared styles, and one header for every page with theme
swatches, the account menu and the page's main action. The lobby,
privacy page and status panels use the new look.
Pits and stores are wells with scattered stones and count badges, the
viewer's store on the right. Below 600 px the board stands upright.
Playable pits preview their move on hover, animated pits are ringed and
the pit of the last move has a dashed ring.
Players beside the board with avatar, online status, store count and
clock, the turn between them, a game-over card over the board, and a
move list with the newest move first and tags for extra turns,
captures and store gains. On phones the bottom player is shown below
the board.
A summary card with the result, date, duration, move count, players and
score; players and the move number beside the board; a controls card
with the transport buttons, speed, timeline and the shown move with its
tags; the landing pit of the shown move is ringed.
The game in progress comes first with a large mini board; live,
popular and recent games are grids of cards with the score, a mini
board and a status pill. Live and popular games are shown together;
live games are hidden while nothing is being played.
AGENTS.md notes on the themes, plain CSS for container queries and
driving the app in Chrome; TODO.md gets the mobile app and rematch as
open work; the spec is marked implemented.
Mangala skips the opponent's store, but Board.move dropped a stone in
every pit and store. Moves with enough stones to pass it gave the
opponent a stone and ended one pit too early, so captures and extra
turns were decided on the wrong pit.

Board.getSowingPath now computes the pits a move sows into, and
Board.move and core's getSowingPath (the web board's move preview)
both use it. Game step indexes are now always within the board.
PitAnimator guessed the played pit of a single stone move from the
first sowing step and skipped index 0, so playing one stone from
player 1's first pit showed it still holding the stone until the
animation ended. It now empties the move's own pit (moveIndex).
Remove the sowing and animation bugs, which are fixed, and add the
open question of who gets the remaining stones when a move empties
the opponent's side.
The apps use the engine from the repo, so publishing the fixed engine to
npm is left as the last deployment step.
Requirements, design and tasks for rewriting the backend in Java 25 with
Quarkus while keeping the protocol, the API and the stored data.
Quarkus 3.40 on Java 25, built with the Maven wrapper. The engine is a
line-by-line port of packages/mancala.js; a parity test replays games
recorded with the TypeScript engine, including illegal moves, and
compares every board, turn, error and the game JSON.
Records for the JSON the clients read, leaving out only the fields
TypeScript leaves undefined. GameLoop is the single thread that owns live
state; ManualScheduler replaces Jest's fake timers in tests. Keycloak
tokens are verified with jose4j and the same checks as before.
GameManager, matchmaking, the game clock, live game snapshots, saving
finished games and live previews, ported from the Node backend with its
tests. Snapshots keep the Node backend's format; a test restores one the
Node backend wrote. Valkey writes and saves run off the game loop.
The Node backend's migrations, runner, queries, keys and JSON, so the
same database and Valkey serve either backend. Integration tests run
Postgres and Valkey with Quarkus Dev Services, including a game row the
Node backend wrote and an unreachable Valkey.
RtmtServer ports the WebSocket protocol (auth handshake, sockets per
user, ping) and runs on the game loop; the websockets-next endpoint at /
only forwards socket events. The HTTP routes, CORS and the access log
match the Express app. Backend wires everything and restores live games
before handling socket events. End-to-end tests play games over real
sockets against Postgres and Valkey.
The Quarkus project moves to apps/backend and the Express sources go.
The image is built from the repo root as before, with Temurin 25, and
runs as a non-root user on port 6000. Compose passes the database as a
JDBC URL with the same MANCALA_DB_PASSWORD.
The backend README, how to run and test it, what is easy to get wrong
with the game loop and the shared data formats, and the deployment note.
The web app was played against it in Chrome: a full game with a
spectator, a reload, a restart mid-game, the replay and a game lost on
time.
Requirements, design and tasks for playing against a bot with four levels
and a strength drawn per game.
Position keeps the board as 14 stone counts and plays the Mangala rules on
it without allocating. Tested against MancalaGame with the recorded games and
random games.
Negamax with alpha-beta on Position scores every move; the strength sets the
depth, the softmax temperature and the chance of a random move. The levels
are ranges of strengths drawn per game. A calibration tournament checks that
each level beats the one below.
new_bot_game starts a game against the bot at the chosen level and ends the
search for an opponent. BotPlayer works out the bot's moves on its own thread
pool and plays them on the game loop after the previous move's animation and a
thinking time. Bot games keep their settings across restarts.
Saved games against the bot keep the bot's level, strength and seed in a new
bot column, so the levels can later be tuned from real games.
getPlayerDisplayName shows the bot as e.g. "Bot · Medium" from its id.
The lobby offers the bot levels after 10 seconds without an opponent, the
home page has a Play with bot menu, and a game against the bot ends with
Play again at the same level.
The lobby offers the bot levels after 10 seconds without an opponent, the
home screen has Play with bot, the bot is shown with its level, and a new
game after a bot game is one at the same level.
The bot in the backend README with the calibration command, AGENTS.md notes on
bot ids and test tags, and the open work in TODO.md.
Requirements, design and tasks for a rules page, interactive lessons and a
practice game with hints against the Easy bot.
RULES defines every rule with an example and a lesson; getMoveOutcome works
out a move's effect with the engine, explainMove says what happened, and
describeMove now tells the kind of capture and how many stones it took.
A How to play page with every rule and a before/after board computed by the
engine, a help button in the header, and the rules in a side panel over the
game page so a game can go on while a rule is looked up.
Six lessons, one per rule, on the real board with the TypeScript engine: a
task, the move animated, praise or an explanation and a retry. Completed
lessons are remembered on the device.
The home page shows newcomers a banner to start the lessons; it goes away for
good after Not now, a lesson or a game. The lessons end with a practice game
against the Easy bot with hints on.
With hints on, the player's pits show whether their move gives an extra turn
or how many stones it takes, and a line under the board says what the last
move did and why. A Hints switch appears only in games against the bot.
A How to play screen with the same rules and examples as the web app, opened
from the help screen and from the game screen's help button.
AGENTS.md and TODO.md notes for the tutorial, and the end-to-end results. A
move that ends the game is no longer explained as giving an extra turn.
The pit animator sends the same board model, changed, at every step, so
React skipped the lesson page's updates and only the first step showed.
Each update now gets a new model.
Only the react-dom/client error is left in the web app.
Rematch from the game over card, alternating first moves and a series
strip with the score of the games the same two players played in a row.
Every game starts a series; a game created in a series gets its seat to
move first. Clients get the series and the first seat with the game, the
end message the series with the ended game; snapshots keep the series.
RematchOffers keeps an offer open for ten minutes after a game nobody
left. A request goes to the opponent; when both have asked the next game
of the series starts with the other player moving first. Requests end on
no, withdrawal, a minute without answer, going offline or looking for
another game. The bot accepts at once.
Migration 004_series adds games.series_id with an index, so the history
can group a series later. Games saved before have none.
The four rematch channels, Series and SeriesGame, the series and first
seat of a game, getSeriesScore and the texts in English and Turkish.
The card asks for a rematch, shows a request from the opponent with
Rematch and No, waits with Cancel and says why a request ended. The game
page follows the next game, keyed by its id so it starts afresh. Play
again against the bot is a rematch. The score is two columns, each name
above its stones, the winner's stones stronger.
From the second game of a series, a strip shows the series score and a
box per game in the winner's colour, with the stores, who moved first
and how it ended; a finished game opens its replay in a new tab. The
game over card shows the series score too. Spectators see names.
The rematch spec is implemented; AGENTS.md lists it with notes on the
offers, the keyed game route and stale dev builds, TODO.md takes the
items left out.
jhalitaksoy changed title from develop to Auth - New UI - Game History 2026-10-17 03:22:28 +03:00
jhalitaksoy changed title from Auth - New UI - Game History to Release: Quarkus backend, Keycloak login, game history, clock, bot, tutorial and rematch 2026-10-17 03:23:28 +03:00
jhalitaksoy merged commit a07390c4cc into main 2026-10-17 03:23:38 +03:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: jhalitaksoy/mancala#3
No description provided.
Delete Branch "develop"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?