toolchain

Documentation

Overview

Package toolchain resolves, verifies, and caches Pawn compilers.

Index

• Variables
• func DefaultCacheDir() (string, error)
• func FindCompiler(lookup PathLookup, candidates ...string) (string, error)
• type CacheFS
• type Clock
• type CompilerArchive
• type CompilerArtifact
  • func (artifact CompilerArtifact) ResolveOptions() ResolveOptions
• type CompilerExecutable
• type CompilerSource
• type Coordinate
• type Downloader
• type HTTPDownloader
  • func (d HTTPDownloader) Download(ctx context.Context, rawURL string) (io.ReadCloser, error)
• type Index
  • func LoadIndex(reader io.Reader, expectedChecksum string) (Index, error)
  • func (index Index) Select(vendor Vendor, version, target string) (CompilerArtifact, error)
• type Info
• type NoNetworkDownloader
  • func (NoNetworkDownloader) Download(context.Context, string) (io.ReadCloser, error)
• type OSCacheFS
  • func (OSCacheFS) MkdirAll(path string) error
  • func (OSCacheFS) RemoveAll(path string) error
  • func (OSCacheFS) Rename(oldPath, newPath string) error
  • func (OSCacheFS) WriteFile(path string, content []byte) error
• type OSPathLookup
  • func (OSPathLookup) LookPath(name string) (string, error)
• type PathLookup
• type Platform
  • func (p Platform) String() string
• type ResolveOptions
• type Resolver
  • func NewResolver(fsys CacheFS, cacheDir string, downloader Downloader, clock Clock) *Resolver
  • func (r *Resolver) List() ([]Info, error)
  • func (r *Resolver) Resolve(ctx context.Context, opts ResolveOptions) (Info, error)
  • func (r *Resolver) Update(ctx context.Context, opts ResolveOptions) (Info, error)
• type SystemClock
  • func (SystemClock) Now() int64
• type Vendor

Variables

var (
	// ErrOffline is returned when a resolution requires a download and
	// none is available (no Downloader configured, or Offline was set).
	ErrOffline = errors.New("toolchain: no network downloader configured (offline)")

	// ErrNotFound is returned when Resolve cannot locate a compiler by any
	// configured mode.
	ErrNotFound = errors.New("toolchain: no compiler could be resolved")

	// ErrChecksumMismatch is returned when a downloaded or locally
	// configured artifact's checksum does not match the expected value.
	ErrChecksumMismatch = errors.New("toolchain: checksum mismatch")

	// ErrInvalidCoordinate is returned for an unsupported vendor or unsafe
	// version string.
	ErrInvalidCoordinate = errors.New("toolchain: invalid toolchain coordinate")

	// ErrDownloadURLRequired is returned when a download is needed but the
	// caller did not provide an artifact URL.
	ErrDownloadURLRequired = errors.New("toolchain: download URL required")
)

var ErrArchiveTooLarge = errors.New("toolchain: archive exceeds extraction limits")

ErrArchiveTooLarge is returned when an archive exceeds the file-count or total-byte extraction limits.

var ErrArchiveTraversal = errors.New("toolchain: archive entry escapes extraction root")

ErrArchiveTraversal is returned when a zip entry's name would extract outside the destination directory.

Functions

func DefaultCacheDir

func DefaultCacheDir() (string, error)

DefaultCacheDir returns the user cache directory for Pawn toolchains.

func FindCompiler

func FindCompiler(lookup PathLookup, candidates ...string) (string, error)

FindCompiler returns the first compiler found in candidate order.

Types

type CacheFS

type CacheFS interface {
	fsx.FS
	MkdirAll(path string) error
	RemoveAll(path string) error
	Rename(oldPath, newPath string) error
	WriteFile(path string, content []byte) error // WriteFile stores content without making it executable.
}

CacheFS adds the writes needed by the toolchain cache.

type Clock

type Clock interface {
	Now() int64 // Unix seconds
}

Clock provides Unix time for cache operations.

type CompilerArchive

type CompilerArchive struct {
	URL      string `json:"url"`
	Format   string `json:"format"`
	Size     int64  `json:"size"`
	Checksum string `json:"checksum"`
}

type CompilerArtifact

type CompilerArtifact struct {
	Vendor     Vendor             `json:"vendor"`
	Version    string             `json:"version"`
	Profiles   []string           `json:"profiles"`
	Target     string             `json:"target"`
	Source     CompilerSource     `json:"source"`
	Archive    CompilerArchive    `json:"archive"`
	Executable CompilerExecutable `json:"executable"`
}

CompilerArtifact identifies one compiler archive.

func (CompilerArtifact) ResolveOptions

func (artifact CompilerArtifact) ResolveOptions() ResolveOptions

ResolveOptions returns the verified download settings for the artifact.

type CompilerExecutable

type CompilerExecutable struct {
	Path         string `json:"path"`
	Architecture string `json:"architecture"`
	Checksum     string `json:"checksum"`
}

type CompilerSource

type CompilerSource struct {
	Repository string `json:"repository"`
	Tag        string `json:"tag"`
	Commit     string `json:"commit"`
}

