clitools

package module
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Jan 24, 2025 License: MIT Imports: 18 Imported by: 2

README

CLI tools

Go Reference

The clitools contains helpers for building TT CLI tools.

Logging in using the ConfigurationHandler

See the example in the Go docs.

Configuration and tokens will be saved in $XDG_CONFIG_HOME or the appropriate user configuration directory for your platform, for Linux this is "~/.config/[name of application]/". Configuration is stored in "config.json" and the access tokens in "tokens.json".

Configuration directory and environment loading

UserConfigDir() gives preference to XDG_CONFIG_HOME, letting users in any OS specify a linux-style user config location. If XDG_CONFIG_HOME is empty it behaves just like os.UserConfigDir().

LoadEnv() loads any ".env" (override by setting DOT_ENV) in the current path and "[user config dir]/[app]/config.env" if they exist. This will not override any variables that are set, and the .env file takes precedence over config.env.

Documentation

Overview

Example
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/ttab/clitools"
)

func main() {
	// SampleConf - any addional configuration you want to store.
	type SampleConf struct {
		SomeSetting string `json:"some_setting"`
	}

	env := clitools.EnvStage

	println("Sample application that demonstrates logging in to elephant from a CLI tool\n")

	app, err := clitools.NewConfigurationHandler[SampleConf]("clitools", "elephant-cli")
	if err != nil {
		panic(fmt.Errorf("create configuration handler: %w", err))
	}

	token, err := app.GetAccessToken(context.Background(), env, []string{
		"doc_read",
	})
	if err != nil {
		panic(fmt.Errorf("authenticate: %w", err))
	}

	app.SetConfiguration(SampleConf{
		SomeSetting: "that we want to track",
	})

	err = app.Save()
	if err != nil {
		panic(fmt.Errorf("save configuration: %w", err))
	}

	enc := json.NewEncoder(os.Stdout)

	enc.SetIndent("", "  ")

	println("Current token:")
	_ = enc.Encode(token)
}

Index

Examples

Constants

View Source
const (
	EnvLocal = "local"
	EnvStage = "stage"
	EnvProd  = "prod"
)

Default environments. EnvLocal will by default be mapped to the stage OIDC configuration endpoint.

View Source
const (
	StageOIDCConfigURL = "https://login.stage.tt.se/realms/elephant/.well-known/openid-configuration"
	ProdOIDCConfigURL  = "https://login.tt.se/realms/elephant/.well-known/openid-configuration"
)

Standard OIDC configurations endpoints at TT.

View Source
const DefaultApplicationID = "elephant-cli"

DefaultApplicationID when authorising CLI applications.

Variables

This section is empty.

Functions

func LoadEnv added in v0.3.0

func LoadEnv(app string) error

This will not override any variables that are set, and the .env file takes precedence over config.env.

func UserConfigDir added in v0.3.0

func UserConfigDir() (string, error)

UserConfigDir gives preference to XDG_CONFIG_HOME, letting users in any OS specify a linux-style user config location. If XDG_CONFIG_HOME is empty it behaves just like os.UserConfigDir().

Types

type AccessToken

type AccessToken struct {
	Token         string    `json:"token"`
	Expires       time.Time `json:"expires"`
	Scopes        []string  `json:"scopes"`
	GrantedScopes []string  `json:"granted_scopes"`
}

AccessToken that can be used to communicate with our APIs.

type ConfigurationHandler

type ConfigurationHandler[T any] struct {
	// contains filtered or unexported fields
}

func NewConfigurationHandler

func NewConfigurationHandler[T any](name string, clientID string) (*ConfigurationHandler[T], error)

NewConfigurationHandler crates a configuration handler using the application specific configuration T, and loads the current configuration from disk if it's available. Name is used as the directory name for the stored configuration, and clientID must match what has been set up in our OIDC provider.

func (*ConfigurationHandler[T]) GetAccessToken

func (ac *ConfigurationHandler[T]) GetAccessToken(
	ctx context.Context, environment string, scopes []string,
) (_ AccessToken, outErr error)

GetAccessToken either returns an existing non-expired token for the environment that matches the requested scope, or starts the authorization flow to get a new token.

During the authorisation flow we will attempt to automatically open a URL in the users browser.

func (*ConfigurationHandler[T]) GetConfiguration

func (ac *ConfigurationHandler[T]) GetConfiguration() T

GetConfiguration returns the application-specific configuration.

func (*ConfigurationHandler[T]) Load added in v0.2.0

func (ac *ConfigurationHandler[T]) Load() error

Load configuration and tokens from disk.

func (*ConfigurationHandler[T]) RegisterEnvironment

func (ac *ConfigurationHandler[T]) RegisterEnvironment(
	ctx context.Context,
	name string, conf OIDCEnvironment,
) error

RegisterEnvironment can be used to register a non-standard environment.

func (*ConfigurationHandler[T]) Save

func (ac *ConfigurationHandler[T]) Save() error

Save configuration and tokens to disk.

func (*ConfigurationHandler[T]) SetConfiguration

func (ac *ConfigurationHandler[T]) SetConfiguration(conf T)

GetConfiguration updates the application-specific configuration.

type OIDCConfig added in v0.2.0

type OIDCConfig struct {
	Issuer                string `json:"issuer"`
	AuthorizationEndpoint string `json:"authorization_endpoint"`
	TokenEndpoint         string `json:"token_endpoint"`
	IntrospectionEndpoint string `json:"introspection_endpoint"`
	UserinfoEndpoint      string `json:"userinfo_endpoint"`
	EndSessionEndpoint    string `json:"end_session_endpoint"`
}

type OIDCEnvironment added in v0.2.0

type OIDCEnvironment struct {
	Refreshed     time.Time   `json:"refreshed,omitempty,omitzero"`
	OIDCConfigURL string      `json:"oidc_config_url,omitempty"`
	OIDCConfig    *OIDCConfig `json:"oidc_config"`
}

func (*OIDCEnvironment) EnsureOIDCConfig added in v0.2.0

func (ce *OIDCEnvironment) EnsureOIDCConfig(
	ctx context.Context, client *http.Client, maxAge time.Duration,
) (outErr error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL