downloader

package module
v0.0.0-...-2a492df Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 12, 2024 License: MIT Imports: 20 Imported by: 0

README

OpenTofu downloader library for Go with minimal dependencies

This library provides an easy way to download, verify, and unpack OpenTofu binaries for local use in Go. It has a minimal set of dependencies and is easy to integrate.

Note: This is not a standalone tool to download OpenTofu, it is purely meant to be used as Go library in support of other tools that need to run tofu. Please check the installation instructions for supported ways to perform an OpenTofu installation.

[!WARNING] This library is work in progress. Please don't use it yet unless you know what you are doing. We'll publish it in its final location in a few days.

Basic usage

The downloader will work without any extra configuration out of the box:

package main

import (
	"context"
	"io"
	"os"
	"os/exec"
	"runtime"

	"github.com/janosdebugs/downloader"
)

func main() {
	// Initialize the downloader:
	dl, err := downloader.New()
	if err != nil {
		panic(err)
	}

	// Download the latest stable version
	// for the current architecture and platform:
	binary, err := dl.Download(context.TODO())
	if err != nil {
		panic(err)
	}

	// Write out the tofu binary to the disk:
	file := "tofu"
	if runtime.GOOS == "windows" {
		file += ".exe"
	}
	if err := os.WriteFile(file, binary, 0755); err != nil {
		panic(err)
	}

	// Run tofu:
	cmd := exec.Command("./"+file, "init")
	if err := cmd.Run(); err != nil {
		panic(err)
	}
}

Advanced usage

Both New() and Download() accept a number of options. You can find the detailed documentation here.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Architecture 

type Architecture string

Architecture describes the architecture to download OpenTofu for. It defaults to the current system architecture. 

const (
	// ArchitectureAuto is the default value and defaults to downloading OpenTofu for the current architecture.
	ArchitectureAuto Architecture = ""
	// Architecture386 describes the 32-bit Intel CPU architecture.
	Architecture386 Architecture = "386"
	// ArchitectureAMD64 describes the 64-bit Intel/AMD CPU architecture.
	ArchitectureAMD64 Architecture = "amd64"
	// ArchitectureARM describes the 32-bit ARM (v7) architecture.
	ArchitectureARM Architecture = "arm"
	// ArchitectureARM64 describes the 64-bit ARM (v8) architecture.
	ArchitectureARM64 Architecture = "arm64"
)

func (Architecture) ResolveAuto 

func (a Architecture) ResolveAuto() (Architecture, error)

ResolveAuto resolves the value of ArchitectureAuto if needed based on the current runtime.GOARCH.

func (Architecture) Validate 

func (a Architecture) Validate() error

Validate returns an error if the platform is not a valid platform descriptor.

type ArtifactCorruptedError 

type ArtifactCorruptedError struct {
	Artifact string
	Cause    error
}

ArtifactCorruptedError indicates that the downloaded artifact is corrupt.

func (ArtifactCorruptedError) Error 

func (e ArtifactCorruptedError) Error() string

Error returns the error message.

func (ArtifactCorruptedError) Unwrap 

func (e ArtifactCorruptedError) Unwrap() error

Unwrap returns the original error.

type Config 

type Config struct {
	// GPGKey holds the ASCII-armored GPG key to verify the binaries against. Defaults to the bundled
	// signing key.
	GPGKey string
	// APIURL describes the URL to the JSON API listing the versions and artifacts. Defaults to branding.DownloadAPIURL.
	APIURL string
	// APIURLAuthorization is an optional Authorization header to add to all request to the API URL. For requests
	// to the default API URL leave this empty.
	APIURLAuthorization string
	// DownloadMirrorAuthorization is an optional Authorization header to add to all requests to the download mirror.
	// Typically, you'll want to set this to "Bearer YOUR-GITHUB-TOKEN".
	DownloadMirrorAuthorization string
	// DownloadMirrorURLTemplate is a Go text template containing a URL with MirrorURLTemplateParameters embedded to
	// generate the download URL. Defaults to branding.DefaultMirrorURLTemplate.
	DownloadMirrorURLTemplate string
	// HTTPClient holds an HTTP client to use for requests. Defaults to the standard HTTP client with hardened TLS
	// settings.
	HTTPClient *http.Client
}

