The table service

class TablesConfig(AppConfig):
    # The package was `cards` when card games were the only table games; the
    # label stays, so the database tables, migrations and admin addresses keep
    # their names (docs/adr/0014).
    name = "tables"
    label = "cards"
    verbose_name = "Tables"

    def ready(self):
        from . import signals  # noqa: F401
        from .engine import check
        from .games import GAMES

        for game in GAMES.values():
            check(game)

REQUIRED = ("slug", "min_players", "max_players", "options", "new", "act", "tick", "deadline", "view", "deciding",
            "bot_action", "fallback", "over")

def check(game: Game) -> None:
    """Refuse a game missing something the service needs, naming it, when
    the site starts rather than at the first table."""
    missing = [name for name in REQUIRED if not hasattr(game, name)]
    if missing:
        raise ImproperlyConfigured(f"The table game {getattr(game, 'slug', game)!r} is missing {', '.join(missing)}.")
    if not 1 <= game.min_players <= game.max_players <= MAX_SEATS:
        raise ImproperlyConfigured(f"The table game {game.slug!r} seats {game.min_players} to {game.max_players}; tables seat 1 to {MAX_SEATS}.")
    if seating(game) not in SEATINGS:
        raise ImproperlyConfigured(f"The table game {game.slug!r} seats people {seating(game)!r}; say one of {', '.join(SEATINGS)}.")

def advance(game: Game, state: dict, bots: dict[int, str], now: float, rng: random.Random, limit: int = 200,
            away=()) -> float | None:
    """Do everything that's due by `now`: the game's timers, bots' moves,
    and whatever can be decided for the `away` seats (every time round, so a
    buy a bot's discard opens doesn't wait on someone who's gone).

    Each bot decision waits its think time after the moment it became the
    bot's to make. The wait is kept in the state (`_bot`) under the
    decision's key, so a stale wait never fires. Returns when to call again.
    """
    for _ in range(limit):
        for seat in away:
            game.away(state, seat, now)
        game.tick(state, now)
        if game.over(state):
            return None
        due = state.setdefault("_bot", {})
        acted = False
        live = game.deciding(state)
        for stale in set(due) - {str(seat) for seat, _, _ in live}:
            del due[stale]
        for seat, kind, decision in live:
            level = bots.get(seat)
            if level is None:
                continue
            key = str(seat)
            wait = due.get(key)
            if not wait or wait[0] != decision:
                wait = due[key] = [decision, now + think(game, kind) * state.get("_pace", 1.0)]
            if now < wait[1]:
                continue
            del due[key]
            action = game.bot_action(state, seat, level, rng)
            try:
                game.act(state, seat, action, now)
            except Illegal:
                # A bot's mistake mustn't jam the table: make the plainest legal move.
                log.exception("Bot at seat %s tried %r", seat, action)
                game.act(state, seat, game.fallback(state, seat, kind), now)
            acted = True
            break  # the state changed: look again from the top
        if not acted:
            break
    if any(seat in bots and str(seat) not in state.get("_bot", {}) for seat, _, _ in game.deciding(state)):
        return now  # stopped at the limit with a bot still to move
    waits = [w[1] for w in state.get("_bot", {}).values()]
    timer = game.deadline(state)
    times = waits + ([timer] if timer is not None else [])
    return min(times) if times else None

# What a game calls its rounds, and whether the highest total wins. Contract
# Rummy plays hands, lowest first.
TERMS = {"round": "round", "rounds": "rounds", "low_wins": False}

GAMES = {g.slug: g for g in (
    alphabet_roulette,
    auction_house,
    bowl,
    bullshit,
    contract_rummy,
    euchre,
    fictionary,
    get_in_line,
    last_one_standing,
    michigan_rails,
    michigan_rummy,
    millbury_mansion,
    quiz_whiz,
    sixty_six,
    vibe_check,
)}

def options(raw: dict | None) -> dict:
    return {"timer": moves.choice(raw, "timer", TIMERS, 0), "bot_pace": moves.choice(raw, "bot_pace", tuple(moves.BOT_PACE), "brisk")}

def new(players: int, seed: str, now: float, settings: dict | None = None) -> dict:
    if not min_players <= players <= max_players:
        raise Illegal(f"Odd One Out is for {min_players} to {max_players} players.")
    settings = options(settings)
    state = {
        "game": slug, "n": players, "seed": seed, "timer": settings["timer"], "_pace": moves.BOT_PACE[settings["bot_pace"]],
        "seq": 0, "logged": 0, "events": [], "round": 0, "phase": "pick",
        "scores": [], "totals": [0] * players, "ready": [False] * players,
    }
    log.event(state, "round", round=0)
    _ask(state, now)
    return state

