Skip to content
quarry Artifact [3f780ba144]
Login

Artifact [3f780ba144]

Artifact 3f780ba1444d631e8f9115251c672a876bd566742f22b3f28cb0407c6b423992:


package install

import (
	"bytes"
	"context"
	"encoding/json"
	"encoding/xml"
	"errors"
	"fmt"
	"io/fs"
	"net/url"
	"path"
	"strconv"
	"strings"

	"craftdesign.group/quarry/internal/ci"
)

// RFC 0030, Without root: on macOS install is per user. Everything is
// under the user's home, the runner is a LaunchAgent, its token is a
// private file the runner reads (never the Keychain through `security`,
// which would put the value in a command line), and jobs run as the user.

const macLabelPrefix = "app.zeitforge.quarry-runner."

// macLayout is where one runner's files are.
type macLayout struct {
	home, name                                        string
	support, dir, work, program, token, log, manifest string
	launchAgents, plist, key, label                   string
}

func macLayoutOf(home, name string) macLayout {
	support := path.Join(home, "Library", "Application Support", "quarry-runner")
	dir := path.Join(support, name)
	la := path.Join(home, "Library", "LaunchAgents")
	label := macLabelPrefix + name
	return macLayout{home: home, name: name, support: support, dir: dir,
		work: path.Join(dir, "work"), program: path.Join(dir, "quarry-runner"), token: path.Join(dir, "token"),
		log: path.Join(dir, "runner.log"), manifest: path.Join(dir, "manifest.json"), key: path.Join(dir, "pickup.key"),
		launchAgents: la, plist: path.Join(la, label+".plist"), label: label}
}

// paths is what a mac install lists in its manifest, in the order
// uninstall removes them: the directory last.
func (l macLayout) paths() []string {
	return []string{l.plist, l.token, l.key, l.program, l.log, l.work, l.manifest, l.dir}
}

func (l macLayout) domain(uid int) string { return "gui/" + strconv.Itoa(uid) }

// checkMac is whether a manifest read from the user's home lists only
// what an install of its name makes: it drives removals.
func (m *Manifest) checkMac(home string) error {
	if m.Platform != "darwin" || !nameShape.MatchString(m.Name) || m.Jobs < 1 || m.Jobs > 64 {
		return fmt.Errorf("does not describe a macOS runner named %q", m.Name)
	}
	if m.Home != home {
		return fmt.Errorf("was made in %q, not in %q", m.Home, home)
	}
	l := macLayoutOf(home, m.Name)
	if m.Program != l.program {
		return fmt.Errorf("program %q is not %s", m.Program, l.program)
	}
	own := map[string]bool{}
	for _, p := range l.paths() {
		own[p] = true
	}
	for _, p := range m.Paths {
		if !own[p] {
			return fmt.Errorf("lists %q, which this install does not make", p)
		}
	}
	return nil
}

func loadMacManifest(s System, name string) (*Manifest, macLayout, error) {
	home, err := s.UserHome()
	if err != nil {
		return nil, macLayout{}, err
	}
	if !nameShape.MatchString(name) {
		return nil, macLayout{}, fmt.Errorf("%q is not a runner name", name)
	}
	l := macLayoutOf(home, name)
	raw, err := s.ReadFile(l.manifest)
	if err != nil {
		return nil, l, err
	}
	var m Manifest
	if err := json.Unmarshal(raw, &m); err != nil {
		return nil, l, fmt.Errorf("%s: %v", l.manifest, err)
	}
	if m.Name != name || m.URL == "" {
		return nil, l, fmt.Errorf("%s does not describe runner %s", l.manifest, name)
	}
	if err := m.checkMac(home); err != nil {
		return nil, l, fmt.Errorf("%s: %v", l.manifest, err)
	}
	return &m, l, nil
}

