Row activity: developer guide¶

Show a spinner on the rows of a pkg/table, pkg/list or pkg/tree that are being worked on, whether the work was started by the user or by something else. The examples use a table; list and tree differ only in the row type and where the spinner draws.

  Name                     │ Sync           │ Health
  ──────────────────────────────────────────────────
▸ payments-metrics-00      │ ⣾ Running      │ Healthy
  search-web-01            │ OutOfSync      │ Degraded
  media-web-02             │ ⣽ Refreshing   │ Progressing
  media-gateway-03         │ Synced         │ Healthy

How it works¶

1. The server is the source of truth. A row spins when the data you fetched says work is running on it, and stops when the data says the work is over.
2. Work the user starts shows immediately. Between the keypress and the next poll, the data can't know yet. The table covers that gap with a claim: the row spins at once, and the claim ends when the truth can take over.

Everything below is one of those two, plus the plumbing that keeps them honest on a real network.

Step 1: show work the server reports¶

This is all a read-only dashboard needs.

type argoApp struct {
    ID, Name, Sync, Health, Phase string
    Rev                           int64
}

o := th.Table()
o.Columns = []table.Column{
    {Title: "Name", Flex: 1},
    {Title: "Sync", Width: 14},   // wide enough for "⣾ Refreshing"
    {Title: "Health", Width: 12},
}
o.ActivityColumn = "Sync"         // where the spinner draws
o.BusyWhen = func(r table.KeyedRow) (string, bool) {
    phase := r.Data.(argoApp).Phase
    return phase, phase == "Running"
}
s.table = table.New(o)

Fetch with a token taken when the request is issued, and apply the reply with ApplyRead:

type fetchedMsg struct {
    read activity.Read
    apps []argoApp
    err  error
}

func (s *Screen) fetch() tea.Cmd {
    rd := s.table.BeginRead()
    return func() tea.Msg {
        apps, err := s.client.ListApps()   // check the HTTP status in here
        return fetchedMsg{rd, apps, err}
    }
}

case fetchedMsg:
    rows := make([]table.KeyedRow, len(m.apps))
    for i, a := range m.apps {
        rows[i] = table.KeyedRow{Key: a.ID, Cells: []string{a.Name, a.Sync, a.Health}, Data: a}
    }
    wasFailing := s.table.ReadsFailing()
    if s.table.ApplyRead(m.read, rows, m.err) {
        s.poll.MarkRefreshed()           // only a read that landed counts
    } else if m.err != nil && !wasFailing {
        return s, app.ErrorOf(m.err)     // once, when reads start failing
    }

Drive fetch from a pkg/poll tick (rule 24). Report an outage once, when reads start failing, and let ReadsFailing() carry it on the title after that. Posting the error on every failed poll puts a fresh error on the statusbar every interval for as long as the server is down.

Choosing the field for BusyWhen. It has to be a field that says "working" while the work runs. It doesn't have to be a column: it's read from Data.

BusyWhen returns the status for every row, busy or not. The table shows it as the label while the row is busy, and compares it to notice when the server acted. activity.Busy("running", "pending") and activity.Settled("succeeded", "failed") build the common predicates.

Step 2: add verbs the user can run¶

For each verb, answer one question: who knows when the work ends?

Every verb has the same shape: Dispatch when the user picks it, and Done when the request answers.

Observed: a POST that answers at once¶

func (s *Screen) Actions() action.Set {
    keys := s.table.Selection()
    return action.Set{Targets: keys, Actions: []action.Action{
        // Multi: without it the menu disables the verb once a second row is
        // marked (action.Set.Arity is len(Targets)).
        {Label: "Sync", Multi: true, Do: func() tea.Cmd { return s.sync(keys) }},
    }}
}

type answeredMsg struct {
    op  activity.Op
    err error
}

func (s *Screen) sync(keys []string) tea.Cmd {
    // One operation per row: DispatchEach calls this once per key.
    return s.table.DispatchEach(keys, "Running", activity.Observed,
        func(op activity.Op, k string) tea.Cmd {
            return func() tea.Msg { return answeredMsg{op, s.client.Sync(k)} }   // 202 = nil error
        })
}