Config describes the base configuration for the downloader.

func (*Config) ApplyDefaults 

func (c *Config) ApplyDefaults()

ApplyDefaults applies defaults for all fields that are not set.

type ConfigOpt 

type ConfigOpt func(config *Config) error

ConfigOpt is a function that modifies the config.

func ConfigAPIURL 

func ConfigAPIURL(url string) ConfigOpt

ConfigAPIURL adds an API URL for the version listing. Defaults to branding.DownloadAPIURL.

func ConfigDownloadMirrorBearerToken 

func ConfigDownloadMirrorBearerToken(token string) ConfigOpt

ConfigDownloadMirrorBearerToken adds a bearer token (e.g. GitHub token) to the Authorization header when downloading a release.

func ConfigDownloadMirrorURLTemplate 

func ConfigDownloadMirrorURLTemplate(urlTemplate string) ConfigOpt

ConfigDownloadMirrorURLTemplate adds a Go text template containing a URL with MirrorURLTemplateParameters embedded to generate the download URL. Defaults to branding.DefaultMirrorURLTemplate.

func ConfigGPGKey 

func ConfigGPGKey(gpgKey string) ConfigOpt

ConfigGPGKey is a config option to set an ASCII-armored GPG key.

func ConfigHTTPClient 

func ConfigHTTPClient(client *http.Client) ConfigOpt

ConfigHTTPClient adds a customized HTTP client to the downloader.

type DownloadOpt 

type DownloadOpt func(spec *DownloadOptions) error

DownloadOpt is a function that modifies the download options.

func DownloadOptArchitecture 

func DownloadOptArchitecture(architecture Architecture) DownloadOpt

DownloadOptArchitecture specifies the architecture to download for. This defaults to the current architecture.

func DownloadOptMinimumStability 

func DownloadOptMinimumStability(stability Stability) DownloadOpt

DownloadOptMinimumStability specifies the minimum stability of the version to download. This is mutually exclusive with setting the Version.

func DownloadOptPlatform 

func DownloadOptPlatform(platform Platform) DownloadOpt

DownloadOptPlatform specifies the platform to download for. This defaults to the current platform.

func DownloadOptVersion 

func DownloadOptVersion(version Version) DownloadOpt

DownloadOptVersion specifies the version to download. Defaults to the latest version with the specified minimum stability.

type DownloadOptions 

type DownloadOptions struct {
	Platform         Platform
	Architecture     Architecture
	Version          Version
	MinimumStability *Stability
}

DownloadOptions describes the settings for downloading. They default to the current architecture and platform.

type Downloader 

type Downloader interface {
	// ListVersions lists all versions matching the filter options in descending order.
	ListVersions(ctx context.Context, opts ...ListVersionOpt) ([]VersionWithArtifacts, error)

	// DownloadVersion downloads the OpenTofu binary from a specific artifact obtained from ListVersions.
	DownloadVersion(ctx context.Context, version VersionWithArtifacts, platform Platform, architecture Architecture) ([]byte, error)

	// Download downloads the OpenTofu binary and provides it as a byte slice.
	Download(ctx context.Context, opts ...DownloadOpt) ([]byte, error)
}

Downloader describes the functions the downloader provides.

func New 

func New(opts ...ConfigOpt) (Downloader, error)

type InvalidArchitectureError 

type InvalidArchitectureError struct {
	Architecture Architecture
}

InvalidArchitectureError describes an error where an architecture name was found to be invalid.

func (InvalidArchitectureError) Error 

func (e InvalidArchitectureError) Error() string