def _ask(state: dict, now: float) -> None:
    # The pick waits for the last reveal to finish playing.
    last = state.get("reveal")
    commit.open(state, now, seconds=state["timer"] or None, after=last["ends"] - now if last else 0.0)

MOVES = {"pick": pick, "ready": ready_move}

def act(state: dict, seat: int, action: dict, now: float) -> None:
    moves.dispatch(state, seat, action, now, MOVES, tick=tick)

def dispatch(state: dict, seat: int, action, now: float, moves: dict, tick=None) -> None:
    """The engine's `act`, for a game whose moves are a table of handlers
    {type: handler(state, seat, action, now)}: time passes first (`tick`, the
    game's own), so a move can't land in a window that's closed; a request
    that isn't a move, or that a handler chokes on, is refused politely; and
    a move that's taken bumps `seq`. (A refused move changes nothing that's
    kept: the service saves only moves that go through.)"""
    if tick is not None:
        tick(state, now)
    if not isinstance(action, dict) or not isinstance(action.get("type"), str) or action["type"] not in moves:
        raise Illegal("That isn't a move in this game.")
    if not isinstance(seat, int) or not 0 <= seat < state["n"]:
        raise Illegal("That seat isn't at this table.")
    try:
        moves[action["type"]](state, seat, action, now)
    except (TypeError, ValueError, AttributeError, KeyError, IndexError, StopIteration):
        raise Illegal(GARBLED)
    state["seq"] = state.get("seq", 0) + 1

def pick(state, seat, action, now):
    if state["phase"] != "pick":
        raise Illegal("There's nothing to pick right now.")
    if action["side"] not in SIDES:
        raise Illegal("Pick heads or tails.")
    commit.put(state, seat, action["side"])

def tick(state: dict, now: float) -> bool:
    changed = commit.wake(state, now)
    if state["phase"] == "pick" and commit.due(state, now):
        _reveal(state, now)
        changed = True
    return changed

def _reveal(state: dict, now: float) -> None:
    picks, filled = commit.take(state, lambda seat: "heads")
    sides = {side: [s for s in range(state["n"]) if picks[s] == side] for side in SIDES}
    small = min(SIDES, key=lambda side: len(sides[side]))
    scorers = [] if len(sides["heads"]) == len(sides["tails"]) or not sides[small] else sides[small]
    rounds.score(state, [int(s in scorers) for s in range(state["n"])])
    alone = [seats[0] for seats in sides.values() if len(seats) == 1]
    log.event(state, "picks", round=state["round"], heads=sides["heads"], tails=sides["tails"], scored=scorers, filled=filled)
    beats = [{"cue": "flip", "ms": 1200, "say": f"Heads: {len(sides['heads'])}. Tails: {len(sides['tails'])}.", **sides}]
    for s in alone:
        log.event(state, "alone", to=[s], seat=s, side=picks[s])
        beats.append({"cue": "alone", "ms": 600, "say": f"You were the only one on {picks[s]}.", "to": [s]})
    beats.append({"cue": "score", "ms": 800, "say": "No one scores." if not scorers else f"{len(scorers)} scored.", "scored": scorers})
    reveal.play(state, beats, now)
    rounds.end(state, last=state["round"] == ROUNDS - 1)

def ready(state: dict, seat: int, now: float) -> None:
    rounds.ready(state, seat, now, _next_round)

def _next_round(state: dict, now: float) -> None:
    state["round"] += 1
    state["phase"] = "pick"
    log.event(state, "round", round=state["round"])
    _ask(state, now)

def view(state: dict, seat) -> dict:
    return {
        "game": slug, "seq": state["seq"], "n": state["n"], "round": state["round"], "of": ROUNDS, "phase": state["phase"],
        "scores": state["scores"], "totals": state["totals"], "ready": list(state["ready"]),
        "pick": commit.seen(state, seat), "reveal": reveal.view(state, seat),
        "events": log.recent(state, seat),
    }

def deciding(state: dict) -> list[tuple[int, str, str]]:
    return commit.deciding(state) + rounds.ready_deciding(state)

def bot_action(state, seat, level, rng):
    """Easy bots toss a coin. The others go against last round's crowd."""
    v = view(state, seat)
    if v["phase"] == "scored":
        return {"type": "ready"}
    last = next((e for e in reversed(v["events"]) if e["type"] == "picks"), None)
    if level == "easy" or not last:
        return {"type": "pick", "side": rng.choice(SIDES)}
    crowd = "heads" if len(last["heads"]) >= len(last["tails"]) else "tails"
    return {"type": "pick", "side": "tails" if crowd == "heads" else "heads"}