case answeredMsg:
    switch s.table.Done(m.op, m.err) {
    case activity.Withdrawn:     // refused: this row stops
        return s, app.ErrorOf(m.err)
    case activity.Acknowledged:  // accepted: still running, polls take over
        return s, app.Info("Sync requested")
    }
case activity.UnobservedMsg:
    return s, app.Info("Sync finished between polls")

Done tells you what the reply means. It returns activity.Acknowledged for an Observed verb (the work has only started, so say "requested"), activity.Ended for a Held one (the work is over), and activity.Withdrawn when the request failed. Switch on it. A reply handler shared by a sync and a refresh that says "completed" on every reply is wrong for the sync, and nothing else will tell you.

One operation per row. DispatchEach gives each row its own operation and its own request, so each gets its own Done. If one row's request is refused, only that row stops. One operation over the whole selection puts every row behind the first refusal; use Dispatch with several keys only when a single request acts on all of them.

A Do verb gets no receipt from the shell (Action.Receipt applies only to Run verbs), so post "requested" yourself, as above.

UnobservedMsg arrives through the table's Update, on the turn after the read that ended the claim. Forward every message to the table (rule 6) and match it in your Update. Its Label is the claim's label ("Running"), not the verb, so name the verb yourself: m.Label + " finished" reads "Running finished".

Claim with the server's own word ("Running"), so the row reads the same from the keypress to the poll that confirms it.

Held: a request that blocks until the work is done¶

func (s *Screen) refresh(keys []string) tea.Cmd {
    return s.table.DispatchEach(keys, "Refreshing", activity.Held,
        func(op activity.Op, k string) tea.Cmd {
            return func() tea.Msg { return refreshedMsg{op, s.client.Refresh(k)} }   // blocks ~2s
        })
}

case refreshedMsg:
    switch s.table.Done(m.op, m.err) {   // the spinner ends here, not at a poll
    case activity.Withdrawn:
        return s, app.ErrorOf(m.err)
    case activity.Ended:
        return s, s.poll.Refresh()       // show what the refresh found now
    }

Held: a job handle¶

The same as a blocking request. The command that follows the job only returns once the job has finished:

return tea.Batch(spin, func() tea.Msg {
    id, err := s.client.StartSync(key)
    if err == nil {
        err = s.client.WaitJob(id)   // poll GET /jobs/{id} until terminal
    }
    return jobDoneMsg{op, err}
})

The title during an outage¶

ReadsFailing() and poll.LastRefresh() answer different questions, so show both. "reads failing" says the rows can't be refreshed; "refreshed Ns ago" says how stale they are. The count comes from the last read that landed, so it keeps climbing through an outage, which is when the user needs it most.

func (s *Screen) titleText() string {
    title := "applications"
    if s.table.ReadsFailing() {
        title += " · reads failing"
    }
    if last := s.poll.LastRefresh(); !last.IsZero() {
        title += fmt.Sprintf(" · refreshed %ds ago", int(time.Since(last).Seconds()))
    }
    return title
}

Call SetTitle(s.titleText()) after every read and on a one-second tea.Tick, so N moves between polls.

Theme swaps¶

SetTheme rebuilds the table (rule 4), so carry the rows and the activity across it:

func (s *Screen) SetTheme(t theme.Theme) {
    rows, act := s.table.KeyedRows(), s.table.ActivityState()
    o := t.Table()
    // … the same options as before …
    s.table = table.New(o)
    s.table.SetKeyedRows(rows)         // rows first
    _ = s.table.SetActivityState(act)  // then the spinners that belong on them
}

SetActivityState returns the spinner's first tick, and SetTheme has nowhere to return it. Dropping it is safe: the table re-arms a stalled spinner on the next message it receives.

What the user sees¶

The table draws no outcome glyph (✓ / ✗). When the spinner stops, the cell shows the row's own value, which already says Failed in your app's colours.

Settings¶

Messages and methods¶

What the table does for you¶

You don't need to write any of this:

• Out-of-order replies. A reply overtaken by a newer one is dropped.
• Reads that race your own write. A poll issued before your POST answered is applied, but it can't end that POST's spinner. That's where the "row blinks off and back on" bug came from.
• Outages. A failed read ends claims that were waiting on a read, and marks observed work Unknown instead of leaving it animating.
• Refused requests. Done with an error stops the spinner at once.

