llmgw/internal/web/admin_mirror.go

package web

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"sort"
	"strconv"
	"strings"
	"time"

	"gitea.mynodes.xyz/ilker/llmgw/internal/hf"
	"gitea.mynodes.xyz/ilker/llmgw/internal/mirror"
	"gitea.mynodes.xyz/ilker/llmgw/internal/sourcecheck"
	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
)

// MirrorAdmin is the mirror's management API as this page needs it.
//
// An interface rather than the client itself so the page can be tested without
// a mirror, and so a deployment without one leaves it nil and the page
// unmounted — the same shape the cluster dashboard uses.
type MirrorAdmin interface {
	List(ctx context.Context) (mirror.ModelsResponse, error)
	Fetch(ctx context.Context, req mirror.FetchRequest) (mirror.FetchResponse, error)
	Remove(ctx context.Context, model, version string) ([]string, error)
	// Addr is the mirror this points at, shown on the page because an operator
	// looking at an empty table needs to know which machine is empty.
	Addr() string
}

// Registry is the model registry the explorer browses. Nil leaves the explorer
// off, which is right for a deployment with no way out to the internet: a
// search box that can only time out is worse than no search box.
type Registry interface {
	Search(ctx context.Context, query string, limit int) ([]hf.Model, error)
	Repo(ctx context.Context, id string) (hf.Repo, error)
}

// repoSet is one thing worth fetching: a file, or every shard of one.
type repoSet struct {
	hf.FileSet
	// Sources are every file in the set, in the order the registry listed them.
	// A shard set goes as one action — a fifteen-shard model is not fifteen
	// decisions, it is one.
	Sources []repoSource
	// Model and Version are what the fetch form starts with. Editable, because
	// the name a catalog entry uses is the operator's to choose and the
	// registry's idea of it is only a good guess.
	Model   string
	Version string
}

type repoSource struct{ URL, Path string }

// mirrorRow is one model version as the page shows it.
type mirrorRow struct {
	mirror.Status
	// URL is what a catalog entry should say. The one string on this page
	// somebody will copy, so it is rendered rather than left to be assembled.
	URL     string
	Percent int
	// Serve is the offer to put this version into service, open on the row the
	// operator clicked. Nil on a row that is still arriving: a catalog entry
	// pointing at a partial file is the thing versioned paths exist to prevent.
	Serve *serveForm

	// HasPercent is false when the upstream never sent a length. The bar is
	// then not drawn at all: a progress bar that has to invent its own total is
	// worse than a byte count that only goes up.
	HasPercent bool
}

type adminMirrorData struct {
	Addr string
	Base string
	Rows []mirrorRow

	Fetching int
	Present  int
	Failed   int

	// Unreachable separates "the mirror holds nothing" from "the mirror did not
	// answer". They render almost identically and mean opposite things: one is
	// a mirror waiting to be filled, the other is a machine to go and look at.
	Unreachable bool

	// HasCatalog is false where the catalogue cannot be changed at runtime, and
	// the serve action is then not offered rather than offered and refused.
	HasCatalog bool

	// The explorer.
	HasRegistry bool
	Query       string
	Results     []hf.Model
	Repo        *hf.Repo
	RepoSets    []repoSet
	RegistryErr string

	Message string
	Error   string
	CSRF    string
	Version string
	Now     string
	// RefreshSec is 0 when nothing is downloading. The page reloads only while
	// there is something to watch, because a reload while an operator is typing
	// a source URL into the form takes the URL with it.
	RefreshSec int
}

// RegisterAdminMirror mounts the model mirror under /admin/mirror.
//
// Fetching and removing, and nothing else. What the mirror holds is operator
// state rather than account state, but the reasoning is the same as
// /admin/users: these two are the work somebody does repeatedly and should not
// need a shell for, while anything that would let a stolen session reach
// further — pointing the control plane at a different mirror, say — stays in
// configuration where changing it means access to the host.
// MirrorDeps is what the mirror page can reach.
//
// A struct rather than five parameters: three of them are optional interfaces
// and two are the same shape, which at a call site is a swap nobody notices
// until a page shows the wrong thing.
type MirrorDeps struct {
	Mirror MirrorAdmin
	// Registry browses a model registry. Nil turns the explorer off.
	Registry Registry
	// Catalog puts a mirrored model into service. Nil leaves the serve action
	// off, which is right where the catalogue cannot be changed at runtime.
	Catalog CatalogAdmin
	// Fleet is the cluster, for saying whether anything could run a model
	// before somebody spends an hour downloading it.
	Fleet Source
}

