Files
mesh-delivery/modules/mesh-delivery-forge-bridge/forgemsg/forge.go
T
jschoubben 630c099972 B1: the forge bridge's one message, head-moved
forgemsg holds one message per move of a watched branch's head: head-moved with repository,
branch, head, before and start, on forge.<owner>.<name>.<escaped branch>.head-moved, refusing
a head equal to the one held and any field it does not have (trees, base). The messages pull,
merged, pushed, refused and open, their trees, inputs, group and members, and the group's end
forge.group.merged go; owed.ended stays.

Builds: design 47 H §739, §764 (the forge bridge: merged, pushed, base, the group's end); lead answers H-A-27, H-A-48

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:13:15 +01:00

158 lines
6.0 KiB
Go

// Package forgemsg is the forge bridge's contract on its own stream `forge` (novox/hq ADR 0633 §4): its one message per
// move of a watched branch's head (HeadMoved, design 47 H §739) and an owed act's outcome (OwedEnded). The forge bridge
// writes them; the gate reads 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 (
"bytes"
"encoding/json"
"fmt"
"regexp"
"strings"
"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"
// HeadMovedKind is the last part of a head-moved message's name.
const HeadMovedKind = "head-moved"
// HeadMoved is the bridge's one message per move of a watched branch's head (design 47 H §739): the repository as
// `<owner>/<name>`, the branch, the head the bridge read through git.branch, the head it held for that branch before
// (empty the first time) and Start, true when said at the bridge's start. It names no pull request and no tree.
type HeadMoved struct {
V int `json:"v"`
Repository string `json:"repository"`
Branch string `json:"branch"`
Head string `json:"head"`
Before string `json:"before,omitempty"`
Start bool `json:"start,omitempty"`
}
// HeadMovedEvent is the name of a head-moved message: `forge.<owner>.<name>.<escaped branch>.head-moved`, the branch
// escaped as a key's name is, so a branch holding a dot is one token (design 47 H H-A-27).
func HeadMovedEvent(repository, branch string) (string, error) {
if err := checkRepository(repository); err != nil {
return "", err
}
if branch == "" {
return "", fmt.Errorf("delivery: a head-moved message names no branch")
}
owner, name, _ := strings.Cut(repository, "/")
return "forge." + owner + "." + name + "." + keys.EscapeName(branch) + "." + HeadMovedKind, nil
}
// HeadMovedEvents is the filter of every head-moved message's name.
func HeadMovedEvents() string { return "forge.*.*.*." + HeadMovedKind }
// ParseHeadMovedEvent is the inverse of HeadMovedEvent.
func ParseHeadMovedEvent(event string) (repository, branch string, err error) {
parts := strings.Split(event, ".")
if len(parts) != 5 || parts[0] != "forge" || parts[4] != HeadMovedKind {
return "", "", fmt.Errorf("delivery: %q is not a head-moved message, forge.<owner>.<name>.<branch>.%s", event, HeadMovedKind)
}
repository = parts[1] + "/" + parts[2]
if err := checkRepository(repository); err != nil {
return "", "", fmt.Errorf("delivery: %q: %w", event, err)
}
if branch, err = keys.UnescapeName(parts[3]); err != nil || branch == "" {
return "", "", fmt.Errorf("delivery: %q: the branch part %q is no escaped name: %v", event, parts[3], err)
}
return repository, branch, nil
}
func (h HeadMoved) check() error {
if err := checkRepository(h.Repository); err != nil {
return err
}
switch {
case h.Branch == "":
return fmt.Errorf("delivery: the head-moved of %s names no branch", h.Repository)
case h.Head == "":
return fmt.Errorf("delivery: the head-moved of %s %s names no head", h.Repository, h.Branch)
case h.Head == h.Before:
return fmt.Errorf("delivery: the head-moved of %s %s names the head it held, %s: a head equal to the one held writes nothing", h.Repository, h.Branch, h.Head)
}
return nil
}
// EncodeHeadMoved is h as JSON at Version; it refuses what check refuses.
func EncodeHeadMoved(h HeadMoved) ([]byte, error) {
if err := h.check(); err != nil {
return nil, err
}
h.V = Version
return json.Marshal(h)
}
// DecodeHeadMoved reads a head-moved message; it refuses an unknown version, a field the message does not have (a tree
// or a base among them) and what EncodeHeadMoved refuses.
func DecodeHeadMoved(data []byte) (HeadMoved, error) {
var h HeadMoved
if err := decode(data, &h); err != nil {
return HeadMoved{}, err
}
if err := h.check(); err != nil {
return HeadMoved{}, err
}
return h, nil
}
// checkRepository refuses a repository that is not `<owner>/<name>`: 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 <owner>/<name>, 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)
}
return nil
}
var nameOK = regexp.MustCompile(`^[-_=a-zA-Z0-9]+$`)
// checkName refuses a name that is empty or holds a dot, a slash, 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, and a field the value's type
// does not have.
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)
}
dec := json.NewDecoder(bytes.NewReader(data))
dec.DisallowUnknownFields()
if err := dec.Decode(into); err != nil {
return fmt.Errorf("delivery: value does not fit its shape: %w", err)
}
return nil
}