Files
mesh-catalog/modules/distribution/internal/holder/list.go
T
jschoubben 681de09f04 RG2: the registry's list pages by module and cursor; the sweep reads it page by page
oci-artifact-registry's list filters by name or module while it reads and
answers at most 768 KB a page with capped, total and the cursor next, in
order of the names; container-image-registry's answers whole as its form
says. The registry takes a removal for retention whoever asks it: the
refusal "not the sweep's" and its read of the sweep seat's holder go. The
sweep reads the list from its cursor until no page is left.

Builds: design 47 H2 §813 (7), §811, §779; H-A-350 DMC-10, H-A-399
2026-11-22 00:49:42 +01:00

167 lines
5.8 KiB
Go

package holder
// **`list`: what the store holds, through the seat** (novox/hq ADR 0632 §3). For one repository, or every repository a
// seat holds, each manifest's digest, whether it is an index and the manifests it names, the tags naming it, its size
// and whether a hold keeps it. Read from the store's own files (files.go), so a manifest no tag names is listed too. The
// two seats share one store and split it by what a manifest keeps: a manifest keeping one blob under an empty
// configuration is a bundle or an archive, oci-artifact-registry's, named by that blob as its references name it;
// every other manifest, an index included, is container-image-registry's.
import (
"context"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
"sort"
"strings"
reg "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/containerimageregistry"
)
// VerbList is the seats' verb list.
const VerbList = reg.VerbList
// StoreFiles is the store's own files as list reads them: Files in the program, a test's stand-in.
type StoreFiles interface {
List(ctx context.Context) (*Listing, error)
Manifests(ctx context.Context, l *Listing) (map[string]*Manifest, map[string]string)
}
// ListPageBytes is the most a page of oci-artifact-registry's list answers (design 47 H2 §811): 768 KB.
const ListPageBytes = 768 << 10
// ListQuery is what a list is asked: Name or Module (`<module>/*`) filter the repositories while the files are read, Next
// is the cursor a page answered, and PageBytes the most a page answers, 0 for the whole answer at once (the seat
// container-image-registry's list, whose form takes no cursor).
type ListQuery struct {
Name, Module, Next string
PageBytes int
}
// ListPage is one page of a list: its repositories in order of their names, Total the repositories the filters hold in
// all, and Next the cursor of the next page, empty at the end; Capped says the page stopped at PageBytes.
type ListPage struct {
Repositories []reg.Repository
Capped bool
Total int
Next string
}
// List is `list` on seat: the repositories it holds, or those q's filters name; a repository the seat holds nothing of is
// not named, and a name not held is an empty answer. A paged list continues after the repository its cursor names, in
// order of the names (design 47 H2 §779, §811, §813 (7)). A manifest whose content cannot be read fails the answer, by
// name: a listing missing one would read as the store not holding it.
func (v *Verbs) List(ctx context.Context, seat, caller string, q ListQuery) (ListPage, error) {
if seat != ImageSeat && seat != ArtifactSeat {
return ListPage{}, fmt.Errorf("list: %s is no seat of distribution's", seat)
}
if v.Files == nil {
return ListPage{}, errors.New("list: this process reads no store files")
}
after, err := listCursor(q.Next)
if err != nil {
return ListPage{}, err
}
l, err := v.Files.List(ctx)
if err != nil {
return ListPage{}, fmt.Errorf("list: the store's files cannot be listed: %w", err)
}
kept := &Listing{Blobs: l.Blobs, Repos: map[string]*Repo{}}
for name, r := range l.Repos {
if (q.Name == "" || name == q.Name) && (q.Module == "" || strings.HasPrefix(name, q.Module+"/")) {
kept.Repos[name] = r
}
}
l = kept
docs, unread := v.Files.Manifests(ctx, l)
if len(unread) > 0 {
keys := make([]string, 0, len(unread))
for k := range unread {
keys = append(keys, k)
}
sort.Strings(keys)
return ListPage{}, fmt.Errorf("list: %d manifests cannot be read, the first %s: %s", len(keys), keys[0], unread[keys[0]])
}
holds, err := v.Holds.List()
if err != nil {
return ListPage{}, fmt.Errorf("list: the holds cannot be read: %w", err)
}
held := map[string]bool{}
for _, h := range holds {
held[h.Key()] = true
}
out := []reg.Repository{}
for _, repo := range l.RepoNames() {
r := l.Repos[repo]
tagsAt := map[string][]string{}
for t, d := range r.Tags {
tagsAt[d] = append(tagsAt[d], t)
}
digests := make([]string, 0, len(r.Revisions))
for d := range r.Revisions {
digests = append(digests, d)
}
sort.Strings(digests)
var manifests []reg.Listed
for _, d := range digests {
m := docs[Key(repo, d)]
artifact := ""
if m.Holder() {
artifact = m.Layers[0]
}
if (artifact != "") != (seat == ArtifactSeat) {
continue
}
e := reg.Listed{Digest: d, Index: len(m.Children) > 0, Platforms: m.Children, Artifact: artifact,
Tags: tagsAt[d], Size: l.Blobs[d]}
for _, b := range m.Refs {
e.Size += l.Blobs[b]
}
sort.Strings(e.Tags)
by := d
if artifact != "" {
by = artifact // a bundle or an archive is held by the blob its references name (HoldOne)
}
e.Held = held[Hold{Seat: seat, Name: repo, Digest: by}.Key()]
manifests = append(manifests, e)
}
if len(manifests) > 0 {
out = append(out, reg.Repository{Name: repo, Manifests: manifests})
}
}
page := ListPage{Repositories: []reg.Repository{}, Total: len(out)}
size := 0
for _, r := range out {
if r.Name <= after {
continue
}
if q.PageBytes > 0 {
raw, _ := json.Marshal(r)
if size+len(raw) > q.PageBytes {
if len(page.Repositories) == 0 {
return ListPage{}, fmt.Errorf("list: the repository %s alone is over a page's %d bytes (%d)", r.Name, q.PageBytes, len(raw))
}
page.Capped = true
page.Next = base64.RawURLEncoding.EncodeToString([]byte(page.Repositories[len(page.Repositories)-1].Name))
break
}
size += len(raw)
}
page.Repositories = append(page.Repositories, r)
}
return page, nil
}
// listCursor is the repository a page's cursor continues after, "" for the first page; a cursor no page answered is refused.
func listCursor(next string) (string, error) {
if next == "" {
return "", nil
}
name, err := base64.RawURLEncoding.DecodeString(next)
if err != nil || len(name) == 0 {
return "", fmt.Errorf("list: %q is no cursor a page of list answered", next)
}
return string(name), nil
}