toolchain

Documentation

Overview

Package toolchain resolves, verifies, and caches Pawn compilers.

Index

• Variables
• func DefaultCacheDir() (string, error)
• type CacheFS
• type Clock
• type Downloader
• type HTTPDownloader
  • func (d HTTPDownloader) Download(ctx context.Context, rawURL string) (io.ReadCloser, 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 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.

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 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 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 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

	// 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"
)