From babcd1bb3153c90f48797a7aee86b252cc8cca3a Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 22 Nov 2026 00:05:58 +0100 Subject: [PATCH] RG1: the registry takes a publish ask once by its id MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A publish carrying an ask id is kept in the state taken for ask-taken-bound (10m): a repeat while the act runs joins it, a repeat after it ended answers the act's state read afresh (the transfer's lacking parts, a held version ended, a transfer gone refused), never publishing twice. Builds: design 47 H2 §775, §820; H-A-359, H-A-381 --- .../cmd/distribution-tools/contract_test.go | 2 +- .../cmd/distribution-tools/main.go | 14 +++- .../cmd/distribution-tools/taken.go | 75 +++++++++++++++++++ .../cmd/distribution-tools/taken_test.go | 63 ++++++++++++++++ .../internal/holder/holder_test.go | 19 +++++ .../distribution/internal/holder/transfer.go | 32 ++++++++ modules/distribution/module.json | 18 ++++- 7 files changed, 217 insertions(+), 6 deletions(-) create mode 100644 modules/distribution/cmd/distribution-tools/taken.go create mode 100644 modules/distribution/cmd/distribution-tools/taken_test.go diff --git a/modules/distribution/cmd/distribution-tools/contract_test.go b/modules/distribution/cmd/distribution-tools/contract_test.go index 9fadaf0bc..28c175e05 100644 --- a/modules/distribution/cmd/distribution-tools/contract_test.go +++ b/modules/distribution/cmd/distribution-tools/contract_test.go @@ -36,7 +36,7 @@ func TestTheVerbsSpeakTheSeatsContract(t *testing.T) { reg.VerbVersions: reg.VersionsInput{}, reg.VerbRemove: reg.RemoveInput{}, reg.VerbHold: reg.HoldInput{}, reg.VerbRelease: reg.ReleaseInput{}, reg.VerbMirror: reg.MirrorInput{}, reg.VerbTags: reg.TagsInput{}} seen := 0 - for _, tool := range tools(&holder.Verbs{}, kept[holder.Window]{}) { + for _, tool := range tools(&holder.Verbs{}, kept[holder.Window]{}, nil) { seat, verb, ok := strings.Cut(tool.Name, ".") in, isVerb := inputs[verb] if !ok || !isVerb || (seat != holder.ImageSeat && seat != holder.ArtifactSeat) { diff --git a/modules/distribution/cmd/distribution-tools/main.go b/modules/distribution/cmd/distribution-tools/main.go index bbecf4d67..2e5fb3b45 100644 --- a/modules/distribution/cmd/distribution-tools/main.go +++ b/modules/distribution/cmd/distribution-tools/main.go @@ -244,7 +244,7 @@ func arg[T any](args map[string]any) (T, error) { func str(args map[string]any, k string) string { s, _ := args[k].(string); return strings.TrimSpace(s) } // tools are distribution's tools over v. -func tools(v *holder.Verbs, windows kept[holder.Window]) []stdio.Tool { +func tools(v *holder.Verbs, windows kept[holder.Window], taken *asks) []stdio.Tool { obj := func(props map[string]any, req ...string) map[string]any { return map[string]any{"type": "object", "required": req, "properties": props} } @@ -262,7 +262,9 @@ func tools(v *holder.Verbs, windows kept[holder.Window]) []stdio.Tool { caller := stdio.CallerOf(args) start := time.Now() logf("%s.publish received from %s: %s %s (%s, %d parts)", seat, caller, in.Name, in.Version, in.Kind, len(in.Parts)) - a, err := v.Publish(seat, caller, publishOf(in)) + r := publishOf(in) + a, err := taken.once(seat, stdio.AskIDOf(args), func() (holder.PublishAnswer, error) { return v.Publish(seat, caller, r) }, + func() (holder.PublishAnswer, error) { return v.Repeat(seat, caller, r) }) if err == nil { // The window's learning asks the delivery view (up to 60 s, past the runner's 30 s call bound), // so it never holds the answer. @@ -503,7 +505,13 @@ func main() { logf("transfer %s had no part for %s: dropped with its parts", id, holder.TransferIdle) }) windows := kept[holder.Window]{state: "windows", key: func(w holder.Window) string { return w.Name }} - if err := stdio.Serve("", tools(v, windows)); err != nil { + bound, err := stdio.SettingDuration(askTakenBound, askTakenDefault) + if err != nil { + logf("the setting %s: %v", askTakenBound, err) + os.Exit(1) + } + taken := &asks{take: stdio.State(stdio.TakenState).TakeOnce, bound: bound} + if err := stdio.Serve("", tools(v, windows, taken)); err != nil { logf("%v", err) os.Exit(1) } diff --git a/modules/distribution/cmd/distribution-tools/taken.go b/modules/distribution/cmd/distribution-tools/taken.go new file mode 100644 index 000000000..4c5ec9f8e --- /dev/null +++ b/modules/distribution/cmd/distribution-tools/taken.go @@ -0,0 +1,75 @@ +package main + +import ( + "fmt" + "sync" + "time" + + "distribution/internal/holder" +) + +// askTakenBound is the setting the taken key of a publish ask lives (design 47 H2 §775, H-A-381 (2)): the holder never +// receives the caller's bound, so it keeps an ask's id this long, the largest caller's bound by default. +const askTakenBound = "ask-taken-bound" + +// askTakenDefault is ask-taken-bound's default, the runner's ask-unanswered-bound (H-A-381 (2)). +const askTakenDefault = 10 * time.Minute + +// asks takes each publish ask once by its id (design 47 H2 §775; ADR 0668 §2; H-A-381): the first call with an id is +// kept in the state taken and acts; a repeat while that act runs joins it and gets its answer; a repeat after it ended +// answers the act's state read afresh (holder.Repeat), never acting twice. No answer is kept in taken. A call that +// carries no ask id is no kept call, and acts as it did before. +type asks struct { + take func(seat, ask string, bound time.Duration) (bool, error) + bound time.Duration + mu sync.Mutex + running map[string]*flight + // joined, when set, is told each repeat that joins a running act (a test's hook). + joined func() +} + +// flight is one act of a taken ask while it runs, which a repeat joins. +type flight struct { + done chan struct{} + a holder.PublishAnswer + err error +} + +func (k *asks) once(seat, ask string, act, repeat func() (holder.PublishAnswer, error)) (holder.PublishAnswer, error) { + if ask == "" || k == nil || k.take == nil { + return act() + } + key := seat + "." + ask + k.mu.Lock() + if f, ok := k.running[key]; ok { + k.mu.Unlock() + if k.joined != nil { + k.joined() + } + <-f.done + return f.a, f.err + } + if k.running == nil { + k.running = map[string]*flight{} + } + f := &flight{done: make(chan struct{})} + k.running[key] = f + k.mu.Unlock() + defer func() { + k.mu.Lock() + delete(k.running, key) + k.mu.Unlock() + close(f.done) + }() + took, err := k.take(seat, ask, k.bound) + switch { + case err != nil: + f.err = fmt.Errorf("publish: the ask %s of %s cannot be taken: %w", ask, seat, err) + case took: + f.a, f.err = act() + default: + logf("%s.publish: the ask %s was taken before; it answers the act's state, acting not again", seat, ask) + f.a, f.err = repeat() + } + return f.a, f.err +} diff --git a/modules/distribution/cmd/distribution-tools/taken_test.go b/modules/distribution/cmd/distribution-tools/taken_test.go new file mode 100644 index 000000000..2107a7265 --- /dev/null +++ b/modules/distribution/cmd/distribution-tools/taken_test.go @@ -0,0 +1,63 @@ +package main + +import ( + "errors" + "sync" + "sync/atomic" + "testing" + "time" + + "distribution/internal/holder" +) + +// A publish ask given twice acts once (design 47 H2 §775; H-A-381): a repeat while the act runs joins it and gets its +// answer, a repeat after it ended answers the act's state, a call with no ask id acts as before, a take that fails is said. +func TestAPublishAskIsTakenOnce(t *testing.T) { + taken := map[string]bool{} + var mu sync.Mutex + k := &asks{bound: time.Minute, take: func(seat, ask string, bound time.Duration) (bool, error) { + mu.Lock() + defer mu.Unlock() + if ask == "broken" { + return false, errors.New("no responders") + } + if bound != time.Minute || taken[seat+"."+ask] { + return false, nil + } + taken[seat+"."+ask] = true + return true, nil + }} + var acts, repeats atomic.Int32 + release, started, joined := make(chan struct{}), make(chan struct{}, 1), make(chan struct{}, 1) + k.joined = func() { joined <- struct{}{} } + act := func() (holder.PublishAnswer, error) { + acts.Add(1) + started <- struct{}{} + <-release + return holder.PublishAnswer{Transfer: "t", Missing: []string{"d"}}, nil + } + repeat := func() (holder.PublishAnswer, error) { repeats.Add(1); return holder.PublishAnswer{Transfer: "t"}, nil } + answers := make(chan holder.PublishAnswer, 2) + go func() { a, _ := k.once(holder.ArtifactSeat, "a1", act, repeat); answers <- a }() + <-started + go func() { a, _ := k.once(holder.ArtifactSeat, "a1", act, repeat); answers <- a }() + <-joined + close(release) + for range 2 { + if a := <-answers; len(a.Missing) != 1 { + t.Errorf("an answer of the running act = %+v", a) + } + } + if a, _ := k.once(holder.ArtifactSeat, "a1", act, repeat); acts.Load() != 1 || repeats.Load() != 1 || a.Transfer != "t" { + t.Errorf("acts %d, repeats %d after a repeat of an ended act", acts.Load(), repeats.Load()) + } + release = make(chan struct{}) + close(release) + act2 := func() (holder.PublishAnswer, error) { acts.Add(1); return holder.PublishAnswer{}, nil } + if _, err := k.once(holder.ArtifactSeat, "", act2, repeat); err != nil || acts.Load() != 2 { + t.Errorf("a call with no ask id: acts %d, %v", acts.Load(), err) + } + if _, err := k.once(holder.ArtifactSeat, "broken", act2, repeat); err == nil || acts.Load() != 2 { + t.Errorf("a failed take: acts %d, %v", acts.Load(), err) + } +} diff --git a/modules/distribution/internal/holder/holder_test.go b/modules/distribution/internal/holder/holder_test.go index 9f2f0f77e..62aa77ca3 100644 --- a/modules/distribution/internal/holder/holder_test.go +++ b/modules/distribution/internal/holder/holder_test.go @@ -251,6 +251,25 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) { } }) + // A publish ask taken before answers the act's state read afresh and never publishes again (design 47 H2 §775; + // H-A-381): an open transfer its lacking parts, a transfer gone with nothing held a refusal naming it. + t.Run("a repeated ask answers the act's state", func(t *testing.T) { + b := newBed(true) + if _, err := b.h.Repeat(ArtifactSeat, builder, req("tr")); err == nil || !strings.Contains(err.Error(), "transfer tr is gone") { + t.Errorf("a repeat of an act that never happened answered %v", err) + } + if _, err := b.h.Publish(ArtifactSeat, builder, req("tr")); err != nil { + t.Fatal(err) + } + opened := len(b.h.Transfers.(memTransfers)) + if a, err := b.h.Repeat(ArtifactSeat, builder, req("tr")); err != nil || !reflect.DeepEqual(a.Missing, []string{part.Digest}) { + t.Errorf("a repeat of an open transfer = %+v, %v", a, err) + } + if len(b.h.Transfers.(memTransfers)) != opened || len(b.said) != 0 { + t.Errorf("a repeat acted: transfers %d, said %+v", len(b.h.Transfers.(memTransfers)), b.said) + } + }) + t.Run("a transfer in parts, cut and resumed, hashed, numbered by the builder, published", func(t *testing.T) { b := newBed(true) a, err := b.h.Publish(ArtifactSeat, builder, req("t1")) diff --git a/modules/distribution/internal/holder/transfer.go b/modules/distribution/internal/holder/transfer.go index 7b3bcba67..11574ddf2 100644 --- a/modules/distribution/internal/holder/transfer.go +++ b/modules/distribution/internal/holder/transfer.go @@ -397,6 +397,38 @@ func (h *Holder) DropIdle() ([]string, error) { return h.receiver().DropIdle() } // already gone. It answers whether it dropped the transfer. func (h *Holder) Expired(id string) (bool, error) { return h.receiver().Expired(id) } +// Repeat is `publish` given again with an ask id the holder already took and whose first act ended (design 47 H2 §775; +// H-A-381): it never publishes twice and keeps no answer, but answers the act's state as it stands, read afresh, which is +// what the act answers when done: a version the store holds ended, an open transfer the parts it lacks; a transfer that +// is gone, with nothing held, says the act never happened, and is refused naming it. +func (h *Holder) Repeat(seat, caller string, r PublishRequest) (PublishAnswer, error) { + if err := checkPublish(seat, r); err != nil { + return PublishAnswer{}, err + } + if r.Version != "" { + var ok bool + err := h.timed("the store's read of what it holds (the program's registry)", func() (err error) { + _, ok, err = h.Store.Held(r.Name, r.Version, r.Digest) + return err + }) + if err != nil { + return PublishAnswer{}, fmt.Errorf("publish: the store cannot say whether it holds %s@%s: %w", r.Name, r.Version, err) + } else if ok { + return PublishAnswer{Transfer: r.Transfer, Ended: true}, nil + } + } + t, found, err := h.Transfers.Get(r.Transfer) + switch { + case err != nil: + return PublishAnswer{}, fmt.Errorf("publish: the transfer %s of a repeated ask cannot be read: %w", r.Transfer, err) + case !found: + return PublishAnswer{}, fmt.Errorf("publish: refused: the ask was taken before, and transfer %s is gone with nothing of %s held: the act did not happen", r.Transfer, r.Name) + case t.Opener != caller: + return PublishAnswer{}, fmt.Errorf("publish: refused for %s: transfer %s was opened by another caller", caller, r.Transfer) + } + return PublishAnswer{Transfer: t.ID, Missing: t.Lacks()}, nil +} + func checkPublish(seat string, r PublishRequest) error { switch { case !slices.Contains(Seats, seat): diff --git a/modules/distribution/module.json b/modules/distribution/module.json index 0aca09da3..501826bf4 100644 --- a/modules/distribution/module.json +++ b/modules/distribution/module.json @@ -257,6 +257,20 @@ "holds", "windows", "mirrors", - "findings" - ] + "findings", + { + "name": "taken", + "key-ttl": true, + "max-mib": 8 + } + ], + "config": { + "ask-taken-bound": { + "type": "string", + "description": "How long the registry keeps the id of a publish ask it took, as a duration such as 10m (design 47 H2 §775): a publish given again with that id within it acts not again but answers the transfer as it stands. The largest caller's bound, the pipeline runner's ask-unanswered-bound, by default.", + "trusted": false, + "runtime": true, + "default": "10m" + } + } }