def away(state, seat, now):
    """Someone away gets heads, so an untimed pick doesn't wait on them."""
    if away_due(state, seat):
        commit.put(state, seat, "heads", auto=True)

def round_no(state: dict) -> int:
    """Which round it is: someone waiting to sit in may take a bot's seat
    as the next one starts (the bot's points go with it)."""
    return state["round"]

def result(state: dict) -> dict:
    return rounds.result(state, high=True)

def create(game: str, name: str, solo: bool = False, bots=(), options=None) -> tuple[Table, Seat, str]:
    rules = GAMES[game]
    name = clean_name(name)
    bots = [b for b in bots if b in BOT_LEVELS]
    if (solo or bots) and not has_bots(rules):
        raise Illegal("This game is played with people, not bots: start a table and share the link.")
    if solo and not rules.min_players - 1 <= len(bots) <= rules.max_players - 1:
        raise Illegal(f"Play against {rules.min_players - 1} to {rules.max_players - 1} bots.")
    Table.objects.filter(updated__lt=timezone.now() - IDLE_TABLES_KEPT).delete()
    with transaction.atomic():
        for _ in range(20):
            try:
                with transaction.atomic():
                    table = Table.objects.create(code=new_code(), game=game, solo=solo, options=_options(rules, options, solo))
                break
            except IntegrityError:
                continue
        seat = Seat(table=table, index=0, name=name, host=True, seen=time.time())
        secret = seat.give_secret()
        seat.save()
        for level in bots:
            _add_bot(table, level)
        if solo:
            _start(table)
    notify.publish(table.code)
    return table, seat, secret

def give_secret(self) -> str:
    secret = secrets.token_urlsafe(24)
    self.token = digest(secret)
    return secret

def join(code: str, name: str) -> tuple[Table, Seat, str]:
    with transaction.atomic():
        table = _locked(code)
        if table.status == Table.CLOSED:
            raise Illegal("That table has closed.")
        if table.status != Table.LOBBY:
            raise Illegal("That game has already started.")
        rules = GAMES[table.game]
        if table.seats.count() >= rules.max_players:
            raise Illegal("That table is full.")
        name = clean_name(name)
        _bots_give_way(table, name)
        seat = Seat(table=table, index=table.seats.count(), name=_unique(table, name), seen=time.time())
        secret = seat.give_secret()
        seat.save()
        _regroup(table)
        seat.refresh_from_db()
        _bump(table)
    notify.publish(code)
    return table, seat, secret

def clean(text, max_len: int) -> str:
    """Compatibility forms folded (NFKC: full-width letters, ligatures),
    control and format characters dropped (so no bidi override can turn a
    name round, nor a zero-width space make two names look alike; only a
    joiner between two emoji stays, so 👨‍👩‍👧 and 👩🏽‍💻 are still one each),
    runs of spaces made one, and cut to `max_len`."""
    text = unicodedata.normalize("NFKC", str(text or ""))
    words = (_word(word) for word in text.split())
    return " ".join(w for w in words if w)[:max_len].strip().rstrip(ZWJ)

def _holders(table, now=None) -> set[int]:
    """Seats that have had a move the table waits on for idle_after or more.
    Each seat's clock is its own (`_since`): someone else moving doesn't
    reset it. A timed buy doesn't count (the game's holds_up says so), as it
    closes anyway and naming who hasn't decided would give away who has passed."""
    if not table.state or table.status != Table.PLAYING:
        return set()
    rules = GAMES[table.game]
    now = time.time() if now is None else now
    since = table.state.get("_since", {})
    out = set()
    for s, kind, key in rules.deciding(table.state):
        if not _holds(rules, table.state, s, kind):
            continue
        mark = since.get(str(s))
        # A table saved before `_since` was kept goes by its last change.
        start = mark[1] if mark and mark[0] == _clock(rules, table.state, s, kind, key) else table.updated.timestamp()
        if now - start >= idle_after(rules):
            out.add(s)
    return out

def _regroup(table) -> None:
    """In a game that seats people together (engine.seating), people sit
    side by side, in the order they came, and bots fill the rest of the
    ring, until the host arranges the seats themselves."""
    _keep_teams(table)
    if seating(GAMES[table.game]) != "together" or _room(table).get("arranged"):
        return
    seats = list(table.seats.order_by("index"))
    _reorder(table, [s for s in seats if s.person] + [s for s in seats if not s.person])

