blob: 5c48e3c7c682adf5ca8414566460f52e2cd5fecd [file] [log] [blame]
// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
package flags
import (
"flag"
"fmt"
"os"
"strings"
"sync"
"v.io/v23/verror"
"v.io/x/ref"
)
const pkgPath = "v.io/x/ref/lib/flags"
var (
errNotNameColonFile = verror.Register(pkgPath+".errNotNameColonFile", verror.NoRetry, "{1:}{2:} {3} is not in 'name:file' format{:_}")
)
// FlagGroup is the type for identifying groups of related flags.
type FlagGroup int
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.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
// --v23.i18n-catalogue
Listen
// --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
Permissions
)
var (
defaultNamespaceRoot = "/(dev.v.io:r:vprod:service:mounttabled)@ns.dev.v.io:8101" // GUARDED_BY namespaceMu
namespaceMu sync.Mutex
defaultProtocol = "wsh" // GUARDED_BY listenMu
defaultHostPort = ":0" // GUARDED_BY listenMu
listenMu sync.RWMutex
)
// Flags represents the set of flag groups created by a call to
// CreateAndRegister.
type Flags struct {
FlagSet *flag.FlagSet
groups map[FlagGroup]interface{}
}
type namespaceRootFlagVar struct {
isSet bool // is true when a flag has been explicitly set.
// isDefault true when a flag has the default value and is needed in
// addition to isSet to distinguish between using a default value
// as opposed to one from an environment variable.
isDefault bool
roots []string
}
func (nsr *namespaceRootFlagVar) String() string {
return fmt.Sprintf("%v", nsr.roots)
}
func (nsr *namespaceRootFlagVar) Set(v string) error {
nsr.isDefault = false
if !nsr.isSet {
// override the default value
nsr.isSet = true
nsr.roots = []string{}
}
for _, t := range nsr.roots {
if v == t {
return nil
}
}
nsr.roots = append(nsr.roots, v)
return nil
}
type permsFlagVar struct {
isSet bool
files map[string]string
}
func (permsf *permsFlagVar) String() string {
return fmt.Sprintf("%v", permsf.files)
}
func (permsf *permsFlagVar) Set(v string) error {
if !permsf.isSet {
// override the default value
permsf.isSet = true
permsf.files = make(map[string]string)
}
parts := strings.SplitN(v, ":", 2)
if len(parts) != 2 {
return verror.New(errNotNameColonFile, nil, v)
}
name, file := parts[0], parts[1]
permsf.files[name] = file
return nil
}
// RuntimeFlags contains the values of the Runtime flag group.
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 []string
// Credentials may be initialized by the ref.EnvCredentials
// environment variable. The command line will override the environment.
Credentials string // TODO(cnicolaou): provide flag.Value impl
// I18nCatalogue may be initialized by the ref.EnvI18nCatalogueFiles
// environment variable. The command line will override the
// environment.
I18nCatalogue string
// Vtrace flags control various aspects of Vtrace.
Vtrace VtraceFlags
namespaceRootsFlag namespaceRootFlagVar
}
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
// VtraceDumpOnShutdown tells the runtime to dump all stored traces
// to Stderr at shutdown if true.
DumpOnShutdown bool
// 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
// LogLevel is the level of vlogs that should be collected as part of
// the trace
LogLevel int
// SpanRegexp matches a regular expression against span names and
// annotations and forces any trace matching trace to be collected.
CollectRegexp string
}
// PermissionsFlags contains the values of the PermissionsFlags flag group.
type PermissionsFlags struct {
// List of named Permissions files.
fileFlag permsFlagVar
// Single json string, overrides everything.
literal string
}
// PermissionsFile returns the file which is presumed to contain Permissions
// information associated with the supplied name parameter.
func (af PermissionsFlags) PermissionsFile(name string) string {
return af.fileFlag.files[name]
}
func (af PermissionsFlags) PermissionsLiteral() string {
return af.literal
}
// ListenAddrs is the set of listen addresses captured from the command line.
// ListenAddrs mirrors rpc.ListenAddrs.
type ListenAddrs []struct {
Protocol, Address string
}
// ListenFlags contains the values of the Listen flag group.
type ListenFlags struct {
Addrs ListenAddrs
Proxy string
protocol tcpProtocolFlagVar
addresses ipHostPortFlagVar
}
type tcpProtocolFlagVar struct {
isSet bool
validator TCPProtocolFlag
}
// Implements flag.Value.Get
func (proto tcpProtocolFlagVar) Get() interface{} {
return proto.validator.String()
}
func (proto tcpProtocolFlagVar) String() string {
return proto.validator.String()
}
// Implements flag.Value.Set
func (proto *tcpProtocolFlagVar) Set(s string) error {
if err := proto.validator.Set(s); err != nil {
return err
}
proto.isSet = true
return nil
}
type ipHostPortFlagVar struct {
isSet bool
validator IPHostPortFlag
flags *ListenFlags
}
// Implements flag.Value.Get
func (ip ipHostPortFlagVar) Get() interface{} {
return ip.String()
}
// Implements flag.Value.Set
func (ip *ipHostPortFlagVar) Set(s string) error {
if err := ip.validator.Set(s); err != nil {
return err
}
a := struct {
Protocol, Address string
}{
ip.flags.protocol.validator.String(),
ip.validator.String(),
}
for _, t := range ip.flags.Addrs {
if t.Protocol == a.Protocol && t.Address == a.Address {
return nil
}
}
ip.flags.Addrs = append(ip.flags.Addrs, a)
ip.isSet = true
return nil
}
// Implements flag.Value.String
func (ip ipHostPortFlagVar) String() string {
s := ""
for _, a := range ip.flags.Addrs {
s += fmt.Sprintf("(%s %s)", a.Protocol, a.Address)
}
return s
}
// createAndRegisterRuntimeFlags creates and registers the RuntimeFlags
// group with the supplied flag.FlagSet.
func createAndRegisterRuntimeFlags(fs *flag.FlagSet) *RuntimeFlags {
var (
f = &RuntimeFlags{}
_, roots = ref.EnvNamespaceRoots()
creds = os.Getenv(ref.EnvCredentials)
i18nCatalogue = os.Getenv(ref.EnvI18nCatalogueFiles)
)
if len(roots) == 0 {
f.namespaceRootsFlag.roots = []string{defaultNamespaceRoot}
f.namespaceRootsFlag.isDefault = true
} else {
f.namespaceRootsFlag.roots = roots
}
fs.Var(&f.namespaceRootsFlag, "v23.namespace.root", "local namespace root; can be repeated to provided multiple roots")
fs.Lookup("v23.namespace.root").DefValue = "[" + defaultNamespaceRoot + "]"
fs.StringVar(&f.Credentials, "v23.credentials", creds, "directory to use for storing security credentials")
fs.Lookup("v23.credentials").DefValue = ""
fs.StringVar(&f.I18nCatalogue, "v23.i18n-catalogue", i18nCatalogue, "18n catalogue files to load, comma separated")
fs.Lookup("v23.i18n-catalogue").DefValue = ""
fs.Float64Var(&f.Vtrace.SampleRate, "v23.vtrace.sample-rate", 0.0, "Rate (from 0.0 to 1.0) to sample vtrace traces.")
fs.BoolVar(&f.Vtrace.DumpOnShutdown, "v23.vtrace.dump-on-shutdown", true, "If true, dump all stored traces on runtime shutdown.")
fs.IntVar(&f.Vtrace.CacheSize, "v23.vtrace.cache-size", 1024, "The number of vtrace traces to store in memory.")
fs.IntVar(&f.Vtrace.LogLevel, "v23.vtrace.v", 0, "The verbosity level of the log messages to be captured in traces")
fs.StringVar(&f.Vtrace.CollectRegexp, "v23.vtrace.collect-regexp", "", "Spans and annotations that match this regular expression will trigger trace collection.")
return f
}
func createAndRegisterPermissionsFlags(fs *flag.FlagSet) *PermissionsFlags {
f := &PermissionsFlags{}
fs.Var(&f.fileFlag, "v23.permissions.file", "specify a perms file as <name>:<permsfile>")
fs.StringVar(&f.literal, "v23.permissions.literal", "", "explicitly specify the runtime perms as a JSON-encoded access.Permissions. Overrides all --v23.permissions.file flags.")
return f
}
// 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.
func SetDefaultProtocol(protocol string) {
listenMu.Lock()
defaultProtocol = protocol
listenMu.Unlock()
}
// 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.
func SetDefaultHostPort(s string) {
listenMu.Lock()
defaultHostPort = s
listenMu.Unlock()
}
// SetDefaultNamespaceRoot sets the default value for --v23.namespace.root
func SetDefaultNamespaceRoot(root string) {
namespaceMu.Lock()
defaultNamespaceRoot = root
namespaceMu.Unlock()
}
// DefaultNamespaceRoot gets the default value of --v23.namespace.root
func DefaultNamespaceRoot() string {
namespaceMu.Lock()
defer namespaceMu.Unlock()
return defaultNamespaceRoot
}
// createAndRegisterListenFlags creates and registers the ListenFlags
// group with the supplied flag.FlagSet.
func createAndRegisterListenFlags(fs *flag.FlagSet) *ListenFlags {
listenMu.RLock()
defer listenMu.RUnlock()
var ipHostPortFlag IPHostPortFlag
if err := ipHostPortFlag.Set(defaultHostPort); err != nil {
panic(err)
}
var protocolFlag TCPProtocolFlag
if err := protocolFlag.Set(defaultProtocol); err != nil {
panic(err)
}
f := &ListenFlags{
protocol: tcpProtocolFlagVar{validator: protocolFlag},
addresses: ipHostPortFlagVar{validator: ipHostPortFlag},
}
f.addresses.flags = f
fs.Var(&f.protocol, "v23.tcp.protocol", "protocol to listen with")
fs.Var(&f.addresses, "v23.tcp.address", "address to listen on")
fs.StringVar(&f.Proxy, "v23.proxy", "", "object name of proxy service to use to export services across network boundaries")
return f
}
// CreateAndRegister creates a new set of flag groups as specified by the
// supplied flag group parameters and registers them with the supplied
// flag.FlagSet.
func CreateAndRegister(fs *flag.FlagSet, groups ...FlagGroup) *Flags {
if len(groups) == 0 {
return nil
}
f := &Flags{FlagSet: fs, groups: make(map[FlagGroup]interface{})}
for _, g := range groups {
switch g {
case Runtime:
f.groups[Runtime] = createAndRegisterRuntimeFlags(fs)
case Listen:
f.groups[Listen] = createAndRegisterListenFlags(fs)
case Permissions:
f.groups[Permissions] = createAndRegisterPermissionsFlags(fs)
}
}
return f
}
func refreshDefaults(f *Flags) {
for _, g := range f.groups {
switch v := g.(type) {
case *RuntimeFlags:
if v.namespaceRootsFlag.isDefault {
v.namespaceRootsFlag.roots = []string{defaultNamespaceRoot}
v.NamespaceRoots = v.namespaceRootsFlag.roots
}
case *ListenFlags:
if !v.protocol.isSet {
v.protocol.validator.Set(defaultProtocol)
}
if !v.addresses.isSet {
v.addresses.validator.Set(defaultHostPort)
}
}
}
}
// RuntimeFlags returns the Runtime flag subset stored in its Flags
// instance.
func (f *Flags) RuntimeFlags() RuntimeFlags {
if p := f.groups[Runtime]; p == nil {
return RuntimeFlags{}
}
from := f.groups[Runtime].(*RuntimeFlags)
to := *from
to.NamespaceRoots = make([]string, len(from.NamespaceRoots))
copy(to.NamespaceRoots, from.NamespaceRoots)
return to
}
// 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.
func (f *Flags) ListenFlags() ListenFlags {
if p := f.groups[Listen]; p != nil {
lf := p.(*ListenFlags)
n := *lf
if len(lf.Addrs) == 0 {
n.Addrs = ListenAddrs{{n.protocol.String(), n.addresses.validator.String()}}
return n
}
n.Addrs = make(ListenAddrs, len(lf.Addrs))
copy(n.Addrs, lf.Addrs)
return n
}
return ListenFlags{}
}
// 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) PermissionsFlags() PermissionsFlags {
if p := f.groups[Permissions]; p != nil {
return *(p.(*PermissionsFlags))
}
return PermissionsFlags{}
}
// HasGroup returns group if the supplied FlagGroup has been created
// for these Flags.
func (f *Flags) HasGroup(group FlagGroup) bool {
_, present := f.groups[group]
return present
}
// Args returns the unparsed args, as per flag.Args.
func (f *Flags) Args() []string {
return f.FlagSet.Args()
}
// Parse parses the supplied args, as per flag.Parse. The config can optionally
// specify flag overrides.
func (f *Flags) Parse(args []string, cfg map[string]string) error {
// Refresh any defaults that may have changed.
refreshDefaults(f)
// TODO(cnicolaou): implement a single env var 'VANADIUM_OPTS'
// that can be used to specify any command line.
if err := f.FlagSet.Parse(args); err != nil {
return err
}
for k, v := range cfg {
if f.FlagSet.Lookup(k) != nil {
f.FlagSet.Set(k, v)
}
}
hasrt := f.groups[Runtime] != nil
if hasrt {
runtime := f.groups[Runtime].(*RuntimeFlags)
if runtime.namespaceRootsFlag.isSet {
// command line overrides the environment.
runtime.NamespaceRoots = runtime.namespaceRootsFlag.roots
} else {
// we have a default value for the command line, which
// is only used if the environment variables have not been
// supplied.
if len(runtime.NamespaceRoots) == 0 {
runtime.NamespaceRoots = runtime.namespaceRootsFlag.roots
}
}
}
return nil
}