diff --git a/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract.go b/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract.go index 1ff6201e..2227b901 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract.go @@ -590,12 +590,20 @@ type HeadsReplacedEvent struct { type RecordOpenedEvent struct { // when At *time.Time `json:"at,omitempty"` + // for a forge-made record, the branch the merge moved + Branch string `json:"branch,omitempty"` + // for a forge-made record, the merge commit + Commit string `json:"commit,omitempty"` // a merge made at the forge, with no Approve ForgeMade bool `json:"forge-made,omitempty"` // its milestone Milestone string `json:"milestone"` + // for a forge-made record, the pull request's number + Pull int64 `json:"pull,omitempty"` // the record's id Record string `json:"record"` + // for a forge-made record, the repository, / + Repository string `json:"repository,omitempty"` } // RecordEndedEventAwayItem is a type of the contract. @@ -642,10 +650,14 @@ type SourceMovedEvent struct { // RecoveryMergedEvent is the body of the event recovery-merged. type RecoveryMergedEvent struct { At *time.Time `json:"at,omitempty"` + // the watched branch the merge moved + Branch string `json:"branch,omitempty"` // the caller the runtime proved By string `json:"by,omitempty"` // the merge commit Commit string `json:"commit"` + // the module the merge changed, from the delivery record + Module string `json:"module,omitempty"` // the repository Repository string `json:"repository"` V int64 `json:"v"` diff --git a/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract_test.go b/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract_test.go index e8c68c9f..421036e9 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract_test.go @@ -31,6 +31,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v HeadsReplacedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.heads-replaced$")}, {name: "record-opened is said", subject: "mesh.seat.mesh-delivery.event.record-opened", given: "{\"at\":\"2026-11-09T18:00:00Z\",\"milestone\":\"47/G\",\"record\":\"47-G\"}", wire: "{\"at\":\"2026-11-09T18:00:00Z\",\"milestone\":\"47/G\",\"record\":\"47-G\"}", decode: func(b []byte) (any, error) { var v RecordOpenedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.record-opened$")}, + {name: "record-opened is said for a merge made at the forge", subject: "mesh.seat.mesh-delivery.event.record-opened", given: "{\"at\":\"2026-11-09T18:00:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"forge-made\":true,\"milestone\":\"47/G\",\"pull\":35,\"record\":\"mesh-tools-35\",\"repository\":\"novox/mesh-tools\"}", wire: "{\"at\":\"2026-11-09T18:00:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"forge-made\":true,\"milestone\":\"47/G\",\"pull\":35,\"record\":\"mesh-tools-35\",\"repository\":\"novox/mesh-tools\"}", + decode: func(b []byte) (any, error) { var v RecordOpenedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.record-opened$")}, {name: "record-ended is said", subject: "mesh.seat.mesh-delivery.event.record-ended", given: "{\"at\":\"2026-11-09T21:00:00Z\",\"away\":[{\"node\":\"laptop\",\"since\":\"2026-11-09T18:00:00Z\"}],\"milestone\":\"47/G\",\"record\":\"47-G\"}", wire: "{\"at\":\"2026-11-09T21:00:00Z\",\"away\":[{\"node\":\"laptop\",\"since\":\"2026-11-09T18:00:00Z\"}],\"milestone\":\"47/G\",\"record\":\"47-G\"}", decode: func(b []byte) (any, error) { var v RecordEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.record-ended$")}, {name: "filling is said", subject: "mesh.seat.mesh-delivery.event.filling", given: "{\"bytes\":650000000,\"cap\":805306368,\"store\":\"records\"}", wire: "{\"bytes\":650000000,\"cap\":805306368,\"store\":\"records\"}", @@ -41,7 +43,7 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RoomEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.room$")}, {name: "main moved to its next source revision", subject: "mesh.seat.mesh-delivery.event.source-moved.main", given: "{\"at\":\"2026-11-10T10:00:00Z\",\"branch\":\"main\",\"revision\":3590,\"v\":1}", wire: "{\"at\":\"2026-11-10T10:00:00Z\",\"branch\":\"main\",\"revision\":3590,\"v\":1}", decode: func(b []byte) (any, error) { var v SourceMovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.source-moved\\.[^.*> ]+$")}, - {name: "a recovery merged", subject: "mesh.seat.mesh-delivery.event.recovery-merged", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"jochen\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-sdk\",\"v\":1,\"why\":\"the live delivery was broken\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"jochen\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-sdk\",\"v\":1,\"why\":\"the live delivery was broken\"}", + {name: "a recovery merged", subject: "mesh.seat.mesh-delivery.event.recovery-merged", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"branch\":\"main\",\"by\":\"jochen\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"module\":\"mesh-sdk\",\"repository\":\"novox/mesh-sdk\",\"v\":1,\"why\":\"the live delivery was broken\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"branch\":\"main\",\"by\":\"jochen\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"module\":\"mesh-sdk\",\"repository\":\"novox/mesh-sdk\",\"v\":1,\"why\":\"the live delivery was broken\"}", decode: func(b []byte) (any, error) { var v RecoveryMergedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.recovery-merged$")}, {name: "approval-carried is said for a pull request approved before G", subject: "mesh.seat.mesh-delivery.event.approval-carried.mesh-tools.35", given: "{\"approver\":\"operator\",\"at\":\"2026-11-11T10:00:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"pull\":35,\"repository\":\"mesh-tools\"}", wire: "{\"approver\":\"operator\",\"at\":\"2026-11-11T10:00:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"pull\":35,\"repository\":\"mesh-tools\"}", decode: func(b []byte) (any, error) { var v ApprovalCarriedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.approval-carried\\.[^.*> ]+\\.[^.*> ]+$")}, diff --git a/modules/mesh-delivery-contracts/seats/mesh-delivery/fixtures/events.json b/modules/mesh-delivery-contracts/seats/mesh-delivery/fixtures/events.json index 52b3fcbe..7d96b149 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-delivery/fixtures/events.json +++ b/modules/mesh-delivery-contracts/seats/mesh-delivery/fixtures/events.json @@ -96,6 +96,21 @@ "at": "2026-11-09T18:00:00Z" } }, + { + "name": "record-opened is said for a merge made at the forge", + "of": "event:record-opened", + "subject": "mesh.seat.mesh-delivery.event.record-opened", + "given": { + "record": "mesh-tools-35", + "milestone": "47/G", + "forge-made": true, + "repository": "novox/mesh-tools", + "pull": 35, + "commit": "0123456789abcdef0123456789abcdef01234567", + "branch": "main", + "at": "2026-11-09T18:00:00Z" + } + }, { "name": "record-ended is said", "of": "event:record-ended", @@ -161,6 +176,8 @@ "given": { "v": 1, "repository": "novox/mesh-sdk", + "module": "mesh-sdk", + "branch": "main", "commit": "0123456789abcdef0123456789abcdef01234567", "why": "the live delivery was broken", "by": "jochen", diff --git a/modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json b/modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json index c3712e59..dcdbb60c 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json @@ -308,6 +308,22 @@ "type": "boolean", "description": "a merge made at the forge, with no Approve" }, + "repository": { + "type": "string", + "description": "for a forge-made record, the repository, /" + }, + "pull": { + "type": "integer", + "description": "for a forge-made record, the pull request's number" + }, + "commit": { + "type": "string", + "description": "for a forge-made record, the merge commit" + }, + "branch": { + "type": "string", + "description": "for a forge-made record, the branch the merge moved" + }, "at": { "type": "string", "format": "date-time", @@ -433,6 +449,14 @@ "type": "string", "description": "the repository" }, + "module": { + "type": "string", + "description": "the module the merge changed, from the delivery record" + }, + "branch": { + "type": "string", + "description": "the watched branch the merge moved" + }, "commit": { "type": "string", "description": "the merge commit" diff --git a/modules/mesh-delivery-contracts/ts/seats/meshdelivery/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/meshdelivery/index.d.ts index 4d9e7332..242203a3 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshdelivery/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/meshdelivery/index.d.ts @@ -361,12 +361,20 @@ export interface HeadsReplacedEvent { export interface RecordOpenedEvent { /** when */ "at"?: string; + /** for a forge-made record, the branch the merge moved */ + "branch"?: string; + /** for a forge-made record, the merge commit */ + "commit"?: string; /** a merge made at the forge, with no Approve */ "forge-made"?: boolean; /** its milestone */ "milestone": string; + /** for a forge-made record, the pull request's number */ + "pull"?: number; /** the record's id */ "record": string; + /** for a forge-made record, the repository, / */ + "repository"?: string; } export interface RecordEndedEventAwayItem { @@ -412,10 +420,14 @@ export interface SourceMovedEvent { /** is the body of the event recovery-merged. */ export interface RecoveryMergedEvent { "at"?: string; + /** the watched branch the merge moved */ + "branch"?: string; /** the caller the runtime proved */ "by"?: string; /** the merge commit */ "commit": string; + /** the module the merge changed, from the delivery record */ + "module"?: string; /** the repository */ "repository": string; "v": number; diff --git a/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/main.go b/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/main.go index f338d719..8104ab20 100644 --- a/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/main.go +++ b/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/main.go @@ -100,6 +100,13 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro if err := hub.Handle(registrationChangedSubject, widens.HearRegistration); err != nil { return fmt.Errorf("hearing %s: %w", registrationChangedSubject, err) } + // A merge named a recovery and a merge made at the forge are told on every channel (design 47 G §81, §170, §514). + if err := hub.Handle(recoveryMergedSubject, widens.HearRecovery); err != nil { + return fmt.Errorf("hearing %s: %w", recoveryMergedSubject, err) + } + if err := hub.Handle(recordOpenedSubject, widens.HearRecordOpened); err != nil { + return fmt.Errorf("hearing %s: %w", recordOpenedSubject, err) + } // Hear the warrants first, so none that comes while the asks are read is missed. if err := client.Listen(t.Answer, t.Said); err != nil { return fmt.Errorf("hearing the router's warrants: %w", err) diff --git a/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/widens.go b/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/widens.go index 4c116f1d..636e490b 100644 --- a/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/widens.go +++ b/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/widens.go @@ -9,6 +9,7 @@ import ( "github.com/nats-io/nats.go/jetstream" "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog" + meshdelivery "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery" mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner" stdio "git.novox.be/novox/mesh-sdk/go" "git.novox.be/novox/mesh-sdk/go/keys" @@ -34,6 +35,8 @@ const ( const ( pipelineEndedSubject = "mesh.seat." + mpr.Seat + ".event." + mpr.EventPipelineEnded + ".>" registrationChangedSubject = meshcatalog.SubjectRegistrationChanged + recoveryMergedSubject = meshdelivery.SubjectRecoveryMerged + recordOpenedSubject = meshdelivery.SubjectRecordOpened ) // widensState is the state widens-said as the teller keeps it. @@ -91,8 +94,7 @@ func (w *Widens) Said(p mpr.PipelineEnded) error { } words := widensWords(p) // The message's key holds the commit, so a say that is made again after a failure to keep it replaces the message. - if _, err := w.Call(notifyKey, map[string]any{"key": "widens." + key + "." + commit7(p.Commit), "subject": p.Module, - "severity": "warning", "summary": words, "headline": words, "every-channel": true}); err != nil { + if err := w.tell("widens."+key+"."+commit7(p.Commit), p.Module, words); err != nil { return fmt.Errorf("the widening of %s %s on %s is not told: %w", p.Module, commit7(p.Commit), p.Branch, err) } if e == nil { @@ -186,3 +188,48 @@ func (w *Widens) logf(format string, args ...any) { w.Logf(format, args...) } } + +// recoveryWords is the message of a merge named a recovery (design 47 G §522, §81). +func recoveryWords(ev meshdelivery.RecoveryMergedEvent) string { + return fmt.Sprintf("Recovery merged: %s %s on %s, named by %s: %s.", ev.Module, commit7(ev.Commit), ev.Branch, ev.By, ev.Why) +} + +// forgeMadeWords is the message of a record opened for a merge made at the forge (design 47 G §522, §170). +func forgeMadeWords(ev meshdelivery.RecordOpenedEvent) string { + return fmt.Sprintf("Merged at the forge, not through the mesh: %s pull request #%d at %s on %s; delivered like any merge.", + ev.Repository, ev.Pull, commit7(ev.Commit), ev.Branch) +} + +// tell says words on every channel under key; a message of the same key is the same message. +func (w *Widens) tell(key, subject, words string) error { + _, err := w.Call(notifyKey, map[string]any{"key": key, "subject": subject, "severity": "warning", "summary": words, + "headline": words, "every-channel": true}) + return err +} + +// HearRecovery is the handler of recovery-merged: it tells the merge named a recovery on every channel (design 47 G §81, §514). +func (w *Widens) HearRecovery(m jetstream.Msg) { + var ev meshdelivery.RecoveryMergedEvent + if err := json.Unmarshal(m.Data(), &ev); err != nil || ev.Commit == "" { + w.logf("%s is not a recovery and is left: %v", m.Subject(), err) + _ = m.Ack() + return + } + w.finish(m, w.tell("recovery."+ev.Repository+"."+commit7(ev.Commit), ev.Repository, recoveryWords(ev))) +} + +// HearRecordOpened is the handler of record-opened: it tells a record opened for a merge made at the forge on every channel +// (design 47 G §170, §514); any other record is left to the watchman. +func (w *Widens) HearRecordOpened(m jetstream.Msg) { + var ev meshdelivery.RecordOpenedEvent + if err := json.Unmarshal(m.Data(), &ev); err != nil { + w.logf("%s is not a record's opening and is left: %v", m.Subject(), err) + _ = m.Ack() + return + } + if !ev.ForgeMade { + _ = m.Ack() + return + } + w.finish(m, w.tell("forge-made."+ev.Record, ev.Repository, forgeMadeWords(ev))) +} diff --git a/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/widens_test.go b/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/widens_test.go index dcab8f71..c4474d83 100644 --- a/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/widens_test.go +++ b/modules/mesh-delivery-teller/cmd/mesh-delivery-teller/widens_test.go @@ -174,3 +174,39 @@ func TestAPipelineEndedIsAcknowledgedOnlyWhenTold(t *testing.T) { t.Errorf("a told say: acked %v naked %v", m.acked, m.naked) } } + +// Design 47 G §81, §170, §522 (TL2, TL3): a recovery and a merge made at the forge are told on every channel in the operator's +// words, with their fields filled; a record opened the ordinary way is told nothing. +func TestARecoveryAndAForgeMadeMergeAreToldInTheOperatorsWords(t *testing.T) { + commit := "0123456789abcdef0123456789abcdef01234567" + for _, tc := range []struct { + name, body string + hear func(*Widens, *fakeMsg) + key, words string + }{ + {"a recovery", `{"v":1,"repository":"novox/mesh-sdk","module":"mesh-sdk","branch":"main","commit":"` + commit + `","why":"the live delivery was broken","by":"jochen"}`, + func(w *Widens, m *fakeMsg) { w.HearRecovery(m) }, "recovery.novox/mesh-sdk.0123456", + "Recovery merged: mesh-sdk 0123456 on main, named by jochen: the live delivery was broken."}, + {"a forge-made record", `{"record":"mesh-tools-35","milestone":"47/G","forge-made":true,"repository":"novox/mesh-tools","pull":35,"commit":"` + commit + `","branch":"main"}`, + func(w *Widens, m *fakeMsg) { w.HearRecordOpened(m) }, "forge-made.mesh-tools-35", + "Merged at the forge, not through the mesh: novox/mesh-tools pull request #35 at 0123456 on main; delivered like any merge."}, + {"an ordinary record", `{"record":"47-G","milestone":"47/G"}`, func(w *Widens, m *fakeMsg) { w.HearRecordOpened(m) }, "", ""}, + } { + c := &calls{} + w := &Widens{State: &widensMem{memStore{entries: map[string]*stdio.StateEntry{}}}, Call: c.call} + m := &fakeMsg{data: []byte(tc.body)} + tc.hear(w, m) + if !m.acked || m.naked { + t.Errorf("%s: acked %v naked %v", tc.name, m.acked, m.naked) + } + if tc.words == "" { + if len(c.notified) != 0 { + t.Errorf("%s: told %v", tc.name, c.notified) + } + continue + } + if len(c.notified) != 1 || c.notified[0]["headline"] != tc.words || c.notified[0]["key"] != tc.key || c.notified[0]["every-channel"] != true { + t.Errorf("%s: told %v, want %q under %s on every channel", tc.name, c.notified, tc.words, tc.key) + } + } +} diff --git a/modules/mesh-delivery-teller/manifest_test.go b/modules/mesh-delivery-teller/manifest_test.go index 75c044ed..bd80a7cb 100644 --- a/modules/mesh-delivery-teller/manifest_test.go +++ b/modules/mesh-delivery-teller/manifest_test.go @@ -113,7 +113,7 @@ func TestManifestDeclarations(t *testing.T) { // 1240/AC1 } // design 47 G §335 (TL1): the widening of a pipeline end is told through the seat operator-channel and kept in widens-said. // design 47 G §387: the keeper's ask for the findings is heard, and the finding stream is declared (§383). - if want := []string{"mesh-conditions.findings-asked", "mesh-delivery-assigner.views.asks", "mesh-catalog.registration-changed", "mesh-pipeline-runner.pipeline-ended"}; !reflect.DeepEqual(m.Consumes, want) { + if want := []string{"mesh-conditions.findings-asked", "mesh-delivery-assigner.views.asks", "mesh-catalog.registration-changed", "mesh-pipeline-runner.pipeline-ended", "mesh-delivery.recovery-merged", "mesh-delivery.record-opened"}; !reflect.DeepEqual(m.Consumes, want) { t.Errorf("consumes = %v, want %v", m.Consumes, want) } if want := []string{"operator-channel"}; !reflect.DeepEqual(sorted(m.Uses), want) { diff --git a/modules/mesh-delivery-teller/module.json b/modules/mesh-delivery-teller/module.json index 606bd8de..2cceaef5 100644 --- a/modules/mesh-delivery-teller/module.json +++ b/modules/mesh-delivery-teller/module.json @@ -19,7 +19,9 @@ "mesh-conditions.findings-asked", "mesh-delivery-assigner.views.asks", "mesh-catalog.registration-changed", - "mesh-pipeline-runner.pipeline-ended" + "mesh-pipeline-runner.pipeline-ended", + "mesh-delivery.recovery-merged", + "mesh-delivery.record-opened" ], "emits": [ "answered",