Help us shape the future of Go! Take the 2026 Go Developer Survey

config

package
v0.48.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package config loads and persists the CLI configuration in ~/.volcano/config.json.

Index

Constants

View Source 
const (

	// AccountTokenPrefix marks an account platform token, which reaches every
	// project the account owns.
	AccountTokenPrefix = "pk-"
	// ProjectTokenPrefix marks a project access token, which reaches only the
	// project it was minted in.
	ProjectTokenPrefix = "pt-"
)
View Source 
const ProjectEnvDeprecation = "VOLCANO_PROJECT_ID is deprecated and will be removed in a future release. " +
	"Unset it and run 'volcano use <project-id>', or 'volcano login --token <token> --project <project-id>' in CI."

ProjectEnvDeprecation is the warning printed when VOLCANO_PROJECT_ID chose the project a command ran against.

Variables

View Source 
var (
	// ErrNotAuthenticated indicates no token is configured for cloud API calls.
	ErrNotAuthenticated = errors.New("not authenticated. Run 'volcano login' first, or 'volcano signup' if you're new to Volcano")
	// ErrNoProjectSelected indicates no active project is configured for project-scoped cloud API calls.
	ErrNoProjectSelected = errors.New("no project selected. Run 'volcano use <project-name>'. " +
		"To create a project and link this directory to it, run 'volcano connect .'")
	// ErrNoProjectSelectedForProjectToken is ErrNoProjectSelected for a project
	// access token, which cannot look a project up by name.
	ErrNoProjectSelectedForProjectToken = errors.New("no project selected. A project access token (" + ProjectTokenPrefix +
		") is scoped to one project: run 'volcano use <project-id>' with that project's ID")
	// ErrAccountTokenRequired indicates a command needs account-wide access but
	// the configured credential only reaches a single project.
	ErrAccountTokenRequired = errors.New("this command needs an account token (" + AccountTokenPrefix +
		") but the current credential is a project access token (" + ProjectTokenPrefix +
		"), which only reaches the project it was minted in. Run 'volcano login', or set VOLCANO_TOKEN to an account token")
)
View Source 
var ErrHomeLink = errors.New("can't link your home directory, because its .volcano directory holds the CLI's config. Use a directory under it")

ErrHomeLink refuses a link in the home directory, whose .volcano directory holds the CLI's own config.

View Source 
var LinkRelPath = filepath.Join(linkDirName, linkFileName)

LinkRelPath is where a linked directory records its project, relative to that directory.

Functions

func ConsumeProjectEnvUse added in v0.48.0 

func ConsumeProjectEnvUse() bool

ConsumeProjectEnvUse reports whether VOLCANO_PROJECT_ID was read for a project since the last call, and clears the record.

func Delete 

func Delete() error

Delete removes ~/.volcano/config.json. A missing file is considered success.

func FirstPartyDeviceClientID 

func FirstPartyDeviceClientID() (string, error)

FirstPartyDeviceClientID resolves the first-party OAuth device client ID.

func FunctionAliasScope added in v0.0.4 

func FunctionAliasScope(apiURL, projectID string) string

FunctionAliasScope returns the config key for aliases bound to one API URL and project ID. The API URL is trimmed so trailing slashes do not split scopes.

func IsHomeDir added in v0.48.0 

func IsHomeDir(dir string) bool

IsHomeDir reports whether dir, an absolute path, is the home directory.

func IsLoopbackAPIURL added in v0.2.0 

func IsLoopbackAPIURL(apiURL string) bool

IsLoopbackAPIURL reports whether apiURL points at a loopback address ("localhost" or a loopback IP). Shared by local-mode's device-client selection and by deriveWebURL below.

func IsProjectToken added in v0.31.0 

func IsProjectToken(token string) bool

IsProjectToken reports whether token is a project access token.

Case-insensitive on purpose. The unknown-prefix default is deliberately fail-open, for credentials minted before the prefixes existed, but "PT-" is not one of those — it is a mangled pt- token, and matching case-sensitively let it past every guard here and fail as an opaque server error instead. 

func LoadIgnoringBadLink() (cfg *Config, linkErr *LinkError, err error)

LoadIgnoringBadLink is Load for the commands that work without the link, or replace it: login, signup and connect. A link that can't be used is left out of the config and returned as linkErr instead of failing the load.

