asterism-games 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6e27396e105e0e9ab5c096030c51cb529a437291460df76fc6b0510fc9dff6d
-  data.tar.gz: 237c4a6b962e98dc9c3a7e1288c646989a256c1773dd8244ddc9146d5873db55
+  metadata.gz: 7bff07a0b8aceb0d5caa131285b00cd98198e8149496b512d22e8009c69f2614
+  data.tar.gz: fc8c5a631fd8a3e93d39fb0bdd8f11c7bab64d201bd1c1b3173455590e72a1c2
 SHA512:
-  metadata.gz: e428ec7e87cc08c9727743c322448eb8a4c39c2d2fa0d6005eb4855dea335d3884d82ceae0a3da66e35e8ca88a07c03518a7c7329cc0d4f6b0395ba702b3da4f
-  data.tar.gz: 1f61104e967413c4c5ee65a75a71ad9ca572007b8fdfa3dd0518257ea585be1e6798cc804dfa0752b6a8fa002bf41046efabe94b80df80fa7cb2766a9af19663
+  metadata.gz: cd5c7400e36ce7ef56787061ddd9470ef58994f1fdb49328cb0cdf22c4501510c718eceda73e0cd0ce6c7fde2acc749bbdba05e91e8d09c1c16e0e1cc4a9e64c
+  data.tar.gz: a7ab03721da396f87a387709edd5466da2bc97cb08ad1464808dd4a7cb2ca24035b2da13718b84734617052678bc76c3492e4958db203e2d1782f82142183740

data/CHANGELOG.md

@@ -5,6 +5,57 @@ described ("games 0.10.0" and the like).
 
 ## Unreleased
 