What it can't do¶

• See work somebody else started and finished between two polls. With Revision set, the row's revision moves, but the table only reports that for operations you dispatched.
• Repair a read path that goes backwards. A replica or cache that answers busy, then settled, then busy again is telling the truth each time; no client-side ordering fixes that.
• Windowed tables. Under SetWindow rows have no keys, and activity is inert.

Troubleshooting¶

List and tree¶

The same methods, with the component's own row type:

o := th.List()
o.BusyWhen = func(it list.KeyedItem) (string, bool) {
    phase := it.Data.(argoApp).Phase
    return phase, phase == "Running"
}

o := th.Tree()
o.BusyWhen = func(n tree.Node) (string, bool) {
    app, ok := n.(appNode)   // your Node carries what the server reported
    return app.phase, ok && app.phase == "Running"
}

A tree evaluates every node, collapsed ones included, so expanding a branch reveals a spinner that is already turning.

Migrating from the first API¶

The first version of this feature had the screen keep the read ordering itself (generation counters, a count of outstanding writes, RetractAll on a failed read) and offered two entrances (ActivityWhen or SetBusy). All of that is gone. Screens written against it will not compile until they move over. Most moves are mechanical.

Call by call¶

New, with nothing to replace: Options.Revision, ReadsFailing(), activity.UnobservedMsg, KeyedRows() / KeyedItems() / Root(), and the Unknown state rows take on while reads fail.

Before and after¶

A polled table with one Sync verb. Before:

o.ActivityColumn = "Sync"
settled := activity.Settled("Synced", "OutOfSync")
o.ActivityWhen = func(c table.Row) (string, bool) { return settled(c[colSync]) }

case action.ChosenMsg:
    s.gen++; s.writing++
    s.claimed[action.RunKey(m.Action, m.Target)] = m.Targets
    cmds = append(cmds, s.table.Expect(m.Targets, "Syncing"))
case runner.Captured:
    s.writing--; s.gen++
    if m.Err != nil { s.table.Retract(s.claimed[m.Tag]...) }
case fetchedMsg:
    if m.gen < s.seen || s.writing > 0 { break }
    s.seen = m.gen
    if m.err != nil { s.table.RetractAll(); break }
    s.table.SetKeyedRows(rowsOf(m.apps))

After:

o.ActivityColumn = "Sync"
o.BusyWhen = func(r table.KeyedRow) (string, bool) {
    phase := r.Data.(argoApp).Phase           // what is busy while work runs
    return phase, phase == "Running"
}
o.Revision = func(r table.KeyedRow) string { return r.Data.(argoApp).FinishedAt }

// the verb: {Label: "Sync", Multi: true, Do: func() tea.Cmd { return s.sync(keys) }}
func (s *Screen) sync(keys []string) tea.Cmd {
    return s.table.DispatchEach(keys, "Running", activity.Observed,
        func(op activity.Op, k string) tea.Cmd {
            return func() tea.Msg { return answeredMsg{op, s.client.Sync(k)} }
        })
}

case answeredMsg:
    switch s.table.Done(m.op, m.err) {
    case activity.Withdrawn:    return s, app.ErrorOf(m.err)
    case activity.Acknowledged: return s, app.Info("Sync requested")
    }
case activity.UnobservedMsg:
    return s, app.Info("Sync finished between polls")
case fetchedMsg:
    wasFailing := s.table.ReadsFailing()
    if s.table.ApplyRead(m.read, rowsOf(m.apps), m.err) {
        s.poll.MarkRefreshed()
    } else if m.err != nil && !wasFailing {
        return s, app.ErrorOf(m.err)
    }

Check the predicate, not just the calls. If the old ActivityWhen watched a status that never says "working" while the work runs, such as Argo's sync.status, a mechanical port keeps the bug: no row will ever spin. Point BusyWhen at the field that is busy during the work (status.operationState.phase for Argo). See Step 1.

Examples¶

• examples/patterns/activityrecipes: one shape per tab (observe, sync, refresh, job handle), each small enough to copy.
• examples/patterns/activity: all of them on one screen, with marking and the output console.