Skip to content

Router that virtually distributes inference across connected devices in the home.

Go
17.1 KB
Raw Blame
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

package main

import (
	"context"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"log/slog"
	"net/http"
	"net/url"
	"os"
	"os/exec"
	"path"
	"strings"
	"time"
)

// Install obtains the engine in user mode: download (checksum-verified)
// then run the declared command. No-op if already detected.
func (e *Executor) Install(ctx context.Context, engine string) error {
	st, err := e.state(engine)
	if err != nil {
		return err
	}
	st.opMu.Lock()
	defer st.opMu.Unlock()
	if ok, _ := e.Detect(engine); ok {
		e.reporter.clear(installFailedID(engine))
		e.emitInstallProgress(engine, "already-installed", 100)
		return nil
	}
	st.mu.Lock()
	port := st.port
	st.mu.Unlock()
	presence := e.reconcilePresence(ctx, engine, st, false, port, false)
	if presence.Identified {
		// A healthy service is already present even though no managed binary
		// was detected. Treat it as an external installation and never fetch a
		// second copy. reconcilePresence emits the adopted state; the terminal
		// progress event clears any remaining install-progress UI.
		e.reporter.clear(installFailedID(engine))
		e.emitInstallProgress(engine, "already-installed", 100)
		return nil
	}
	if presence.Occupied && st.plat.Runtime.modeOrDefault() == "process" {
		err := fmt.Errorf("cannot install engine %q for port %d: the port is occupied by a service that did not identify as %s; use the existing service or choose another port", engine, port, st.manifest.DisplayName)
		e.reportInstallFailed(engine, err)
		return err
	}
	inst := st.plat.Install
	if inst == nil {
		return fmt.Errorf("engine %q has no install block for this platform", engine)
	}
	if inst.ModeOrDefault() == "admin" {
		err := fmt.Errorf("engine %q declares an admin install, which is refused (engine-manager is user-mode only)", engine)
		e.reportInstallFailed(engine, err)
		return err
	}
	if err := os.MkdirAll(st.installDir, 0o755); err != nil {
		return fmt.Errorf("create install dir: %w", err)
	}

	vars := map[string]string{"install_dir": st.installDir}

	if len(inst.Script) > 0 {
		// Escape hatch: vendor-script install with no checksum. Logged
		// loudly so the weaker guarantee is never silent.
		slog.Warn("running UNPINNED script install (no checksum verification)", "engine", engine)
		e.emitInstallProgress(engine, "installing", 0)
		argv, err := resolveArgs(inst.Script, vars)
		if err != nil {
			e.reportInstallFailed(engine, err)
			return err
		}
		for i := range argv {
			argv[i] = expandPath(argv[i])
		}
		if err := e.runCommand(ctx, argv); err != nil {
			werr := fmt.Errorf("script install failed: %w", err)
			e.reportInstallFailed(engine, werr)
			return werr
		}
	} else {
		if inst.Fetch != nil {
			e.emitInstallProgress(engine, "downloading", 0)
			dp, err := e.download(ctx, engine, inst.Fetch)
			if err != nil {
				e.reportInstallFailed(engine, err)
				return err
			}
			defer os.Remove(dp)
			vars["download"] = dp
			e.emitInstallProgress(engine, "verified", 0)
		}
		if len(inst.Artifacts) > 0 {
			paths, artifactVars, err := e.downloadInstallArtifacts(ctx, engine, inst.Artifacts)
			defer removeDownloadedFiles(paths)
			if err != nil {
				e.reportInstallFailed(engine, err)
				return err
			}
			for name, downloadPath := range artifactVars {
				vars[name] = downloadPath
			}
			e.emitInstallProgress(engine, "verified", 50)
		}
		if len(inst.Run) > 0 {
			e.emitInstallProgress(engine, "installing", 0)
			args, err := resolveArgs(inst.Run, vars)
			if err != nil {
				e.reportInstallFailed(engine, err)
				return err
			}
			for i := range args {
				args[i] = expandPath(args[i])
			}
			if err := e.runCommandWithEnv(ctx, args, installCommandEnv(vars, inst.Artifacts)); err != nil {
				werr := fmt.Errorf("install command failed: %w", err)
				e.reportInstallFailed(engine, werr)
				return werr
			}
		}
	}

	if !e.waitDetect(engine, true, e.detectTimeout) {
		err := fmt.Errorf("engine %q was not detected after install", engine)
		e.reportInstallFailed(engine, err)
		return err
	}
	// Claim the install now that it is real and detected. A failure to record it
	// only costs the ability to uninstall later, so it must not fail the install.
	if err := writeInstallMarker(st.installDir, engine); err != nil {
		slog.Warn("could not record that PAIR installed this engine; uninstall will decline it", "engine", engine, "err", err)
	}
	e.reporter.clear(installFailedID(engine))
	e.emitInstallProgress(engine, "done", 100)
	e.emitState(engine)
	return nil
}