def _start(table: Table) -> None:
    rules = GAMES[table.game]
    _regroup(table)
    n = table.seats.count()
    if not rules.min_players <= n <= rules.max_players:
        raise Illegal(f"This game needs {rules.min_players} to {rules.max_players} players.")
    now = time.time()
    seed = secrets.token_hex(8)
    # The rules are told which seats bots are playing (a game where bots
    # don't do everything people do needs to know), and given whatever
    # they asked to read before the deal (the IO edge, below).
    settings = {**(table.options or {}), "_bots": sorted(s.index for s in table.seats.all() if s.bot)}
    sides = teams_by_seat(table)
    if sides is not None:
        settings["_teams"] = sides
        settings["_team_names"] = team_names(table)
    # A game may leave a little for its next game at the same table (its
    # state's "_carry": questions it has asked, say), handed over as "_before".
    carry = (table.state or {}).get("_carry") if table.state else None
    carry = carry if carry is not None else _room(table).get("carry")
    if carry is not None:
        settings["_before"] = carry
    prepare = getattr(rules, "prepare", None)
    if prepare:
        try:
            settings["_data"] = prepare(seed, settings)
        except Exception:
            # (The rules deal without it: a game's data is a nicety, never a gate.)
            logger.exception("Couldn't prepare a %s game", table.game)
    table.state = rules.new(n, seed, now, settings)
    table.status = Table.PLAYING
    _room(table).pop("round", None)
    table.room.pop("left", None)
    # A new game: covered only if a bot's still playing for someone who left.
    table.seats.update(covered=False)
    table.seats.exclude(token="").exclude(bot="").update(covered=True)
    _advance(table, now)
    _bump(table)

def play(code: str, secret, action: dict) -> None:
    with transaction.atomic():
        table = _locked(code)
        me = seat_for(table, secret)
        if not me:
            raise Illegal("You're not at this table.")
        if table.status != Table.PLAYING:
            raise Illegal("The game isn't on.")
        if me.bot:
            raise Illegal("A bot is playing for you. Take your seat back first.")
        if me.index in (table.room or {}).get("left", []):
            raise Illegal("You left this game. Come back in first.")
        if isinstance(action, dict) and "host" in action:
            # (The host's moves come through host(…, "move"), which says so.)
            raise Illegal("That isn't a move in this game.")
        rules = GAMES[table.game]
        now = time.time()
        _advance(table, now)
        rules.act(table.state, me.index, action, now)
        me.seen = now
        me.save(update_fields=["seen"])
        _advance(table, now)
        _bump(table)
    notify.publish(code)

def tick(code: str) -> bool:
    """Let time pass at a table whose timer is due. True if anything moved."""
    with transaction.atomic():
        try:
            table = Table.objects.select_for_update().get(code=code)
        except Table.DoesNotExist:
            return False
        if table.status != Table.PLAYING or table.wake_at is None or table.wake_at > time.time():
            return False
        # What anyone could see is marked by these three (tables.engine): a
        # bot's wait or an idle clock moving on is kept, but isn't news.
        # (Someone sitting in at a new round changes the seats: news too.)
        seen = lambda: (table.state.get("seq"), table.state.get("phase"), table.state.get("logged"), len((table.room or {}).get("waiting", [])))
        before = seen()
        _advance(table, time.time())
        changed = before != seen()
        if changed:
            _bump(table)
        else:
            # Nothing anyone can see moved: keep the next wake (and the
            # state's own clocks) without a new version or a new `updated`.
            out = _take_out(table)
            table.save(update_fields=["wake_at", "state", "room"] if out else ["wake_at", "state"])
            _spill(table.game, out)
    if changed:
        notify.publish(code)
    return changed

def _advance(table: Table, now: float) -> None:
    rules = GAMES[table.game]
    seats = list(table.seats.all())
    bots = {s.index: s.bot for s in seats if s.bot}
    left = set((table.room or {}).get("left", []))
    people = [s for s in seats if s.person and not s.bot and s.index not in left]
    # Whatever can be decided for someone who's away (passing on a buy) is,
    # so they don't hold up everyone else.
    # (A game may count someone away sooner than the room does: away_after.)
    after = getattr(rules, "away_after", ONLINE)
    gone = [s.index for s in people if s.seen is None or now - s.seen >= after] if hasattr(rules, "away") else []
    wake = advance(rules, table.state, bots, now, random.Random(), away=gone)
    # Nothing else may be due (the upcard has no timer), so wake when someone
    # who owes a decision would count as away. Each is still in the future:
    # anyone already gone was just decided for.
    due = getattr(rules, "away_due", None)
    if due and not rules.over(table.state):
        wakes = [s.seen + after for s in people if s.index not in gone and due(table.state, s.index)]
        wake = min([w for w in (wake, *wakes) if w is not None], default=None)
    table.wake_at = wake
    _track(rules, table.state, now)
    _sit_in_at_new_round(table, rules)
    if rules.over(table.state):
        if table.status != Table.OVER:
            # Counted here, not in a view: a bot's move can end the game too.
            # The count stays anonymous; the game is kept only for the
            # signed-in players at it (docs/adr/0010).
            Event.objects.create(kind="table_finished", game=table.game, mode="solo" if table.solo else "together")
            table.state.setdefault("_finished", now)
            history.record(table)
        table.status = Table.OVER
        table.wake_at = None