func (p *AccountPages) RegisterAdminMirror(mux *http.ServeMux, d MirrorDeps) {
	m := d.Mirror
	p.hasMirror = true
	p.registry = d.Registry
	p.catalog = d.Catalog
	p.fleet = d.Fleet

	mux.HandleFunc("GET /admin/mirror", p.adminOnly(
		func(w http.ResponseWriter, r *http.Request, _ store.User) {
			p.renderMirror(w, r, m, "", "")
		}))

	mux.HandleFunc("POST /admin/mirror/fetch", p.mirrorAction(m,
		func(ctx context.Context, admin store.User, r *http.Request) (string, error) {
			// One form posts one source or fifteen. A sharded model is one
			// decision, not one per shard, and the mirror fetches each file
			// independently anyway.
			sources, files := r.Form["source"], r.Form["file"]
			if len(sources) == 0 || strings.TrimSpace(sources[0]) == "" {
				return "", errors.New("a source URL is required")
			}
			model := strings.TrimSpace(r.FormValue("model"))
			version := strings.TrimSpace(r.FormValue("version"))

			var started int
			for i, src := range sources {
				src = strings.TrimSpace(src)
				if src == "" {
					continue
				}
				req := mirror.FetchRequest{Source: src, Model: model, Version: version}
				if i < len(files) {
					req.File = strings.TrimSpace(files[i])
				}
				if _, err := m.Fetch(ctx, req); err != nil {
					// Reported with what already went, so a set that fails on
					// its fourth shard does not read as though nothing started.
					return "", fmt.Errorf("%d of %d started, then %s: %w",
						started, len(sources), mirror.LastPathElement(src), err)
				}
				started++
			}
			// Named as started, not as done. The mirror answered 202 and the
			// bytes are still moving; a message saying "added" would invite
			// somebody to point the catalog at a partial file.
			return fmt.Sprintf("started downloading %s/%s (%s)",
				model, version, plural(started, "file", "files")), nil
		}))

	if d.Catalog != nil {
		mux.HandleFunc("POST /admin/mirror/serve", p.mirrorAction(m,
			func(ctx context.Context, admin store.User, r *http.Request) (string, error) {
				model, err := buildModel(r.FormValue)
				if err != nil {
					return "", err
				}
				// The same check `llmgw ctl model add` makes. This page builds
				// the source out of a row the mirror reported, so it is right
				// far more often than something typed — but a file removed
				// between the listing and the click, or a mirror that has gone
				// down since, both end as a replica failing on a node minutes
				// later with an error naming the node. Asking costs one HEAD.
				if _, err := sourcecheck.Check(ctx, model.Source); err != nil {
					return "", err
				}
				if err := d.Catalog.Add(ctx, model, admin.Email); err != nil {
					return "", err
				}
				// Placed on the next pass, not now: saying it is serving would
				// be wrong for however long the weights take to reach a node.
				return fmt.Sprintf(
					"%s added to the catalog, %s; it is placed on the next pass",
					model.Name, plural(model.Scaling.Min, "replica", "replicas")), nil
			}))
	}

	mux.HandleFunc("POST /admin/mirror/{model}/{version}/remove", p.mirrorAction(m,
		func(ctx context.Context, _ store.User, r *http.Request) (string, error) {
			model, ver := r.PathValue("model"), r.PathValue("version")
			removed, err := m.Remove(ctx, model, ver)
			if err != nil {
				return "", err
			}
			return "removed " + model + "/" + ver +
				" (" + plural(len(removed), "file", "files") + ")", nil
		}))
}

// mirrorAction wraps a change: admin session, CSRF, audit line, re-render.
//
// The audit line is not optional. Removing a version deletes weights every node
// may be about to fetch, and the only record that it happened on purpose is
// this log entry naming who clicked it.
func (p *AccountPages) mirrorAction(m MirrorAdmin,
	do func(ctx context.Context, admin store.User, r *http.Request) (string, error),
) http.HandlerFunc {
	return p.adminOnly(func(w http.ResponseWriter, r *http.Request, admin store.User) {
		sess, _, _ := p.session(r)
		if !p.accounts.CheckCSRF(sess, r.FormValue("csrf")) {
			http.Error(w, "bad request", http.StatusBadRequest)
			return
		}
		msg, err := do(r.Context(), admin, r)
		if err != nil {
			p.log.Warn("a mirror action was refused",
				"admin", admin.Email, "mirror", m.Addr(), "err", err)
			p.renderMirror(w, r, m, "", err.Error())
			return
		}
		p.log.Info("the mirror was changed",
			"admin", admin.Email, "mirror", m.Addr(), "what", msg)
		p.renderMirror(w, r, m, msg, "")
	})
}