// Uninstall runs the manifest's uninstall command (user-mode), stopping
// the engine first. No-op if the engine isn't currently detected.
func (e *Executor) Uninstall(ctx context.Context, engine string) error {
	st, err := e.state(engine)
	if err != nil {
		return err
	}
	st.opMu.Lock()
	defer st.opMu.Unlock()
	if ok, _ := e.Detect(engine); !ok {
		// Already gone — by its own uninstaller, or by hand. Drop our ownership
		// claim with it: left behind, it would authorise removing a copy the
		// user installs later, which PAIR has no right to touch.
		clearInstallMarker(st.installDir)
		return e.setDesiredEnabled(engine, false)
	}
	un := st.plat.Uninstall
	if un == nil || (len(un.Run) == 0 && len(un.Remove) == 0) {
		return fmt.Errorf("engine %q has no uninstall defined for this platform", engine)
	}
	st.mu.Lock()
	binPath := st.binPath // resolved by the Detect at the top of Uninstall
	st.mu.Unlock()
	if st.plat.Runtime.modeOrDefault() == "process" && !isManagedInstallPath(binPath, st.installDir) {
		err := fmt.Errorf("cannot uninstall engine %q: its executable is outside NVPAIR's managed install directory (%s)", engine, binPath)
		e.reporter.report(serviceError{ID: uninstallFailedID(engine), Message: err.Error(), Severity: "error", Action: "none", EngineType: engine, Operation: "uninstall"})
		return err
	}
	// A command-mode engine's vendor script picks its own destination, so the
	// managed-path test above can never vouch for one. Without the install
	// marker this could be the copy the user installed themselves, holding the
	// model library they built up in it — decline rather than guess.
	if st.plat.Runtime.modeOrDefault() == "command" && !installedByPAIR(st.installDir) {
		err := fmt.Errorf("cannot uninstall engine %q: NVIDIA PAIR has no record of installing it, so it may be your own installation; remove it with %s's own uninstaller", engine, st.manifest.DisplayName)
		e.reporter.report(serviceError{ID: uninstallFailedID(engine), Message: err.Error(), Severity: "error", Action: "none", EngineType: engine, Operation: "uninstall"})
		return err
	}
	// Detect proves only that the managed image exists, not whether a process is
	// serving. Reconcile first so doStop can either stop our exact managed
	// process (including a handle-less orphan) or refuse an external owner.
	st.mu.Lock()
	port := st.port
	st.mu.Unlock()
	presence := e.reconcilePresence(ctx, engine, st, true, port, false)
	st.mu.Lock()
	ownedProcess := st.proc != nil
	st.mu.Unlock()
	if presence.Occupied && !presence.Identified && !ownedProcess {
		err := fmt.Errorf("cannot uninstall engine %q: port %d is occupied by an unidentified service", engine, port)
		e.reporter.report(serviceError{ID: uninstallFailedID(engine), Message: err.Error(), Severity: "error", Action: "none", EngineType: engine, Operation: "uninstall"})
		return err
	}
	if err := e.doStop(st, engine); err != nil {
		werr := fmt.Errorf("cannot uninstall engine %q: %w", engine, err)
		e.reporter.report(serviceError{ID: uninstallFailedID(engine), Message: werr.Error(), Severity: "error", Action: "none", EngineType: engine, Operation: "uninstall"})
		return werr
	}

	vars := st.pathVars()
	args, err := resolveArgs(un.Run, vars)
	if err != nil {
		return err
	}
	for i := range args {
		args[i] = expandPath(args[i])
	}
	targets, err := resolveArgs(un.Remove, vars)
	if err != nil {
		return err
	}
	// One attempt is the command followed by the declared removals, so a retry
	// re-runs the process-stopping command before trying the tree again — which
	// is what clears the case this retry loop exists for.
	attemptUninstall := func() error {
		if len(args) > 0 {
			if err := e.runCommand(ctx, args); err != nil {
				return err
			}
		}
		for _, target := range targets {
			if err := removeTreePreserving(target, st.modelsDir); err != nil {
				return err
			}
		}
		return nil
	}
	var runErr error
	for attempt := 1; attempt <= uninstallRetries; attempt++ {
		if runErr = attemptUninstall(); runErr == nil {
			break
		}
		if attempt < uninstallRetries {
			slog.Warn("uninstall command failed; retrying", "engine", engine, "attempt", attempt, "of", uninstallRetries, "err", runErr)
			select {
			case <-ctx.Done():
				return ctx.Err()
			case <-time.After(uninstallBackoff):
			}
		}
	}
	// Detection is the verdict, not the delete errors. Removal is best-effort
	// inside the tree, so a file the engine still holds open leaves a harmless
	// remnant while the executable itself is gone — reporting that as a failure
	// would tell the user to retry an uninstall that already worked.
	if !e.waitDetect(engine, false, e.detectTimeout) {
		uerr := fmt.Errorf("engine %q still detected after uninstall", engine)
		if runErr != nil {
			uerr = fmt.Errorf("uninstall failed after %d attempts: %w", uninstallRetries, runErr)
		}
		e.reporter.report(serviceError{ID: uninstallFailedID(engine), Message: uerr.Error(), Severity: "error", Action: "retry", EngineType: engine, Operation: "uninstall"})
		return uerr
	}
	if runErr != nil {
		slog.Warn("engine removed, but some of its files could not be deleted", "engine", engine, "err", runErr)
	}
	st.mu.Lock()
	st.binPath = ""
	st.mu.Unlock()
	clearInstallMarker(st.installDir)
	e.reporter.clear(uninstallFailedID(engine))
	e.emitState(engine)
	return e.setDesiredEnabled(engine, false)
}