def _bump(table: Table) -> None:
    table.version += 1
    fresh = []
    if table.state:
        # Move the game's new events into the table's log.
        last = table.state.get("_logged", 0)
        fresh = [e for e in table.state.get("events", []) if e["id"] > last]
        if fresh:
            table.state["_logged"] = fresh[-1]["id"]
    out = _take_out(table)
    table.save()
    Entry.objects.bulk_create(
        [Entry(table=table, game=table.games_played, n=e["id"], data=e) for e in fresh], ignore_conflicts=True)
    _spill(table.game, out)

def _op_move(table, me, action=None):
    """A move only the host may make (a party game's pause, say): the
    game's own `act`, told it's the host's by `"host": True` (engine.Game).
    The host's seat makes it, even with a bot playing for them."""
    if table.status != Table.PLAYING:
        raise Illegal("The game isn't on.")
    if not isinstance(action, dict):
        raise Illegal("That move didn't make sense.")
    if me.bot:
        raise Illegal("A bot is playing for you. Take your seat back first.")
    rules = GAMES[table.game]
    now = time.time()
    _advance(table, now)
    rules.act(table.state, me.index, {**action, "host": True}, now)
    _advance(table, now)

def _heir(table, host: Seat, seats=None) -> Seat | None:
    """Who hosting passes to when the host leaves or goes quiet: the person
    at the table seen most recently, whether or not a bot is covering their
    seat (but not anyone who's left the game). One rule for both."""
    left = set((table.room or {}).get("left", []))
    seats = table.seats.all() if seats is None else seats
    people = [s for s in seats if s.person and s.pk != host.pk and s.index not in left]
    return max(people, key=lambda s: (s.seen or 0, -s.index), default=None)

def _pass_host(table_id: int) -> bool:
    """The host has been away HOST_AWAY (a closed tab, a phone gone to
    sleep, without pressing Leave): hosting passes to whoever's at the table
    (`_heir`), so the table never freezes on them. They don't get it back by
    returning. True if it passed."""
    if not Seat.objects.filter(_host_gone(), table_id=table_id).exists():
        return False
    with transaction.atomic():
        table = Table.objects.select_for_update().filter(pk=table_id).first()
        if not table or table.status == Table.CLOSED or table.solo:
            return False
        # (Looked at again under the lock: someone else's check-in may have passed it.)
        host = table.seats.filter(_host_gone()).first()
        heir = host and _heir(table, host)
        if not heir or heir.seen is None or time.time() - heir.seen >= ONLINE:
            return False
        host.host, heir.host = False, True
        host.save(update_fields=["host"])
        heir.save(update_fields=["host"])
        _bump(table)
    return True

def watch(table: Table, key: str) -> None:
    """A browser without a seat is watching. Written down at most every
    WATCH_EVERY seconds; a new watcher is news (the count shows)."""
    if not key:
        return
    now = time.time()
    seen = (table.room or {}).get("watching", {}).get(key)
    if seen and now - seen < WATCH_EVERY:
        return
    with transaction.atomic():
        locked = Table.objects.select_for_update().filter(pk=table.pk).first()
        if not locked:
            return
        seen = _room(locked).setdefault("watching", {})
        new = key not in seen or now - seen[key] >= ONLINE
        seen[key] = now
        for gone in [k for k, at in seen.items() if now - at >= ONLINE]:
            del seen[gone]
        for extra in sorted(seen, key=seen.get)[:-WATCHERS_KEPT]:
            del seen[extra]
        locked.save(update_fields=["room"])
    table.room = locked.room
    if new:
        notify.publish(table.code)