// plistText is the LaunchAgent: the runner at login, kept alive, its
// log beside it, its token read from the private file.
func plistText(m *Manifest, l macLayout) string {
	args := []string{m.Program, "--work", l.work, "--max-tasks", strconv.Itoa(m.Jobs), "--token-file", l.token}
	for _, p := range [][2]string{{"--checkout", m.Checkout}, {"--zit", m.Zit}, {"--branch", m.Branch}, {"--tasks", m.Tasks}} {
		if p[1] != "" {
			args = append(args, p[0], p[1])
		}
	}
	args = append(args, m.URL)
	esc := func(v string) string {
		var b bytes.Buffer
		xml.EscapeText(&b, []byte(v))
		return b.String()
	}
	var w strings.Builder
	w.WriteString(`<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>` + esc(l.label) + `</string>
	<key>ProgramArguments</key>
	<array>
`)
	for _, a := range args {
		w.WriteString("\t\t<string>" + esc(a) + "</string>\n")
	}
	// ProcessType Standard: with none set, macOS may treat an agent as
	// background work and throttle it, and CI jobs then run slower than
	// the same command in a terminal (a lock test's window closed under
	// the runner on a Mac mini, 2026-11-19).
	w.WriteString(`	</array>
	<key>WorkingDirectory</key>
	<string>` + esc(l.dir) + `</string>
	<key>EnvironmentVariables</key>
	<dict>
		<key>HOME</key>
		<string>` + esc(l.home) + `</string>
	</dict>
	<key>RunAtLoad</key>
	<true/>
	<key>KeepAlive</key>
	<true/>
	<key>ProcessType</key>
	<string>Standard</string>
	<key>ThrottleInterval</key>
	<integer>5</integer>
	<key>StandardOutPath</key>
	<string>` + esc(l.log) + `</string>
	<key>StandardErrorPath</key>
	<string>` + esc(l.log) + `</string>
</dict>
</plist>
`)
	return w.String()
}

func refuseRoot(s System, what string) error {
	if s.Geteuid() == 0 {
		return fmt.Errorf("%s as yourself, not as root: a macOS runner is per user, and its jobs run as you", what)
	}
	return nil
}

func installDarwin(ctx context.Context, e Env, forge *url.URL, repo, repoURL string, o installOpts) error {
	s := e.Sys
	if err := refuseRoot(s, "install"); err != nil {
		return err
	}
	if _, err := s.LookPath("launchctl"); err != nil {
		return errors.New("launchctl is not installed")
	}
	home, err := s.UserHome()
	if err != nil {
		return err
	}
	if err := forgeReachable(ctx, e, forge); err != nil {
		return err
	}
	name := Name(ci.GroupFor(repo))
	l := macLayoutOf(home, name)
	m := &Manifest{Version: e.Version, URL: repoURL, Repo: repo, Name: name, Jobs: o.jobs,
		Checkout: o.checkout, Zit: o.zit, Branch: o.branch, Tasks: o.tasks, Program: l.program, Platform: "darwin", Home: home}

	haveToken := strings.TrimSpace(e.Getenv("QUARRY_RUNNER_TOKEN"))
	if haveToken == "" {
		if raw, err := s.ReadFile(l.token); err == nil {
			haveToken = strings.TrimSpace(string(raw))
		}
	}
	redeemCode, wantRequest := "", false
	if haveToken == "" {
		if redeemCode, err = installCode(e, o.code); err != nil {
			return err
		}
		wantRequest = redeemCode == ""
	}
	if prev, _, _ := loadMacManifest(s, name); prev != nil {
		m.TokenID = prev.TokenID
	}

	tx := &txn{}
	b := &builder{s: s, m: m, tx: tx}
	if err := b.createMac(l); err != nil {
		tx.rollback()
		return err
	}
	token := haveToken
	if redeemCode != "" || wantRequest {
		var group string
		if wantRequest {
			if token, m.TokenID, err = b.request(ctx, e, forge, l.key, "", ""); err != nil {
				tx.rollback()
				return err
			}
		} else if token, m.TokenID, group, err = redeem(ctx, e, forge, repo, redeemCode, o.label); err != nil {
			tx.rollback()
			return fmt.Errorf("redeeming the install code: %w", err)
		}
		created := tx
		tx = &txn{}
		switch {
		case !tokenShape.MatchString(token):
			return b.refuseTokenMac(ctx, e, forge, created, "", "the forge answered with something that is not a worker token")
		case group != "" && Name(group) != name:
			return b.refuseTokenMac(ctx, e, forge, created, token, fmt.Sprintf("the forge's worker group %q is not the one this install was made for (%s)", group, name))
		}
	}
	after := func(err error) error {
		return fmt.Errorf("%w; the token is kept in %s, read `quarry-runner doctor %s` to see what is wrong", err, l.token, name)
	}
	if err := b.file(l.token, []byte(token+"\n"), "", "", 0o600); err != nil {
		return after(err)
	}
	if err := b.macManifest(l); err != nil {
		return after(err)
	}
	dom := l.domain(s.Geteuid())
	// A second install repairs the first: what is loaded is taken out
	// first, and its absence is not a failure.
	s.Run(ctx, "launchctl", "bootout", dom+"/"+l.label)
	if _, err := s.Run(ctx, "launchctl", "bootstrap", dom, l.plist); err != nil {
		return after(err)
	}
	fmt.Fprintf(e.Out, "installed %s; jobs run as you (macOS has no job users), so this runner takes no job that uses secrets; install as root on Linux for that\nchecking it\n", l.label)
	return Doctor(ctx, e, []string{name})
}