+## 0.23.0
+
+Asterism wire protocol 2 (asterism 0.14.0; docs/install.md "From 0.22.0
+to 0.23.0"). **Not compatible with protocol 1**: the host, the console
+(0.4.0), the boards' firmware and the browser build move together. A
+protocol 1 board or browser page still sees the tables' values, but its
+calls (sit, play, view) are refused with the error kind `protocol`.
+
+- Needs asterism 0.14.0 (`~> 0.14`): the host, `bin/mahjong-bots`,
+  `asterism-games play` and the commentary go through the connection
+  object `Asterism.connect` returns.
+- The tables' keys are protocol 2 topics with their types:
+  `<table>/state` and what a game tells (`<table>/strokes` of the board)
+  are declared when the host connects; the games' types
+  (`asterism-games/othello.state`, `mahjong.state`, `mahjong.spectate`,
+  `board.strokes`, ...) are defined by the host, field types by name,
+  with `any` and repeated `[]` for the members, the final ranks and pao.
+  A reader finds them with `asterism topic list` before a value comes.
+- The spectate views move to the node's shared place:
+  `asterism/<node>/@shared/spectate/<table>/state` (was
+  `asterism/<node>/spectate/<table>/state`). Outside the rooms the host's
+  own application `games` declares them; a room's host whose certificate
+  is its own opens the application `room<slot>` of the host's node outside
+  the room and declares its tables there (`spectate/room<slot>-<table>/state`).
+  Each value carries its sender.
+- The present value is asked, not kept on the network: `games` and each
+  `room<slot>` expose the object `spectate`, whose `state(table)` answers
+  the last spectate view (as delayed as the key). The commentary asks it
+  at a sender's first value, after lost values, when the sender started
+  again and after it left; the play clients ask their view when a state
+  value says values were lost or the host started again.
+- `record(id)`'s head gives `time` in ms since 1970 (was seconds). The
+  record book keeps seconds in its own files and database.
+- The roles in the console (docs/install.md section 7): `games-host` adds
+  `asterism/${node}/*/@profile`, `asterism/${node}/*/@pubs`,
+  `asterism/${node}/@shared/**`, `asterism/${node}/room$*`,
+  `asterism/${node}/room$*/**` and Read `asterism/*/game/protocol/*`;
+  `spectator` reads `asterism/*/@shared/spectate/**`, the senders'
+  `@profile`, `@pubs` and liveliness tokens (`games/protocol/*`,
+  `room$*/protocol/*`: its `asterism topic list` shows the spectate keys),
+  and calls `spectate` under its own name.
+  asterism-console 0.4.0's update adds all of these to roles made before.
+- The Gemfile takes asterism from a checkout with `ASTERISM_DIR` (a lock
+  of its own, `Gemfile.asterism_dir.lock`, not committed).
+- The image can be built before an asterism release is published:
+  `ASTERISM_REF=<commit>` (a build arg of the Dockerfile and of
+  `docker-compose.build.yml`) takes asterism from its git repository at
+  that commit, locked in the image's copy of `Gemfile.lock`
+  (docs/install.md "Building the image yourself"). The image keeps the lock
+  its build resolved (`COPY . .` no longer puts the checkout's back).
+
 ## 0.22.0
 
 - Needs CRuby 3.4 or newer (`required_ruby_version >= 3.4`; 3.2 is past its end of life). The image is built on `ruby:3.4.11-slim`.

data/README.md

@@ -166,6 +166,15 @@ seats and tokens). When the router goes away, it connects again every 3 s.
 
 asterism comes from rubygems at a fixed version (0.8.0); riichi_engine from
 the `fmrb` branch of the fork on GitHub (see "riichi_engine" below).
+`ASTERISM_DIR=<a checkout of asterism>` takes asterism from that checkout
+instead, for developing both at once: the Gemfile then uses a lock file of
+its own, `Gemfile.asterism_dir.lock` (not committed; Bundler 2.6 or newer),
+and `Gemfile.lock` keeps the released version.
+
+```
+ASTERISM_DIR=../asterism bundle install
+ASTERISM_DIR=../asterism bundle exec rake test
+```
 
 ## Settings
 
@@ -235,8 +244,10 @@ An Asterism console (0.2.2 and later) makes rooms: a key space of its own
   beyond the one a room needs anyway. The people in the room open the link
   and see the table in the screen's list, as on a home network
   (`games/games/mahjong1`).
-- **One process per room.** The asterism gem keeps one connection a
-  process, so the supervisor forks a host process (Host) per room. It joins
+- **One process per room.** Every room's host is the same application
+  (`<node>/games`, each in its room's namespace), which one program of the
+  asterism gem opens once, so the supervisor forks a host process (Host)
+  per room. It joins
   the router in the room's namespace (`room/<slot>`): its keys are the
   room's, and nothing of it reaches other rooms or the registered side (the
   router's ACL). **Which certificate** (0.5.0): when `rooms.json` lists the
@@ -248,7 +259,10 @@ An Asterism console (0.2.2 and later) makes rooms: a key space of its own
   router. With a console before 0.3.0 it joins with the slot's certificate
   (`certs/room-<slot>.tar`, in the same volume, read-only), as before. A
   console that lists the host while the host has no certificate set: the
-  log says so and the rooms get no table that works. At most `rooms.max` rooms have tables (3); a room
+  log says so and the rooms get no table that works. With its own
+  certificate a room's host whose tables give a spectate view (mahjong)
+  is also the application `room<slot>` of the host's node outside the
+  room, for its tables' spectate keys ("Spectate"). At most `rooms.max` rooms have tables (3); a room
   beyond that gets none (the status says so). A host process that stops is
   started again after 1, 2, 4 ... 30 s.
 - **A slot used again.** The tables of a room are saved under
@@ -440,7 +454,7 @@ Whether the host sees the others come and go is the router's business:
 |---|---|---|
 | a home network (a plain zenohd, no access control) | yes | away at once (measured 10-20 ms after the node left; 6-14 ms after the table app closed while its node kept another application, games 0.10.0) |
 | a room (console 0.3.0, seats) | yes: a room's host reads the whole room, the seats' liveliness tokens included | away at once (measured 6-7 ms) |
-| the permanent tables (console roles `games-host` and `games`) | yes, when the role `games-host` has `Read asterism/*/game` (the console's docs/rooms.md): the router sends the host the players' table apps' liveliness tokens | away at once (measured 13 ms on the console's rehearsal) |
+| the permanent tables (console roles `games-host` and `games`) | yes, when the role `games-host` has `Read asterism/*/game` and `asterism/*/game/protocol/*` (the console's docs/rooms.md; protocol 2's token is `asterism/<node>/game/protocol/2`): the router sends the host the players' table apps' liveliness tokens | away at once (measured 13 ms on the console's rehearsal) |
 
 A role `games-host` made before that line (with only `Watch asterism/**`)
 gets just the tokens on its own keys: the host then falls back to the time
@@ -456,6 +470,49 @@ sent); at a table, a host that leaves shows the connection lost, the
 screen stops asking its view (one every 30 s, should the word not come)
 and asks again as soon as the host is back.
 
+## Topics and types
+
+What the host puts on its application's keys are topics of protocol 2
+(asterism's `docs/protocol.md` 9-11): each table's `<table>/state` and
+what a game tells (the board's `<table>/strokes`), declared with
+`net.publish` on the host's connection when it connects, with their
+types, so a reader finds them before any value comes (`asterism topic
+list games/games`, `net.pubs_of("games", "games")`), and each value
+carries its sequence number (a reader counts what it missed). The types
+are defined with `net.define_type` (`asterism topic info
+games/games/othello1/state`, `net.types_of`):
+
+| Topic | Type | |
+|---|---|---|
+| `<table>/state` of othello | `asterism-games/othello.state` | the public view ("Views" of othello); `res` an `asterism-games/othello.result` |
+| `<table>/state` of mahjong | `asterism-games/mahjong.state` | the public view ("Views"); `res` an `asterism-games/mahjong.result` with `wn` of `asterism-games/mahjong.win` |
+| `<table>/state` of the board | `asterism-games/board.state` | the board's state |
+| `<table>/strokes` of the board | `asterism-games/board.strokes` | each change of the picture ("The drawing board") |
+
+A field of mixed parts (`mb`, the members as `[name, seat, flags]`) is
+an `any[]`, an array of arrays `int[][]` (mahjong's `fin`) or `any[][]`
+(a winner's `pa`). A game declares its types in its class (`Game::TYPES`, `STATE_TYPE`,
+`TOLD_TYPES`).
+
+The spectate keys (`asterism/<node>/@shared/spectate/<table>/state`,
+"Spectate") are in the node's shared place (asterism's `docs/protocol.md`
+17), not under the host's application: the host declares each one on its
+own connection with `net.publish("spectate/<table>/state", shared: :node,
+type: ...)`, and a room's tables are declared by the room's application
+`room<slot>` ("Spectate", "Outside the rooms"), each with the types
+defined on its own connection (a reader reads a shared key's type from
+its sender, `info.from`; `asterism topic list games/games`, `asterism
+topic info games/@shared/spectate/mahjong1/state`):
+
+| Shared topic | Type | |
+|---|---|---|
+| `spectate/<table>/state` of mahjong | `asterism-games/mahjong.spectate` | the spectate view ("Spectate"); `seats` of `asterism-games/mahjong.seat` |
+
+A game declares them in its class too (`Game::SPECTATE_TYPE`,
+`SPECTATE_TYPES`). Every value carries its sender and its sequence number
+(`[seq, nil, "<node>/<app>"]`): a reader counts what it missed per
+sender.
+
 ## Status
 
 The host tells its tables' counts on the network (games 0.9.0), as
@@ -501,18 +558,18 @@ the host offers: its money of the day (`usd`), the limit it stops at
 - **Who reads it.** `asterism watch` and `asterism tree` (the asterism
   gem's command line), its MCP bridge (`asterism_status`), the console's
   details of the host's node (console 0.3.4), or anyone with
-  `Asterism.status_of("games", "games")`.
+  `net.status_of("games", "games")` (which asks the application's
+  profile, `asterism/<node>/<app>/@profile?status`).
 - **Where.** On a home network and on the permanent tables. The role
-  `games-host` needs `asterism/${node}/*/@status` in "Read and write" (the
-  console's docs/rooms.md): a `**` does not match the chunk `@status`. A
-  room's host tells none (the rooms' rules let it write only its own
-  place, which `@status` is not part of, and the console only watches who
-  is in a room).
-- **The asterism gem.** With an asterism that has `Asterism.status`
-  (0.8.0, the version this repository is pinned to) the host uses it
-  (`net.status`); with an asterism 0.7.1 (the gem's lowest) it does the
-  same by hand on the connection's session (`Host::TablesStatus`: a
-  queryable on the key and a put when the counts change).
+  `games-host` needs `asterism/${node}/*/@status` and
+  `asterism/${node}/*/@pubs` in "Read and write" and the queryable of
+  `asterism/${node}/*/@profile` (the console's docs/rooms.md): a `**` does
+  not match a chunk that starts with `@`. A room's host tells none (the
+  rooms' rules let it write only its own place, which `@status` is not
+  part of, and the console only watches who is in a room).
+- **The asterism gem.** The host uses Asterism's status (`net.status`,
+  `Host::TablesStatus`): Asterism puts it when it changes and answers the
+  application's profile.
 - **Size.** Five tables take about 300 bytes (the largest put is in the
   log's `largest message` with the others).
 
@@ -526,22 +583,33 @@ asterism gem's command line and MCP bridge). The mahjong table puts the
 four hands there; othello and the drawing board put nothing (they hide
 nothing: their state is the whole game).
 
-- **The key.** `asterism/<node>/spectate/<table>/state`: the host's node,
-  the application `spectate` (not the host's `games`, so the players' role
-  `asterism/*/games/**` does not match it), and the table. A room's table
-  is `room<slot>-<table>` there (`asterism/games/spectate/room01-mahjong1/state`),
-  so the rooms' tables and the permanent ones never meet. The value is
-  MessagePack, like the state.
+- **The key.** `asterism/<node>/@shared/spectate/<table>/state`: the
+  host's node and its shared place (asterism's `docs/protocol.md` 17: data
+  with no single owner application, a chunk `@shared` that the players'
+  role `asterism/*/games/**` and every `**` do not match), and the table. A
+  room's table is `room<slot>-<table>` there
+  (`asterism/games/@shared/spectate/room01-mahjong1/state`), so the rooms'
+  tables and the permanent ones never meet. The value is MessagePack, like
+  the state.
+- **Who declares it.** The permanent tables' host and a host of its own
+  declare their tables' keys on their own application's connection
+  (`games`, with `shared: :node`), with the game's spectate types; they
+  are in its `@pubs`. Each value carries its sender (`"games/games"`), so
+  a reader tells who put it and counts what it missed per sender.
 - **Outside the rooms.** Every key a room's host writes on its own
   connection gets the room's namespace (`room/<slot>/...`), which every
-  seat of the room reads whole. So a room's host opens a second connection
-  of its own for the spectate keys, with its own certificate and without
-  the namespace: the key is then on the registered side, where the seats'
-  rules do not reach. It does so only with the host's own certificate (a
-  console from 0.3.0 lists the host in `rooms.json`'s `"hosts"`); with the
-  slot's certificate of an older console it puts nothing (that
-  certificate is the room's). The permanent tables' host and a host of its
-  own put on their one connection.
+  seat of the room reads whole. So a room's host opens a second Asterism
+  connection, the application `room<slot>` of the host's node (`room01`;
+  asterism: one application a connection, several in one program), with
+  its own certificate and without the namespace: it declares the room's
+  tables' keys in the node's shared place, on the registered side, where
+  the seats' rules do not reach, with its own types, liveliness token and
+  profile. Its values' sender is `"games/room01"`. It does so only with
+  the host's own certificate (a console from 0.3.0 lists the host in
+  `rooms.json`'s `"hosts"`); with the slot's certificate of an older
+  console it puts nothing (that certificate is the room's). It goes and
+  comes back with the room's host's connection (tried again every 30 s
+  when it cannot open).
 - **What the mahjong table puts.** The table in words, as `look` gives it
   ("Playing from a program") to a member without a seat, with each seat's
   `hand` and `drawn` tile, the same four hands a spectator member's view
@@ -553,7 +621,7 @@ nothing: their state is the whole game).
   member's node or token (`test/test_spectate.rb` looks for them):
 
   ```
-  games/spectate/mahjong1/state
+  games/@shared/spectate/mahjong1/state
   {"table":"mahjong1","status":"play","sv":212,
    "seats":[{"seat":0,"name":"CPU1","kind":"cpu","score":21000,"wind":"north","riichi":false,
              "river":["2z","4z","5z","1m",...],"melds":[{"type":"pon","tiles":["7z","7z","7z"],"from":1}],
@@ -572,25 +640,42 @@ nothing: their state is the whole game).
   At most 8 MB is kept per table; past that the oldest is dropped (never
   shown rather than shown early). The last one put is put again every
   5 s, so a new subscriber has it within that.
+- **The value now.** Asterism keeps no current value on the network
+  (protocol 2): a reader that missed values (`info.lost > 0`) or saw the
+  sender start again (`info.restarted?`, counted per sender) asks the
+  sender. The application that declares the keys exposes the object
+  `spectate` (`games/games/spectate`, a room's `games/room01/spectate`):
+  `state(table)` answers the value last put on
+  `@shared/spectate/<table>/state` (the table as the key names it, a room's
+  `room01-mahjong1`; as delayed as the key), nil before the first one. The
+  commentary does so ("Commentary"); `asterism call
+  games/games/spectate state '"mahjong1"'` too. A table named `spectate` keeps
+  its name, and its host does not expose the object.
 - **Who reads it.** The console's docs/rooms.md, "Watching the tables
-  from outside": the host's role `games-host` needs
-  `asterism/${node}/spectate` and `asterism/${node}/spectate/**` in "Read
-  and write" (without them the router drops the puts, and nothing else
-  changes); a role `spectator` (Read `asterism/*/spectate` and
-  `asterism/*/spectate/**`, Watch `asterism/**`) reads them with the
-  command line, and the `viewer` role (Read `asterism/**`) with the
-  command line and the MCP bridge. The players' role `games` and the
-  rooms' seats do not reach them.
-- **Looking.** With the asterism gem's command line (asterism 0.10.0's
-  `object` commands): `asterism object echo 'games/spectate/*' --credentials
-  spectator.tar` (each put as it comes; `-o json` a line each), `asterism
-  object get games/spectate/mahjong1 --credentials viewer.tar` (the next
-  one). The MCP bridge (`asterism mcp --credentials viewer.tar`):
-  `asterism_values` with the pattern `games/spectate/*/state`. The bridge
-  subscribes to `asterism/**`, which a `spectator` row may not, so it
-  needs the viewer role. The host's application `spectate` is on the
-  network (a liveliness token) while it puts, so the values show as an
-  application that is there.
+  from outside", and `docs/install.md` section 7: the host's role
+  `games-host` needs `asterism/${node}/@shared/**` (the keys),
+  `asterism/${node}/room$*` and `asterism/${node}/room$*/**` (the rooms'
+  applications) in "Read and write" beside its lines for `games` (without
+  them the router drops the puts, and nothing else changes); a role
+  `spectator` reads `asterism/*/@shared/spectate/**` (Watch
+  `asterism/**`), and, for the types (`asterism topic info`,
+  `net.type_of`), the senders' declarations (Read
+  `asterism/*/games/@profile`, `asterism/*/games/@pubs`,
+  `asterism/*/room$*/@profile`, `asterism/*/room$*/@pubs`; Ask
+  `asterism/*/games/@profile`, `asterism/*/room$*/@profile`), and, to
+  ask the value now, Read and Ask `asterism/*/games/spectate/call/${node}`
+  and `asterism/*/room$*/spectate/call/${node}`, and, for `asterism topic
+  list` to find the senders, Read `asterism/*/games/protocol/*` and
+  `asterism/*/room$*/protocol/*` (their liveliness tokens only). The
+  players' role `games` and the rooms' seats do not reach them.
+- **Looking.** With the asterism gem's command line: `asterism object echo
+  'games/@shared/spectate/*/state' --credentials spectator.tar` (each put
+  as it comes, with its sender; `-o json` a line each), `asterism object
+  get games/@shared/spectate/mahjong1/state --credentials viewer.tar` (the
+  next one). The MCP bridge: `asterism_values` with the pattern
+  `games/@shared/spectate/*/state` (each sender's latest value). `asterism
+  topic list games/games` and `asterism topic list games/room01` show who
+  declares them.
 - **Writing a game.** `spectate_view(now)` (nil, the default: nothing) and
   `spectate_delay_ms` (0) of `AsterismGames::Game`.
 
@@ -673,7 +758,7 @@ What the framework gives a game:
 | `changed`, `dirty?`, `unsaved?` | a change to save and put; a change only one member's view shows (`@unsaved = true`) is saved, not put |
 | `to_saved` / `restore` / `resume_clock`, `SAVE_FORMAT` | the saved form (one JSON file per table, `state_dir/<table>.json`, written to a temporary file and renamed); a state of another format is not read. Times are saved as the time left and resumed with the host's clock |
 | `tell(sub, value)`, `SAVE_HOLD_MS` | more than the state: the host puts `value` on `asterism/<node>/<app>/<table>/<sub>` on its next step, in the order told, before the state (the board's strokes). A game that changes many times a second writes its saved state at most once per `SAVE_HOLD_MS` (the host writes what is held when it stops) |
-| `spectate_view(now)`, `spectate_delay_ms` | what the host puts on `asterism/<node>/spectate/<table>/state` for those who watch from outside the table ("Spectate"), held for the delay; nil (the default): nothing. It may hold what the players do not see of each other, never what nobody knows yet |
+| `spectate_view(now)`, `spectate_delay_ms` | what the host puts on `asterism/<node>/@shared/spectate/<table>/state` for those who watch from outside the table ("Spectate"), held for the delay; nil (the default): nothing. It may hold what the players do not see of each other, never what nobody knows yet |
 | `summary(now)` | the counts the status shows (`st`, `members`, `humans`, `cpus`, `away`, and the game's own): no names, no nodes, no tokens. `busy` (`bin/asterism-games status --idle`) is `humans - away` |
 | `settings`, `tables`, `screens`, `DEFAULTS` | the table keys of the settings file and the environment, the tables a host serves by default, the table apps that get the tables in a room, the table's options |
 
@@ -844,7 +929,7 @@ hand.
   spectators are. A host started again starts the delay over (the past is
   not saved).
 - **From outside the table.** The same four hands, in words and as old
-  as the spectators' view, go on `asterism/<node>/spectate/<table>/state`
+  as the spectators' view, go on `asterism/<node>/@shared/spectate/<table>/state`
   for a console's spectators and viewers ("Spectate"), a key the players
   cannot read.
 - **The default is no delay.** The spectators see the hands as they are:
@@ -1218,7 +1303,7 @@ assistant through `asterism mcp`).
 | Method | Arguments | Returns |
 |---|---|---|
 | `records` | from (optional, 0) | `{"records" => [...], "total", "next"}`: the games, newest first, from the from-th, as many as fit one message; `next` is the from of the next page (none: the end). Each: `id`, `at` (the host's local time, `"2026-10-18 21:05"`), `game` (`hanchan` / `tonpuu`), `names`, `ranks`, `scores` (in seat order), `watch` (`true` for a watch game, "Watch games"; else absent) |
-| `record` | id | the game's head: `id`, `at`, `time` (Unix seconds), `table`, `game`, `rules` (as `look`'s), `names`, `kinds` (human / cpu / ai), `final` (`[[seat, rank, score, points x 10], ...]`), `reason` (as the view's `fr`), `rounds` (`[[wind, number, honba, kind, [four changes]], ...]`) |
+| `record` | id | the game's head: `id`, `at`, `time` (ms since 1970), `table`, `game`, `rules` (as `look`'s), `names`, `kinds` (human / cpu / ai), `final` (`[[seat, rank, score, points x 10], ...]`), `reason` (as the view's `fr`), `rounds` (`[[wind, number, honba, kind, [four changes]], ...]`) |
 | `record` | id, round | round `round` (from 0) as below, with `id`, `round`, `of` (how many rounds), `part`, `parts` |
 | `record` | id, round, part | a round too big for one message comes in parts (`parts` > 1): part 0 has everything with the first moves, part k the moves from `move_from` on |
 
@@ -1543,7 +1628,7 @@ when it is taken), prints the address and opens it in the browser (macOS
 |---|---|
 | `--router LOCATOR`, `--credentials FILE` | as `play` (with neither, `ASTERISM_ROUTER` / `ASTERISM_CREDENTIALS`, all or nothing; with nothing, `tcp/127.0.0.1:7447`) |
 | `--namespace PREFIX` | a room's tables: `room/01` shows `room01-<table>` (the spectate keys are outside the room, so the connection has no namespace) |
-| `--table TABLE` | the table to show first: `mahjong1`, `games/mahjong1` or `games/spectate/mahjong1`; without it, every table that puts its spectate key is offered and the first one shown |
+| `--table TABLE` | the table to show first: `mahjong1`, `games/mahjong1` or `games/@shared/spectate/mahjong1`; without it, every table that puts its spectate key is offered and the first one shown |
 | `--node NODE` | the node ID (default `commentate-<host>-<pid>`, or the `.tar`'s name) |
 | `--port N` | the page's port (default 7470) |
 | `--public` | hide the hands: the views sent to the page lose `hand` and `drawn`, and no line tells a hand |
@@ -1555,10 +1640,22 @@ when it is taken), prints the address and opens it in the browser (macOS
 | `--ai-model MODEL` | the model they ask (default `claude-haiku-5-5`) |
 | `--ai-daily-usd USD` | what they may cost a day (default 3); then the fixed commentary alone |
 
-- **The role.** The spectate keys are `asterism/<host>/spectate/<table>/state`.
-  On a console's network a `viewer` (Read `asterism/**`) or a `spectator`
-  (Read `asterism/*/spectate` and `asterism/*/spectate/**`) reads them; the
+- **The role.** The spectate keys are
+  `asterism/<host>/@shared/spectate/<table>/state` (it subscribes
+  `*/@shared/spectate/*/state`; the host of a value is its sender's node,
+  `info.from`, the permanent tables' `games` or a room's `room<slot>`).
+  On a console's network a `spectator` (Read
+  `asterism/*/@shared/spectate/**`) or a `viewer` whose role reads the
+  nodes' shared places reads them ("Spectate", "Who reads it"); the
   players' role `games` does not. On a plain zenohd anyone does.
+- **Values lost, a host started again.** At a table's first value from
+  its sender (the host, a room), when a value comes after lost ones, when
+  the sender started again, and when it left the network and came back,
+  the command asks the sender for the table now (`<node>/<app>/spectate`,
+  `state`, "Spectate", "The value now") and shows that, unless a newer
+  value came meanwhile; one ask at a time per table, on a thread of its
+  own. Without the role's lines for the call it says so and goes on with
+  the next value.
 - **The page.** A bar of states on top (the table, the voice, the delay the
   host puts on the table, a host that is not there), the table in a
   canvas (the round, honba, riichi sticks, the wall and the dora
@@ -2293,7 +2390,8 @@ ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 bundle exec rake test   # also through a
   letter), the countdown rewritten in place on a terminal (only the time
   line, between ESC 7 and ESC 8), and the screens (a round in kanji with
   its two-row hand and a river that goes on below, emoji and MPSZ; the lobby, a result,
-  the end, a call, a spectator). With `ASTERISM_TEST_ROUTER`, a host in a
+  the end, a call, a spectator), the view asked again after lost state
+  values or a host that started again. With `ASTERISM_TEST_ROUTER`, a host in a
   process of its own and three clients at once (kanji by default, emoji,
   MPSZ) that play a
   tonpuu game against three CPUs each to the end from scripted input
@@ -2311,7 +2409,9 @@ ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 bundle exec rake test   # also through a
   frames, `--public`, `--json`, a page that opens late, a host that leaves
   and comes back), the web server (the page, the sheets byte for byte,
   404 / 405 / a foreign Host refused, 127.0.0.1 only, the events stream, a
-  port taken), the options and `--help`; with the table there, a CPU
+  port taken), the options and `--help`, the table asked again after lost
+  values or a sender that started again (once at a time, a newer value
+  wins, a failed ask); with the table there, a CPU
   round played here through the hub.
 - `test_commentate_voice.rb`: the commentary's voice (in `rake test:gem`
   too), against a small VOICEVOX engine started in the test: a character
@@ -2332,8 +2432,13 @@ ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 bundle exec rake test   # also through a
   board), the keys of the permanent tables and of a room, what the rooms
   give their hosts, the mahjong view (the four hands, no token, node, wall
   or ura dora), a CPU game on the host, the delay (0, and 3 s across a
-  round's end, in order, never sooner), a room's table on the connection
-  outside the room only, and the last put again after 5 s.
+  round's end, in order, never sooner), the keys in the node's shared
+  place declared by the host's application and numbered with their
+  sender, a room's table declared and put by the room's application
+  `room<slot>` outside the room only, who opens that application, the
+  last put again after 5 s, and the object `spectate` that answers the
+  value last put (the host's and a room's application; none for a table
+  named `spectate`).
 - `test_play_commands.rb`: `--commands "sit,cpu,start"` against a table
   in this process: they wait for the lobby when a game is going on as
   the client joins (and then sit, fill and start), the owner's wait for

data/VERSION

@@ -1 +1 @@
-0.22.0
+0.23.0

data/lib/asterism_games/board/table.rb

@@ -56,6 +56,20 @@ module AsterismGames
       # A page of picture: at most this many points.
       PAGE_POINTS = 400
       KEY = "strokes"
+      # The state's type (public_view's keys; mb, the members as [name,
+      # flags], an any[]) and the strokes' (the messages above).
+      STATE_TYPE = "#{TYPE_PREFIX}board.state".freeze
+      STROKES_TYPE = "#{TYPE_PREFIX}board.strokes".freeze
+      TOLD_TYPES = { KEY => STROKES_TYPE }.freeze
+      TYPES = {
+        STATE_TYPE => [[%w[v int], %w[t str], %w[st str], %w[n int], %w[np int], %w[last int], %w[mb any[]],
+                        %w[lim int[]]],
+                       "A drawing board: its version, the strokes and points on it, the last stroke's id, the " \
+                       "members as [name, flags], the limits"],
+        STROKES_TYPE => [[%w[o str], %w[id int], %w[c int], %w[w int], %w[p int[]], %w[k int], %w[v int]],
+                         "A change of a board: o \"a\" points of stroke id (k 0 a new stroke), \"u\" stroke id " \
+                         "taken back, \"c\" the board cleared; v the board's version"]
+      }.freeze
 
       attr_reader :strokes, :points, :owner
 

data/lib/asterism_games/commentate/mahjong.rb

@@ -266,10 +266,111 @@ module AsterismGames
       end
     end
 
+    # Asterism's protocol 2 keeps no current value on the network: a
+    # reader asks the sender for it (Host#spectate_now, the object
+    # <node>/<app>/spectate) at the first value of a table from a sender,
+    # and again when it missed values (info.lost > 0) or saw the sender
+    # start again (info.restarted?; both counted per sender on the shared
+    # place). A sender that left the network (on_app_leave) is forgotten:
+    # Asterism then forgets its numbers too, so its next value comes as a
+    # first one (lost 0, not restarted), and is asked for again. The
+    # answer goes to the hub unless a newer value came while asking. The
+    # asking is on a thread of its own: the values come on the receiving
+    # thread, where no call may wait.
+    class Refetch
+      attr_reader :asked, :taken
+
+      # call: ->(from, name) { the current value } ("<node>/<app>" of the
+      # sender, the table's name under spectate/); log: ->(message).
+      def initialize(hub, call:, log: ->(_m) {})
+        @hub = hub
+        @call = call
+        @log = log
+        @lock = Monitor.new
+        @seen = Hash.new(0) # table id => values given to the hub
+        @from = {}          # table id => the sender of its last value
+        @want = {}          # table id => [from, host, name, @seen when asked]
+        @queue = Thread::Queue.new
+        @asked = 0
+        @taken = 0
+      end
+
+      # A value of a table came (the receiving thread): blk gives it to
+      # the hub; at a sender's first value, after lost values or when the
+      # sender started again, the current one is asked for (once at a time
+      # per table). Returns blk's.
+      def came(info, host, name, &blk)
+        id = MahjongHub.id(host, name)
+        why = nil
+        out = @lock.synchronize do
+          r = blk.call
+          @seen[id] += 1
+          from = info.from.to_s
+          first = @from[id] != from
+          @from[id] = from
+          why = if !from.include?("/") || @want.key?(id) then nil
+                elsif info.restarted? then "#{from} started again"
+                elsif info.lost.to_i.positive? then "#{info.lost} value(s) lost"
+                elsif first then "the first value from #{from}"
+                end
+          @want[id] = [from, host, name, @seen[id]] if why
+          r
+        end
+        if why
+          @log.call("#{id}: #{why}; asking #{info.from}/#{Commentate::MahjongRunner::SPECTATE_OBJECT} for the table now")
+          @queue << id
+        end
+        out
+      end
+
+      # A sender ("<node>/<app>") left the network: its next value is a
+      # first one.
+      def forget(from)
+        @lock.synchronize { @from.delete_if { |_id, f| f == from } }
+      end
+
+      # Asks for one table's current value and gives it to the hub (a
+      # newer value that came meanwhile wins). :taken, :newer, :none (the
+      # sender has nothing yet) or :error.
+      def run_one(id)
+        from, host, name, at = @lock.synchronize { @want[id] }
+        return :none unless from
+        @asked += 1
+        v = @call.call(from, name)
+        @lock.synchronize do
+          @want.delete(id)
+          return :newer if @seen[id] != at
+          return :none unless v.is_a?(Hash)
+          @hub.update(host, name, v)
+          @seen[id] += 1
+        end
+        @taken += 1
+        @log.call("#{id}: took the table now from #{from}")
+        :taken
+      rescue StandardError => e
+        @lock.synchronize { @want.delete(id) }
+        @log.call("#{id}: asking #{from}/#{Commentate::MahjongRunner::SPECTATE_OBJECT}: #{e.class}: #{e.message}")
+        :error
+      end
+
+      def start
+        @thread = Thread.new { loop { run_one(@queue.pop) } }
+        self
+      end
+
+      def stop
+        @thread&.kill
+      end
+    end
+
     # `asterism-games commentate mahjong`: the connection, the spectate
     # keys, the web server and the browser.
     module MahjongRunner
-      SPECTATE = "asterism/*/spectate/*/state"
+      # The spectate keys in every node's shared place (README "Spectate").
+      SPECTATE = "*/@shared/spectate/*/state"
+      # The sender's object that answers a table's current spectate value
+      # (Host::SPECTATE_OBJECT): <node>/<app>/spectate, state(table).
+      SPECTATE_OBJECT = "spectate"
       STALE_S = 15
 
       module_function
@@ -289,18 +390,20 @@ module AsterismGames
         info.puts "commentate: hands hidden (--public)" if opts[:public]
         open_browser(server.url, err) if opts[:open]
         prefix = room_prefix(opts[:namespace])
+        refetch = nil
         connect(opts, err) do |net|
           net.on_leave { |n| hub.host_left(n) }
           net.on_join { |n| hub.host_back(n) }
+          refetch = Refetch.new(hub, call: ->(from, name) { net["#{from}/#{SPECTATE_OBJECT}", timeout: 2].state(name) },
+                                     log: ->(m) { err.puts "commentate: #{m}" }).start
+          net.on_app_leave { |n, a| refetch.forget("#{n}/#{a}") }
           net.start
-          net.session.subscribe(SPECTATE) do |sample|
-            next if sample.respond_to?(:kind) && sample.kind == :delete
-            _, host, _, name, = sample.key.to_s.split("/")
+          net.subscribe(SPECTATE) do |v, info|
+            host, name = spectate_source(info)
             next unless wanted?(host, name, opts[:table], prefix)
-            v = Asterism::Codec.unpack(sample.payload)
-            hub.update(host, name, v)
+            refetch.came(info, host, name) { hub.update(host, name, v) }
           rescue StandardError => e
-            err.puts "commentate: #{sample.key}: #{e.class}: #{e.message}"
+            err.puts "commentate: #{info.key}: #{e.class}: #{e.message}"
           end
           stop = Thread::Queue.new
           %w[INT TERM].each { |s| trap(s) { stop << true } }
@@ -310,6 +413,7 @@ module AsterismGames
           end
         end
       ensure
+        refetch&.stop
         server&.stop
         voice&.stop
         ai&.stop
@@ -349,6 +453,17 @@ module AsterismGames
         end
       end
 
+      # [host node, table] of a spectate value: the node of its sender
+      # (info.from, "<node>/<app>": the host's games or a room's room<slot>,
+      # the same node), else the key's; the table from the name under
+      # @shared/ (spectate/<table>/state).
+      def spectate_source(info)
+        from = info.from.to_s
+        host = from.include?("/") ? from.split("/").first : info.node
+        parts = info.name.to_s.split("/")
+        [host, parts[0] == "spectate" ? parts[1] : nil]
+      end
+
       # --namespace room/01: the room's tables are room01-<table> outside it.
       def room_prefix(ns)
         return nil if ns.to_s.empty?
@@ -363,8 +478,8 @@ module AsterismGames
         parts.size >= 3 ? "#{parts[0]}/#{parts[-1]}" : t
       end
 
-      # --table: <table>, <host>/<table>, <host>/spectate/<table> or the
-      # play's <host>/games/<table>.
+      # --table: <table>, <host>/<table>, <host>/@shared/spectate/<table>
+      # or the play's <host>/games/<table>.
       def wanted?(host, name, table, prefix)
         return false if host.nil? || name.nil?
         return false if prefix && !name.start_with?(prefix)