func (p *AccountPages) renderMirror(w http.ResponseWriter, r *http.Request,
	m MirrorAdmin, msg, errMsg string,
) {
	d := adminMirrorData{
		Addr:    m.Addr(),
		Message: msg,
		Error:   errMsg,
		CSRF:    csrfFor(r),
		Version: p.version,
		Now:     time.Now().UTC().Format(time.RFC3339),
	}

	d.HasCatalog = p.catalog != nil
	p.explore(r, &d)

	got, err := m.List(r.Context())
	if err != nil {
		p.log.Error("could not read the mirror", "mirror", m.Addr(), "err", err)
		d.Unreachable = true
		if d.Error == "" {
			d.Error = err.Error()
		}
		render(w, "admin_mirror", d)
		return
	}

	d.Base = got.Base
	for _, st := range got.Models {
		row := mirrorRow{
			Status: st,
			URL: mirror.Entry{Model: st.Model, Version: st.Version, File: st.File}.
				URL(got.Base),
		}
		if pc, ok := st.Percent(); ok {
			row.Percent, row.HasPercent = pc, true
		}
		switch st.State {
		case mirror.Fetching:
			d.Fetching++
		case mirror.Failed:
			d.Failed++
		default:
			d.Present++
		}
		d.Rows = append(d.Rows, row)
	}

	// The one row whose serve form is open, and only when the catalog can be
	// changed at all.
	if p.catalog != nil {
		if want := r.URL.Query().Get("serve"); want != "" {
			byVersion := map[string][]mirror.Status{}
			for _, st := range got.Models {
				byVersion[st.Model+"/"+st.Version] = append(byVersion[st.Model+"/"+st.Version], st)
			}
			for i := range d.Rows {
				key := d.Rows[i].Model + ":" + d.Rows[i].Version
				if key != want || d.Rows[i].State != mirror.Present {
					continue
				}
				form := planServe(d.Rows[i].Status,
					byVersion[d.Rows[i].Model+"/"+d.Rows[i].Version], got.Base, p.fleet, p.catalog)
				d.Rows[i].Serve = &form
				break
			}
		}
	}

	// Downloads first, then failures, then what is simply here. The two states
	// somebody opened this page for are at the top; the rest is a list they
	// scroll. Within a state the order is fixed so rows do not shuffle between
	// reloads while a byte count ticks.
	sort.SliceStable(d.Rows, func(i, j int) bool {
		a, b := d.Rows[i], d.Rows[j]
		if ra, rb := mirrorRank(a.State), mirrorRank(b.State); ra != rb {
			return ra < rb
		}
		if a.Model != b.Model {
			return a.Model < b.Model
		}
		if a.Version != b.Version {
			return a.Version < b.Version
		}
		return a.File < b.File
	})

	if d.Fetching > 0 {
		d.RefreshSec = 5
	}
	render(w, "admin_mirror", d)
}

func mirrorRank(s mirror.State) int {
	switch s {
	case mirror.Fetching:
		return 0
	case mirror.Failed:
		return 1
	default:
		return 2
	}
}

func plural(n int, one, many string) string {
	if n == 1 {
		return "1 " + one
	}
	return strconv.Itoa(n) + " " + many
}

// explore fills in the registry half of the page: a search, or one repository.
//
// A failure here is reported in its own line rather than as the page's error.
// The registry is somebody else's server on the other side of the internet, and
// it being down says nothing about the mirror — which is the thing this page is
// actually for, and which must keep working when Hugging Face does not.
func (p *AccountPages) explore(r *http.Request, d *adminMirrorData) {
	if p.registry == nil {
		return
	}
	d.HasRegistry = true
	d.Query = strings.TrimSpace(r.URL.Query().Get("q"))

	if repo := strings.TrimSpace(r.URL.Query().Get("repo")); repo != "" {
		got, err := p.registry.Repo(r.Context(), repo)
		if err != nil {
			d.RegistryErr = err.Error()
			return
		}
		d.Repo = &got
		var weights []hf.File
		for _, f := range got.Files {
			if !f.IsWeights() {
				// Thirty files of which four are worth gigabytes. The rest are
				// a README and a tokenizer, and listing them buries the ones
				// somebody came for.
				continue
			}
			weights = append(weights, f)
		}
		for _, set := range hf.Group(weights) {
			rs := repoSet{
				FileSet: set,
				Model:   defaultModelName(got.ID),
				// The revision, not the date: two fetches of the same commit
				// land in the same place, and a repository re-uploaded under
				// the same branch lands somewhere else.
				Version: got.ShortRevision(),
			}
			for _, f := range set.Files {
				rs.Sources = append(rs.Sources,
					repoSource{URL: got.DownloadURL("", f.Path), Path: f.Path})
			}
			d.RepoSets = append(d.RepoSets, rs)
		}
		return
	}

	if d.Query != "" {
		got, err := p.registry.Search(r.Context(), d.Query, 20)
		if err != nil {
			d.RegistryErr = err.Error()
			return
		}
		d.Results = got
	}
}

// defaultModelName is the catalog name a repository suggests.
//
// The last element, lowercased, with the quantisation marker dropped: the owner
// is not part of what anybody calls the model, and "-GGUF" describes the file
// format rather than the model, which is already clear from the file being
// fetched.
func defaultModelName(repoID string) string {
	name := mirror.LastPathElement(repoID)
	name = strings.TrimSuffix(name, "-GGUF")
	name = strings.TrimSuffix(name, "-gguf")
	return strings.ToLower(name)
}