func Path 

func Path() (string, error)

Path returns the default on-disk config path.

func Update added in v0.25.0 

func Update(mutate func(*Config) (bool, error)) error

Update locks, reloads, and conditionally saves the config.

Types

type Config 

type Config struct {
	// APIBaseURL overrides the compiled API URL for synthetic command configs.
	// It is intentionally not persisted to the user's cloud config file.
	APIBaseURL     string         `json:"-"`
	UserToken      string         `json:"user_token,omitempty"`
	UserID         string         `json:"user_id,omitempty"`
	AnonKey        string         `json:"-"`
	ServiceKey     string         `json:"-"`
	CurrentProject *ProjectConfig `json:"current_project,omitempty"`
	// Link is the working directory's project link, found by Load. It is never
	// saved here: the link lives in the linked directory.
	Link *Link `json:"-"`
	// FunctionAliases stores per-user function invoke aliases by API URL and
	// project ID scope. Scope keys are produced by FunctionAliasScope.
	FunctionAliases map[string]map[string]string `json:"function_aliases,omitempty"`
	// DocsSource persists a non-default documentation source override so that
	// `volcano docs` commands resolve the same repo/ref/path across invocations
	// without repeating --repo/--ref/--path flags. Nil means "use the compiled
	// default source".
	DocsSource *DocsSourceConfig `json:"docs_source,omitempty"`
	// IgnoreEnv disables environment overrides for synthetic command configs.
	IgnoreEnv bool `json:"-"`
}

Config represents the CLI configuration stored in ~/.volcano/config.json.

func Default 

func Default() *Config

Default returns an empty config.

func Load 

func Load() (*Config, error)

Load reads ~/.volcano/config.json and the working directory's project link. Missing config is not an error. A link that can't be used is a *LinkError. 

func LoadWithoutLink() (*Config, error)

LoadWithoutLink reads ~/.volcano/config.json alone, for configs that never use a project link.

func (*Config) APIURL 

func (c *Config) APIURL() string

APIURL returns the API URL with VOLCANO_API_URL taking precedence unless env overrides are disabled. Precedence: env > runtime override (APIBaseURL) > compiled default.

func (*Config) DeleteFunctionAlias added in v0.0.4 

func (c *Config) DeleteFunctionAlias(scope, alias string) bool

DeleteFunctionAlias removes alias from the given scope and reports whether it existed.

func (*Config) FunctionAlias added in v0.0.4 

func (c *Config) FunctionAlias(scope, alias string) (string, bool)

FunctionAlias returns the function ID configured for alias in the given scope.

func (*Config) FunctionInvokeToken added in v0.0.4 

func (c *Config) FunctionInvokeToken() string

FunctionInvokeToken returns the token used for runtime function invocation. Cloud uses the reserved data-plane service key (via the invoke token provider) or falls back to the configured token. In local mode the session layer sends no credential at all (see session.Factory.APIClient), so this value is unused there.

func (*Config) Project added in v0.48.0 

func (c *Config) Project() *ProjectConfig

Project returns the selected project without the VOLCANO_PROJECT_ID override: the working directory's link, else the project `volcano use` saved. Nil when neither is set.

func (*Config) ProjectID 

func (c *Config) ProjectID() string

ProjectID returns the current project ID, with VOLCANO_PROJECT_ID taking precedence unless env overrides are disabled. Precedence: env > the working directory's link > the project `volcano use` saved.

func (*Config) ProjectIDFromEnv added in v0.31.0 

func (c *Config) ProjectIDFromEnv() string

ProjectIDFromEnv returns VOLCANO_PROJECT_ID alone, without the project a previous 'volcano use' saved. Callers that have to tell the two apart — a failure that names the project it ran against — need the distinction.

Trimmed for the same reason as Token: CI sets it the same way, where the value is as likely to arrive with a trailing newline, and untrimmed it failed UUID parsing as "invalid UUID length: 37".

The variable is deprecated. A non-empty value is recorded so the CLI can warn once, after the command, that it was used; see ConsumeProjectEnvUse.

func (*Config) RequireAccountToken added in v0.31.0 

func (c *Config) RequireAccountToken() error

RequireAccountToken rejects a project access token on a command that needs account-wide access. Any other credential is treated as an account token: the server is the authority on what a token may do, and tokens minted before the prefixes existed carry neither.