Error returns the error message.

type InvalidConfigurationError 

type InvalidConfigurationError struct {
	Message string
	Cause   error
}

InvalidConfigurationError indicates that the base configuration for the downloader is invalid.

func (InvalidConfigurationError) Error 

func (e InvalidConfigurationError) Error() string

Error returns the error message.

func (InvalidConfigurationError) Unwrap 

func (e InvalidConfigurationError) Unwrap() error

type InvalidOptionsError 

type InvalidOptionsError struct {
	Cause error
}

InvalidOptionsError indicates that the request options are invalid.

func (InvalidOptionsError) Error 

func (e InvalidOptionsError) Error() string

Error returns the error message.

func (InvalidOptionsError) Unwrap 

func (e InvalidOptionsError) Unwrap() error

Unwrap returns the original error.

type InvalidPlatformError 

type InvalidPlatformError struct {
	Platform Platform
}

InvalidPlatformError describes an error where a platform name was found to be invalid.

func (InvalidPlatformError) Error 

func (e InvalidPlatformError) Error() string

Error returns the error message.

type InvalidVersionError 

type InvalidVersionError struct {
	Version Version
}

InvalidVersionError describes an error where the version string is invalid.

func (InvalidVersionError) Error 

func (e InvalidVersionError) Error() string

Error returns the error message.

type ListVersionOpt 

type ListVersionOpt func(options *ListVersionsOptions) error

ListVersionOpt is an option for the ListVersions call.

func ListVersionOptMinimumStability 

func ListVersionOptMinimumStability(stability Stability) ListVersionOpt

ListVersionOptMinimumStability sets the minimum stability for listing versions.

type ListVersionsOptions 

type ListVersionsOptions struct {
	Stability *Stability
}

ListVersionsOptions are the options for listing versions.

type MirrorURLTemplateParameters 

type MirrorURLTemplateParameters struct {
	Version  Version
	Artifact string
}

MirrorURLTemplateParameters describes the parameters to a URL template for mirrors.

type NoSuchArtifactError 

type NoSuchArtifactError struct {
	ArtifactName string
}

NoSuchArtifactError indicates that there is no artifact for the given version with the given name.

func (NoSuchArtifactError) Error 

func (e NoSuchArtifactError) Error() string

Error returns the error message.

type NoSuchVersionError 

type NoSuchVersionError struct {
	Version Version
}

NoSuchVersionError indicates that the given version does not exist on the API endpoint.

func (NoSuchVersionError) Error 

func (e NoSuchVersionError) Error() string

Error returns the error message.

type Platform 

type Platform string

Platform describes the operating system to download OpenTofu for. Defaults to the current operating system. 

const (
	// PlatformAuto is the default value and describes the current operating system.
	PlatformAuto Platform = ""
	// PlatformWindows describes the Windows platform.
	PlatformWindows Platform = "windows"
	// PlatformLinux describes the Linux platform.
	PlatformLinux Platform = "linux"
	// PlatformMacOS describes the macOS (Darwin) platform.
	PlatformMacOS Platform = "darwin"
	// PlatformSolaris describes the Solaris platform. (Note: this is currently only supported on AMD64.)
	PlatformSolaris Platform = "solaris"
	// PlatformOpenBSD describes the OpenBSD platform. (Note: this is currently only supported on 386 and AMD64.)
	PlatformOpenBSD Platform = "openbsd"
	// PlatformFreeBSD describes the FreeBSD platform. (Note: this is currently not supported on ARM64)
	PlatformFreeBSD Platform = "freebsd"
)

func (Platform) ResolveAuto 

func (p Platform) ResolveAuto() (Platform, error)

ResolveAuto resolves the value of PlatformAuto if needed based on the current runtime.GOOS.

func (Platform) Validate 

func (p Platform) Validate() error

Validate returns an error if the platform is not a valid platform descriptor.

type RequestFailedError 