def reserve(code: str, name) -> tuple[Table, str]:
    """Hold a place at a table's next game for someone who arrived late.
    They watch until then; the place is a seat when the host plays again
    (or a bot's seat at the next round, in a game that allows it)."""
    with transaction.atomic():
        table = _locked(code)
        rules = GAMES[table.game]
        if table.status == Table.CLOSED:
            raise Illegal("That table has closed.")
        if table.solo:
            raise Illegal("That's a game against bots. Start a table of your own.")
        if table.status == Table.LOBBY and table.seats.count() < rules.max_players:
            raise Illegal("There's a seat free: take it.")
        name = clean_name(name)
        waiting = _room(table).setdefault("waiting", [])
        if table.seats.exclude(token="").count() + len(waiting) >= rules.max_players:
            raise Illegal("There's no place left at the next game.")
        secret = secrets.token_urlsafe(24)
        waiting.append({"name": _unique(table, name, waiting=True), "token": digest(secret), "at": time.time()})
        _bump(table)
    notify.publish(code)
    return table, secret

def _sit_in_at_new_round(table: Table, rules) -> None:
    """A game with `round_no` lets someone waiting to sit in take a bot's
    seat as a new round starts (the bot's score goes with it)."""
    round_no = getattr(rules, "round_no", None)
    if round_no is None or rules.over(table.state):
        return
    room = _room(table)
    now = round_no(table.state)
    if room.get("waiting") and room.get("round") is not None and now != room["round"]:
        for seat in _seat_waiting(table, bots_only=True):
            _note(table, seat, "sit_in")
    room["round"] = now

def snapshot(table: Table, seat: Seat | None, secret=None) -> dict:
    """The table as this seat sees it; None is a spectator, who sees only
    what's public. `secret`, for a browser without a seat: whether it's
    holding a place at the next game."""
    rules = GAMES[table.game]
    now = time.time()
    seats = list(table.seats.all())
    # Who's holding up the table: a decision they've sat on for a minute.
    waiting = _holders(table, now)
    shown = {s.index: _presence(s, now, waiting) for s in seats}
    left = set((table.room or {}).get("left", []))
    sides = _sides(table) if table.status in (Table.LOBBY,) else None
    return {
        "table": {
            "code": table.code, "game": table.game, "status": table.status, "solo": table.solo, "version": table.version,
            "game_no": table.games_played, "ended": bool(table.state and table.state.get("ended")),
            "min": rules.min_players, "max": rules.max_players, "options": table.options,
            # Whether bots can sit here at all (engine.has_bots; docs/adr/0031).
            "bots": has_bots(rules),
            # What a game in teams calls them (the host may rename them).
            **({"team_names": team_names(table)} if getattr(rules, "teams", None) else {}),
            # Whether the host has seated everyone themselves.
            "arranged": bool((table.room or {}).get("arranged")),
            "seats": [{
                "index": s.index, "name": s.name, "bot": s.bot, "person": s.person, "host": s.host,
                **({"team": sides[s.pk]} if sides else {}),
                "online": shown[s.index][0], "holding": shown[s.index][1],
                # Left the game (a bot plays for them), rather than just away;
                # picks missed in a row (tables.commit).
                "left": s.index in left, "missed": commit.missed(table.state, s.index),
                # Whose seat this was, if it was handed to someone sitting in this game.
                "took": (table.room or {}).get("handed", {}).get(str(s.index)),
            } for s in seats],
            "you": seat.index if seat else None,
            "host": bool(seat and seat.host),
            # Who'd host if the host left now (_heir), for the host's Leave.
            **({"heir": getattr(_heir(table, seat, seats), "index", None)} if seat and seat.host else {}),
            # Whether this seat's game goes in an account's history, and,
            # once it has, the result's shareable page (docs/adr/0010).
            "linked": bool(seat and seat.user_id),
            "result": _result_url(table) if seat and table.status == Table.OVER else None,
            # What the game did to this seat's rating, once kept: this seat's
            # own, so only its view says it (docs/ratings.md).
            "rating": _rating(table, seat) if seat and seat.user_id and table.status == Table.OVER else None,
            # How it came out, once it's over (public then), in the game's
            # own words (engine.terms): for the room's share.
            "standings": _standings(table, rules),
            "terms": terms(rules),
            # Browsers without a seat (a count, no more), and who's waiting
            # to sit in at the next game; `reserved`: this browser is.
            "watching": watching(table, now),
            "waiting": [w["name"] for w in (table.room or {}).get("waiting", [])],
            "reserved": bool(not seat and waiting_for(table, secret)),
            # The secret sent holds nothing here (any more): a place given
            # up, or a seat removed, so the browser can forget it.
            "lost": bool(secret and not seat and not waiting_for(table, secret)),
            # ... because it was taken on another device (the player's account).
            "moved": bool(not seat and moved(table, secret)),
        },
        "game": rules.view(table.state, seat.index if seat else None) if table.state else None,
        "now": now,
    }

