plugin

package
v1.4.0 Latest Latest
Warning

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

Go to latest
Published: May 14, 2024 License: Apache-2.0 Imports: 17 Imported by: 32

Documentation

Overview

Package plugin provides types and functions common among plugins.

See examples in "github.com/IBM-Cloud/ibm-cloud-cli-sdk/plugin_examples".

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Start

func Start(plugin Plugin)

Start starts the plugin.

func StartWithArgs

func StartWithArgs(plugin Plugin, args []string)

StartWithArgs starts the plugin with the given arguments.

Types

type Command

type Command struct {
	Namespace   string   // full qualified name of the command's namespace
	Name        string   // name of the command
	Alias       string   // Deprecated: use Aliases instead.
	Aliases     []string // command aliases
	Description string   // short description of the command
	Usage       string   // usage detail to be displayed in command help
	Flags       []Flag   // command options
	Hidden      bool     // true to hide the command in help text
	Stage       Stage    // stage of the command
}

Command describes the metadata of a plugin command

func (Command) NameAndAliases added in v0.2.0

func (c Command) NameAndAliases() []string

type Flag

type Flag struct {
	Name        string // name of the option
	Description string // description of the option
	HasValue    bool   // whether the option requires a value or not
	Hidden      bool   // true to hide the option in command help
}

Flag describes a command option

func ConvertCobraFlagsToPluginFlags added in v0.10.0

func ConvertCobraFlagsToPluginFlags(cmd *cobra.Command) []Flag

ConvertCobraFlagsToPluginFlags will convert flags defined by Cobra framework to Plugin Flags Method is used when defining the Flags in command metadata. @see Plugin#GetMetadata() for use case

type Namespace

type Namespace struct {
	ParentName  string   // full qualified name of the parent namespace
	Name        string   // base name
	Aliases     []string // aliases
	Description string   // description of the namespace
	Stage       Stage    // stage of the commands in the namespace
}

Namespace represents a category of commands that have similar functionalities. A command under a namespace is run using 'bx [namespace] [command]'.

Some namespaces are predefined by Bluemix CLI and sharable among plugins; others are non-shared and defined in each plugin. The Plugin can reference a predefined namespace or define a non-shared namespace of its own.

Namespace also supports hierarchy. For example, namespace 'A' can have a sub namespace 'B'. And the full qualified name of namespace B is 'A B'.

func (Namespace) NameAndAliases added in v0.2.0

func (n Namespace) NameAndAliases() []string

type Plugin

type Plugin interface {
	// GetMetadata returns the metadata of the plugin.
	GetMetadata() PluginMetadata

	// Run runs the plugin with given plugin context and arguments.
	//
	// Note: the first arg in args is a command or alias no matter the command
	// has namespace or not. To get the namespace, call
	// PluginContext.CommandNamespace.
	Run(c PluginContext, args []string)
}

Plugin is an interface for Bluemix CLI plugins.

type PluginConfig

