Files
mesh-catalog/modules/messenger/cmd/messenger/holdback.go
T
jschoubben 6f7d070769 M1-M5: the router holds back the asker's oldest ask behind a fourth and offers it again when one ends; the seat operator-channel's ask-again offers it now (milestone 47/G, issue 1966)
Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW

ask-again is the seat operator-channel's verb (key in; state or error out), not the module tool messenger_ask_again, and records no hand act (G §394, §450).
(Joined from 681975ec.)
Builds: design 47 G §40, §83, §403 (RTR1, RTR2)

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
2026-11-11 14:48:07 +01:00

198 lines
6.3 KiB
Go

package main
import (
"fmt"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"sort"
"time"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
)
// An ask held back (novox/hq ADR 0666 §12, design 46 § 6): an asker has at most MostOpen asks offered at once; a fourth
// is offered and nothing is refused, so no ask is hidden: the asker's oldest offered ask is held back, its tickets
// withdrawn and its message edited to say it waits behind newer asks, and it is offered again, with new tickets, when
// one of the asker's offered asks ends. `held` is another state, an ask no ready channel can carry (ADR 0397).
// StateHeldBack is an ask kept open behind newer asks of its asker.
const StateHeldBack = "held-back"
// liveState is whether an ask has not ended: offered, held for want of a channel, or held back.
func liveState(state string) bool {
return state == StateOpen || state == StateHeld || state == StateHeldBack
}
// behindLocked are the keys of the newer offered asks of the asker of rec, oldest first; h.mu is held.
func (h *Holder) behindLocked(key string, rec AskRecord) []string {
var behind []string
for k, e := range h.asks {
if k != key && e.rec.Asker == rec.Asker && (e.rec.State == StateOpen || e.rec.State == StateHeld) && e.rec.Opened.After(rec.Opened) {
behind = append(behind, k)
}
}
sort.Slice(behind, func(i, j int) bool {
a, b := h.asks[behind[i]].rec, h.asks[behind[j]].rec
if !a.Opened.Equal(b.Opened) {
return a.Opened.Before(b.Opened)
}
return behind[i] < behind[j]
})
return behind
}
// pickLocked is the key of the asker's asks in one of the states, the oldest first (by opening, then key); "" when
// there is none, never except; h.mu is held.
func (h *Holder) pickLocked(asker, except string, states ...string) string {
pick := ""
for k, e := range h.asks {
if e.rec.Asker != asker || k == except {
continue
}
in := false
for _, s := range states {
in = in || e.rec.State == s
}
if !in {
continue
}
if pick == "" || e.rec.Opened.Before(h.asks[pick].rec.Opened) || (e.rec.Opened.Equal(h.asks[pick].rec.Opened) && k < pick) {
pick = k
}
}
return pick
}
// offeredCount is how many of the asker's asks are offered now: open, or held for want of a channel.
func (h *Holder) offeredCount(asker string) int {
h.mu.Lock()
defer h.mu.Unlock()
n := 0
for _, e := range h.asks {
if e.rec.Asker == asker && (e.rec.State == StateOpen || e.rec.State == StateHeld) {
n++
}
}
return n
}
// freshAsk is an ask's record read again from the store, where there is one.
func (h *Holder) freshAsk(key string) (AskRecord, uint64, bool) {
e := h.askOf(key)
if e == nil {
return AskRecord{}, 0, false
}
rec, rev := e.rec, e.rev
if h.Asks != nil {
if got, r, err := h.Asks.GetAsk(key); err == nil && got != nil {
rec, rev = *got, r
}
}
return rec, rev, true
}
// holdBackOldest holds back the asker's oldest offered ask other than except (the newest, just taken): its tickets
// are withdrawn, it stays open, and its own message is edited to say it waits. One held for want of a channel counts as offered
// and is held back the same way. The work lock is held.
func (h *Holder) holdBackOldest(asker, except string) {
h.mu.Lock()
key := h.pickLocked(asker, except, StateOpen, StateHeld)
h.mu.Unlock()
if key == "" {
return
}
rec, rev, ok := h.freshAsk(key)
if !ok || (rec.State != StateOpen && rec.State != StateHeld) {
return
}
now := h.Now()
rec.State, rec.HeldBackSince, rec.Tickets, rec.HeldSince, rec.HeldWhy = StateHeldBack, now, nil, time.Time{}, ""
if !h.saveHeld(key, rec, rev) {
return
}
h.Logf("[messenger] %s's ask %q (%s) is held back behind its newer asks: it is offered again when one ends", asker, rec.Ask.Headline, rec.Ask.ID)
h.mu.Lock()
r := h.open[rec.Record]
h.mu.Unlock()
if r == nil || r.Origin != "ask" {
return // a condition's message is the newer ask's to show
}
h.mu.Lock()
r.Answered = "Waits behind newer questions of " + asker + ".\nIt is offered again, with its answers, when one of them ends."
h.mu.Unlock()
h.edit(r, "answered", false)
h.persist(r)
}
// offerHeldBack offers the asker's oldest held-back ask again when a slot is free: new tickets, its message edited back
// to the question. The work lock is held.
func (h *Holder) offerHeldBack(asker string) {
if h.offeredCount(asker) >= occ.MostOpen {
return
}
h.mu.Lock()
key := h.pickLocked(asker, "", StateHeldBack)
h.mu.Unlock()
if key != "" {
h.offerOneHeldBack(key)
}
}
// offerOneHeldBack offers one held-back ask again now.
func (h *Holder) offerOneHeldBack(key string) {
rec, rev, ok := h.freshAsk(key)
if !ok || rec.State != StateHeldBack {
return
}
now := h.Now()
rec.HeldBackSince = time.Time{}
rec.Tickets = h.ticketsFor(rec.Ask)
rec.State = StateOpen
if len(rec.Tickets) == 0 {
rec.Tickets, rec.State, rec.HeldSince, rec.HeldWhy = nil, StateHeld, now, h.holdWhy(rec.Ask)
}
if !h.saveHeld(key, rec, rev) {
return
}
h.Logf("[messenger] %s's ask %q (%s) is offered again", rec.Asker, rec.Ask.Headline, rec.Ask.ID)
if rec.State != StateOpen {
return
}
h.mu.Lock()
r := h.open[rec.Record]
h.mu.Unlock()
if r != nil && r.Origin == "ask" {
h.mu.Lock()
r.Answered, r.Ask = "", key
h.mu.Unlock()
h.offerAsk(r)
h.persist(r)
return
}
rec.Record = h.recordFor(rec.Asker, key, rec.Ask)
h.showAsk(key, rec, now)
}
// AskAgain is the seat operator-channel's verb ask-again (G §394, §450): offer a held-back ask now, holding back the
// asker's oldest offered ask in its place when the asker already has the most offered. It answers the ask's state after it,
// or the error that says why it was not offered.
func (h *Holder) AskAgain(key string) oc.AskAgainAnswer {
h.work.Lock()
defer h.work.Unlock()
h.mu.Lock()
h.init()
h.mu.Unlock()
rec, _, ok := h.freshAsk(key)
switch {
case !ok:
return oc.AskAgainAnswer{Error: fmt.Sprintf("this router holds no ask %q: its key is <asker>.<id>, as operator-channel.asks lists", key)}
case rec.State != StateHeldBack:
return oc.AskAgainAnswer{Error: fmt.Sprintf("the ask %s is %s, not held back: only a held-back ask is offered again", key, rec.State)}
}
if h.offeredCount(rec.Asker) >= occ.MostOpen {
h.holdBackOldest(rec.Asker, key)
}
h.offerOneHeldBack(key)
got, _, _ := h.freshAsk(key)
return oc.AskAgainAnswer{State: string(got.State)}
}