class Table(models.Model):
    # CLOSED: the host closed it before dealing; nothing more happens there.
    LOBBY, PLAYING, OVER, CLOSED = "lobby", "playing", "over", "closed"

    code = models.CharField(max_length=CODE_LENGTH, unique=True)
    game = models.CharField(max_length=40)
    status = models.CharField(max_length=10, default=LOBBY)
    solo = models.BooleanField(default=False, help_text="One person against bots.")
    options = models.JSONField(default=dict, blank=True, help_text="The table's settings, like how long buying stays open.")
    state = models.JSONField(null=True, blank=True)
    version = models.PositiveIntegerField(default=0, help_text="Goes up with every change, so browsers know when to redraw.")
    wake_at = models.FloatField(null=True, blank=True, help_text="When a timer or bot is next due (Unix time).")
    games_played = models.PositiveIntegerField(default=0)
    # What the service keeps about the room beyond the game (tables.service):
    # who's watching (counted, never named), who's waiting to sit in at the
    # next game, seats moved to another device, the host's own seating. Null
    # until there's something to keep, so code from before it can still
    # make tables while a deploy rolls out.
    room = models.JSONField(null=True, blank=True, help_text="Spectators, people waiting to sit in, moved seats.")
    created = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True, db_index=True)

    class Meta:
        ordering = ["-updated"]

    def __str__(self):
        return f"{self.game} {self.code} ({self.status})"

urlpatterns = [
    path("", views.create, name="create"),
    path("house-rules/", views.house_rules, name="house_rules"),
    path("<str:code>/", views.state, name="state"),
    path("<str:code>/join/", views.join, name="join"),
    path("<str:code>/reserve/", views.reserve, name="reserve"),
    path("<str:code>/act/", views.act, name="act"),
    path("<str:code>/arrange/", views.arrange, name="arrange"),
    path("<str:code>/log/", views.log, name="log"),
    path("<str:code>/host/", views.host, name="host"),
    path("<str:code>/link/", views.link, name="link"),
    path("<str:code>/take/", views.take, name="take"),
    path("<str:code>/say/", views.say, name="say"),
    path("<str:code>/talk/", views.talk, name="talk"),
    path("<str:code>/stream/", views.stream, name="stream"),
]

def _secret(request):
    return request.headers.get("X-Seat", "")

async def stream(request, slug, code):
    """Server-sent events: the table's snapshot each time it changes. A
    fetch() stream, not EventSource, so it can carry the X-Seat header."""
    _game(slug)
    code = str(code).upper()
    secret = _secret(request)
    watch = _watch(request)
    # What's been said that this browser has heard (?talk=n): none given,
    # it hears from now on.
    heard = _after(request)
    # Listen before the first look, so a change in between isn't missed.
    queue = notify.subscribe(code)
    try:
        first = await _look(slug, code, secret, True, watch=watch, heard=heard)
    except BaseException:
        notify.unsubscribe(code, queue)
        raise
    if first[0] is None:
        notify.unsubscribe(code, queue)
        raise Http404("No such table")

    async def events():
        try:
            shown, snap, wake, said = first
            yield f"data: {json.dumps(snap)}\n\n"
            heard = said["n"]
            if said["said"]:
                yield f"event: talk\ndata: {json.dumps(said)}\n\n"
            started = last_check_in = time.time()
            while time.time() - started < STREAM_LIFE:
                wait = KEEPALIVE if wake is None else max(0.05, min(KEEPALIVE, wake - time.time() + 0.02))
                try:
                    await asyncio.wait_for(queue.get(), wait)
                except TimeoutError:
                    pass
                check_in = time.time() - last_check_in > KEEPALIVE
                if check_in:
                    last_check_in = time.time()
                try:
                    seen, snap, wake, said = await _look(slug, code, secret, check_in, known=shown, watch=watch, heard=heard)
                except DatabaseError:
                    logger.exception("Couldn't read table %s; trying again", code)
                    await asyncio.sleep(1)
                    continue
                if seen is None:
                    return
                if said["said"]:
                    yield f"event: talk\ndata: {json.dumps(said)}\n\n"
                heard = said["n"]
                if seen != shown:
                    shown = seen
                    yield f"data: {json.dumps(snap)}\n\n"
                elif not said["said"]:
                    yield ": still here\n\n"
        finally:
            notify.unsubscribe(code, queue)

    response = StreamingHttpResponse(events(), content_type="text/event-stream")
    response["Cache-Control"] = "no-cache"
    response["X-Accel-Buffering"] = "no"
    return response