// createMac makes the files of a mac install, except the token.
func (b *builder) createMac(l macLayout) error {
	for _, d := range []string{l.support, l.launchAgents} {
		mode := fs.FileMode(0o700)
		if d == l.launchAgents {
			mode = 0o755
		}
		if err := b.sharedDirAs(d, "", "", mode); err != nil {
			return err
		}
	}
	for _, d := range []string{l.dir, l.work} {
		if err := b.dir(d, "", "", 0o700); err != nil {
			return err
		}
	}
	if err := b.programCopyTo(l.program, "", ""); err != nil {
		return err
	}
	if err := b.file(l.plist, []byte(plistText(b.m, l)), "", "", 0o644); err != nil {
		return err
	}
	return b.macManifest(l)
}

func (b *builder) macManifest(l macLayout) error {
	b.m.Paths = nil
	for _, p := range l.paths() {
		if p != l.key {
			addOnce(&b.m.Paths, p)
		}
	}
	raw, err := json.MarshalIndent(b.m, "", "  ")
	if err != nil {
		return err
	}
	return b.file(l.manifest, append(raw, '\n'), "", "", 0o644)
}

// refuseTokenMac is refuseToken for a mac install.
func (b *builder) refuseTokenMac(ctx context.Context, e Env, forge *url.URL, created *txn, token, why string) error {
	m := b.m
	if token != "" {
		host, _ := e.Sys.Hostname()
		err := postJSON(ctx, e.client(), forge.Scheme+"://"+forge.Host+"/api/v1/r/"+url.PathEscape(m.Repo)+"/ci/worker-tokens/retire", "",
			map[string]string{"token": token, "host": host}, nil)
		if err == nil {
			created.rollback()
			return fmt.Errorf("%s; the token it minted was retired and nothing is left installed; ask for a new one", why)
		}
		l := macLayoutOf(m.Home, m.Name)
		if werr := b.file(l.token, []byte(token+"\n"), "", "", 0o600); werr == nil && b.macManifest(l) == nil {
			return fmt.Errorf("%s, and the token could not be retired (%v); it is kept in %s, read `quarry-runner doctor %s`, or uninstall", why, err, l.token, m.Name)
		}
	}
	created.rollback()
	return fmt.Errorf("%s; its token (id %s) could not be retired: revoke it in the repository's Settings, Worker tokens", why, m.TokenID)
}

// macNames are the runners installed for this user.
func macNames(s System) []string {
	home, err := s.UserHome()
	if err != nil {
		return nil
	}
	support := path.Join(home, "Library", "Application Support", "quarry-runner")
	names, _ := s.ReadDir(support)
	var out []string
	for _, n := range names {
		if nameShape.MatchString(n) && s.Exists(macLayoutOf(home, n).manifest) {
			out = append(out, n)
		}
	}
	return out
}

func uninstallDarwin(ctx context.Context, e Env, name string) error {
	s := e.Sys
	if err := refuseRoot(s, "uninstall"); err != nil {
		return err
	}
	m, l, err := loadMacManifest(s, name)
	if err != nil {
		return fmt.Errorf("no manifest, so nothing is known to remove: %w", err)
	}
	dom := l.domain(s.Geteuid())
	if _, err := s.Run(ctx, "launchctl", "bootout", dom+"/"+l.label); err != nil {
		fmt.Fprintf(e.Out, "could not stop %s: %v\n", l.label, err)
	}
	var retireErr error
	token := ""
	if raw, err := s.ReadFile(l.token); err == nil {
		token = strings.TrimSpace(string(raw))
	}
	switch {
	case token != "":
		if u, err := url.Parse(m.URL); err == nil {
			host, _ := s.Hostname()
			retireErr = postJSON(ctx, e.client(), u.Scheme+"://"+u.Host+"/api/v1/r/"+url.PathEscape(m.Repo)+"/ci/worker-tokens/retire", "",
				map[string]string{"token": token, "host": host}, nil)
		} else {
			retireErr = err
		}
	case m.TokenID != "":
		retireErr = errors.New("the token file holds no token to retire it with")
	}
	for _, p := range m.Paths {
		if p == l.work {
			if err := s.RemoveAll(p); err != nil {
				return err
			}
			continue
		}
		// A file, or the directory once it is empty: what is not the
		// manifest's stays.
		if err := s.Remove(p); err != nil && p != l.dir {
			return err
		}
	}
	s.Remove(l.support)
	if retireErr != nil {
		return fmt.Errorf("removed, but the forge did not retire the worker token (id %s): %v; revoke it in the repository's Settings, Worker tokens", m.TokenID, retireErr)
	}
	fmt.Fprintf(e.Out, "uninstalled %s\n", name)
	return nil
}