// maxDownloadBytes caps a single engine download (engine installers /
// archives run large — e.g. CUDA-bundled ~2 GB — but this guards against
// an unbounded/malicious response filling the disk). A var, not a const,
// so tests can lower it.
var maxDownloadBytes int64 = 8 << 30 // 8 GiB

// uninstallRetries / uninstallBackoff bound retrying a failed uninstall
// command. A command-mode engine's daemon (e.g. LM Studio's backend) can
// outlive its `stop` and briefly hold files open, so a straight rm hits
// "directory not empty"; a short retry lets the tree settle. Vars so tests
// can shrink the backoff.
var (
	uninstallRetries = 4
	uninstallBackoff = 3 * time.Second
)

// validateDownloadURL requires engine downloads over HTTPS, with plain
// http allowed only from loopback (the live tests serve the artifact from
// a local httptest server, and a user might run a LAN mirror). This is the
// only transport protection for an unpinned (no-sha256) fetch.
func validateDownloadURL(raw string) error {
	u, err := url.Parse(raw)
	if err != nil {
		return fmt.Errorf("invalid download url %q: %w", raw, err)
	}
	if u.Hostname() == "" {
		return fmt.Errorf("download url %q must include a host", raw)
	}
	switch u.Scheme {
	case "https":
		return nil
	case "http":
		if h := u.Hostname(); h == "127.0.0.1" || h == "::1" || strings.EqualFold(h, "localhost") {
			return nil
		}
		return fmt.Errorf("download url %q must be https (plain http is allowed only from loopback)", raw)
	default:
		return fmt.Errorf("download url %q must use https", raw)
	}
}

func (e *Executor) download(ctx context.Context, engine string, f *Fetch) (string, error) {
	return e.downloadWithProgress(ctx, engine, f, func(percent int) {
		e.emitInstallProgress(engine, "downloading", percent)
	})
}

func (e *Executor) downloadInstallArtifacts(
	ctx context.Context,
	engine string,
	artifacts []InstallArtifact,
) ([]string, map[string]string, error) {
	paths := make([]string, 0, len(artifacts))
	vars := make(map[string]string, len(artifacts))
	e.emitInstallProgress(engine, "downloading", 0)
	for index, artifact := range artifacts {
		fetch := &Fetch{URL: artifact.URL, SHA256: artifact.SHA256}
		downloadPath, err := e.downloadWithProgress(ctx, engine, fetch, func(percent int) {
			e.emitInstallProgress(engine, "downloading", aggregateArtifactProgress(index, len(artifacts), percent))
		})
		if err != nil {
			return paths, vars, fmt.Errorf("download artifact %q: %w", artifact.Name, err)
		}
		paths = append(paths, downloadPath)
		vars["download_"+artifact.Name] = downloadPath
		e.emitInstallProgress(engine, "downloading", aggregateArtifactProgress(index, len(artifacts), 100))
	}
	return paths, vars, nil
}

func aggregateArtifactProgress(index, count, percent int) int {
	percent = max(0, min(percent, 100))
	start := index * 50 / count
	end := (index + 1) * 50 / count
	return start + (end-start)*percent/100
}

func removeDownloadedFiles(paths []string) {
	for _, downloadPath := range paths {
		_ = os.Remove(downloadPath)
	}
}

func installCommandEnv(vars map[string]string, artifacts []InstallArtifact) map[string]string {
	env := map[string]string{"NVPAIR_INSTALL_DIR": vars["install_dir"]}
	if downloadPath := vars["download"]; downloadPath != "" {
		env["NVPAIR_INSTALL_DOWNLOAD"] = downloadPath
	}
	for _, artifact := range artifacts {
		env["NVPAIR_INSTALL_DOWNLOAD_"+strings.ToUpper(artifact.Name)] = vars["download_"+artifact.Name]
	}
	return env
}