@sync_to_async
def _look(slug, code, secret, check_in, known=None, watch="", heard=None):
    """Check in, tick if due, then this seat's snapshot and when to look again.

    Returns (what's shown, snapshot, wake time, talk). "What's shown" is
    service.presence: the table's version plus who's at the table and who's
    holding it up, so someone leaving, coming back or going quiet is news
    even though nothing in the game moved. When it's still `known`, there's
    nothing to tell, and the table isn't drawn (snapshot None): a keepalive
    on a quiet table costs a couple of queries, not a view. "Talk" is
    what's been said since line `heard` (tables.talk), told apart from the
    table, so an emote never redraws it."""
    try:
        table = Table.objects.filter(game=slug, code=code).first()
        if not table:
            return None, None, None, None
        # Check in first: arriving mustn't count as having been away.
        seat = service.seat_for(table, secret)
        if seat and check_in:
            service.check_in(seat)
        elif not seat and check_in:
            service.watch(table, service.watch_key(table, secret, watch))
        if table.wake_at and table.wake_at <= time.time() and service.tick(code):
            table.refresh_from_db()
        shown = service.presence(table)
        said = talking.since(table, heard)
        if known is not None and shown == known:
            return shown, None, table.wake_at, said
        return shown, service.snapshot(table, seat, secret), table.wake_at, said
    finally:
        # A stream lasts minutes; holding a connection that long for every
        # open tab would use up a small database's allowance.
        connection.close()

def publish(code: str) -> None:
    """Call after the change is committed."""
    _deliver(code)
    if connection.vendor == "postgresql":
        try:
            with connection.cursor() as cursor:
                cursor.execute("SELECT pg_notify(%s, %s)", [CHANNEL, code])
        except Exception:
            log.exception("Couldn't announce a change to table %s", code)

def _listen_forever() -> None:
    import time

    import psycopg

    keys = ("dbname", "user", "password", "host", "port", "sslmode")
    params = {k: v for k, v in connection.get_connection_params().items() if k in keys and v}
    # TCP keepalives, and a query every half minute, so a connection that's
    # silently gone is noticed and replaced rather than listened to forever.
    params.update(keepalives=1, keepalives_idle=30, keepalives_interval=10, keepalives_count=3)
    while True:
        try:
            with psycopg.connect(**params, autocommit=True) as conn:
                conn.execute(f"LISTEN {CHANNEL}")
                while True:
                    for note in conn.notifies(timeout=30):
                        _deliver(note.payload)
                    conn.execute("SELECT 1")
        except Exception:
            log.exception("Table notifications dropped; reconnecting")
            time.sleep(2)

def say(code: str, seat, kind: str, what) -> dict:
    """Seat `seat` says something: kind "emote" (one of EMOTES) or "chat"
    (a line, cleaned). Returns what was said, as browsers get it."""
    if seat is None or not seat.person:
        raise Illegal("Take a seat to say something.")
    if kind == "emote":
        if not isinstance(what, str) or what not in EMOTES:
            raise Illegal("That isn't one of the emotes.")
        text = what
    elif kind == "chat":
        # (Only words: anything else would be shown as Python wrote it.)
        if not isinstance(what, str):
            raise Illegal("Type something to send.")
        text = clean(what, CHAT_LEN)
        if not text:
            raise Illegal("Type something to send.")
    else:
        raise Illegal("That request didn't make sense.")
    now = time.time()
    with transaction.atomic():
        table = Table.objects.select_for_update().filter(pk=seat.table_id).first()
        if table is None:
            raise Illegal("There’s no table with that code.")
        if table.status == Table.CLOSED:
            raise Illegal("That table has closed.")
        if seat.index in (table.room or {}).get("left", []):
            # Gone from the game (they pressed Leave): gone from its talk too.
            raise Illegal("You've left this game.")
        # (options() never turns it on in a game that doesn't offer it.)
        if kind == "chat" and not (table.options or {}).get("chat"):
            raise Illegal("Chat is off at this table.")
        talk = _talk(table)
        by = talk["by"].setdefault(f"{kind[0]}{seat.index}", [])
        by[:] = _within(by, SEAT_EMOTES if kind == "emote" else SEAT_CHAT, now)
        if len(by) >= (SEAT_EMOTES if kind == "emote" else SEAT_CHAT)[0]:
            raise TooFast("Slow down a moment.")
        if kind == "emote":
            recent = [s for s in talk["said"] if s["kind"] == "emote" and now - s["at"] < TABLE_EMOTES[1]]
            if len(recent) >= TABLE_EMOTES[0]:
                raise TooFast("Slow down a moment.")
        by.append(now)
        talk["n"] += 1
        line = {"n": talk["n"], "at": now, "kind": kind, "seat": seat.index, "name": seat.name, "text": text}
        talk["said"].append(line)
        _prune(talk, now)
        table.save(update_fields=["room", "updated"])
    notify.publish(table.code)
    return line