Files
mesh-delivery/modules/mesh-delivery-forge-bridge/cmd/mesh-delivery-forge-bridge/owed.go
T
jschoubben dcb7ba016c FB12: the forge bridge opens its state performed by its binding
The state performed is a requires entry, so the bridge reaches it by mesh-sdk's process.Binding: the seat mesh-broker's
show asked at the start as a kept call and again on its recreated and dropped, the bucket opened by the name show
answers. Until it answers, nothing owed is performed and the bridge says it waits, naming the entry. The old name
<module>_performed goes. mesh-sdk's Binding is cherry-picked on feat/47-G-fix11-b3c from feat/47-G-fix11-a7 (fa0a107).

Builds: design 47 G §577

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 06:17:01 +01:00

358 lines
14 KiB
Go

package main
import (
"context"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
"log"
"strconv"
"strings"
"time"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliveryclient"
git "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/git"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
checker "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdeliverychecker"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-forge-bridge/forgemsg"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-forge-bridge/internal/bridge"
"mesh-delivery-forge-bridge/internal/groups"
)
// The state performed (manifest `requires`, the template state, opened by its binding: bound.go) keeps one key per owed act it
// performed, the act's outcome and when, with the owed event as heard (novox/hq design 47 *What the gate owes the
// forge*). It is a saving and a read, never what keeps an act from happening twice: every act is safe to repeat at the
// forge. The group ends' bookkeeping (`published.`, `groups.`, groups.go) is in it too, under the same 7 days.
// performedKey is the key of one act in performed: the seat that said it and its id, the id in unpadded base64url, since
// an id may hold what a key may not (`#`, `/`).
func performedKey(of, id string) string {
return of + "." + base64.RawURLEncoding.EncodeToString([]byte(id))
}
// Performed is one value of the state performed: the outcome said as owed.ended, and the owed event it answers, so
// bridge_owed_again performs it again from here.
type Performed struct {
Ended forgemsg.OwedEnded `json:"ended"`
Owed json.RawMessage `json:"owed,omitempty"`
}
// performedStore is the state performed as the owing reads and writes it.
type performedStore interface {
Get(ctx context.Context, key string) (value []byte, found bool, err error)
Put(ctx context.Context, key string, value []byte) error
}
type kvPerformed struct{ kv keptStore }
func (s kvPerformed) Get(ctx context.Context, key string) ([]byte, bool, error) {
e, err := s.kv.Get(ctx, key)
if errors.Is(err, jetstream.ErrKeyNotFound) {
return nil, false, nil
}
if err != nil {
return nil, false, err
}
return e.Value(), true, nil
}
func (s kvPerformed) Put(ctx context.Context, key string, value []byte) error {
_, err := s.kv.Put(ctx, key, value)
return err
}
// owing performs what the gate and the checker owe the forge (design 47 *What the gate owes the forge*): each owed act
// through the seat git's verb under its id, its outcome said as owed.ended on the stream forge and then kept in
// performed. It holds no timer.
type owing struct {
call caller
pub publisher
performed performedStore
// waits, when set, says why the state performed cannot be used yet (its binding, design 47 G §577); empty when it can.
waits func() string
now func() time.Time
logger *log.Logger
}
// readerOf is the reading of the seat of's owed event into the seat git's verb.
func readerOf(of string) (func([]byte) (bridge.OwedCall, error), error) {
switch of {
case seat.Seat:
return bridge.GateOwed, nil
case checker.Seat:
return bridge.CheckerOwed, nil
}
return nil, fmt.Errorf("the seat %q says no owed act the bridge performs", of)
}
// heard performs one owed event the seat of said. Its error is only an outcome that could not be said on the stream
// forge: the event is then heard again, and the act, safe to repeat, performed again.
func (o *owing) heard(ctx context.Context, of string, data []byte) (forgemsg.OwedEnded, error) {
read, err := readerOf(of)
if err != nil {
return o.end(ctx, forgemsg.OwedEnded{Of: of, Outcome: forgemsg.OwedUndecodable, Words: err.Error()}, data)
}
c, err := read(data)
if err != nil {
return o.end(ctx, forgemsg.OwedEnded{Of: of, ID: c.ID,
Outcome: forgemsg.OwedUndecodable, Words: err.Error()}, data)
}
if w := o.waiting(); w != "" {
return forgemsg.OwedEnded{Of: c.Of, ID: c.ID}, fmt.Errorf("the bridge %s", w)
}
if o.held(ctx, c.Of, c.ID) {
// said twice, or said again while its outcome was on its way: performed once, the outcome said once
return forgemsg.OwedEnded{Of: c.Of, ID: c.ID}, nil
}
if words, done := o.switchedDone(ctx, c.Of, c.ID); done {
// performed by the old bridge before the switch: said performed, never done twice
return o.end(ctx, forgemsg.OwedEnded{Of: c.Of, ID: c.ID,
Outcome: forgemsg.OwedPerformed, Words: words}, data)
}
return o.perform(ctx, c, data)
}
// switchedDone says whether a switched act (design 47 *The switch carries what is owed*: the gate's act of a key of its
// old state owed or merges, its id meshdeliveryclient.SwitchedActID) was performed by the old bridge: its own bookkeeping
// in performed, `<state>.<key>`, holds that key at the act's revision or a later one. Any other id, and bookkeeping that
// cannot be read, is not: the act is performed, which changes nothing at the forge.
func (o *owing) switchedDone(ctx context.Context, of, id string) (string, bool) {
state, key, rev, ok := meshdeliveryclient.ParseSwitchedActID(id)
if !ok || of != seat.Seat {
return "", false
}
kept, found, err := o.performed.Get(ctx, state+"."+key)
if err != nil || !found {
return "", false
}
at, err := strconv.ParseUint(strings.TrimSpace(string(kept)), 10, 64)
if err != nil || at < rev {
return "", false
}
return fmt.Sprintf("performed by the bridge before the switch: its %s.%s at revision %d", state, key, at), true
}
// hear is one message of a seat's stream owed: performed and acknowledged, or, when its outcome could not be said,
// left to come again (design 47: the bridge stopped between an act and its owed.ended performs it again).
func (o *owing) hear(ctx context.Context, of string, m delivered) {
if _, err := o.heard(ctx, of, m.Data()); err != nil {
o.logger.Printf("%s, so the act is heard again: %v", m.Subject(), err)
_ = m.NakWithDelay(retryDelay)
return
}
_ = m.Ack()
}
// waiting is why the state performed cannot be used yet, or empty.
func (o *owing) waiting() string {
if o.waits == nil {
return ""
}
return o.waits()
}
// perform calls the seat git's verb of one act and says what it came to.
func (o *owing) perform(ctx context.Context, c bridge.OwedCall, data []byte) (forgemsg.OwedEnded, error) {
answer, callErr := o.call(ctx, "seat:"+git.Seat+"."+c.Verb, c.Input)
outcome, words := bridge.Outcome(answer, callErr)
if outcome != forgemsg.OwedPerformed {
o.logger.Printf("the owed %s %s of %s#%d (said by %s) is %s: %s", c.Act, c.ID, c.Repository, c.Number, c.Of, outcome, words)
}
return o.end(ctx, forgemsg.OwedEnded{Of: c.Of, ID: c.ID,
Outcome: outcome, Words: words}, data)
}
// end says an act's outcome as owed.ended on the stream forge, then keeps it in performed. An outcome not kept is
// logged: the act may be performed again, which changes nothing at the forge.
func (o *owing) end(ctx context.Context, e forgemsg.OwedEnded, owed []byte) (forgemsg.OwedEnded, error) {
e.At = o.now().UTC()
data, err := forgemsg.EncodeOwedEnded(e)
if err != nil {
return e, fmt.Errorf("the outcome of the owed %s cannot be said: %w", e.ID, err)
}
if _, err := o.pub.Publish(ctx, forgeSubject(forgemsg.OwedEndedEvent), data); err != nil {
return e, fmt.Errorf("the outcome %s of the owed %s could not be said on the stream forge: %w", e.Outcome, e.ID, err)
}
if e.ID == "" {
return e, nil // an undecodable act with no id is said, and has no key to keep
}
if !json.Valid(owed) {
owed = nil
}
v, err := json.Marshal(Performed{Ended: e, Owed: owed})
if err == nil {
err = o.performed.Put(ctx, performedKey(e.Of, e.ID), v)
}
if err != nil {
o.logger.Printf("the outcome %s of the owed %s is said but could not be kept in performed: %v", e.Outcome, e.ID, err)
}
return e, nil
}
// held says whether performed holds an outcome of the act already. One that cannot be read is not held: the act is
// performed again, which changes nothing at the forge.
func (o *owing) held(ctx context.Context, of, id string) bool {
_, found, err := o.performed.Get(ctx, performedKey(of, id))
if err != nil {
o.logger.Printf("performed of the owed %s cannot be read, so it is performed again: %v", id, err)
return false
}
return found
}
// catchUp reads the seat mesh-delivery's groups and performs every act said there with no recorded outcome that
// performed does not hold either (design 47 *The bridge catches up from the seat*). It answers how many it performed.
func (o *owing) catchUp(ctx context.Context) (int, error) {
if w := o.waiting(); w != "" {
return 0, fmt.Errorf("the bridge %s", w)
}
of, err := groups.Read(ctx, o.call)
if err != nil {
return 0, err
}
n := 0
for _, g := range of {
for _, act := range g.Acts {
if act.Outcome != "" || o.held(ctx, seat.Seat, act.Owed.ID) {
continue // answered, or performed and its outcome on its way to the gate
}
data, err := json.Marshal(act.Owed)
if err != nil {
return n, err
}
if _, err := o.heard(ctx, seat.Seat, data); err != nil {
return n, err
}
n++
}
}
return n, nil
}
// owedOf is the owed event of an act to perform again: as performed keeps it, else, for the gate's, as its groups say it.
func (o *owing) owedOf(ctx context.Context, of, id string) ([]byte, error) {
v, found, err := o.performed.Get(ctx, performedKey(of, id))
if err != nil {
return nil, fmt.Errorf("performed cannot be read: %w", err)
}
if found {
var p Performed
if err := json.Unmarshal(v, &p); err == nil && len(p.Owed) > 0 {
return p.Owed, nil
}
}
if of != seat.Seat {
return nil, fmt.Errorf("the bridge holds no owed act %s of %s: the checker says its unanswered acts again at its start", id, of)
}
raw, err := o.call(ctx, "seat:"+seat.Seat+"."+seat.VerbGroups, seat.GroupsInput{All: seat.GroupsInputAllTrue})
if err != nil {
return nil, fmt.Errorf("the seat %s's groups could not be read: %w", seat.Seat, err)
}
var a seat.GroupsAnswer
if err := json.Unmarshal(raw, &a); err != nil || a.Error != "" {
return nil, fmt.Errorf("the seat %s's groups do not answer: %v %s", seat.Seat, err, a.Error)
}
for _, g := range a.Groups {
for _, act := range g.Acts {
if act.Owed.ID == id {
return json.Marshal(act.Owed)
}
}
}
return nil, fmt.Errorf("neither the bridge nor the seat %s's groups hold an owed act %s", seat.Seat, id)
}
// answer answers one owed ask: an act performed again now, whatever performed holds of it; an act dropped, said as
// owed.ended with the outcome dropped and the ask's why (the tool wrote the hand-act log first); or the consumers' backlog.
func (o *owing) answer(ctx context.Context, a groups.OwedAsk, backlog func(context.Context) []groups.Backlog) groups.OwedAsk {
a.Answered = o.now().UTC()
switch a.Kind {
case groups.OwedBacklog:
a.Backlog, a.Answer = backlog(ctx), "the backlog of each seat's stream owed"
return a
}
data, err := o.owedOf(ctx, a.Of, a.ID)
if err != nil {
a.Answer = err.Error()
return a
}
var e forgemsg.OwedEnded
if a.Kind == groups.OwedDrop {
e, err = o.end(ctx, forgemsg.OwedEnded{Of: a.Of, ID: a.ID, Outcome: forgemsg.OwedDropped, Words: a.Why + " (dropped by " + a.By + ")"}, data)
} else if read, rerr := readerOf(a.Of); rerr != nil {
err = rerr
} else if c, rerr := read(data); rerr != nil {
e, err = o.end(ctx, forgemsg.OwedEnded{Of: a.Of, ID: a.ID, Outcome: forgemsg.OwedUndecodable, Words: rerr.Error()}, data)
} else {
e, err = o.perform(ctx, c, data)
}
if err != nil {
a.Answer = err.Error()
return a
}
a.Outcome, a.Answer = e.Outcome, "said as owed.ended: "+e.Outcome
if e.Words != "" {
a.Answer += ": " + e.Words
}
return a
}
// asked answers one value of the state owed-asks not yet answered, written back by compare-and-set at its revision; an
// answered one (this bridge's own write) is left.
func (o *owing) asked(ctx context.Context, kv jetstream.KeyValue, key string, rev uint64, value []byte, backlog func(context.Context) []groups.Backlog) {
a, err := groups.DecodeOwedAsk(value)
if err != nil {
o.logger.Printf("%s.%s holds what is not an owed ask, left: %v", groups.OwedAsksState, key, err)
return
}
if a.Done() {
return
}
a = o.answer(ctx, a, backlog)
o.logger.Printf("the owed ask %s of %s %s by %s (%s): %s", a.Kind, a.Of, a.ID, a.By, a.Why, a.Answer)
data, err := json.Marshal(a)
if err != nil {
return
}
if _, err := kv.Update(ctx, key, data, rev); err != nil && !errors.Is(err, jetstream.ErrKeyExists) && !errors.Is(err, jetstream.ErrKeyRevisionMismatch) {
o.logger.Printf("%s.%s: the answer could not be written: %v", groups.OwedAsksState, key, err)
}
}
// owedBacklog reads the bridge's durable on each seat's stream owed: its acknowledged floor, what waits and what is held,
// and the time of the first event after the floor.
func owedBacklog(js jetstream.JetStream, cred process.Account, now func() time.Time) func(context.Context) []groups.Backlog {
return func(ctx context.Context) []groups.Backlog {
var out []groups.Backlog
for _, kept := range []string{seat.StreamOwed, checker.StreamOwed} {
row := groups.Backlog{Stream: kept, Consumer: cred.EventConsumerName()}
c, err := js.Consumer(ctx, row.Stream, row.Consumer)
var info *jetstream.ConsumerInfo
if err == nil {
info, err = c.Info(ctx)
}
if err != nil {
row.Error = err.Error()
out = append(out, row)
continue
}
row.LastApplied, row.Waiting, row.Held = info.AckFloor.Stream, info.NumPending, uint64(info.NumAckPending)
if row.Waiting+row.Held > 0 {
if s, err := js.Stream(ctx, row.Stream); err == nil {
if m, err := s.GetMsg(ctx, info.AckFloor.Stream+1); err == nil {
row.Oldest, row.OldestSecs = m.Time.UTC(), int64(now().Sub(m.Time).Seconds())
}
}
}
out = append(out, row)
}
return out
}
}