func (e *Executor) downloadWithProgress(
	ctx context.Context,
	engine string,
	f *Fetch,
	onProgress func(int),
) (string, error) {
	if err := validateDownloadURL(f.URL); err != nil {
		return "", err
	}
	dctx, cancel := context.WithTimeout(ctx, 30*time.Minute)
	defer cancel()
	req, err := http.NewRequestWithContext(dctx, http.MethodGet, f.URL, nil)
	if err != nil {
		return "", err
	}
	resp, err := e.client.Do(req)
	if err != nil {
		return "", fmt.Errorf("download %s: %w", f.URL, err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("download %s: HTTP %d", f.URL, resp.StatusCode)
	}

	// Preserve the URL suffix so tools that require one (notably PowerShell's
	// -File, which accepts only .ps1 files) can execute the downloaded artifact
	// directly instead of evaluating remote content inline.
	tmp, err := os.CreateTemp("", "nvpair-engine-"+engine+"-*"+path.Ext(req.URL.Path))
	if err != nil {
		return "", err
	}
	pw := &progressWriter{total: resp.ContentLength, onPct: onProgress}
	h := sha256.New()
	// Read one byte past the cap so we can detect (and reject) overflow.
	n, err := io.Copy(io.MultiWriter(tmp, h), io.TeeReader(io.LimitReader(resp.Body, maxDownloadBytes+1), pw))
	tmp.Close()
	if err != nil {
		os.Remove(tmp.Name())
		return "", fmt.Errorf("download %s: %w", f.URL, err)
	}
	if n > maxDownloadBytes {
		os.Remove(tmp.Name())
		return "", fmt.Errorf("download %s exceeds the %d-byte limit", f.URL, int64(maxDownloadBytes))
	}

	sum := hex.EncodeToString(h.Sum(nil))
	if want := strings.TrimSpace(f.SHA256); want != "" {
		if !strings.EqualFold(sum, want) {
			os.Remove(tmp.Name())
			return "", fmt.Errorf("checksum mismatch for %s: got %s, want %s", f.URL, sum, want)
		}
	} else {
		// Unpinned download: bytes are not integrity-checked, only
		// transport-secured (HTTPS, enforced above) — the same weaker
		// guarantee as a `script` install. Logged loudly, and the computed
		// digest is surfaced so a manifest author can pin it later.
		slog.Warn("UNPINNED download: manifest has no sha256, integrity not verified",
			"engine", engine, "url", f.URL, "computed_sha256", sum)
	}
	return tmp.Name(), nil
}

// runCommand executes a manifest-declared argv (an install or uninstall
// step), hiding the console window on Windows; on failure it returns the
// combined output for diagnostics.
func (e *Executor) runCommand(ctx context.Context, argv []string) error {
	return runManifestCommand(ctx, argv, nil)
}

func (e *Executor) runCommandWithEnv(ctx context.Context, argv []string, environment map[string]string) error {
	return runManifestCommand(ctx, argv, environment)
}

// runManifestCommand is independent of any Executor so the standalone
// --uninstall-managed pass can run a manifest's uninstall command without
// building the service's full runtime.
func runManifestCommand(ctx context.Context, argv []string, environment map[string]string) error {
	if len(argv) == 0 {
		return nil
	}
	cmd := exec.CommandContext(ctx, argv[0], argv[1:]...)
	if len(environment) > 0 {
		cmd.Env = os.Environ()
		for key, value := range environment {
			cmd.Env = append(cmd.Env, key+"="+value)
		}
	}
	configureSysProcAttr(cmd) // hide the console window on Windows
	out, err := cmd.CombinedOutput()
	if err != nil {
		return fmt.Errorf("%v: %s", err, strings.TrimSpace(string(out)))
	}
	return nil
}

func (e *Executor) reportInstallFailed(engine string, err error) {
	e.emitInstallFrame(engine, "failed", -1, err.Error())
	e.reporter.report(serviceError{
		ID: installFailedID(engine), Message: err.Error(),
		Severity: "error", Action: "retry", EngineType: engine, Operation: "install",
	})
}

// progressWriter counts bytes and reports integer-percent download
// progress; it satisfies io.Writer for use as a TeeReader sink.
type progressWriter struct {
	total int64
	read  int64
	last  int
	onPct func(int)
}

func (p *progressWriter) Write(b []byte) (int, error) {
	n := len(b)
	p.read += int64(n)
	if p.total > 0 && p.onPct != nil {
		pct := int(p.read * 100 / p.total)
		if pct != p.last {
			p.last = pct
			p.onPct(pct)
		}
	}
	return n, nil
}