config

Documentation

Overview

Package config manages global configuration parameters. It has a data type and helpers for getting information out of the runtime environment, and making it available to commands that need it.

Index

• Constants
• Variables
• type CLI
• type Data
  • func (d *Data) Endpoint() (string, Source)
  • func (d *Data) Token() (string, Source)
  • func (d *Data) Verbose() bool
• type Environment
  • func (e *Environment) Read(state map[string]string)
• type Fastly
• type File
  • func (f *File) Load(configEndpoint string, c api.HTTPClient, d time.Duration, fpath string) error
  • func (f *File) Read(fpath string, in io.Reader, out io.Writer) error
  • func (f *File) UseStatic(cfg []byte, fpath string) error
  • func (f *File) ValidConfig(verbose bool, out io.Writer) bool
  • func (f *File) Write(fpath string) error
• type Flag
• type Language
• type LegacyFile
• type Rust
• type Source
• type StarterKit
• type StarterKitLanguages
• type User

Constants

const (
	// SourceUndefined indicates the parameter isn't provided in any of the
	// available sources, similar to "not found".
	SourceUndefined Source = iota

	// SourceFile indicates the parameter came from a config file.
	SourceFile

	// SourceEnvironment indicates the parameter came from an env var.
	SourceEnvironment

	// SourceFlag indicates the parameter came from an explicit flag.
	SourceFlag

	// SourceDefault indicates the parameter came from a program default.
	SourceDefault

	// DirectoryPermissions is the default directory permissions for the config file directory.
	DirectoryPermissions = 0700

	// FilePermissions is the default file permissions for the config file.
	FilePermissions = 0600

	// RemoteEndpoint represents the API endpoint where we'll pull the dynamic
	// configuration file from.
	//
	// NOTE: once the configuration is stored locally, it will allow for
	// overriding this default endpoint.
	RemoteEndpoint = "https://developer.fastly.com/api/internal/cli-config"

	// UpdateSuccessful represents the message shown to a user when their
	// application configuration has been updated successfully.
	UpdateSuccessful = "Successfully updated platform compatibility and versioning information."

	// ConfigRequestTimeout is how long we'll wait for the CLI API endpoint to
	// return a response before timing out the request.
	ConfigRequestTimeout = 5 * time.Second
)

const DefaultEndpoint = "https://api.fastly.com"

DefaultEndpoint is the default Fastly API endpoint.

Variables

var ErrInvalidConfig = errors.New("the configuration file is invalid")

ErrInvalidConfig indicates that the configuration file used was the static one embedded into the compiled CLI binary and that failed to be unmarshalled.

var ErrLegacyConfig = errors.New("the configuration file is in the legacy format")

ErrLegacyConfig indicates that the local configuration file is using the legacy format.

var FilePath = func() string {
	if dir, err := os.UserConfigDir(); err == nil {
		return filepath.Join(dir, "fastly", "config.toml")
	}
	if dir, err := os.UserHomeDir(); err == nil {
		return filepath.Join(dir, ".fastly", "config.toml")
	}
	panic("unable to deduce user config dir or user home dir")
}()

FilePath is the location of the fastly CLI application config file.

var RemediationManualFix = "You'll need to manually fix any invalid configuration syntax."

RemediationManualFix indicates that the configuration file used was invalid and that the user rejected the use of the static config embedded into the compiled CLI binary and so the user must resolve their invalid config.

Types

type CLI

type CLI struct {
	RemoteConfig string `toml:"remote_config"`
	TTL          string `toml:"ttl"`
	LastChecked  string `toml:"last_checked"`
	Version      string `toml:"version"`
}

CLI represents CLI specific configuration.

type Data

type Data struct {
	File   File
	Env    Environment
	Output io.Writer
	Flag   Flag
	ErrLog fsterr.LogInterface

	Client    api.Interface
	RTSClient api.RealtimeStatsInterface
}

Data holds global-ish configuration data from all sources: environment variables, config files, and flags. It has methods to give each parameter to the components that need it, including the place the parameter came from, which is a requirement.

If the same parameter is defined in multiple places, it is resolved according to the following priority order: the config file (lowest priority), env vars, and then explicit flags (highest priority).

This package and its types are only meant for parameters that are applicable to most/all subcommands (e.g. API token) and are consistent for a given user (e.g. an email address). Otherwise, parameters should be defined in specific command structs, and parsed as flags.

func (*Data) Endpoint

func (d *Data) Endpoint() (string, Source)

Endpoint yields the API endpoint.

func (*Data) Token

func (d *Data) Token() (string, Source)

Token yields the Fastly API token.

func (*Data) Verbose

func (d *Data) Verbose() bool

Verbose yields the verbose flag, which can only be set via flags.

type Environment

type Environment struct {
	Token    string
	Endpoint string
}

