Findings writer: a Write or Clear never holds its caller on the bus past SayWithin, and never holds its lock while waiting on it

The writer's lock was held through the event's resend (up to PublishRetryFor, one minute), so one unacknowledged event
blocked every other Write and Clear behind it.

Builds: design 47 G §383 (the next statement covers an event not acknowledged; the state alone holds the finding)
This commit is contained in:
2026-11-15 01:38:17 +01:00
parent 958b327432
commit 8eb20000c9
2 changed files with 106 additions and 15 deletions
+61 -15
View File
@@ -566,40 +566,45 @@ func (w *Writer[F, C, S, A]) ModuleNode() (string, string) { return w.cfg.Module
// §383, §461). The key's `since` stays where the key exists.
func (w *Writer[F, C, S, A]) Write(ctx context.Context, finding F) error {
w.mu.Lock()
defer w.mu.Unlock()
f, old, err := w.complete(finding)
if err != nil {
w.mu.Unlock()
return err
}
if _, err := w.cfg.State.Put(keyOf(f), f); err != nil {
w.mu.Unlock()
return fmt.Errorf("writing the finding %s: %w", keyOf(f), err)
}
if old != nil && unsaid(old) == unsaid(f) {
w.mu.Unlock()
return nil
}
raw, _ := json.Marshal(f)
w.say(ctx, "finding-written", keyOf(f), raw)
w.mu.Unlock()
w.sayWithin(ctx, "finding-written", keyOf(f), raw)
return nil
}
// Clear deletes the finding's key and says `finding-cleared`; a key that does not exist is deleted of nothing and is said
// all the same, so a keeper holding the finding clears it (design 47 G §485).
func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why string) error {
w.mu.Lock()
defer w.mu.Unlock()
key := FindingKey(scope, id, kind)
if !w.owns(kind) {
return fmt.Errorf("the finding kind %q is not one this writer owns (%v)", kind, w.cfg.Kinds)
}
w.mu.Lock()
if err := w.cfg.State.Delete(key); err != nil {
w.mu.Unlock()
return fmt.Errorf("clearing the finding %s: %w", key, err)
}
var cleared C
if err := fillFrom(&cleared, wire{"kind": kind, "scope": scope, "id": id, "at": w.now(), "why": why}); err != nil {
w.mu.Unlock()
return err
}
raw, _ := json.Marshal(&cleared)
w.say(ctx, "finding-cleared", key, raw)
w.mu.Unlock()
w.sayWithin(ctx, "finding-cleared", key, raw)
return nil
}
@@ -607,21 +612,32 @@ func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why str
// pending, and says `findings-stated` (design 47 G §384, §461); asked is the ask it answers, none at a start. An error of
// observe says no set.
func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
raw, err := w.stated(ctx, asked)
if err != nil || raw == nil {
return err
}
w.say(ctx, "findings-stated", w.cfg.Module, raw)
return nil
}
// stated judges and keeps the set under the writer's lock and answers the statement's body to say, none when it is said
// through Send or could not be sent; the lock is never held while the bus is waited on.
func (w *Writer[F, C, S, A]) stated(ctx context.Context, asked string) ([]byte, error) {
w.mu.Lock()
defer w.mu.Unlock()
obs, err := w.cfg.Observe(ctx)
if err != nil {
return fmt.Errorf("observe: %w", err)
return nil, fmt.Errorf("observe: %w", err)
}
keep := map[string]bool{}
findings, pending := []wire{}, []wire{}
for _, finding := range obs.Findings {
f, _, err := w.complete(finding)
if err != nil {
return err
return nil, err
}
if _, err := w.cfg.State.Put(keyOf(f), f); err != nil {
return fmt.Errorf("writing the finding %s: %w", keyOf(f), err)
return nil, fmt.Errorf("writing the finding %s: %w", keyOf(f), err)
}
keep[keyOf(f)] = true
findings = append(findings, f)
@@ -632,7 +648,7 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
}
keys, err := w.cfg.State.Keys()
if err != nil {
return fmt.Errorf("the keys of the state findings: %w", err)
return nil, fmt.Errorf("the keys of the state findings: %w", err)
}
slices.Sort(keys)
for _, k := range keys {
@@ -645,7 +661,7 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
}
if !keep[k] && w.ownsKey(k) {
if err := w.cfg.State.Delete(k); err != nil {
return fmt.Errorf("deleting the finding %s: %w", k, err)
return nil, fmt.Errorf("deleting the finding %s: %w", k, err)
}
}
}
@@ -658,24 +674,30 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
}
var body S
if err := fillFrom(&body, stated); err != nil {
return err
return nil, err
}
raw, _ := json.Marshal(&body)
if w.cfg.Send != nil {
if raw, err = w.cfg.Send("findings-stated."+w.cfg.Module, raw); err != nil {
w.cfg.Logf("the findings-stated of %s could not be sent, the next statement covers it: %v", w.cfg.Module, err)
return nil
return nil, nil
}
}
w.say(ctx, "findings-stated", w.cfg.Module, raw)
return nil
return raw, nil
}
// say publishes one event awaiting the bus's acknowledgement, sent again for PublishRetryFor when unacknowledged, then
// written in the journal as an error naming what it said (design 47 G §383); the next statement covers it.
func (w *Writer[F, C, S, A]) say(ctx context.Context, event, what string, data []byte) {
w.mu.Lock()
w.seq++
id := fmt.Sprintf("%s-%s-%d-%d", w.cfg.Module, event, w.now().UnixNano(), w.seq)
seq := w.seq
w.mu.Unlock()
w.sayAs(ctx, seq, event, what, data)
}
func (w *Writer[F, C, S, A]) sayAs(ctx context.Context, seq uint64, event, what string, data []byte) {
id := fmt.Sprintf("%s-%s-%d-%d", w.cfg.Module, event, w.now().UnixNano(), seq)
start := w.now()
for delay := time.Second; ; delay = min(delay*2, 10*time.Second) {
subject, err := w.subject(event)
@@ -692,6 +714,30 @@ func (w *Writer[F, C, S, A]) say(ctx context.Context, event, what string, data [
}
}
// SayWithin is how long Write and Clear wait for the bus to acknowledge their event: the tool runner's call bound is 30 s,
// so a caller is never held longer than this; the event is still sent again in the background for PublishRetryFor.
var SayWithin = 3 * time.Second
// sayWithin says an event and returns when it is acknowledged or after SayWithin: the finding is kept in the state either
// way, and an event not yet acknowledged is said once to be going on in the background (design 47 G §383: the state alone
// holds the finding until the statement covers it).
func (w *Writer[F, C, S, A]) sayWithin(ctx context.Context, event, what string, data []byte) {
w.mu.Lock()
w.seq++
seq := w.seq
w.mu.Unlock()
done := make(chan struct{})
go func() {
defer close(done)
w.sayAs(ctx, seq, event, what, data)
}()
select {
case <-done:
case <-time.After(SayWithin):
w.cfg.Logf("%s for %s is not acknowledged by the bus within %s: the finding is kept in the state alone and the event is sent again for %s", event, what, SayWithin, PublishRetryFor)
}
}
// fillFrom sets the contract body v from its wire form.
func fillFrom(v any, m wire) error {
raw, err := json.Marshal(m)
+45
View File
@@ -643,7 +643,52 @@ func subHeldWriterSeedsAtStart(t *testing.T) {
}
// TestFindingSubjectsAreTheEventsStreamForm runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
// A Write or Clear whose event the bus does not acknowledge returns within SayWithin, with the finding kept in the state and
// the delay said once; another Write is not held behind it (the writer's lock is not held while the bus is waited on).
func subWriteNeverBlocksItsCallerOnTheBus(t *testing.T) {
old := views.SayWithin
views.SayWithin = 20 * time.Millisecond
defer func() { views.SayWithin = old }()
state := &fakeState{m: map[string][]byte{}}
block := make(chan struct{})
defer close(block)
var mu sync.Mutex
var logs []string
w, err := views.NewWriter(testConfig{
Module: "m", State: state, Node: "n1", Asked: asked,
Observe: func(context.Context) (testObserved, error) { return testObserved{}, nil },
Logf: func(f string, a ...any) { mu.Lock(); logs = append(logs, fmt.Sprintf(f, a...)); mu.Unlock() },
Now: time.Now,
Wait: func(ctx context.Context, d time.Duration) bool { <-block; return false },
Publish: func(context.Context, string, []byte, string) error { <-block; return errors.New("no ack") },
Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil },
})
if err != nil {
t.Fatal(err)
}
done := make(chan struct{})
go func() {
defer close(done)
_ = w.Write(context.Background(), finding("a", "one"))
_ = w.Write(context.Background(), finding("b", "one"))
}()
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("Write was held by the bus")
}
if len(state.m) != 2 {
t.Fatalf("state holds %d findings", len(state.m))
}
mu.Lock()
defer mu.Unlock()
if len(logs) != 2 || !strings.Contains(logs[0], "kept in the state alone") {
t.Fatalf("journal: %v", logs)
}
}
func TestFindingSubjectsAreTheEventsStreamForm(t *testing.T) {
t.Run("WriteNeverBlocksItsCallerOnTheBus", subWriteNeverBlocksItsCallerOnTheBus)
t.Run("FindingSubjectsAreTheEventsStreamForm", subFindingSubjectsAreTheEventsStreamForm)
t.Run("WriterSaysUnderItsFindingEventsBindingOrOnTheOldStream", subWriterSaysUnderItsFindingEventsBindingOrOnTheOldStream)
t.Run("WriterWritesAndClearsFindingsAsEvents", subWriterWritesAndClearsFindingsAsEvents)