import "v.io/x/ref/lib/flags"
Package flags implements utilities to augment the standard Go flag package. It defines commonly used Vanadium flags, and implementations of the flag.Value interface for those flags to ensure that only valid values of those flags are supplied. Some of these flags may also be specified using environment variables directly and are documented accordingly; in these cases the command line value takes precedence over the environment variable.
Flags are defined as 'groups' of related flags so that the caller may choose which ones to use without having to be burdened with the full set. The groups may be used directly or via the Flags type that aggregates multiple groups. In all cases, the flags are registered with a supplied flag.FlagSet and hence are not forced onto the command line unless the caller passes in flag.CommandLine as the flag.FlagSet to use.
In general, this package will be used by vanadium profiles and the runtime implementations, but can also be used by any application that wants access to the flags and environment variables it supports.
Default values are provided for all flags that can be overridden either by calling functions in this package, or globally, by providing a new source code file, that provides an init function (see aaa.go) that provides an additional set of default values to be merged with the original ones. It should be placed in a file that is lexicographically less than zzz.go, e.g. site.go.
defaults.go doc.go flags.go listen.go namespace.go permissions.go sitedefaults.go test_site_defaults.go
DefaultCredentialsDir returns the current default for --v23.credentials taking V23_CREDENTIALS into account
DefaultCredentialsDirNoEnv returns the current default for --v23.credentials ignoring V23_CREDENTIALS
DefaultHostPort returns the current default host port.
DefaultI18nCatalogue returns the current default for --v23.i18n-catalogue. taking V23_V23_I18N_CATALOGUE into account.
DefaultI18nCatalogueNoEnv returns the current default for --v23.i18n-catalogue ignoring V23_I18N_CATALOGUE.
DefaultNamespaceRoots returns the current default value of -v23.namespace.root taking the environment variables V23_NAMESPACE_ROOT0... into account.
DefaultNamespaceRootsNoEnv returns the current default value of -v23.namespace.root ignoring V23_NAMESPACE_ROOT0...
DefaultPermissions returns the current default values for --v23.permissions.file as a map.
DefaultPermissionsLiteral returns the current default value for --v23.permissions.literal.
DefaultProtocol returns the current default protocol.
DefaultProxy returns the current default proxy.
func RegisterListenFlags(fs *flag.FlagSet, f *ListenFlags)
RegisterListenFlags registers the supplied ListenFlags variable with the supplied FlagSet.
func RegisterPermissionsFlags(fs *flag.FlagSet, f *PermissionsFlags)
RegisterPermissionsFlags registers the supplied PermissionsFlags with the supplied FlagSet.
func RegisterRuntimeFlags(fs *flag.FlagSet, f *RuntimeFlags)
RegisterRuntimeFlags registers the supplied RuntimeFlags variable with the supplied FlagSet.
SetDefaultCredentialsDir sets the default value for --v23.credentials. It must be called before flags are parsed for it to take effect.
SetDefaultHostPort sets the default host and port used when --v23.tcp.address is not provided. It must be called before flags are parsed for it to take effect.
SetDefaultI18nCatalogue sets the default value for --v23.i18n-catalogue. It must be called before flags are parsed for it to take effect.
SetDefaultNamespaceRoots sets the default value for --v23.namespace.root
SetDefaultPermissions adds a name, file pair to the default value for --v23.permissions.file.
SetDefaultPermissionsLiteral sets the default value for --v23.permissions.literal.
SetDefaultProtocol sets the default protocol used when --v23.tcp.protocol is not provided. It must be called before flags are parsed for it to take effect.
SetDefaultProxy sets the default proxy used when --v23.proxy is not provided. It must be called before flags are parsed for it to take effect.
FlagGroup is the type for identifying groups of related flags.
const (
// Runtime identifies the flags and associated environment variables
// used by the Vanadium process runtime. Namely:
// --v23.namespace.root (which may be repeated to supply multiple values)
// --v23.credentials
// --v23.i18n-catalogue
// --v23.vtrace.sample-rate
// --v23.vtrace.dump-on-shutdown
// --v23.vtrace.cache-size
// --v23.vtrace.collect-regexp
Runtime FlagGroup = iota
// Listen identifies the flags typically required to configure
// rpc.ListenSpec. Namely:
// --v23.tcp.protocol
// --v23.tcp.address
// --v23.proxy
Listen
// Permissions identifies the flags typically required to configure
// authorization.
// --v23.permissions.file (which may be repeated to supply multiple values)
// Permissions files are named - i.e. --v23.permissions.file=<name>:<file>
// with the name "runtime" reserved for use by the runtime. "file" is
// a JSON-encoded representation of the Permissions type defined in the
// VDL package v.io/v23/security/access
// --v23.permissions.literal (which may be repeated to supply multiple values
// which will be concatenated)
// This flag allows permissions to specified directly on the command line.
Permissions
)Flags represents the set of flag groups created by a call to CreateAndRegister.
CreateAndRegister creates a new set of flag groups as specified by the supplied flag group parameters and registers them with the supplied flag.FlagSet.
Args returns the unparsed args, as per flag.Args.
HasGroup returns group if the supplied FlagGroup has been created for these Flags.
func (f *Flags) ListenFlags() ListenFlags
ListenFlags returns a copy of the Listen flag group stored in Flags. This copy will contain default values if the Listen flag group was not specified when CreateAndRegister was called. The HasGroup method can be used for testing to see if any given group was configured.
Parse parses the supplied args, as per flag.Parse. The config can optionally specify flag overrides.
func (f *Flags) PermissionsFlags() PermissionsFlags
PermissionsFlags returns a copy of the Permissions flag group stored in Flags. This copy will contain default values if the Permissions flag group was not specified when CreateAndRegister was called. The HasGroup method can be used for testing to see if any given group was configured.
func (f *Flags) RuntimeFlags() RuntimeFlags
RuntimeFlags returns the Runtime flag subset stored in its Flags instance.
IPFlag implements flag.Value in order to provide validation of IP addresses in the flag package.
Get implements flag.Getter.
Set implements flag.Value.
Implements flag.Value.String
IPHostPortFlag implements flag.Value to provide validation of the command line value it is set to. The allowed format is <host>:<port> in ip4 and ip6 formats. The host may be specified as a hostname or as an IP address (v4 or v6). If a hostname is used and it resolves to multiple IP addresses then all of those addresses are stored in IPHostPort.
func (ip IPHostPortFlag) Get() interface{}
Get implements flag.Getter.
func (ip *IPHostPortFlag) Set(s string) error
Set implements flag.Value.
func (ip IPHostPortFlag) String() string
Implements flag.Value.String
ListenAddrs is the set of listen addresses captured from the command line. ListenAddrs mirrors rpc.ListenAddrs.
type ListenFlags struct {
Addrs ListenAddrs
Proxy string `cmdline:"v23.proxy,,object name of proxy service to use to export services across network boundaries"`
Protocol tcpProtocolFlagVar `cmdline:"v23.tcp.protocol,,protocol to listen with"`
Addresses ipHostPortFlagVar `cmdline:"v23.tcp.address,,address to listen on"`
}ListenFlags contains the values of the Listen flag group.
func CreateAndRegisterListenFlags(fs *flag.FlagSet) *ListenFlags
CreateAndRegisterListenFlags creates and registers the ListenFlags group with the supplied flag.FlagSet.
func NewListenFlags() *ListenFlags
NewListenFlags creates a new ListenFlags with appropriate defaults.
NamespaceRootFlag represents a flag.Value for --v23.namespace.root.
func (nsr *NamespaceRootFlag) Set(v string) error
Set implements flag.Value
func (nsr *NamespaceRootFlag) String() string
String implements flag.Value.
type PermissionsFlag struct {
// contains filtered or unexported fields
}PermissionsFlag represents a flag.Value for --v23.permissions.file
func (permsf *PermissionsFlag) Set(v string) error
Set implements flag.Value.
func (permsf *PermissionsFlag) String() string
String implements flag.Value.
type PermissionsFlags struct {
// List of named Permissions files.
Files PermissionsFlag `cmdline:"v23.permissions.file,,specify a perms file as <name>:<permsfile>"`
// Literal permissions, override everything else.
Literal PermissionsLiteralFlag `cmdline:"v23.permissions.literal,,explicitly specify the runtime perms as a JSON-encoded access.Permissions. Overrides all --v23.permissions.file flags"`
}PermissionsFlags contains the values of the PermissionsFlags flag group.
func CreateAndRegisterPermissionsFlags(fs *flag.FlagSet) *PermissionsFlags
CreateAndRegisterPermissionsFlags creates and registers a PermissionsFlags with the supplied FlagSet.
func NewPermissionsFlags() *PermissionsFlags
NewPermissionsFlags creates a PermissionsFlags with appropriate defaults.
func (af PermissionsFlags) AddPermissionsFile(arg string) error
AddPermissionsFile adds a permissions file, which must be in the same format as accepted by --v23.permissions.file
func (af PermissionsFlags) AddPermissionsLiteral(arg string) error
AddPermissionsLiteral adds another literal permissions statement.
func (af PermissionsFlags) ExplicitlySpecified() bool
ExplicitlySpecified returns true if either of the permissions flags was explicitly set on the command line.
func (af PermissionsFlags) PermissionsFile(name string) string
PermissionsFile returns the file which is presumed to contain Permissions information associated with the supplied name parameter.
func (af PermissionsFlags) PermissionsLiteral() string
PermissionsLiteral returns the in-line literal permissions provided on the command line.
func (af PermissionsFlags) PermissionsNamesAndFiles() map[string]string
PermissionsNamesAndFiles returns the set of permission names and associated files specified using --v23.permissions.file.
type PermissionsLiteralFlag struct {
// contains filtered or unexported fields
}PermissionsLiteralFlag represents a flag.Value for --v23.permissions.literal
func (permsl *PermissionsLiteralFlag) Set(v string) error
Set implements flag.Value.
func (permsl *PermissionsLiteralFlag) String() string
String implements flag.Value.
type RuntimeFlags struct {
// NamespaceRoots may be initialized by ref.EnvNamespacePrefix* enivornment
// variables as well as --v23.namespace.root. The command line
// will override the environment.
NamespaceRoots NamespaceRootFlag `cmdline:"v23.namespace.root,,local namespace root; can be repeated to provided multiple roots"`
// Credentials may be initialized by the ref.EnvCredentials
// environment variable. The command line will override the environment.
// TODO(cnicolaou): provide flag.Value impl
Credentials string `cmdline:"v23.credentials,,directory to use for storing security credentials"`
// I18nCatalogue may be initialized by the ref.EnvI18nCatalogueFiles
// environment variable. The command line will override the
// environment.
I18nCatalogue string `cmdline:"v23.i18n-catalogue,,'18n catalogue files to load, comma separated'"`
// VtraceFlags control various aspects of Vtrace.
VtraceFlags
}RuntimeFlags contains the values of the Runtime flag group.
func CreateAndRegisterRuntimeFlags(fs *flag.FlagSet) *RuntimeFlags
CreateAndRegisterRuntimeFlags creates and registers a RuntimeFlags with the supplied flag.FlagSet.
func NewRuntimeFlags() *RuntimeFlags
NewRuntimeFlags creates a new RuntimeFlags with appropriate defaults.
TCPProtocolFlag implements flag.Value to provide validation of the command line values passed to it: tcp, tcp4, tcp6, ws, ws4, ws6, wsh, wsh4, and wsh6 being the only allowed values.
func (t TCPProtocolFlag) Get() interface{}
Get implements flag.Getter.
func (t *TCPProtocolFlag) Set(s string) error
Set implements flag.Value.
func (t TCPProtocolFlag) String() string
String implements flag.Value.
type VtraceFlags struct {
// VtraceSampleRate is the rate (from 0.0 - 1.0) at which
// vtrace traces started by this process are sampled for collection.
SampleRate float64 `cmdline:"v23.vtrace.sample-rate,,Rate (from 0.0 to 1.0) to sample vtrace traces"`
// VtraceDumpOnShutdown tells the runtime to dump all stored traces
// to Stderr at shutdown if true.
DumpOnShutdown bool `cmdline:"v23.vtrace.dump-on-shutdown,true,'If true, dump all stored traces on runtime shutdown'"`
// VtraceCacheSize is the number of traces to cache in memory.
// TODO(mattr): Traces can be of widely varying size, we should have
// some better measurement then just number of traces.
CacheSize int `cmdline:"v23.vtrace.cache-size,1024,The number of vtrace traces to store in memory"`
// LogLevel is the level of vlogs that should be collected as part of
// the trace
LogLevel int `cmdline:"v23.vtrace.v,,The verbosity level of the log messages to be captured in traces"`
// SpanRegexp matches a regular expression against span names and
// annotations and forces any trace matching trace to be collected.
CollectRegexp string `cmdline:"v23.vtrace.collect-regexp,,Spans and annotations that match this regular expression will trigger trace collection"`
}VtraceFlags represents the flags used to configure rpc tracing.
Package flags imports 12 packages (graph) and is imported by 18 packages. Updated 2019-02-08. Refresh now. Tools for package owners.