type PluginConfig interface {
	// Get returns the value for a given key.
	// The value can be float64, bool, string, []interface{},
	// map[string]interface or nil if the key not exist.
	Get(key string) interface{}

	// GetWithDefault returns the value for a given key, or defaultVal if the
	// key not exist.
	GetWithDefault(key string, defaultVal interface{}) interface{}

	// GetString returns string value for a given key.
	GetString(key string) (string, error)

	// GetStringWithDefault returns string value for a given key or defaultVal
	// if the key not exist.
	GetStringWithDefault(key string, defaultVal string) (string, error)

	// GetBool returns boolean value for a given key.
	// If the value is a string, it attempts to convert it to bool.
	GetBool(key string) (bool, error)

	// GetBoolWithDefault returns boolean value for a given key or defaultVal if
	// the key not exist.
	GetBoolWithDefault(key string, defaultVal bool) (bool, error)

	// GetInt returns int value for a given key.
	// If the value is float or string, attempts to convert it to int.
	GetInt(key string) (int, error)

	// GetIntWithDefault returns int value for a given key or defaultVal if the
	// key not exist.
	// If the value is float or string, it attempts to convert it to int.
	GetIntWithDefault(key string, defaultVal int) (int, error)

	// GetFloat returns float64 value for a given key.
	// If the value is int or string, it attempts to convert it to float64.
	GetFloat(key string) (float64, error)

	// GetFloatWithDefault returns float64 value for a given key or defaultVal
	// if the key not exist.
	// If the value is int or string, it attempts to convert it to float64.
	GetFloatWithDefault(key string, defaultVal float64) (float64, error)

	// GetStringSlice return string slice for a given key.
	// If the key not exists, return empty string slice.
	GetStringSlice(key string) ([]string, error)

	// GetIntSlice return string slice for a given key.
	GetIntSlice(key string) ([]int, error)

	// GetFloatSlice return string slice for a given key.
	GetFloatSlice(key string) ([]float64, error)

	// GetStringMap return map[string]interface{} for a given key.
	GetStringMap(key string) (map[string]interface{}, error)

	// GetStringMap return map[string]string for a given key.
	GetStringMapString(key string) (map[string]string, error)

	// Exists checks whether the value for a given key exists or not.
	Exists(key string) bool

	// Set sets the value for a given key.
	Set(string, interface{}) error

	// Erase delete a given key.
	Erase(key string) error
}

PluginConfig defines methods to access plug-in's private configuration stored in a JSON format.

type PluginConfigInvalidTypeError

type PluginConfigInvalidTypeError struct {
	Key          string
	ExpectedType string
	Value        interface{}
}

PluginConfigInvalidTypeError describes the value for a given key in plugin configuration was not appropriate for a value of a specific type.

func (PluginConfigInvalidTypeError) Error

type PluginContext

type PluginContext interface {
	// APIEndpoint returns the targeted API endpoint of IBM Cloud
	APIEndpoint() string

	// HasAPIEndpoint() returns whether an IBM Cloud has been targeted
	HasAPIEndpoint() bool

	// IsPrivateEndpointEnabled returns whether use of the private endpoint has been chosen
	IsPrivateEndpointEnabled() bool

	// IsAccessFromVPC returns true if the access from VPC private endpoint is enabled.
	IsAccessFromVPC() bool

	// ConsoleEndpoint returns console's public endpoint if api endpoint is public, or returns
	// private endpoint if api endpoint is private.
	ConsoleEndpoint() string

	// ConsoleEndpoints returns both the public and private endpoint of console.
	ConsoleEndpoints() models.Endpoints

	// IAMEndpoint returns IAM's public endpoint if api endpoint is public, or returns private
	// endpoint if api endpoint is private.
	IAMEndpoint() string

	// IAMEndpoints returns both the public and private endpoint of IAM.
	IAMEndpoints() models.Endpoints

	// GetEndpoint is a utility method to return private or public endpoint for a requested service.
	// It supports public cloud only. For non public clouds, plugin needs its own way to determine endpoint.
	GetEndpoint(endpoints.Service) (string, error)

	// CloudName returns the name of the target cloud
	CloudName() string

	// CloudType returns the type of the target cloud (like 'public',
	// 'dedicated' etc)
	CloudType() string

	// Region returns the targeted region
	CurrentRegion() models.Region

	// CRIType returns the type of compute resource the user logged in as, if applicable. Valid values are `IKS`, `VPC`, or `OTHER`
	CRIType() string

	// VPCCRITokenURL() returns the value specified by the environment variable 'IBMCLOUD_CR_VPC_URL', if set.
	// Otherwise, the default VPC auth url specified by the constant `DefaultServerEndpoint` is returned
	VPCCRITokenURL() string

	// HasTargetedRegion() return whether a region is targeted
	HasTargetedRegion() bool

	// IAMToken returns the IAM access token
	IAMToken() string

	// IAMRefreshToken returns the IAM refresh token
	IAMRefreshToken() string

	// RefreshIAMToken refreshes and returns the IAM access token
	RefreshIAMToken() (string, error)

	// UserEmail returns the Email of the logged in user
	UserEmail() string

	// IsLoggedIn returns if a user has logged into IBM Cloud
	IsLoggedIn() bool

	// IsLoggedInWithServiceID returns if a user has logged into IBM Cloud using service ID.
	IsLoggedInWithServiceID() bool

	// IsLoggedInAsProfile returns true if a user logged into IBM Cloud using an IAM token pertaining to a trusted profile
	IsLoggedInAsProfile() bool

	// IsLoggedInAsCRI returns true if a user logged into IBM Cloud as a compute resource.
	IsLoggedInAsCRI() bool

	// IMSAccountID returns ID of the IMS account linked to the targeted BSS
	// account
	IMSAccountID() string

	// Account returns the targeted a BSS account
	CurrentAccount() models.Account

	// HasTargetedAccount returns whether an account has been targeted
	HasTargetedAccount() bool

	// HasTargetedProfile returns whether a profile has been targeted
	HasTargetedProfile() bool

	// CurrentProfile returns the targeted trusted profile
	CurrentProfile() models.Profile

	// HasTargetedComputeResource returns whether a compute resource has been targeted
	HasTargetedComputeResource() bool

	// ResourceGroup returns the targeted resource group
	CurrentResourceGroup() models.ResourceGroup

	// HasTargetedResourceGroup returns whether a resource group has been targeted
	HasTargetedResourceGroup() bool

	// Locale returns user specified locale
	Locale() string

	// Trace returns user specified trace setting.
	// The value is "true", "false" or path of the trace output file.
	Trace() string

	// ColorEnabled returns whether terminal displays color or not
	ColorEnabled() string

	// IsSSLDisabled returns whether skipping SSL validation or not
	IsSSLDisabled() bool

	// PluginDirectory returns the installation directory of the plugin
	PluginDirectory() string

	// HTTPTimeout returns a timeout for HTTP Client
	HTTPTimeout() int

	// VersionCheckEnabled() returns whether checking for update is performmed
	VersionCheckEnabled() bool

	// PluginConfig returns the plugin specific configuarion
	PluginConfig() PluginConfig

	// CommandNamespace returns the name of the parsed namespace
	CommandNamespace() string

	// CLIName returns binary name of the Bluemix CLI that is invoking the plugin
	CLIName() string
}

