// Package forgemsg is the forge bridge's contract on its own stream `forge` (novox/hq ADR 0633 §4): its messages (Forge, // one per pull request, merge, refusal or list of open pull requests) and a delivery group's end (ForgeGroupEnd). The // forge bridge writes them; the indexer and the gate read them. It is the forge bridge's own package: one module owns // these types, so they live with it and not in mesh-sdk (the operator, 2026-11-04). package forgemsg import ( "encoding/json" "fmt" "reflect" "regexp" "strings" "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliveryclient" "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/trunk" "git.novox.be/novox/mesh-sdk/go/keys" ) // Version is the version of every value this package writes and the only one it reads: mesh-sdk's delivery values'. const Version = keys.Version // ForgeStream is the forge bridge's stream as its manifest declares it; the broker derives the real names. const ForgeStream = "forge" // The kinds of forge message, the last part of a forge event's name. const ( ForgePull = "pull" ForgeMerged = "merged" // ForgePushed is a move of a watched branch the forge names no pull request's merge for (design 47 G §509): an // admitted push, taken in as a merged message is. ForgePushed = "pushed" ForgeRefused = "refused" ForgeOpen = "open" ) // OpenPull names an open pull request into the trunk: the repository as `/` and the number. type OpenPull struct { Repository string `json:"repository"` Number int `json:"number"` } // OpenEvent is the name of an open message: `forge.open`. It names no repository: it says every open pull request of // every repository the forge bridge reads (novox/hq ADR 0443 §5). func OpenEvent() string { return "forge." + ForgeOpen } // The actions of a pull message. const ( PullOpened = "opened" PullUpdated = "updated" PullClosed = "closed" ) // checkRepository refuses a repository that is not `/`: exactly one slash, each part a valid name. func checkRepository(repository string) error { owner, name, ok := strings.Cut(repository, "/") if !ok || strings.Contains(name, "/") { return fmt.Errorf("delivery: the repository %q is not /, with exactly one slash", repository) } if err := checkName("repository owner", owner); err != nil { return fmt.Errorf("delivery: the repository %q: %w", repository, err) } if err := checkName("repository name", name); err != nil { return fmt.Errorf("delivery: the repository %q: %w", repository, err) } if strings.Contains(owner, "/") { return fmt.Errorf("delivery: the repository %q is not /, with exactly one slash", repository) } return nil } func checkForgeKind(kind string) error { switch kind { case ForgePull, ForgeMerged, ForgePushed, ForgeRefused, ForgeOpen: return nil } return fmt.Errorf("delivery: the forge kind %q is not pull, merged, pushed, refused or open", kind) } // ForgeEvent is the name of a forge message of the given kind: `forge...`. func ForgeEvent(repository, kind string) (string, error) { if err := checkForgeKind(kind); err != nil { return "", err } if kind == ForgeOpen { return "", fmt.Errorf("delivery: an open message names no repository, its event is %s", OpenEvent()) } if err := checkRepository(repository); err != nil { return "", err } owner, name, _ := strings.Cut(repository, "/") return "forge." + owner + "." + name + "." + kind, nil } // ParseForgeEvent is the inverse of ForgeEvent. func ParseForgeEvent(event string) (repository, kind string, err error) { if event == OpenEvent() { return "", ForgeOpen, nil } parts := strings.Split(event, ".") if len(parts) != 4 || parts[0] != "forge" { return "", "", fmt.Errorf("delivery: %q is not a forge event, forge...", event) } repository = parts[1] + "/" + parts[2] if _, err := ForgeEvent(repository, parts[3]); err != nil { return "", "", fmt.Errorf("delivery: %q is not a forge event: %w", event, err) } return repository, parts[3], nil } // Forge is a message of the forge bridge's stream, trimmed to repository, branch, pull request and head. A pull // message says Action; a merged message carries the merge commit, the tree of every directory holding a // module.json and the repository's root tree; a refused message names the owed act it answers and the forge's own // words. A pull message may also carry the module directories its head changes (Dirs, in the order the forge said) and // DirsKnown, true when the forge could say them: known and empty is DirsKnown with no Dirs, not known is neither // (the forge's module_dirs and module_dirs_said, mesh-catalog modules/gitea/trunk.ts). Other messages carry neither. type Forge struct { V int `json:"v"` Kind string `json:"kind"` Repository string `json:"repository"` // Branch is a pull or merged message's pull request branch, and a pushed message's branch pushed. Branch string `json:"branch,omitempty"` // Base is the watched branch a merged message's commit landed on (design 47 G §714). Base string `json:"base,omitempty"` Number int `json:"number,omitempty"` // Head is a pull or merged message's pull request head commit, and a pushed message's new head of its branch (A-236). Head string `json:"head,omitempty"` // Before is a pushed message's head of its branch before, as the forge bridge last wrote it (A-236), empty for none. Before string `json:"before,omitempty"` Action string `json:"action,omitempty"` Dirs []string `json:"dirs,omitempty"` DirsKnown bool `json:"dirs-known,omitempty"` Merge string `json:"merge,omitempty"` Trees map[string]string `json:"trees,omitempty"` Root string `json:"root,omitempty"` // Manifests are the module.json bytes, exact, of each module directory: of the merge's trees on a merged message, // of Dirs at the head on a pull message. Locks are, of each such directory, its lock files' hex sha256 by path // relative to it (novox/hq ADR 0465 clause 1). Older writers send neither. Manifests map[string]string `json:"manifests,omitempty"` Locks map[string]map[string]string `json:"locks,omitempty"` // Needs are, of each such directory whose manifest names templates, the reader capabilities of the module whole: // its manifest's and its templates' text's at the same commit (catalogue.ModuleNeeds; novox/hq ADR 0632 §2). The // indexer takes them over the manifest's own; a directory absent, or an older writer, has the manifest's alone. Needs map[string][]string `json:"needs,omitempty"` // Paths are, of each module directory whose manifest names paths on every artifact, each named path's git object // id at the same commit as its manifest, by path relative to the directory (novox/hq ADR 0499 clause 3). The // indexer names the paths; a message without them gives such a module none. Older writers send none. Paths map[string]map[string]string `json:"paths,omitempty"` // Packages are, of each module directory, the mesh packages its lock file names (MeshPackagesOf; novox/hq ADR 0573 // §2): the indexer keeps them in the module's inputs and takes each one's latest published version into its // fingerprint. Absent for a directory that uses none, and from an older writer. Packages map[string][]string `json:"packages,omitempty"` Act string `json:"act,omitempty"` Words string `json:"words,omitempty"` Open []OpenPull `json:"open,omitempty"` // RetiredAssignments is the assignments files a bridge before ADR 0567 carried (ADR 0549 §2, ADR 0559 §2): assignments is // the seat mesh-module-assigner's state now and no repository holds it (ADR 0567 §11), so a message carrying them is // refused, loudly, rather than read with them dropped. RetiredAssignments json.RawMessage `json:"assignments,omitempty"` RetiredRead bool `json:"assignments-read,omitempty"` // Predefined is the catalogue's predefined.json, exact, at the merge commit of a merged message (novox/hq ADR 0565 // §2): what the indexer keeps as its state `predefined`. PredefinedRead says the bridge read the merge and it holds // no predefined.json. Carried on a merged message only; an older bridge sends neither, and the indexer keeps what it // held. Predefined json.RawMessage `json:"predefined,omitempty"` PredefinedRead bool `json:"predefined-read,omitempty"` // Group is the delivery group a merged message's pull request was merged in, and Members every approved member of // that group with its approved head, this one included (novox/hq ADR 0633 §4): the forge bridge sets both from the // seat mesh-delivery's verb groups, and the indexer gathers the group's merges until the group's end (ForgeGroupEnd). A merge // with no group carries neither, and an older bridge sends neither; an older reader ignores both. Group string `json:"group,omitempty"` Members []meshdeliveryclient.Head `json:"members,omitempty"` } // checkGroup refuses a group on anything but a merged message, a group without its members or members without a // group, a member that is not a repository's pull request at a head, a member named twice, and members that leave out // the message's own pull request. func (f Forge) checkGroup() error { if f.Group == "" && len(f.Members) == 0 { return nil } if f.Kind != ForgeMerged { return fmt.Errorf("delivery: only a merged message names its delivery group, not a %s message", f.Kind) } if f.Group == "" || len(f.Members) == 0 { return fmt.Errorf("delivery: a merged message names its group and the group's members together, or neither") } self := false seen := map[string]bool{} for _, m := range f.Members { if err := checkRepository(m.Repository); err != nil { return err } if m.Number <= 0 || m.Head == "" { return fmt.Errorf("delivery: the member %s of the group %q needs its pull request number and head", m.Repository, f.Group) } k := fmt.Sprintf("%s#%d", m.Repository, m.Number) if seen[k] { return fmt.Errorf("delivery: the group %q names its member %s twice", f.Group, k) } seen[k] = true self = self || (trunk.SameRepository(m.Repository, f.Repository) && m.Number == f.Number) } if !self { return fmt.Errorf("delivery: the members of the group %q leave out the merged pull request %s#%d", f.Group, f.Repository, f.Number) } return nil } // checkPredefined refuses the predefined list on anything but a merged message, a list that is not one JSON object, and // a list said both present and absent. func (f Forge) checkPredefined() error { if len(f.Predefined) == 0 && !f.PredefinedRead { return nil } if f.Kind != ForgeMerged && f.Kind != ForgePushed { return fmt.Errorf("delivery: only a merged or pushed message carries the predefined list, not a %s message", f.Kind) } if len(f.Predefined) > 0 && f.PredefinedRead { return fmt.Errorf("delivery: a merged message carries the predefined list and says the merge holds none (predefined-read)") } var list map[string]json.RawMessage if len(f.Predefined) > 0 && json.Unmarshal(f.Predefined, &list) != nil { return fmt.Errorf("delivery: the predefined list a merged message carries is not one JSON object") } return nil } func (f Forge) check() error { if err := checkForgeKind(f.Kind); err != nil { return err } if f.Kind == ForgeOpen { return f.checkOpen() } if len(f.Open) > 0 { return fmt.Errorf("delivery: only an open message names open pull requests") } if len(f.RetiredAssignments) > 0 || f.RetiredRead { return fmt.Errorf("delivery: a forge message carries assignments files, which no repository holds since ADR 0567: " + "assignments is the seat mesh-module-assigner's state") } if err := f.checkPredefined(); err != nil { return err } if err := f.checkGroup(); err != nil { return err } if err := checkRepository(f.Repository); err != nil { return err } switch f.Kind { case ForgePull: if f.Number <= 0 { return fmt.Errorf("delivery: a pull message needs its pull request number") } if f.Head == "" { return fmt.Errorf("delivery: a pull message needs its head") } switch f.Action { case PullOpened, PullUpdated, PullClosed: default: return fmt.Errorf("delivery: the pull action %q is not opened, updated or closed", f.Action) } if len(f.Dirs) > 0 && !f.DirsKnown { return fmt.Errorf("delivery: a pull message with module directories must say it knows them (dirs-known)") } dirs := map[string]bool{} for _, d := range f.Dirs { dirs[d] = true } if err := f.checkInputs(func(d string) bool { return dirs[d] }, "its module directories"); err != nil { return err } case ForgeMerged, ForgePushed: if len(f.Dirs) > 0 || f.DirsKnown { return fmt.Errorf("delivery: a %s message carries no module directories", f.Kind) } if f.Kind == ForgeMerged && f.Number <= 0 { return fmt.Errorf("delivery: a merged message needs its pull request number") } if f.Kind == ForgePushed && (f.Number != 0 || f.Merge != "" || f.Base != "") { return fmt.Errorf("delivery: a pushed message names no pull request, merge commit or base: its branch is the one pushed") } if f.Kind == ForgePushed && f.Branch == "" { return fmt.Errorf("delivery: a pushed message needs its branch") } if f.Head == "" { return fmt.Errorf("delivery: a %s message needs its head", f.Kind) } if f.Kind == ForgeMerged && f.Merge == "" { return fmt.Errorf("delivery: a merged message needs its merge commit") } if f.Root == "" { return fmt.Errorf("delivery: a %s message needs the repository's root tree", f.Kind) } // No trees is a merge that leaves the repository with no module.json anywhere (a documents repository, or one // whose last module was removed): it is written all the same, so the indexer takes the merge in and drops the // repository's modules (novox/hq issue 1126). An older writer always sent at least one tree, so none is unambiguous; // such a message carries no manifests, locks or paths (checkInputs below: each names a directory of its trees). for dir, tree := range f.Trees { if tree == "" { return fmt.Errorf("delivery: a merged message's tree of the directory %q is empty", dir) } } if err := f.checkInputs(func(d string) bool { _, ok := f.Trees[d]; return ok }, "its trees"); err != nil { return err } case ForgeRefused: if len(f.Dirs) > 0 || f.DirsKnown { return fmt.Errorf("delivery: a refused message carries no module directories") } if len(f.Manifests) > 0 || len(f.Locks) > 0 || len(f.Paths) > 0 { return fmt.Errorf("delivery: a refused message carries no manifests, lock hashes or named paths") } if f.Act == "" { return fmt.Errorf("delivery: a refused message needs the act it answers") } if f.Words == "" { return fmt.Errorf("delivery: a refused message needs the forge's words") } } return nil } // checkInputs refuses a manifest or a lock hash of a directory that known does not know (of is what it knows them // by), an empty manifest and an empty lock path or hash, naming the directory. func (f Forge) checkInputs(known func(dir string) bool, of string) error { for dir, m := range f.Manifests { if !known(dir) { return fmt.Errorf("delivery: the manifest of the directory %q is not of %s", dir, of) } if m == "" { return fmt.Errorf("delivery: the manifest of the directory %q is empty", dir) } } for dir, locks := range f.Locks { if !known(dir) { return fmt.Errorf("delivery: the lock hashes of the directory %q are not of %s", dir, of) } for path, hash := range locks { if path == "" || hash == "" { return fmt.Errorf("delivery: the lock %q of the directory %q has an empty path or hash", path, dir) } } } for dir, paths := range f.Paths { if !known(dir) { return fmt.Errorf("delivery: the named paths of the directory %q are not of %s", dir, of) } for path, object := range paths { if path == "" || object == "" { return fmt.Errorf("delivery: the named path %q of the directory %q has an empty path or object", path, dir) } } } return nil } // checkOpen refuses an open message that names a repository, a branch, a head or anything of the other kinds, or // an open pull request that is not `/` and a number. func (f Forge) checkOpen() error { if f.Repository != "" || f.Branch != "" || f.Number != 0 || f.Head != "" || f.Action != "" || len(f.Dirs) > 0 || f.DirsKnown || f.Merge != "" || len(f.Trees) > 0 || len(f.Manifests) > 0 || len(f.Locks) > 0 || len(f.Paths) > 0 || f.Root != "" || f.Act != "" || f.Words != "" || f.Group != "" || len(f.Members) > 0 { return fmt.Errorf("delivery: an open message carries only the open pull requests it names") } for _, p := range f.Open { if err := checkRepository(p.Repository); err != nil { return err } if p.Number <= 0 { return fmt.Errorf("delivery: the open pull request of %s has no number", p.Repository) } } return nil } // EncodeForge is f as JSON at Version; it refuses a message missing what its kind needs. func EncodeForge(f Forge) ([]byte, error) { if err := f.check(); err != nil { return nil, err } f.V = Version return json.Marshal(f) } // DecodeForge reads a forge message; it refuses an unknown version (ErrUnknownVersion) and what EncodeForge refuses. func DecodeForge(data []byte) (Forge, error) { var f Forge if err := decode(data, &f); err != nil { return Forge{}, err } if err := f.check(); err != nil { return Forge{}, err } return f, nil } // SameForge says whether two forge messages are the same value. func SameForge(a, b Forge) bool { return reflect.DeepEqual(a, b) } var nameOK = regexp.MustCompile(`^[-/_=a-zA-Z0-9]+$`) // checkName refuses a name that is empty or holds a dot, a wildcard, whitespace or a character a bus key refuses // (mesh-sdk delivery's rule for a name). func checkName(kind, name string) error { if name == "" { return fmt.Errorf("delivery: the %s name is empty", kind) } if !nameOK.MatchString(name) { return fmt.Errorf("delivery: the %s name %q holds a dot, a wildcard, whitespace or a character a key refuses", kind, name) } return nil } // decode reads a value of Version, refusing another or none with keys.ErrUnknownVersion, as mesh-sdk delivery's // values are read. func decode(data []byte, into any) error { var probe struct { V *int `json:"v"` } if err := json.Unmarshal(data, &probe); err != nil { return fmt.Errorf("delivery: value is not JSON: %w", err) } if probe.V == nil { return fmt.Errorf("%w: no version in the value, this reader reads %d", keys.ErrUnknownVersion, Version) } if *probe.V != Version { return fmt.Errorf("%w: the value is version %d, this reader reads %d", keys.ErrUnknownVersion, *probe.V, Version) } if err := json.Unmarshal(data, into); err != nil { return fmt.Errorf("delivery: value does not fit its shape: %w", err) } return nil }