runtimeinstall

Documentation

Overview

Package runtimeinstall acquires and installs the external runtime binaries that Veil's managed systemd units invoke. After the plugin-based protocol refactor, protocol plugins contribute their own install descriptors via RuntimeProvider.RuntimeInstall; this package's Catalog only holds runtimes that are not tied to a protocol plugin, such as WARP (sing-box).

Veil install only writes the Panel and the dormant managed unit files; before this package, those units pointed at /usr/local/bin/<binary> paths that were never created, so every protocol failed to start with systemd status 203/EXEC ("Failed to locate executable"). This package fills that gap by downloading each runtime from its upstream GitHub release (verifying SHA256 checksums where the project publishes them) or, for runtimes that ship no release binaries, building them from source with `go install`.

Index

• func DefaultBinDir() string
• func ExtractArchiveBinary(body []byte, binary string) ([]byte, error)
• func VerifyChecksum(body []byte, assetName, binary string, checksums []byte) error
• type Asset
• type GoToolchain
  • func NewGoToolchain(cacheDir string) *GoToolchain
  • func (gt *GoToolchain) Ensure(ctx context.Context) (string, error)
• type Method
• type Options
• type Release
• type Result
  • func Install(ctx context.Context, opts Options, runtime Runtime) Result
  • func InstallAll(ctx context.Context, opts Options) []Result
• type Runtime
  • func Catalog(arch string) []Runtime

Functions

func DefaultBinDir

func DefaultBinDir() string

DefaultBinDir is the canonical install directory for runtime binaries.

func ExtractArchiveBinary

func ExtractArchiveBinary(body []byte, binary string) ([]byte, error)

ExtractArchiveBinary returns the named binary's bytes from a .tar.gz archive, matching on the base filename so archives that nest the binary in a versioned directory (sing-box) and those that don't (mieru) both work.

func VerifyChecksum

func VerifyChecksum(body []byte, assetName, binary string, checksums []byte) error

VerifyChecksum confirms body's checksum matches the value recorded for the asset. Upstream checksum files reference either the asset filename (mieru, caddy) or a build path ending in the binary name (hysteria's hashes.txt), so both forms are accepted. The digest algorithm is selected by the recorded hex length: 64 chars -> SHA-256 (mieru, hysteria), 128 chars -> SHA-512 (caddy).

Types

type Asset

type Asset struct {
	Name               string `json:"name"`
	BrowserDownloadURL string `json:"browser_download_url"`
}

Asset is a single release asset.

type GoToolchain

type GoToolchain struct {
	CacheDir string
	Version  string
	// contains filtered or unexported fields
}

GoToolchain manages a self-contained Go installation cached under CacheDir/go.

func NewGoToolchain

func NewGoToolchain(cacheDir string) *GoToolchain

func (*GoToolchain) Ensure

func (gt *GoToolchain) Ensure(ctx context.Context) (string, error)

Ensure returns the path to the go binary, downloading and installing it into the cache if necessary.

type Method

type Method string

Method describes how a runtime binary is acquired.

const (
	// MethodRawBinary downloads a single executable file directly.
	MethodRawBinary Method = "raw-binary"
	// MethodArchive downloads a .tar.gz and extracts a single named binary.
	MethodArchive Method = "archive"
	// MethodGoInstall builds the binary from source with `go install`.
	MethodGoInstall Method = "go-install"
	// MethodCaddyNaive builds Caddy from source with the klzgrad/forwardproxy
	// (naive) fork, which vanilla Caddy releases do not include.
	MethodCaddyNaive Method = "caddy-naive"
)

type Options

type Options struct {
	// BinDir is where binaries are written (default /usr/local/bin).
	BinDir string
	// CaddyCacheDir is where the Caddy build workspace is cached. Defaults to
	// a directory under the OS cache (e.g. /var/cache/veil or /tmp/veil-runtime).
	CaddyCacheDir string
	// Arch is the normalized architecture ("amd64" or "arm64").
	Arch string
	// HTTPClient performs release-metadata and download requests.
	HTTPClient *http.Client
	// FetchRelease resolves the latest release for a repo. Injectable for tests.
	FetchRelease func(ctx context.Context, repo string) (*Release, error)
	// Download fetches a URL's bytes. Injectable for tests.
	Download func(ctx context.Context, url string) ([]byte, error)
	// GoInstall builds a source package into BinDir. Injectable for tests.
	GoInstall func(ctx context.Context, binDir, sourcePackage string) error
	// BuildCaddy builds a Caddy binary with the naive forwardproxy fork.
	// Injectable for tests.
	BuildCaddy func(ctx context.Context, outPath string) error
	// EnsureGo provisions a Go toolchain if system go is unavailable, returning
	// the path to the go binary. If nil, methods requiring Go are skipped when
	// no system go is found.
	EnsureGo func(ctx context.Context) (string, error)
	// LookPath resolves an executable in PATH. Injectable for tests; defaults
	// to exec.LookPath. Used to detect whether a Go toolchain is present.
	LookPath func(string) (string, error)
	// Now supplies the clock (unused today, reserved for retry/backoff).
	Now func() time.Time
}

Options configures an installation run.

type Release

type Release struct {
	TagName string  `json:"tag_name"`
	Assets  []Asset `json:"assets"`
}

Release is a subset of the GitHub Releases API response.

type Result

type Result struct {
	Name       string
	Binary     string
	Path       string
	Method     Method
	Version    string
	Installed  bool
	Skipped    bool
	SkipReason string
	Err        error
}

Result records the outcome for a single runtime.

func Install

func Install(ctx context.Context, opts Options, runtime Runtime) Result

Install acquires and installs a single runtime binary.

func InstallAll

func InstallAll(ctx context.Context, opts Options) []Result

InstallAll installs every runtime in the catalog and returns per-runtime results. It does not stop at the first failure: each runtime is independent, so a single broken upstream release should not block the others.

type Runtime

type Runtime struct {
	// Name is the protocol-facing label (e.g. "mieru", "hysteria2").
	Name string
	// Binary is the installed binary filename under the bin directory
	// (e.g. "mita", "hysteria", "sing-box", "caddy", "olcrtc").
	Binary string
	// Method selects the acquisition strategy.
	Method Method
	// Repo is the GitHub "owner/name" for release-based methods.
	Repo string
	// AssetMatch selects the release asset for the current platform.
	AssetMatch func(assetName string) bool
	// ChecksumMatch selects the checksums asset, when the project ships one.
	ChecksumMatch func(assetName string) bool
	// SourcePackage is the Go package path for MethodGoInstall.
	SourcePackage string
	// Description is a human-readable sentence describing how the runtime is
	// acquired. It is used by the CLI to build protocol-agnostic help text.
	Description string
}

Runtime describes one protocol runtime binary Veil installs.

func Catalog

func Catalog(arch string) []Runtime

Catalog returns the runtime install descriptors for non-plugin runtimes such as WARP (sing-box). Protocol plugins supply their own descriptors via RuntimeProvider.RuntimeInstall, so they are not duplicated here.