PluginContext is a Bluemix CLI context passed to plugin's Run method. It carries service endpoints info, login session, user configuration, plugin configuration and provides utility methods.

func InitPluginContext

func InitPluginContext(pluginName string) PluginContext

InitPluginContext initializes a plugin context for a given plugin

type PluginMetadata

type PluginMetadata struct {
	Name          string      // name of the plugin
	Aliases       []string    // aliases of the plugin
	Version       VersionType // version of the plugin
	MinCliVersion VersionType // minimal version of CLI required by the plugin
	Namespaces    []Namespace // list of namespaces provided by the plugin
	Commands      []Command   // list of commands provided by the plugin

	// SDKVersion is SDK version used by the plugin.
	// It is set by the plugin framework to check SDK compatibility with the CLI.
	SDKVersion VersionType

	// If DelegateBashCompletion is true, plugin command's completion is handled by plugin.
	// The CLI will invoke '<plugin_binary> SendCompletion <args>'
	DelegateBashCompletion bool

	// Whether the plugin supports private endpoint
	PrivateEndpointSupported bool

	// Whether the plugin supports private endpoint access via VPC
	IsAccessFromVPC bool

	// Whether the plugin was built using Cobra
	IsCobraPlugin bool
}

PluginMetadata describes metadata of a plugin.

func (PluginMetadata) NameAndAliases added in v0.2.0

func (p PluginMetadata) NameAndAliases() []string

type Stage added in v0.3.0

type Stage string

Stage decribes the stage of the namespace or command and will be shown in the help text

const (
	StageExperimental Stage = "experimental"
	StageBeta         Stage = "beta"
	StageDeprecated   Stage = "deprecated"
)

Valid stages

type VersionType

type VersionType struct {
	Major int // major version
	Minor int // minimal version
	Build int // build number
}

VersionType describes the version info

func (VersionType) String

func (v VersionType) String() string

Directories

Path Synopsis
Code generated by counterfeiter.
Code generated by counterfeiter.

Jump to

Keyboard shortcuts

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