package meshdeliveryclient import ( "bytes" "encoding/json" "fmt" "reflect" "strconv" "strings" "time" seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery" "git.novox.be/novox/mesh-sdk/go/keys" ) // The values of the seat's states `source`, `merges`, `asks`, `owed` and `turns`, in the seat's types: each is stamped // with Version when encoded, read strictly (an unknown field refused) and its version checked when decoded, and its rules // held on both sides, so the gate that writes them and the readers (the forge bridge, the teller, the assigner, the view) // agree. What the schema cannot say is written here once (ADR 0625 ยง4). // Version is the layout version of the seat's values. const Version = 1 // MergeState is the state of a pull request in a merge. type MergeState string // The states a merge's pull request is in. const ( MergeMerging MergeState = "merging" MergeMerged MergeState = "merged" MergeRefused MergeState = "refused" ) // SourceMainKey is the one key of the state source. const SourceMainKey = "main" func encodeValue(v any, check error, stamp func()) ([]byte, error) { if check != nil { return nil, check } stamp() return json.Marshal(v) } // ApprovedKey is the key, in a merge's approved heads, of a pull request: `@`. func ApprovedKey(repository string, number int) string { return repository + "@" + strconv.Itoa(number) } // TurnsKey is the key, in the state turns, of a repository: `.`, lower-case and escaped. func TurnsKey(repository string) (string, error) { repository = strings.ToLower(repository) part, err := escapeRepository(repository) if err != nil { return "", err } return strings.Replace(part, "/", ".", 1), nil } // ParseTurnsKey is the inverse of TurnsKey; a key that does not name a lower-case / is refused. func ParseTurnsKey(key string) (string, error) { owner, name, ok := strings.Cut(key, ".") if !ok || owner == "" || name == "" || strings.Contains(name, ".") { return "", fmt.Errorf("meshdeliveryclient: %q is not a turns key, .", key) } repository, err := unescapeRepository(owner + "/" + name) if err != nil { return "", fmt.Errorf("meshdeliveryclient: %q is not a turns key: %w", key, err) } if again, err := TurnsKey(repository); err != nil || again != key { return "", fmt.Errorf("meshdeliveryclient: %q is not a turns key: it does not name a lowercase /", key) } return repository, nil } // ----- source // CheckSource refuses a source naming no repository, a repository with no name or an empty head. func CheckSource(s seat.SourceByMainValue) error { if len(s.Heads) == 0 { return fmt.Errorf("meshdeliveryclient: a source names no repository") } for repository, head := range s.Heads { if repository == "" { return fmt.Errorf("meshdeliveryclient: a source names a repository with no name") } if head == "" { return fmt.Errorf("meshdeliveryclient: the source's head of %s is empty", repository) } } return nil } // EncodeSource is s as the value of the key main. func EncodeSource(s seat.SourceByMainValue) ([]byte, error) { return encodeValue(&s, CheckSource(s), func() { s.V = Version }) } // DecodeSource reads the value of the key main. func DecodeSource(data []byte) (seat.SourceByMainValue, error) { if err := keys.CheckVersion(data); err != nil { return seat.SourceByMainValue{}, err } s, err := seat.DecodeSourceByMainValue(data) if err != nil { return s, fmt.Errorf("meshdeliveryclient: a source does not fit its shape: %w", err) } return s, CheckSource(s) } // SameSource says whether two sources are the same. func SameSource(a, b seat.SourceByMainValue) bool { return reflect.DeepEqual(a, b) } // ----- merge // CheckMerge refuses a merge naming no group, ask or pull request, a pull request outside the approved heads or at // another head than the Approve was for, and a state that lacks what it needs: merged its commit, refused the forge's words. func CheckMerge(m seat.MergesByGroupValue) error { if m.Group == "" { return fmt.Errorf("meshdeliveryclient: a merge names no group") } if m.Ask == "" { return fmt.Errorf("meshdeliveryclient: a merge names no ask") } if len(m.Pulls) == 0 { return fmt.Errorf("meshdeliveryclient: a merge names no pull request") } for key, sha := range m.Approved { if sha == "" { return fmt.Errorf("meshdeliveryclient: the approved head of %s is empty", key) } } for _, p := range m.Pulls { who := fmt.Sprintf("%s#%d", p.Repository, p.Number) if len(m.Approved) > 0 { sha, ok := m.Approved[ApprovedKey(p.Repository, int(p.Number))] if !ok { return fmt.Errorf("meshdeliveryclient: the pull request %s is handed to the merge but is not among the approved heads", who) } if sha != p.Head { return fmt.Errorf("meshdeliveryclient: the pull request %s is handed at head %q but the Approve was for %q", who, p.Head, sha) } } switch MergeState(p.State) { case MergeMerging: case MergeMerged: if p.Commit == "" { return fmt.Errorf("meshdeliveryclient: the merged pull request %s has no merge commit", who) } case MergeRefused: if p.Words == "" { return fmt.Errorf("meshdeliveryclient: the refused pull request %s has no words of the forge", who) } default: return fmt.Errorf("meshdeliveryclient: the state %q of %s is not merging, merged or refused", p.State, who) } } return nil } // EncodeMerge is m as the value of a group's key. func EncodeMerge(m seat.MergesByGroupValue) ([]byte, error) { return encodeValue(&m, CheckMerge(m), func() { m.V = Version }) } // DecodeMerge reads the value of a group's key. func DecodeMerge(data []byte) (seat.MergesByGroupValue, error) { if err := keys.CheckVersion(data); err != nil { return seat.MergesByGroupValue{}, err } m, err := seat.DecodeMergesByGroupValue(data) if err != nil { return m, fmt.Errorf("meshdeliveryclient: a merge does not fit its shape: %w", err) } return m, CheckMerge(m) } // SameMerge says whether two merges are the same. func SameMerge(a, b seat.MergesByGroupValue) bool { return reflect.DeepEqual(a, b) } // ----- ask // HeadsOf are an ask's heads as Heads (for HeadsHash and MergeAskKey). func HeadsOf(items []seat.AsksByMergeGroupHeadsValueHeadsItem) []Head { out := make([]Head, len(items)) for i, h := range items { out[i] = Head{Repository: h.Repository, Number: int(h.Number), Head: h.Head} } return out } // CheckAsk refuses an ask with no group or heads, a negative count, or an ask that is no object. func CheckAsk(a seat.AsksByMergeGroupHeadsValue) error { if a.Asking < 0 { return fmt.Errorf("meshdeliveryclient: the ask's asking %d is negative", a.Asking) } if _, err := MergeAskKey(a.Group, HeadsOf(a.Heads)); err != nil { return fmt.Errorf("meshdeliveryclient: an ask needs its group and at least one pull request's head: %w", err) } raw, err := json.Marshal(a.Ask) var fields map[string]json.RawMessage if err != nil || len(bytes.TrimSpace(raw)) == 0 || json.Unmarshal(raw, &fields) != nil || fields == nil { return fmt.Errorf("meshdeliveryclient: the value carries no router's ask") } return nil } // EncodeAsk is a as the value of a merge ask's key; a.Ask may be a json.RawMessage. func EncodeAsk(a seat.AsksByMergeGroupHeadsValue) ([]byte, error) { return encodeValue(&a, CheckAsk(a), func() { a.V = Version }) } // DecodeAsk reads the value of a merge ask's key; its Ask is the router's ask as a decoded object. func DecodeAsk(data []byte) (seat.AsksByMergeGroupHeadsValue, error) { if err := keys.CheckVersion(data); err != nil { return seat.AsksByMergeGroupHeadsValue{}, err } a, err := seat.DecodeAsksByMergeGroupHeadsValue(data) if err != nil { return a, fmt.Errorf("meshdeliveryclient: an ask does not fit its shape: %w", err) } return a, CheckAsk(a) } // SameAsk says whether two asks are the same (the router's ask by its content). func SameAsk(a, b seat.AsksByMergeGroupHeadsValue) bool { return reflect.DeepEqual(a, b) } // ----- owed // EncodeOwed is o as the value of an owed key, after CheckOwed. func EncodeOwed(o seat.OwedByRepositoryNumberHeadActValue) ([]byte, error) { return encodeValue(&o, CheckOwed(o), func() { o.V = Version }) } // DecodeOwed reads the value of an owed key. func DecodeOwed(data []byte) (seat.OwedByRepositoryNumberHeadActValue, error) { if err := keys.CheckVersion(data); err != nil { return seat.OwedByRepositoryNumberHeadActValue{}, err } o, err := seat.DecodeOwedByRepositoryNumberHeadActValue(data) if err != nil { return o, fmt.Errorf("meshdeliveryclient: an owed value does not fit its shape: %w", err) } return o, CheckOwed(o) } // SameOwed says whether two owed values are the same. func SameOwed(a, b seat.OwedByRepositoryNumberHeadActValue) bool { return a == b } // ----- turns // CheckTurn refuses a turn whose repository is not lower-case, that names no delivery, or whose deliveries repeat a heads // hash, lack their times, are out of the order of the Approve, or name a wait without a verdict key. func CheckTurn(t seat.TurnsByRepositoryValue) error { repository := strings.ToLower(t.Repository) if repository != t.Repository { return fmt.Errorf("meshdeliveryclient: the turn's repository %q is not lowercase", t.Repository) } if _, err := escapeRepository(repository); err != nil { return err } if len(t.Waiting) == 0 { return fmt.Errorf("meshdeliveryclient: the turn of %s names no delivery: its key is deleted instead", t.Repository) } seen := map[string]bool{} for i, w := range t.Waiting { if w.Group == "" { return fmt.Errorf("meshdeliveryclient: a delivery in the turn of %s names no group", t.Repository) } if !hashOK.MatchString(w.Heads) { return fmt.Errorf("meshdeliveryclient: the heads hash %q in the turn of %s is not 12 lowercase hex digits", w.Heads, t.Repository) } if seen[w.Heads] { return fmt.Errorf("meshdeliveryclient: the turn of %s names the heads %s twice", t.Repository, w.Heads) } seen[w.Heads] = true if w.Approved.IsZero() || w.Since.IsZero() { return fmt.Errorf("meshdeliveryclient: the delivery %s in the turn of %s says no time of its Approve or of its wait", w.Group, t.Repository) } if i > 0 && w.Approved.Before(t.Waiting[i-1].Approved) { return fmt.Errorf("meshdeliveryclient: the turn of %s is not in the order of the Approve: %s was approved before %s", t.Repository, w.Group, t.Waiting[i-1].Group) } if w.WaitsFor != "" { if _, _, err := parseVerdictKey(w.WaitsFor); err != nil { return fmt.Errorf("meshdeliveryclient: the delivery %s in the turn of %s waits for what is not a verdict key: %w", w.Group, t.Repository, err) } } else if (w.WaitsSince != nil && !w.WaitsSince.IsZero()) || w.Step != "" { return fmt.Errorf("meshdeliveryclient: the delivery %s in the turn of %s says when and where a check runs, and names no check", w.Group, t.Repository) } } return nil } // parseVerdictKey is the checker's verdict key `.` (the checker's client has the same rule over its // own seat; a client uses its own seat's contract alone). func parseVerdictKey(key string) (group, heads string, err error) { i := strings.LastIndex(key, ".") if i < 0 || !hashOK.MatchString(key[i+1:]) || i == 0 || strings.Contains(key[:i], ".") { return "", "", fmt.Errorf("%q is not a verdict key, .", key) } if group, err = keys.UnescapeName(key[:i]); err != nil { return "", "", err } return group, key[i+1:], nil } // TurnHolds says whether a delivery at these heads is not in the turn while the turn names others: the delivery's // check or merge holds back for the one before it. func TurnHolds(t seat.TurnsByRepositoryValue, heads string) bool { if len(t.Waiting) == 0 { return false } for _, w := range t.Waiting { if w.Heads == heads { return false } } return true } // EncodeTurn is t as the value of a repository's key. func EncodeTurn(t seat.TurnsByRepositoryValue) ([]byte, error) { if err := CheckTurn(t); err != nil { return nil, err } t.V = Version return json.Marshal(t) } // DecodeTurn reads the value of a repository's key. func DecodeTurn(data []byte) (seat.TurnsByRepositoryValue, error) { if err := keys.CheckVersion(data); err != nil { return seat.TurnsByRepositoryValue{}, err } t, err := seat.DecodeTurnsByRepositoryValue(data) if err != nil { return t, fmt.Errorf("meshdeliveryclient: a turn does not fit its shape: %w", err) } return t, CheckTurn(t) } // SameTurn says whether two turns are the same, a time by the instant it names. func SameTurn(a, b seat.TurnsByRepositoryValue) bool { if len(a.Waiting) != len(b.Waiting) || a.Repository != b.Repository || a.V != b.V { return false } for i := range a.Waiting { x, y := a.Waiting[i], b.Waiting[i] if !x.Approved.Equal(y.Approved) || !x.Since.Equal(y.Since) || !sameTime(x.WaitsSince, y.WaitsSince) { return false } x.Approved, y.Approved, x.Since, y.Since, x.WaitsSince, y.WaitsSince = time.Time{}, time.Time{}, time.Time{}, time.Time{}, nil, nil if !reflect.DeepEqual(x, y) { return false } } return true } func sameTime(a, b *time.Time) bool { if a == nil || a.IsZero() { return b == nil || b.IsZero() } return b != nil && a.Equal(*b) } // Answer is the operator's answer to a merge ask as the gate acts on it: the option chosen, the warrant that proves who // answered, and the words said. It is the teller's state `answers` under the ask's key (the teller's own record; this is // its layout for the gate that reads it). type Answer struct { V int `json:"v"` Option string `json:"option"` Warrant string `json:"warrant"` Words string `json:"words"` } // CheckAnswer refuses an answer lacking its option, warrant or words. func CheckAnswer(a Answer) error { for _, f := range []struct{ name, value string }{{"option", a.Option}, {"warrant", a.Warrant}, {"words", a.Words}} { if f.value == "" { return fmt.Errorf("meshdeliveryclient: an answer has no %s", f.name) } } return nil } // EncodeAnswer is a as the value of an answer's key. func EncodeAnswer(a Answer) ([]byte, error) { return encodeValue(&a, CheckAnswer(a), func() { a.V = Version }) } // DecodeAnswer reads the value of an answer's key. func DecodeAnswer(data []byte) (Answer, error) { if err := keys.CheckVersion(data); err != nil { return Answer{}, err } var a Answer dec := json.NewDecoder(bytes.NewReader(data)) dec.DisallowUnknownFields() if err := dec.Decode(&a); err != nil { return Answer{}, fmt.Errorf("meshdeliveryclient: an answer does not fit its shape: %w", err) } return a, CheckAnswer(a) } // SameAnswer says whether two answers are the same. func SameAnswer(a, b Answer) bool { return a == b }