type Coordinate

type Coordinate struct {
	Vendor           Vendor
	Version          string
	ExpectedChecksum string
}

Coordinate identifies one pinned compiler.

type Downloader

type Downloader interface {
	Download(ctx context.Context, url string) (io.ReadCloser, error)
}

Downloader fetches a remote artifact by URL.

type HTTPDownloader

type HTTPDownloader struct {
	Client *http.Client
}

HTTPDownloader fetches HTTPS artifacts with an injected client.

func (HTTPDownloader) Download

func (d HTTPDownloader) Download(ctx context.Context, rawURL string) (io.ReadCloser, error)

type Index

type Index struct {
	SchemaVersion int                `json:"schemaVersion"`
	ID            string             `json:"id"`
	GeneratedAt   string             `json:"generatedAt"`
	Artifacts     []CompilerArtifact `json:"artifacts"`
}

Index contains reviewed compiler artifacts.

func LoadIndex

func LoadIndex(reader io.Reader, expectedChecksum string) (Index, error)

LoadIndex reads a compiler index with an expected outer checksum.

func (Index) Select

func (index Index) Select(vendor Vendor, version, target string) (CompilerArtifact, error)

Select returns the exact compiler artifact for target.

type Info

type Info struct {
	Vendor           Vendor
	Version          string
	Path             string // absolute path to the compiler binary
	Checksum         string // "sha256:<hex>" of the binary at Path
	ArtifactChecksum string // checksum of the downloaded artifact
}

Info describes a resolved compiler toolchain.

type NoNetworkDownloader

type NoNetworkDownloader struct{}

NoNetworkDownloader rejects every download with ErrOffline.

func (NoNetworkDownloader) Download

func (NoNetworkDownloader) Download(context.Context, string) (io.ReadCloser, error)

type OSCacheFS

type OSCacheFS struct {
	fsx.OS
}

OSCacheFS implements CacheFS against the real filesystem.

func (OSCacheFS) MkdirAll

func (OSCacheFS) MkdirAll(path string) error

func (OSCacheFS) RemoveAll

func (OSCacheFS) RemoveAll(path string) error

func (OSCacheFS) Rename

func (OSCacheFS) Rename(oldPath, newPath string) error

func (OSCacheFS) WriteFile

func (OSCacheFS) WriteFile(path string, content []byte) error

type OSPathLookup

type OSPathLookup struct{}

OSPathLookup searches the current process PATH.

func (OSPathLookup) LookPath

func (OSPathLookup) LookPath(name string) (string, error)

type PathLookup

type PathLookup interface {
	LookPath(string) (string, error)
}

PathLookup finds executables using the host's command search rules.

type Platform

type Platform struct {
	OS   string // "linux", "windows", "darwin"
	Arch string // "x86_64", "arm64"
}

Platform identifies a target platform for a downloadable artifact.

func (Platform) String

func (p Platform) String() string

String returns an "os-arch" platform identifier.

type ResolveOptions

type ResolveOptions struct {
	// LocalPath takes precedence and never uses the network.
	LocalPath string

	// Vendor and Version identify a pinned toolchain.
	Vendor  Vendor
	Version string

	// DownloadURL is the HTTPS artifact URL used when the requested compiler
	// is not cached. It is ignored for local paths and cache hits.
	DownloadURL string

	// ExpectedChecksum verifies the local or downloaded artifact when set.
	ExpectedChecksum string

	// ExpectedSize is the exact downloaded artifact size when non-zero.
	ExpectedSize int64

	// ArchiveFormat and ExecutablePath describe a reviewed artifact layout.
	ArchiveFormat  string
	ExecutablePath string

	// ExpectedExecutableChecksum verifies the extracted compiler.
	ExpectedExecutableChecksum string

	// Offline restricts Resolve to local and cached compilers.
	Offline bool
}

ResolveOptions configures one Resolve call.

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver resolves, caches, and lists compiler toolchains.

func NewResolver

func NewResolver(fsys CacheFS, cacheDir string, downloader Downloader, clock Clock) *Resolver

NewResolver builds a Resolver. A nil downloader disables network access.

func (*Resolver) List

func (r *Resolver) List() ([]Info, error)

List returns every toolchain currently in the cache.

func (*Resolver) Resolve

func (r *Resolver) Resolve(ctx context.Context, opts ResolveOptions) (Info, error)

Resolve checks a local path, the cache, then the configured download. Cached versions are never updated implicitly.

func (*Resolver) Update

func (r *Resolver) Update(ctx context.Context, opts ResolveOptions) (Info, error)

Update downloads and replaces a cached toolchain. Offline is ignored.

type SystemClock

type SystemClock struct{}

SystemClock calls the real wall clock.

func (SystemClock) Now

func (SystemClock) Now() int64

type Vendor

type Vendor string

Vendor identifies a compiler lineage.

const (
	VendorPawnLang        Vendor = "pawn-lang"
	VendorOpenMultiplayer Vendor = "openmultiplayer"
	VendorOriginalPawn    Vendor = "original-pawn"
	VendorLocal           Vendor = "local"
)