func (*Config) RequireAuth 

func (c *Config) RequireAuth() error

RequireAuth returns an old-CLI-compatible error when no token is available.

func (*Config) RequireProject 

func (c *Config) RequireProject() error

RequireProject returns an old-CLI-compatible error when no project is selected.

func (*Config) Save 

func (c *Config) Save() error

Save writes the config to ~/.volcano/config.json with owner-only permissions.

func (*Config) SetFunctionAlias added in v0.0.4 

func (c *Config) SetFunctionAlias(scope, alias, functionID string)

SetFunctionAlias stores alias in the given scope.

func (*Config) Token 

func (c *Config) Token() string

Token returns the configured token, with VOLCANO_TOKEN taking precedence unless env overrides are disabled.

func (*Config) WebURL added in v0.0.4 

func (c *Config) WebURL() string

WebURL returns the Volcano web URL for c.APIURL(). See WebURLForAPIURL for callers that already resolved the API URL through another path (e.g. a runtime override that doesn't flow through c.APIURL()).

func (*Config) WebURLForAPIURL added in v0.2.1 

func (c *Config) WebURLForAPIURL(apiURL string) string

WebURLForAPIURL returns the Volcano web URL for a specific, already-resolved API URL: VOLCANO_WEB_URL takes precedence, then an explicitly compiled-in default (e.g. via `make local`'s DEFAULT_WEB_URL, which differs from the shipped defaultCompiledWebURL literal only when someone set it), then a URL derived from apiURL (see deriveWebURL), then the shipped compiled default. The explicit compiled default has to win over derivation: otherwise a loopback API URL baked in alongside a non-conventional compiled web URL (e.g. a frontend dev server not on port 3000) would have its own compiled default silently overridden by the :3000 convention.

func (*Config) WebURLOverride added in v0.0.4 

func (c *Config) WebURLOverride() (string, bool)

WebURLOverride returns an explicit VOLCANO_WEB_URL value when one is set, reporting false otherwise. Used only by Signup, to fail fast on a misconfigured override before allocating a device code (see WebURLForAPIURL for the derived-origin precedence Signup otherwise falls back to). LoginWithBrowser does not use this: its browser flow opens the backend's device-authorization verification URL directly and never routes through Volcano Web.

type DocsSourceConfig added in v0.1.0 

type DocsSourceConfig struct {
	Repo string `json:"repo,omitempty"`
	Ref  string `json:"ref,omitempty"`
	Path string `json:"path,omitempty"`
}

DocsSourceConfig persists a documentation source override. Empty fields fall back to the compiled defaults during resolution. 

type Link struct {
	// Dir is the linked directory, the one holding .volcano/project.json.
	Dir     string
	Project ProjectConfig
}

Link is a directory's link to a cloud project, read from .volcano/project.json. Inside a linked directory the linked project takes precedence over the one `volcano use` saved globally, so two checkouts on one machine can point at different projects. 

func FindLink(start string) (*Link, error)

FindLink looks for .volcano/project.json in start and its parents. The walk stops after the first directory holding a .git entry, and below the home directory, so a repository never picks up a link from a directory above it. It returns nil when no link is found.

func FindLinkFromWorkingDir added in v0.48.0 

func FindLinkFromWorkingDir() (*Link, error)

FindLinkFromWorkingDir is FindLink from the current directory. 

func WriteLink(dir string, project ProjectConfig) (*Link, error)

WriteLink links dir to project by writing dir/.volcano/project.json. It refuses to write through a symlink, and in the home directory.

func (Link) Path added in v0.48.0 

func (l Link) Path() string

Path returns the link file's path.

type LinkError added in v0.48.0 

type LinkError struct {
	// Dir is the directory holding the link.
	Dir string
	Err error
}

LinkError is a project link that can't be used: unreadable, malformed, or without a valid project ID.

func (*LinkError) Error added in v0.48.0 

func (e *LinkError) Error() string

func (*LinkError) Path added in v0.48.0 

func (e *LinkError) Path() string

Path returns the link file's path.

func (*LinkError) Unwrap added in v0.48.0 

func (e *LinkError) Unwrap() error

type ProjectConfig 

type ProjectConfig struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

ProjectConfig represents the currently selected Volcano project.

Source Files

View all Source files

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.