Skip to content

Commit

Permalink
Add the idea of "env-flags"
Browse files Browse the repository at this point in the history 
Env-flags are "flags" that can only be set by env var (see caveat below).
All of the real flags have a corresponding env-flag (kind of, but not
really).  The real goal was to deprecate `--password` but keep the env
var as a documented interface.

This does that (though --password still works) and updates the usage and
manual.

This allows some future work to follow the pattern.  We do not register
every CLI flag as an env-flag because the help text would be
duplicative.  This probably wants a wrapper API that allows declaring of
abstract flags, with CLI, env, or both sources.

Caveat:

ACTUALLY, these still have a flag, but the flag is specially named and
hidden.  This makes testing a little easier where passing flags is
handled well but env vars is not.
  • Loading branch information
@thockin
thockin committed Jun 13, 2024
1 parent aa0f015 commit 4597da9
Show file tree
Hide file tree
Showing 4 changed files with 181 additions and 70 deletions.
52 changes: 26 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,8 @@ OPTIONS
Many options can be specified as either a commandline flag or an environment
variable, but flags are preferred because a misspelled flag is a fatal
error while a misspelled environment variable is silently ignored.
error while a misspelled environment variable is silently ignored. Some
options can only be specified as an environment variable.
--add-user, $GITSYNC_ADD_USER
Add a record to /etc/passwd for the current UID/GID. This is
Expand All @@ -161,11 +162,12 @@ OPTIONS
--credential <string>, $GITSYNC_CREDENTIAL
Make one or more credentials available for authentication (see git
help credential). This is similar to --username and --password or
--password-file, but for specific URLs, for example when using
submodules. The value for this flag is either a JSON-encoded
object (see the schema below) or a JSON-encoded list of that same
object type. This flag may be specified more than once.
help credential). This is similar to --username and
$GITSYNC_PASSWORD or --password-file, but for specific URLs, for
example when using submodules. The value for this flag is either a
JSON-encoded object (see the schema below) or a JSON-encoded list
of that same object type. This flag may be specified more than
once.
Object schema:
- url: string, required
Expand Down Expand Up @@ -294,16 +296,14 @@ OPTIONS
--one-time, $GITSYNC_ONE_TIME
Exit after one sync.
--password <string>, $GITSYNC_PASSWORD
$GITSYNC_PASSWORD
The password or personal access token (see github docs) to use for
git authentication (see --username). NOTE: for security reasons,
users should prefer --password-file or $GITSYNC_PASSWORD_FILE for
specifying the password.
git authentication (see --username). See also --password-file.
--password-file <string>, $GITSYNC_PASSWORD_FILE
The file from which the password or personal access token (see
github docs) to use for git authentication (see --username) will be
read.
read. See also $GITSYNC_PASSWORD.
--period <duration>, $GITSYNC_PERIOD
How long to wait between sync attempts. This must be at least
Expand Down Expand Up @@ -376,8 +376,8 @@ OPTIONS
--username <string>, $GITSYNC_USERNAME
The username to use for git authentication (see --password-file or
--password). If more than one username and password is required
(e.g. with submodules), use --credential.
$GITSYNC_PASSWORD). If more than one username and password is
required (e.g. with submodules), use --credential.
-v, --verbose <int>, $GITSYNC_VERBOSE
Set the log verbosity level. Logs at this level and lower will be
Expand Down Expand Up @@ -435,31 +435,31 @@ AUTHENTICATION
and "git@example.com:repo" will try to use SSH.
username/password
The --username (GITSYNC_USERNAME) and --password-file
(GITSYNC_PASSWORD_FILE) or --password (GITSYNC_PASSWORD) flags
will be used. To prevent password leaks, the --password-file flag
or GITSYNC_PASSWORD environment variable is almost always
preferred to the --password flag.
The --username ($GITSYNC_USERNAME) and $GITSYNC_PASSWORD or
--password-file ($GITSYNC_PASSWORD_FILE) flags will be used. To
prevent password leaks, the --password-file flag or
$GITSYNC_PASSWORD environment variable is almost always preferred
to the --password flag, which is deprecated.
A variant of this is --askpass-url (GITSYNC_ASKPASS_URL), which
A variant of this is --askpass-url ($GITSYNC_ASKPASS_URL), which
consults a URL (e.g. http://metadata) to get credentials on each
sync.
When using submodules it may be necessary to specify more than one
username and password, which can be done with --credential
(GITSYNC_CREDENTIAL). All of the username+password pairs, from
both --username/--password and --credential are fed into 'git
credential approve'.
($GITSYNC_CREDENTIAL). All of the username+password pairs, from
both --username/$GITSYNC_PASSWORD and --credential are fed into
'git credential approve'.
SSH
When an SSH transport is specified, the key(s) defined in
--ssh-key-file (GITSYNC_SSH_KEY_FILE) will be used. Users are
--ssh-key-file ($GITSYNC_SSH_KEY_FILE) will be used. Users are
strongly advised to also use --ssh-known-hosts
(GITSYNC_SSH_KNOWN_HOSTS) and --ssh-known-hosts-file
(GITSYNC_SSH_KNOWN_HOSTS_FILE) when using SSH.
($GITSYNC_SSH_KNOWN_HOSTS) and --ssh-known-hosts-file
($GITSYNC_SSH_KNOWN_HOSTS_FILE) when using SSH.
cookies
When --cookie-file (GITSYNC_COOKIE_FILE) is specified, the
When --cookie-file ($GITSYNC_COOKIE_FILE) is specified, the
associated cookies can contain authentication information.
HOOKS
Expand Down
101 changes: 95 additions & 6 deletions env.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,16 @@ limitations under the License.
package main

import (
"cmp"
"fmt"
"io"
"os"
"slices"
"strconv"
"strings"
"time"

"github.com/spf13/pflag"
)

func envString(def string, key string, alts ...string) string {
Expand All @@ -30,12 +35,25 @@ func envString(def string, key string, alts ...string) string {
}
for _, alt := range alts {
if val := os.Getenv(alt); val != "" {
fmt.Fprintf(os.Stderr, "env %s has been deprecated, use %s instead\n", alt, key)
fmt.Fprintf(os.Stderr, "env $%s has been deprecated, use $%s instead\n", alt, key)
return val
}
}
return def
}
func envFlagString(key string, def string, usage string, alts ...string) *string {
registerEnvFlag(key, "string", usage)
val := envString(def, key, alts...)
// also expose it as a flag, for easier testing
flName := "__env__" + key
flHelp := "DO NOT SET THIS FLAG EXCEPT IN TESTS; use $" + key
newExplicitFlag(&val, flName, flHelp, pflag.String)
if err := pflag.CommandLine.MarkHidden(flName); err != nil {
fmt.Fprintf(os.Stderr, "FATAL: %v\n", err)
os.Exit(1)
}
return &val
}

func envStringArray(def string, key string, alts ...string) []string {
parse := func(s string) []string {
Expand All @@ -47,7 +65,7 @@ func envStringArray(def string, key string, alts ...string) []string {
}
for _, alt := range alts {
if val := os.Getenv(alt); val != "" {
fmt.Fprintf(os.Stderr, "env %s has been deprecated, use %s instead\n", alt, key)
fmt.Fprintf(os.Stderr, "env $%s has been deprecated, use $%s instead\n", alt, key)
return parse(val)
}
}
Expand All @@ -68,7 +86,7 @@ func envBoolOrError(def bool, key string, alts ...string) (bool, error) {
}
for _, alt := range alts {
if val := os.Getenv(alt); val != "" {
fmt.Fprintf(os.Stderr, "env %s has been deprecated, use %s instead\n", alt, key)
fmt.Fprintf(os.Stderr, "env $%s has been deprecated, use $%s instead\n", alt, key)
return parse(alt, val)
}
}
Expand Down Expand Up @@ -98,7 +116,7 @@ func envIntOrError(def int, key string, alts ...string) (int, error) {
}
for _, alt := range alts {
if val := os.Getenv(alt); val != "" {
fmt.Fprintf(os.Stderr, "env %s has been deprecated, use %s instead\n", alt, key)
fmt.Fprintf(os.Stderr, "env $%s has been deprecated, use $%s instead\n", alt, key)
return parse(alt, val)
}
}
Expand Down Expand Up @@ -128,7 +146,7 @@ func envFloatOrError(def float64, key string, alts ...string) (float64, error) {
}
for _, alt := range alts {
if val := os.Getenv(alt); val != "" {
fmt.Fprintf(os.Stderr, "env %s has been deprecated, use %s instead\n", alt, key)
fmt.Fprintf(os.Stderr, "env $%s has been deprecated, use $%s instead\n", alt, key)
return parse(alt, val)
}
}
Expand Down Expand Up @@ -158,7 +176,7 @@ func envDurationOrError(def time.Duration, key string, alts ...string) (time.Dur
}
for _, alt := range alts {
if val := os.Getenv(alt); val != "" {
fmt.Fprintf(os.Stderr, "env %s has been deprecated, use %s instead\n", alt, key)
fmt.Fprintf(os.Stderr, "env $%s has been deprecated, use $%s instead\n", alt, key)
return parse(alt, val)
}
}
Expand All @@ -173,3 +191,74 @@ func envDuration(def time.Duration, key string, alts ...string) time.Duration {
}
return val
}

// explicitFlag is a pflag.Value which only sets the real value if the flag is
// set to a non-zero-value.
type explicitFlag[T comparable] struct {
pflag.Value
realPtr *T
flagPtr *T
}

// newExplicitFlag allocates an explicitFlag
func newExplicitFlag[T comparable](ptr *T, name, usage string, fn func(name string, value T, usage string) *T) {
h := &explicitFlag[T]{
realPtr: ptr,
}
var zero T
h.flagPtr = fn(name, zero, usage)
fl := pflag.CommandLine.Lookup(name)
// wrap the original pflag.Value with our own
h.Value = fl.Value
fl.Value = h
}

func (h *explicitFlag[T]) Set(val string) error {
if err := h.Value.Set(val); err != nil {
return err
}
var zero T
if v := *h.flagPtr; v != zero {
*h.realPtr = v
}
return nil
}

// envFlag is like a flag in that it is declared with a type, validated, and
// shows up in help messages, but can only be set by env-var, not on the CLI.
// This is useful for things like passwords, which should not be on the CLI
// because it can be seen in `ps`.
type envFlag struct {
name string
typ string
help string
}

var allEnvFlags = []envFlag{}

// registerEnvFlag is internal. Use functions like envFlagString to actually
// create envFlags.
func registerEnvFlag(name, typ, help string) {
for _, ef := range allEnvFlags {
if ef.name == name {
fmt.Fprintf(os.Stderr, "FATAL: duplicate env var declared: %q\n", name)
os.Exit(1)
}
}
allEnvFlags = append(allEnvFlags, envFlag{name, typ, help})
}

// printEnvFlags prints "usage" for all registered envFlags.
func printEnvFlags(out io.Writer) {
width := 0
for _, ef := range allEnvFlags {
if n := len(ef.name); n > width {
width = n
}
}
slices.SortFunc(allEnvFlags, func(l, r envFlag) int { return cmp.Compare(l.name, r.name) })

for _, ef := range allEnvFlags {
fmt.Fprintf(out, "% *s %s %*s%s\n", width+2, ef.name, ef.typ, max(8, 32-width), "", ef.help)
}
}
Loading

0 comments on commit 4597da9

Please sign in to comment.