// runChecksDarwin is doctor on macOS.
func runChecksDarwin(ctx context.Context, e Env, name string) []Check {
	s := e.Sys
	var out []Check
	add := func(label, status, detail string) {
		out = append(out, Check{N: len(out) + 1, Name: label, Status: status, Detail: detail})
	}
	m, l, merr := loadMacManifest(s, name)
	if merr != nil {
		add(macCheckNames[0], statFail, merr.Error())
		for _, label := range macCheckNames[1:] {
			add(label, statFail, "needs the manifest")
		}
		return out
	}
	add(macCheckNames[0], statOK, l.manifest)
	st, detail := program2(ctx, e, m)
	add(macCheckNames[1], st, detail)

	// The agent is loaded in this user's domain.
	st, detail = statOK, ""
	if _, err := s.Run(ctx, "launchctl", "print", l.domain(s.Geteuid())+"/"+l.label); err != nil {
		st, detail = statFail, l.label+" is not loaded; run install again"
	}
	add(macCheckNames[2], st, detail)

	// The token file: private to the user, and holding a token.
	token := ""
	info, err := s.Stat(l.token)
	switch {
	case err != nil:
		add(macCheckNames[3], statFail, l.token+" is missing")
	case info.Mode != 0o600:
		add(macCheckNames[3], statFail, fmt.Sprintf("%s is %04o, want 0600", l.token, info.Mode))
	default:
		if raw, err := s.ReadFile(l.token); err == nil {
			token = strings.TrimSpace(string(raw))
		}
		if token == "" {
			add(macCheckNames[3], statFail, l.token+" holds no token")
		} else {
			add(macCheckNames[3], statOK, "")
		}
	}

	var bad []string
	for _, w := range []string{l.dir, l.work} {
		if info, err := s.Stat(w); err != nil || !info.IsDir {
			bad = append(bad, w+" is missing")
		} else if info.Mode != 0o700 {
			bad = append(bad, fmt.Sprintf("%s is %04o, want 0700", w, info.Mode))
		}
	}
	if !s.Exists(l.plist) {
		bad = append(bad, l.plist+" is missing")
	}
	if len(bad) > 0 {
		add(macCheckNames[4], statFail, strings.Join(bad, ", "))
	} else {
		add(macCheckNames[4], statOK, "")
	}

	forgeOK := false
	if u, err := url.Parse(m.URL); err != nil {
		add(macCheckNames[5], statFail, err.Error())
		add(macCheckNames[6], statFail, "needs the forge")
	} else {
		if status, err := get(ctx, e, u.Scheme+"://"+u.Host+"/api/v1"); err != nil {
			add(macCheckNames[5], statFail, firstLine(err.Error()))
		} else if status != 200 {
			add(macCheckNames[5], statFail, fmt.Sprintf("answered %d", status))
		} else {
			forgeOK = true
			add(macCheckNames[5], statOK, "")
		}
		switch {
		case token == "":
			add(macCheckNames[6], statFail, "no token to try")
		case !forgeOK:
			add(macCheckNames[6], statFail, "the forge did not answer")
		default:
			bs, bd := bridge(ctx, e, m, token)
			add(macCheckNames[6], bs, bd)
		}
	}

	switch has, err := e.Trunk(ctx, m.URL); {
	case err != nil:
		add(macCheckNames[7], statWarn, "could not read trunk: "+firstLine(err.Error()))
	case !has:
		add(macCheckNames[7], statWarn, "nothing to run yet")
	default:
		add(macCheckNames[7], statOK, "")
	}

	if m.Checkout == "zit" {
		bin := m.Zit
		if bin == "" {
			bin = "zit"
		}
		if _, err := s.Run(ctx, bin, "version"); err != nil {
			add(macCheckNames[8], statFail, bin+" does not run")
		} else {
			add(macCheckNames[8], statOK, bin)
		}
	} else {
		add(macCheckNames[8], statOK, "not used")
	}

	if free, err := s.DiskFree(l.work); err != nil {
		add(macCheckNames[9], statWarn, err.Error())
	} else if free < 1<<30 {
		add(macCheckNames[9], statWarn, fmt.Sprintf("%d MB free", free>>20))
	} else {
		add(macCheckNames[9], statOK, fmt.Sprintf("%d GB free", free>>30))
	}
	return out
}

var macCheckNames = []string{"manifest", "program", "agent", "token", "files", "forge", "bridge", "trunk", "zit", "disk"}