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(env map[string]string)
• type Fastly
• type File
  • func (f *File) Load(configEndpoint string, httpClient api.HTTPClient) error
  • func (f *File) Read(fpath string) error
  • func (f *File) Write(filename 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 (
	// EnvVarToken is the env var we look in for the Fastly API token.
	// gosec flagged this:
	// G101 (CWE-798): Potential hardcoded credentials
	// Disabling as we use the value in the command help output.
	/* #nosec */
	EnvVarToken = "FASTLY_API_TOKEN"

	// EnvVarEndpoint is the env var we look in for the API endpoint.
	EnvVarEndpoint = "FASTLY_API_ENDPOINT"
)

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

DefaultEndpoint is the default Fastly API endpoint.

Variables

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.

Types

type CLI

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

CLI represents CLI specific configuration.

type Data

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

	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(env 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 {
	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"`
}

File represents our dynamic application toml configuration.

func (*File) Load

func (f *File) Load(configEndpoint string, httpClient api.HTTPClient) 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) error

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

func (*File) Write

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

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

NOTE: the expected workflow for this method is for the caller to have modified the public field(s) first so that we can write new content to the config file from the receiver object itself.

EXAMPLE: file.CLI.LastChecked = time.Now().Format(time.RFC3339) file.Write(configFilePath)

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
	ToolchainVersion string `toml:"toolchain_version"`

	// 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"`
}

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"`
	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"`
	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.