type RequestFailedError struct {
	Cause error
}

RequestFailedError indicates that a request to an API or the download mirror failed.

func (RequestFailedError) Error 

func (e RequestFailedError) Error() string

Error returns the error message.

func (RequestFailedError) Unwrap 

func (e RequestFailedError) Unwrap() error

Unwrap returns the original error.

type SignatureError 

type SignatureError struct {
	Message string
	Cause   error
}

SignatureError indicates that the signature verification failed.

func (SignatureError) Error 

func (e SignatureError) Error() string

Error returns the error message.

func (SignatureError) Unwrap 

func (e SignatureError) Unwrap() error

type Stability 

type Stability string

Stability describes the minimum stability to download. 

const (
	// StabilityAlpha accepts any stability.
	StabilityAlpha Stability = "alpha"
	// StabilityBeta accepts beta, release candidate and stable versions.
	StabilityBeta Stability = "beta"
	// StabilityRC accepts release candidate and stable versions.
	StabilityRC Stability = "rc"
	// StabilityStable accepts only stable versions.
	StabilityStable Stability = ""
)

func (Stability) AsInt 

func (s Stability) AsInt() int

AsInt returns a numeric representation of the stability for easier comparison.

func (Stability) Matches 

func (s Stability) Matches(version Version) bool

Matches returns true if the provided version matches the current stability or higher.

func (Stability) Validate 

func (s Stability) Validate() error

Validate returns an error if the stability is not one of the listed stabilities.

type UnsupportedArchitectureError 

type UnsupportedArchitectureError struct {
	Architecture Architecture
}

UnsupportedArchitectureError indicates that the given runtime.GOARCH architecture is not supported and cannot automatically resolve to a build artifact.

func (UnsupportedArchitectureError) Error 

func (e UnsupportedArchitectureError) Error() string

Error returns the error message.

type UnsupportedPlatformError 

type UnsupportedPlatformError struct {
	Platform Platform
}

UnsupportedPlatformError indicates that the given runtime.GOOS platform is not supported and cannot automatically resolve to a build artifact.

func (UnsupportedPlatformError) Error 

func (e UnsupportedPlatformError) Error() string

Error returns the error message.

type UnsupportedPlatformOrArchitectureError 

type UnsupportedPlatformOrArchitectureError struct {
	Platform     Platform
	Architecture Architecture
	Version      Version
}

UnsupportedPlatformOrArchitectureError describes an error where the platform name and architecture are syntactically valid, but no release artifact was found matching that name.

func (UnsupportedPlatformOrArchitectureError) Error 

func (e UnsupportedPlatformOrArchitectureError) Error() string

type Version 

type Version string

Version describes a version number with this project's version and stability understanding.

func (Version) Compare 

func (v Version) Compare(other Version) int

Compare returns 1 if the current version is larger than the other, -1 if it is smaller, 0 otherwise.

func (Version) Major 

func (v Version) Major() int

Major returns the major version. The version must be valid or this function will panic.

func (Version) Minor 

func (v Version) Minor() int

Minor returns the minor version. The version must be valid or this function will panic.

func (Version) Patch 

func (v Version) Patch() int

Patch returns the patch version. The version must be valid or this function will panic.

func (Version) Stability 

func (v Version) Stability() Stability

Stability returns the stability string for the version. The version must be valid or this function will panic.

func (Version) StabilityVer 

func (v Version) StabilityVer() int

StabilityVer returns the stability version number for the version. The version must be valid or this function will panic.

func (Version) Validate 

func (v Version) Validate() error

Validate checks if the version is valid

type VersionWithArtifacts 

type VersionWithArtifacts struct {
	ID    Version  `json:"id"`
	Files []string `json:"files"`
}

VersionWithArtifacts is a version and the list of artifacts belonging to that version.

Source Files

View all Source files

Directories

Path Synopsis
tools
bundle-gpg-key
license-headers
lint

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.