Environment represents all of the configuration parameters that can come from environment variables.

func (*Environment) Read

func (e *Environment) Read(state map[string]string)

Read populates the fields from the provided environment.

type Fastly

type Fastly struct {
	APIEndpoint string `toml:"api_endpoint"`
}

Fastly represents fastly specific configuration.

type File

type File struct {
	ConfigVersion int                 `toml:"config_version"`
	Fastly        Fastly              `toml:"fastly"`
	CLI           CLI                 `toml:"cli"`
	User          User                `toml:"user"`
	Language      Language            `toml:"language"`
	StarterKits   StarterKitLanguages `toml:"starter-kits"`

	// We store off a possible legacy configuration so that we can later extract
	// the relevant email and token values that may pre-exist.
	Legacy LegacyFile `toml:"legacy"`

	// Store off copy of the static application configuration that has been
	// embedded into the compiled CLI binary.
	Static []byte `toml:",omitempty"`
}

File represents our dynamic application toml configuration.

func (*File) Load

func (f *File) Load(configEndpoint string, c api.HTTPClient, d time.Duration, fpath string) error

Load gets the configuration file from the CLI API endpoint and encodes it from memory into config.File.

func (*File) Read

func (f *File) Read(fpath string, in io.Reader, out io.Writer) error

Read decodes a toml file from the local disk into config.File.

If reading from disk fails, then we'll use the static config embedded into the CLI binary (which we expect to be valid). If an attempt to unmarshal the static config fails then we have to consider something fundamental has gone wrong and subsequently expect the caller to exit the program.

func (*File) UseStatic

func (f *File) UseStatic(cfg []byte, fpath string) error

UseStatic allow us to switch the in-memory configuration with the static version embedded into the CLI binary and writes it back to disk.

func (*File) ValidConfig

func (f *File) ValidConfig(verbose bool, out io.Writer) bool

ValidConfig checks the current config version isn't different from the config statically embedded into the CLI binary. If it is then we consider the config not valid and we'll fallback to the embedded config.

func (*File) Write

func (f *File) Write(fpath string) error

Write the instance of File to a local application config file.

type Flag

type Flag struct {
	Token    string
	Verbose  bool
	Endpoint string
}

Flag represents all of the configuration parameters that can be set with explicit flags. Consumers should bind their flag values to these fields directly.

type Language

type Language struct {
	Rust Rust `toml:"rust"`
}

Language represents C@E language specific configuration.

type LegacyFile

type LegacyFile struct {
	Token string `toml:"token"`
	Email string `toml:"email"`
}

LegacyFile represents the old toml configuration format.

NOTE: this exists to catch situations where an existing CLI user upgrades their version of the CLI and ends up trying to use the latest iteration of the toml configuration. We don't want them to have to re-enter their email or token, so we'll decode the existing config file into the LegacyFile type and then extract those details later when constructing the proper File type.

I had tried to make this an unexported type but it seemed the toml decoder would fail to unmarshal the configuration unless it was an exported type.

type Rust

type Rust struct {
	// ToolchainVersion is the `rustup` toolchain string for the compiler that we
	// support
	//
	// DEPRECATED in favour of ToolchainConstraint
	ToolchainVersion string `toml:"toolchain_version"`

	// ToolchainConstrain is the `rustup` toolchain constraint for the compiler
	// that we support (a range is expected, e.g. >= 1.49.0 < 2.0.0).
	ToolchainConstraint string `toml:"toolchain_constraint"`

	// WasmWasiTarget is the Rust compilation target for Wasi capable Wasm.
	WasmWasiTarget string `toml:"wasm_wasi_target"`

	// FastlySysConstraint is a free-form semver constraint for the internal Rust
	// ABI version that should be supported.
	FastlySysConstraint string `toml:"fastly_sys_constraint"`

	// RustupConstraint is a free-form semver constraint for the rustup version
	// that should be installed.
	RustupConstraint string `toml:"rustup_constraint"`
}

Rust represents Rust C@E language specific configuration.

type Source

type Source uint8

Source enumerates where a config parameter is taken from.

type StarterKit

type StarterKit struct {
	Name        string `toml:"name"`
	Description string `toml:"description"`
	Path        string `toml:"path"`
	Tag         string `toml:"tag"`
	Branch      string `toml:"branch"`
}

StarterKit represents starter kit specific configuration.

type StarterKitLanguages

type StarterKitLanguages struct {
	AssemblyScript []StarterKit `toml:"assemblyscript"`
	JavaScript     []StarterKit `toml:"javascript"`
	Rust           []StarterKit `toml:"rust"`
}

StarterKitLanguages represents language specific starter kits.

type User

type User struct {
	Token string `toml:"token"`
	Email string `toml:"email"`
}

User represents user specific configuration.