// Package meshdeliveryclient holds the logic the holders and callers of the seat mesh-delivery share over its contract // (novox/hq ADR 0625 §4, ADR 0634 §2, ADR 0635 §5): the keys of its states `merges`, `asks` and `owed` and the rules their // values keep, the id the teller gives the router for an ask, and the act an ask's options bind. The gate writes them, the // forge bridge, the teller and the assigner read them; the contract's decoding is strict by schema only, so these rules are // written once here and no caller copies them. package meshdeliveryclient import ( "crypto/sha256" "encoding/hex" "fmt" "regexp" "sort" "strconv" "strings" seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery" "git.novox.be/novox/mesh-sdk/go/keys" ) // AskKindMerge is the kind of the gate's ask for a group's merge, the first part of its key. const AskKindMerge = "merge" // VerbMerge is the act an ask for a group's merge binds in its options, `mesh-delivery.merge` (Approve). const VerbMerge = "merge" // Head is one pull request at one commit: the repository as `/` and the full sha. type Head struct { Repository string `json:"repository"` Number int `json:"number"` Head string `json:"head"` } // HeadsHash is the first 12 hex digits of the sha256 over the lines `#=`, sorted and joined by a // newline: the same for every order of heads, different when any head changes. An empty list is refused. func HeadsHash(heads []Head) (string, error) { if len(heads) == 0 { return "", fmt.Errorf("meshdeliveryclient: a heads hash needs at least one pull request") } lines := make([]string, len(heads)) for i, h := range heads { lines[i] = fmt.Sprintf("%s#%d=%s", h.Repository, h.Number, h.Head) } sort.Strings(lines) sum := sha256.Sum256([]byte(strings.Join(lines, "\n"))) return hex.EncodeToString(sum[:])[:12], nil } var hashOK = regexp.MustCompile(`^[0-9a-f]{12}$`) func groupKey(group string) (string, error) { if group == "" { return "", fmt.Errorf("meshdeliveryclient: the group name is empty") } return keys.EscapeName(group), nil } // MergesKey is the key, in the state merges, of a group: ``, escaped so a branch such as `fix/1.2` keys. func MergesKey(group string) (string, error) { return groupKey(group) } // MergeAskKey is the key, in the state asks, of the ask for merging a group at these heads: `merge..`. // The teller's answer has the same key. func MergeAskKey(group string, heads []Head) (string, error) { part, err := groupKey(group) if err != nil { return "", err } hash, err := HeadsHash(heads) if err != nil { return "", err } return AskKindMerge + "." + part + "." + hash, nil } // ParseAskKey is the inverse of MergeAskKey: the kind, the group and the heads hash. func ParseAskKey(key string) (kind, group, hash string, err error) { parts := strings.Split(key, ".") if len(parts) != 3 || parts[0] != AskKindMerge { return "", "", "", fmt.Errorf("meshdeliveryclient: %q is not an ask key, merge..", key) } if parts[1] == "" { return "", "", "", fmt.Errorf("meshdeliveryclient: %q is not an ask key: the group name is empty", key) } if group, err = keys.UnescapeName(parts[1]); err != nil { return "", "", "", fmt.Errorf("meshdeliveryclient: %q is not an ask key: %w", key, err) } if !hashOK.MatchString(parts[2]) { return "", "", "", fmt.Errorf("meshdeliveryclient: %q is not an ask key: %q is not 12 hex digits", key, parts[2]) } return parts[0], group, parts[2], nil } // SettleGroupPrefix begins the group of a settle ask (novox/hq ADR 0556 clause 5): a person's ask to settle deliveries held // because their merge reached the trunk without a passing check. It is kept in the asks under MergeAskKey like a merge ask, // so the teller carries it unchanged. Git forbids a colon in a branch name, so no pull request's group ever begins with it. const SettleGroupPrefix = "settle:" // SettleGroup is the group of the settle ask of these delivery ids: the prefix and twelve hex digits of the sha256 over the // ids, sorted and joined by a newline, so the same deliveries asked again keep one key. func SettleGroup(ids []string) string { sorted := append([]string(nil), ids...) sort.Strings(sorted) sum := sha256.Sum256([]byte(strings.Join(sorted, "\n"))) return SettleGroupPrefix + hex.EncodeToString(sum[:])[:12] } // AskVerb is the act the options of an ask bind, by its group: a settle ask's `mesh-delivery.settle`, any other // `mesh-delivery.merge`. The gate composes the act with it and the teller checks a warrant against it. func AskVerb(group string) string { if strings.HasPrefix(group, SettleGroupPrefix) { return seat.Seat + "." + seat.VerbSettle } return seat.Seat + "." + VerbMerge } // AskID is the id the teller gives the router for the ask at askKey. The router's ids refuse dots, so in the readable part a // dot becomes `-` and any other byte outside letters, digits, `_` and `-` becomes `_`; that part is cut to fit, and every id // ends in `-` and the first 12 hex digits of the sha256 of the whole key, so two keys never give one id. It cannot be read // back: the teller keeps the key beside it. func AskID(askKey string) string { const most = 64 // the router's bound on an id const tail = 13 // "-" and 12 hex digits readable := []byte(askKey) for i, c := range readable { switch { case c >= 'A' && c <= 'Z', c >= 'a' && c <= 'z', c >= '0' && c <= '9': case c == '.': readable[i] = '-' default: // a slash, an equals sign or any other byte the router's id refuses readable[i] = '_' } } if len(readable) > 0 && (readable[0] == '-' || readable[0] == '_') { readable[0] = 'k' // an id starts with a letter or digit } if len(readable) > most-tail { readable = readable[:most-tail] } sum := sha256.Sum256([]byte(askKey)) return string(readable) + "-" + hex.EncodeToString(sum[:])[:12] } // AskingID is the id of the asking-th writing of the ask at askKey. Asking 0 and 1 give AskID(askKey), so the first asking's // id is unchanged; asking n of 2 or more gives the AskID form of askKey + "." + n, so each asking has an id of its own and the // router, which drops an ask under an id it keeps as a redelivery, takes each as new and an answer to an earlier asking is // never taken for a later one. func AskingID(askKey string, asking int) string { if asking < 2 { return AskID(askKey) } return AskID(askKey + "." + strconv.Itoa(asking)) } // The acts the gate owes the forge, the last part of an owed key. const ( OwedStatus = "status" OwedView = "view" OwedNote = "note" OwedComment = "comment" ) // The status contexts the mesh owes the forge. const ( StatusContextMergeGate = "mesh/merge-gate" StatusContextDelivery = "mesh/delivery" StatusContextDeliveryGroup = "mesh/delivery-group" StatusContextRepoCheck = "mesh/repo-check" StatusContextCheck = "mesh/check" ) var statusContexts = []string{StatusContextMergeGate, StatusContextDelivery, StatusContextDeliveryGroup, StatusContextRepoCheck, StatusContextCheck} // StatusContexts is the contexts, in a new slice. func StatusContexts() []string { return append([]string(nil), statusContexts...) } // The states a status the gate owes the forge may carry. var statusStates = []string{"pending", "success", "failure", "error", "warning"} func checkStatusContext(context string) error { for _, c := range statusContexts { if context == c { return nil } } return fmt.Errorf("meshdeliveryclient: the status context %q is not one of %s", context, strings.Join(statusContexts, ", ")) } // ParseOwedAct splits an owed act into its kind and, for a status, its context, for a comment its sequence as digits. The act // is `status=`, `view`, `note` or `comment.`. func ParseOwedAct(act string) (kind, context string, err error) { kind, context, hasContext := strings.Cut(act, "=") switch kind { case OwedStatus: if !hasContext { return "", "", fmt.Errorf("meshdeliveryclient: the owed act %q is a status without its context, status=", act) } if err := checkStatusContext(context); err != nil { return "", "", err } return kind, context, nil case OwedView, OwedNote: if hasContext { return "", "", fmt.Errorf("meshdeliveryclient: the owed act %q takes no context", act) } return kind, "", nil } if kind, seq, ok := strings.Cut(act, "."); ok && kind == OwedComment { if n, err := strconv.Atoi(seq); err != nil || n < 1 || strconv.Itoa(n) != seq { return "", "", fmt.Errorf("meshdeliveryclient: the owed act %q is a comment without its sequence, comment. with seq of 1 or more", act) } return OwedComment, seq, nil } return "", "", fmt.Errorf("meshdeliveryclient: the owed act %q is not status=, view, note or comment.", act) } // OwedCommentAct is the act of the seq-th comment on a head: `comment.`, seq of 1 or more, so a second comment has a key // of its own and does not overwrite the first. func OwedCommentAct(seq int) (string, error) { if seq < 1 { return "", fmt.Errorf("meshdeliveryclient: a comment's sequence is 1 or more, not %d", seq) } return OwedComment + "." + strconv.Itoa(seq), nil } func escapeRepository(repository string) (string, error) { owner, name, ok := strings.Cut(repository, "/") if !ok || owner == "" || name == "" || strings.Contains(name, "/") { return "", fmt.Errorf("meshdeliveryclient: the repository %q is not /, with exactly one slash", repository) } return keys.EscapeName(owner) + "/" + keys.EscapeName(name), nil } func unescapeRepository(part string) (string, error) { owner, name, ok := strings.Cut(part, "/") if !ok || owner == "" || name == "" || strings.Contains(name, "/") { return "", fmt.Errorf("meshdeliveryclient: the repository %q is not /, with exactly one slash", part) } o, err := keys.UnescapeName(owner) if err != nil { return "", err } n, err := keys.UnescapeName(name) if err != nil { return "", err } return o + "/" + n, nil } // OwedKey is the key, in the state owed, of an act the gate owes the forge on a pull request at a head: // `...`. The number is 0 for a commit no pull request names, and never negative. func OwedKey(repository string, number int, head, act string) (string, error) { repo, err := escapeRepository(repository) if err != nil { return "", err } if number < 0 { return "", fmt.Errorf("meshdeliveryclient: an owed key's pull request number is 0 (none) or more, not %d", number) } if err := keys.CheckName("head", head); err != nil { return "", err } if _, _, err := ParseOwedAct(act); err != nil { return "", err } return repo + "." + strconv.Itoa(number) + "." + head + "." + act, nil } // ParseOwedKey is the inverse of OwedKey; act is whole, as `status=` for a status. func ParseOwedKey(key string) (repository string, number int, head, act string, err error) { parts := strings.SplitN(key, ".", 4) // a comment's act holds a dot if len(parts) != 4 { return "", 0, "", "", fmt.Errorf("meshdeliveryclient: %q is not an owed key, ...", key) } number, convErr := strconv.Atoi(parts[1]) if convErr != nil { return "", 0, "", "", fmt.Errorf("meshdeliveryclient: %q is not an owed key: %q is not a pull request number", key, parts[1]) } if repository, err = unescapeRepository(parts[0]); err != nil { return "", 0, "", "", fmt.Errorf("meshdeliveryclient: %q is not an owed key: %w", key, err) } if _, err := OwedKey(repository, number, parts[2], parts[3]); err != nil { return "", 0, "", "", fmt.Errorf("meshdeliveryclient: %q is not an owed key: %w", key, err) } return repository, number, parts[2], parts[3], nil } // CheckOwed refuses an owed value the forge bridge could not perform: a status needs its context (one the mesh owes), a // state of the list and a target; a view and a comment need text; a note needs text and a ref. func CheckOwed(o seat.OwedByRepositoryNumberHeadActValue) error { const who = "meshdeliveryclient: " switch o.Act { case OwedStatus: if o.Context == "" { return fmt.Errorf(who + "an owed status has no context") } if err := checkStatusContext(o.Context); err != nil { return err } if o.Target == "" { return fmt.Errorf(who + "an owed status has no target") } for _, s := range statusStates { if o.State == s { return nil } } return fmt.Errorf(who+"the owed status state %q is not %s", o.State, strings.Join(statusStates, ", ")) case OwedView, OwedComment: if o.Text == "" { return fmt.Errorf(who+"an owed %s has no text", o.Act) } case OwedNote: if o.Text == "" { return fmt.Errorf(who + "an owed note has no text") } if o.Ref == "" { return fmt.Errorf(who + "an owed note has no ref") } default: return fmt.Errorf(who+"the owed act %q is not status, view, note or comment", o.Act) } return nil }