Files
coder/coderd/x/chatd/chatstate/machine.go
T
Callum Styan d412c38afb perf: validate chat transitions from the locked row (#30886)
One of the main costs in terms of DB load from chats is extra round
trips during transactions. This results in locks being held for longer
periods of time -> an increase in lock waits for chats related queries.

One of the opportunities for reducing some of the round trips is to
eliminate extra chat row reads after we have just read the row in order
to lock it.

In this PR `ChatMachine.Update` now seeds the transaction struct with
the row returned by `LockChatAndBumpSnapshotVersion`, plus a queue count
taken right after it. We can then pass it into `Update` as an optional
parameter validate against it, so neither re-reads the chat row from the
database while the row lock is held.

`updateChat` (send, edit, promote, tool results, interrupt, compact,
clear, reconcile), hook failure, family archive, and the worker's
generation and task transitions use it instead of reloading the chat
under the lock.

This PR relative to main:
|measurement | main | this PR | percent change |
|-- | -- | -- | -- |
| Round trips under lock  | 180.9 | 142.0 | -39% |
| Statements under lock  | 86.1 | 66.6 | -23% |
| GetChatByID under lock | 54.1 | 35.8 | -34% |
| GetChatByID total | 75.5 | 57.1 | -25% |
| Statements  | 235.8 | 216.2 | -8% |

Generated by Coder Agents on behalf of @cstyan.
2026-11-13 09:59:39 -07:00

330 lines
12 KiB
Go

package chatstate
import (
"context"
"database/sql"
"errors"
"github.com/google/uuid"
"golang.org/x/xerrors"
"github.com/coder/coder/v2/coderd/database"
coderdpubsub "github.com/coder/coder/v2/coderd/pubsub"
)
// HeartbeatStaleSeconds is the threshold chatstate uses when deciding
// whether to publish a `chat:ownership` hint for a runnable chat. A
// heartbeat older than this many seconds (by database time) counts
// as stale and triggers a hint so an idle worker can attempt a
// takeover.
const HeartbeatStaleSeconds = 30
// ChatMachine is a chat-scoped handle for state-machine operations on
// a single chat row. It captures the database store, the pubsub
// publisher, and the chat ID at construction time so callers do not
// have to thread them through Update, Lock, or any transition method.
//
// ChatMachine values are cheap. Create one per chat for the lifetime
// of a request or worker turn; do not cache mutable chat state across
// calls.
type ChatMachine struct {
store database.Store
publisher Publisher
chatID uuid.UUID
}
// NewChatMachine constructs a chat-scoped state machine handle. The
// store may be the root database handle or an existing transaction
// handle; publisher is the pubsub used for `chat:update` and
// `chat:ownership` emissions. Both are required and captured for the
// lifetime of the returned machine.
func NewChatMachine(
store database.Store,
publisher Publisher,
chatID uuid.UUID,
) *ChatMachine {
return &ChatMachine{
store: store,
publisher: publisher,
chatID: chatID,
}
}
// Tx is the per-transaction handle passed to [ChatMachine.Update]
// callbacks. A transition validates against its input's Snapshot when
// set and reads the chat otherwise.
type Tx struct {
ctx context.Context
store database.Store
chatID uuid.UUID
}
// ChatSnapshot is the locked chat row and its queue state, read by
// Update before the callback runs. It is used as a performance
// optimization to avoid refetching the chat row at the beginning of a
// transition.
//
// The chat row is never refreshed and should only be passed to a
// callback's first transition, and only if nothing has written the chat
// or its queue beforehand.
type ChatSnapshot struct {
Chat database.Chat
Queue QueueState
}
// State classifies the snapshot's execution state.
func (s *ChatSnapshot) State() ExecutionState {
return ClassifyExecutionState(s.Chat, s.Queue, true)
}
// Ctx returns the context the surrounding [ChatMachine.Update] call
// is using.
func (tx *Tx) Ctx() context.Context { return tx.ctx }
// ChatID returns the chat ID this transaction is scoped to.
func (tx *Tx) ChatID() uuid.UUID { return tx.chatID }
// Store exposes the active transaction store so callers can perform
// validation reads (for example loading the messages affected by an
// EditMessage transition) and metadata writes (for example updating
// title or labels) that must be atomic with the transition.
//
// Callers MUST NOT use Store to mutate execution-state tables
// (chats.status, chat_messages, chat_queued_messages, chat_heartbeats,
// or the version fields on chats). Those mutations belong to the
// transition methods and are validated against the state machine
// matrix.
func (tx *Tx) Store() database.Store { return tx.store }
func (tx *Tx) loadState(snapshot *ChatSnapshot) (database.Chat, ExecutionState, error) {
if snapshot != nil {
return snapshot.Chat, snapshot.State(), nil
}
return tx.readState()
}
func (tx *Tx) queueState(snapshot *ChatSnapshot) (QueueState, error) {
if snapshot != nil {
return snapshot.Queue, nil
}
queue, err := LoadQueueState(tx.ctx, tx.store, tx.chatID)
if err != nil {
return QueueState{}, xerrors.Errorf("load queue state: %w", err)
}
return queue, nil
}
// readState returns ErrChatNotFound if the chat row was deleted in
// this transaction (or never existed).
func (tx *Tx) readState() (database.Chat, ExecutionState, error) {
chat, err := tx.store.GetChatByID(tx.ctx, tx.chatID)
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
return database.Chat{}, StateN, ErrChatNotFound
}
return database.Chat{}, "", xerrors.Errorf("load chat: %w", err)
}
queue, err := LoadQueueState(tx.ctx, tx.store, tx.chatID)
if err != nil {
return database.Chat{}, "", xerrors.Errorf("load queue state: %w", err)
}
return chat, ClassifyExecutionState(chat, queue, true), nil
}
// requireFromAllowed validates t against the transition matrix from
// snapshot, or from a fresh read when snapshot is nil. Returns that
// chat and execution state on success, [ErrInvalidState] when the chat
// is in an invalid state and t is not
// [TransitionReconcileInvalidState], and a typed *TransitionError
// otherwise.
func (tx *Tx) requireFromAllowed(t Transition, snapshot *ChatSnapshot) (database.Chat, ExecutionState, error) {
chat, from, err := tx.loadState(snapshot)
if err != nil {
return chat, from, err
}
if from == StateInvalid && t != TransitionReconcileInvalidState {
return chat, from, ErrInvalidState
}
if err := requireExecutionTransition(t, from); err != nil {
return chat, from, err
}
return chat, from, nil
}
// Update applies one or more transitions to the machine's chat.
//
// Update opens a transaction on the captured store, atomically locks
// the chat row with FOR UPDATE and increments `snapshot_version`
// exactly once, then runs fn against a fresh [*Tx], the active
// transaction store, and a [ChatSnapshot] of the locked row. The
// snapshot is never nil. It constructs a [PublishBuffer], enqueues
// `chat:update` (and a `chat:ownership` hint
// when the post-transition state is worker-runnable and ownership is
// missing or stale) inside the transaction, and flushes the buffer only after
// the transaction function succeeds. If the transaction rolls back,
// the deferred Discard suppresses every buffered publication so
// subscribers never see uncommitted state.
//
// If Update is called with a store that is already in a transaction,
// [database.Store.InTx] reuses the active transaction. In that case,
// callers that need outer-transaction publication semantics can pass a
// [PublishBuffer] as the machine publisher. The inner buffer flushes
// into the outer buffer, and the outer owner remains responsible for
// publishing only after the outer transaction commits.
//
// If the chat row does not exist, Update returns [ErrChatNotFound]
// without mutating anything.
//
// Callbacks that return an error roll back the transaction (rolling
// back the automatic snapshot bump) and publish nothing.
//
// Update returns the chat row it reads after fn for publication, so
// callers do not read it again under the lock. The row is zero if fn or
// that read failed. If a later step fails, including the commit and the
// publication after it, Update returns the row with the error whether
// or not the transaction committed, so a caller can compare it with a
// fresh read to tell whether it did.
func (m *ChatMachine) Update(
ctx context.Context,
fn func(*Tx, database.Store, *ChatSnapshot) error,
) (database.Chat, error) {
if m.store == nil {
return database.Chat{}, xerrors.New("chatstate: ChatMachine has nil store")
}
if m.publisher == nil {
return database.Chat{}, xerrors.New("chatstate: ChatMachine has nil publisher")
}
buffer := NewPublishBuffer(m.publisher)
defer buffer.Discard()
var updated database.Chat
err := m.store.InTx(func(store database.Store) error {
locked, err := store.LockChatAndBumpSnapshotVersion(ctx, m.chatID)
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
return ErrChatNotFound
}
return xerrors.Errorf("lock chat and bump snapshot: %w", err)
}
queue, err := LoadQueueState(ctx, store, m.chatID)
if err != nil {
return xerrors.Errorf("load queue state: %w", err)
}
tx := &Tx{
ctx: ctx,
store: store,
chatID: m.chatID,
}
if err := fn(tx, store, &ChatSnapshot{Chat: locked, Queue: queue}); err != nil {
return err
}
// The callback may have written the chat, so publish a fresh read.
chat, state, err := tx.readState()
if err != nil {
return err
}
updated = chat
if err := buffer.Publish(
coderdpubsub.ChatStateUpdateChannel(chat.ID),
buildChatUpdateMessage(chat),
); err != nil {
return xerrors.Errorf("buffer chat update: %w", err)
}
if state.IsRunnable() {
stale, err := ownershipStaleOrMissing(ctx, store, chat, HeartbeatStaleSeconds)
if err != nil {
return xerrors.Errorf("evaluate ownership: %w", err)
}
if stale {
if err := buffer.Publish(
coderdpubsub.ChatStateOwnershipChannel,
buildChatOwnershipMessage(chat),
); err != nil {
return xerrors.Errorf("buffer ownership hint: %w", err)
}
}
}
return nil
}, nil)
if err != nil {
return updated, err
}
return updated, buffer.Flush()
}
// Lock locks the chat row with FOR UPDATE and runs fn in a
// transaction without advancing snapshot_version. It uses the store
// captured by [NewChatMachine]. Use it when the caller needs a
// consistent chat snapshot plus related rows such as messages or
// queued messages but is NOT applying a transition.
//
// Callers must not pass a store here; it belongs on the machine.
//
// Lock publishes nothing. Callback errors roll back the transaction
// and propagate to the caller.
func (m *ChatMachine) Lock(
ctx context.Context,
fn func(database.Store) error,
) error {
if m.store == nil {
return xerrors.New("chatstate: ChatMachine has nil store")
}
return m.store.InTx(func(store database.Store) error {
// GetChatByIDForUpdate locks the row WITHOUT bumping snapshot.
_, err := store.GetChatByIDForUpdate(ctx, m.chatID)
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
return ErrChatNotFound
}
return xerrors.Errorf("lock chat: %w", err)
}
return fn(store)
}, nil)
}
// ReadSnapshot runs fn in a read-only REPEATABLE READ transaction without
// advancing snapshot_version. It uses the store captured by
// [NewChatMachine]. Use it when the caller needs a consistent chat
// snapshot plus related rows such as messages or queued messages but is
// NOT applying a transition.
//
// Snapshot isolation gives fn a consistent multi-statement view without
// taking any row lock, so it never blocks (or is blocked by) the FOR
// UPDATE writers in [ChatMachine.Update] and [ChatMachine.Lock]. A
// transition committing mid-read is simply not visible to this snapshot;
// callers reconcile ordering via snapshot_version, so an older snapshot
// triggers a later refetch rather than an inconsistent read.
//
// ReadSnapshot does not check that the chat exists; fn's own reads report
// a missing chat as sql.ErrNoRows.
//
// Callers must not pass a store here; it belongs on the machine.
//
// ReadSnapshot publishes nothing. Callback errors roll back the
// transaction and propagate to the caller.
func (m *ChatMachine) ReadSnapshot(fn func(database.Store) error) error {
if m.store == nil {
return xerrors.New("chatstate: ChatMachine has nil store")
}
return m.store.InTx(fn, &database.TxOptions{
Isolation: sql.LevelRepeatableRead,
ReadOnly: true,
})
}
// ownershipStaleOrMissing reports whether the chat's current
// (chat_id, runner_id) lease is missing or stale. The staleSeconds
// threshold is forwarded to [database.IsChatHeartbeatStale] so the
// comparison runs against database time inside a single SQL query.
func ownershipStaleOrMissing(ctx context.Context, store database.Store, chat database.Chat, staleSeconds int32) (bool, error) {
if !chat.WorkerID.Valid || !chat.RunnerID.Valid {
return true, nil
}
return store.IsChatHeartbeatStale(ctx, database.IsChatHeartbeatStaleParams{
ChatID: chat.ID,
RunnerID: chat.RunnerID.UUID,
StaleSeconds: staleSeconds,
})
}