plugins

package
v1.50.4 Latest Latest
Warning

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

 Go to latest Published: Aug 21, 2026 License: Apache-2.0 Imports: 39 Imported by: 0

Documentation

Overview

Package plugins provides the plugin system for extending the CLI.

Index

Constants

This section is empty.

Variables

View Source 
var (
	PluginDev   = false
	PluginsPath string
)

dev mode vars

Functions

func BackfillMissingInstalledPluginMetadata added in v1.42.14 

func BackfillMissingInstalledPluginMetadata(ctx context.Context, config config.IConfig, fs afero.Fs, apiBaseURL, dashboardBaseURL string) error

BackfillMissingInstalledPluginMetadata refreshes local metadata for plugins that were installed before `plugin-metadata/*.toml` became the source of truth. It first migrates from the legacy cached `plugins.toml` on disk when that cache still describes the installed version, then falls back to the live metadata endpoint for plugins not present in that cache. Failures are best-effort: a failed backfill should not prevent existing plugin commands from being registered via the same cached-manifest fallback.

func CheckLatestPluginVersion added in v1.42.2 

func CheckLatestPluginVersion(ctx context.Context, config config.IConfig, fs afero.Fs, plugin Plugin, apiBaseURL, dashboardBaseURL string)

CheckLatestPluginVersion prints an upgrade hint to stderr if live metadata has a newer version of the plugin than what is currently installed.

func CleanupAllClients added in v1.8.1 

func CleanupAllClients()

CleanupAllClients tears down and disconnects all "managed" plugin clients

func FetchRemoteResource 

func FetchRemoteResource(url string) ([]byte, error)

FetchRemoteResource returns the remote resource body

func GetBinaryExtension added in v1.8.6 

func GetBinaryExtension() string

GetBinaryExtension returns the appropriate file extension for plugin binary

func GetInstalledPluginNames added in v1.41.0 

func GetInstalledPluginNames(config config.IConfig, fs afero.Fs) ([]string, error)

GetInstalledPluginNames returns the union of plugin names recorded in config and plugin names with persisted local metadata.

func IsPluginCommand added in v1.8.2 

func IsPluginCommand(cmd *cobra.Command) bool

IsPluginCommand returns true if the command invoked is for a plugin false otherwise

func PersistInstalledPluginState added in v1.41.0 

func PersistInstalledPluginState(config config.IConfig, fs afero.Fs, plugin Plugin) error

PersistInstalledPluginState ensures local metadata and installed_plugins are both updated for a locally installed plugin.

func RecordInstalledPlugin added in v1.41.0 

func RecordInstalledPlugin(config config.IConfig, pluginName string) error

RecordInstalledPlugin ensures a plugin name is persisted in installed_plugins.

func RemoveInstalledPlugin added in v1.41.0 

func RemoveInstalledPlugin(config config.IConfig, pluginName string) error

RemoveInstalledPlugin removes a plugin name from installed_plugins if present.

func ValidatePluginShortname added in v1.42.14 

func ValidatePluginShortname(pluginName string) error

ValidatePluginShortname rejects names that could escape the plugin install or metadata directories when joined onto local filesystem paths.

Types

type CLIPluginGRPC added in v1.13.8 

type CLIPluginGRPC struct {
	// GRPCPlugin must still implement the Plugin interface
	hcplugin.Plugin
	// Concrete implementation, written in Go. This is only used for plugins
	// that are written in Go.
	Impl DispatcherGRPC
}

CLIPluginGRPC is the implementation of plugin.GRPCPlugin so we can serve/consume this.

func (*CLIPluginGRPC) GRPCClient added in v1.13.8 

func (p *CLIPluginGRPC) GRPCClient(ctx context.Context, broker *hcplugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

GRPCClient creates the GRPC client.

func (*CLIPluginGRPC) GRPCServer added in v1.13.8 

func (p *CLIPluginGRPC) GRPCServer(broker *hcplugin.GRPCBroker, s *grpc.Server) error

GRPCServer creates the GRPC server.

type CLIPluginV1 

type CLIPluginV1 struct {
	// Impl Injection
	Impl Dispatcher
}

CLIPluginV1 is the implementation of plugin.Plugin so we can serve/consume this

This has two methods: Server must return an RPC server for this plugin type. We construct a DispatcherRPCServer for this.

Client must return an implementation of our interface that communicates over an RPC client. We return a PluginClient for this.

Ignore MuxBroker. That is used to create more multiplexed streams on a plugin connection and is a more advanced use case.

func (CLIPluginV1) Client 

func (CLIPluginV1) Client(b *hcplugin.MuxBroker, c *rpc.Client) (interface{}, error)

Client returns the rpc client

func (*CLIPluginV1) Server 

func (p *CLIPluginV1) Server(*hcplugin.MuxBroker) (interface{}, error)

Server returns the rpc server

type CLIPluginV3 added in v1.37.4 

type CLIPluginV3 struct {
	hcplugin.Plugin
	Impl DispatcherV3
}

CLIPluginV3 is the implementation of plugin.GRPCPlugin so we can serve/consume this.

func (*CLIPluginV3) GRPCClient added in v1.37.4 

func (p *CLIPluginV3) GRPCClient(ctx context.Context, broker *hcplugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

GRPCClient creates the GRPC client.

func (*CLIPluginV3) GRPCServer added in v1.37.4 

func (p *CLIPluginV3) GRPCServer(broker *hcplugin.GRPCBroker, s *grpc.Server) error

GRPCServer creates the GRPC server.

type CommandInfo added in v1.40.1 

type CommandInfo struct {
	Name     string        `toml:"Name" json:"name"`
	Desc     string        `toml:"Desc" json:"desc,omitempty"`
	Commands []CommandInfo `toml:"Command,omitempty" json:"commands,omitempty"`
}

CommandInfo describes a plugin subcommand for tree display (e.g. in --map).

type CoreCLIHelper added in v1.37.4 

type CoreCLIHelper interface {
	Echo(input string) (string, error)
	SendAnalytics(eventName string, eventValue string) error
	KeychainGetPassword(key string) (string, bool, error)
	KeychainSetPassword(key string, value string) error
	KeychainDeletePassword(key string) (bool, error)
	KeychainFindCredentials() ([]string, error)
	RunPeerPlugin(pluginName string, args []string, cwd string) error
	ResolveCredentials(livemode bool) (token string, stripeContext string, resolvedLivemode bool, err error)
	ResolveCredentialsForAnyMode(livemode bool) (token string, stripeContext string, resolvedLivemode bool, err error)
}

CoreCLIHelper is the interface that's implemented by the host and called by the plugin.

func NewCoreCLIHelper added in v1.37.4 

func NewCoreCLIHelper(ctx context.Context, cfg config.IConfig, fs afero.Fs) CoreCLIHelper

NewCoreCLIHelper creates a new CoreCLIHelper with the given context, config, and filesystem.

type CoreCLIHelperClient added in v1.37.4 

type CoreCLIHelperClient struct {
	// contains filtered or unexported fields
}

func (*CoreCLIHelperClient) Echo added in v1.37.4 

func (c *CoreCLIHelperClient) Echo(input string) (string, error)

func (*CoreCLIHelperClient) KeychainDeletePassword added in v1.38.0 

func (c *CoreCLIHelperClient) KeychainDeletePassword(key string) (bool, error)

func (*CoreCLIHelperClient) KeychainFindCredentials added in v1.38.0 

func (c *CoreCLIHelperClient) KeychainFindCredentials() ([]string, error)

func (*CoreCLIHelperClient) KeychainGetPassword added in v1.38.0 

func (c *CoreCLIHelperClient) KeychainGetPassword(key string) (string, bool, error)

func (*CoreCLIHelperClient) KeychainSetPassword added in v1.38.0 

func (c *CoreCLIHelperClient) KeychainSetPassword(key string, value string) error

func (*CoreCLIHelperClient) ResolveCredentials added in v1.50.1 

func (c *CoreCLIHelperClient) ResolveCredentials(livemode bool) (string, string, bool, error)

func (*CoreCLIHelperClient) ResolveCredentialsForAnyMode added in v1.50.3 

func (c *CoreCLIHelperClient) ResolveCredentialsForAnyMode(livemode bool) (string, string, bool, error)

func (*CoreCLIHelperClient) RunPeerPlugin added in v1.40.7 

func (c *CoreCLIHelperClient) RunPeerPlugin(pluginName string, args []string, cwd string) error

func (*CoreCLIHelperClient) SendAnalytics added in v1.37.4 

func (c *CoreCLIHelperClient) SendAnalytics(eventName string, eventValue string) error

type CoreCLIHelperServer added in v1.37.4 

type CoreCLIHelperServer struct {
	proto.CoreCLIHelperServer
	Impl CoreCLIHelper
}

func (*CoreCLIHelperServer) Echo added in v1.37.4 

func (s *CoreCLIHelperServer) Echo(ctx context.Context, req *proto.EchoRequest) (*proto.EchoResponse, error)

func (*CoreCLIHelperServer) KeychainDeletePassword added in v1.38.0 

func (s *CoreCLIHelperServer) KeychainDeletePassword(ctx context.Context, req *proto.KeychainDeletePasswordRequest) (*proto.KeychainDeletePasswordResponse, error)

func (*CoreCLIHelperServer) KeychainFindCredentials added in v1.38.0 

func (s *CoreCLIHelperServer) KeychainFindCredentials(ctx context.Context, req *proto.KeychainFindCredentialsRequest) (*proto.KeychainFindCredentialsResponse, error)

func (*CoreCLIHelperServer) KeychainGetPassword added in v1.38.0 

func (s *CoreCLIHelperServer) KeychainGetPassword(ctx context.Context, req *proto.KeychainGetPasswordRequest) (*proto.KeychainGetPasswordResponse, error)

func (*CoreCLIHelperServer) KeychainSetPassword added in v1.38.0 

func (s *CoreCLIHelperServer) KeychainSetPassword(ctx context.Context, req *proto.KeychainSetPasswordRequest) (*proto.KeychainSetPasswordResponse, error)

func (*CoreCLIHelperServer) ResolveCredentials added in v1.50.1 

func (s *CoreCLIHelperServer) ResolveCredentials(ctx context.Context, req *proto.ResolveCredentialsRequest) (*proto.ResolveCredentialsResponse, error)

func (*CoreCLIHelperServer) ResolveCredentialsForAnyMode added in v1.50.3 

func (s *CoreCLIHelperServer) ResolveCredentialsForAnyMode(ctx context.Context, req *proto.ResolveCredentialsRequest) (*proto.ResolveCredentialsResponse, error)

func (*CoreCLIHelperServer) RunPeerPlugin added in v1.40.7 

func (s *CoreCLIHelperServer) RunPeerPlugin(ctx context.Context, req *proto.RunPeerPluginRequest) (*proto.RunPeerPluginResponse, error)

func (*CoreCLIHelperServer) SendAnalytics added in v1.37.4 

func (s *CoreCLIHelperServer) SendAnalytics(ctx context.Context, req *proto.SendAnalyticsRequest) (*proto.SendAnalyticsResponse, error)

type Dispatcher 

type Dispatcher interface {
	RunCommand(args []string) (string, error)
}

Dispatcher is the interface that we're exposing as a plugin. It is named so because it is able to dispatch a command from the main CLI to the plugin

type DispatcherGRPC added in v1.13.8 

type DispatcherGRPC interface {
	RunCommand(additionalInfo *proto.AdditionalInfo, args []string) error
}

DispatcherGRPC is the interface that's implemented by the plugin and used by the host.

type DispatcherRPCServer 

type DispatcherRPCServer struct {
	// This is the real implementation
	Impl Dispatcher
}

DispatcherRPCServer is the RPC server that a plugin talks to, conforming to the requirements of net/rpc

func (*DispatcherRPCServer) RunCommand 

func (s *DispatcherRPCServer) RunCommand(args []string, resp *string) error

RunCommand is the main entry command that can be invoked remotely by the Stripe CLI it is defined here on the plugin's RPC server then we call the internal RunCommand method finally, we then return the response back via the DispatcherRPC interface that the CLI is interacting with

type DispatcherV3 added in v1.37.4 

type DispatcherV3 interface {
	RunCommand(additionalInfo *proto.AdditionalInfo, args []string, coreCLIHelper CoreCLIHelper) error
}

DispatcherV3 is the interface that's implemented by the plugin and used by the host.

type ErrPluginNotFound added in v1.42.2 

type ErrPluginNotFound struct {
	Name string
}

ErrPluginNotFound is returned when a plugin cannot be found via the metadata endpoint or in cached local plugin metadata.

func (*ErrPluginNotFound) Error added in v1.42.2 

func (e *ErrPluginNotFound) Error() string

type FailingWriteConfig added in v1.41.0 

type FailingWriteConfig struct {
	TestConfig
	WriteErr                 error
	MutateInstalledPluginsOn bool
}

func (*FailingWriteConfig) WriteConfigField added in v1.41.0 

func (c *FailingWriteConfig) WriteConfigField(field string, value interface{}) error

type GRPCClient added in v1.13.8 

type GRPCClient struct {
	// contains filtered or unexported fields
}

GRPCClient is an implementation of the gRPC client that talks over gRPC.

func (*GRPCClient) RunCommand added in v1.13.8 

func (m *GRPCClient) RunCommand(additionalInfo *proto.AdditionalInfo, args []string) error

RunCommand calls the RPC.

type GRPCClientV3 added in v1.37.4 

type GRPCClientV3 struct {
	// contains filtered or unexported fields
}

GRPCClientV3 is an implementation of the gRPC client that talks over gRPC.

func (*GRPCClientV3) RunCommand added in v1.37.4 

func (m *GRPCClientV3) RunCommand(additionalInfo *proto.AdditionalInfo, args []string, coreCLIHelper CoreCLIHelper) error

RunCommand calls the RPC.

type GRPCServer added in v1.13.8 

type GRPCServer struct {
	proto.MainServer
	// This is the real implementation
	Impl DispatcherGRPC
}

GRPCServer is the gRPC server that GRPCClient talks to.

func (*GRPCServer) RunCommand added in v1.13.8 

func (m *GRPCServer) RunCommand(ctx context.Context, req *proto.RunCommandRequest) (*proto.RunCommandResponse, error)

RunCommand takes the incoming RPC request and calls the real implementation.

type GRPCServerV3 added in v1.37.4 

type GRPCServerV3 struct {
	proto.MainServer
	Impl DispatcherV3
	// contains filtered or unexported fields
}

GRPCServerV3 is the gRPC server that GRPCClientV3 talks to.

func (*GRPCServerV3) RunCommand added in v1.37.4 

func (m *GRPCServerV3) RunCommand(ctx context.Context, req *proto.RunCommandRequest) (*proto.RunCommandResponse, error)

RunCommand takes the incoming RPC request and calls the real implementation.

type Plugin 

type Plugin struct {
	Shortname        string        `toml:"Shortname" json:"shortname"`
	Shortdesc        string        `toml:"Shortdesc" json:"shortdesc"`
	Description      string        `toml:"Description,omitempty" json:"description,omitempty"`
	Binary           string        `toml:"Binary" json:"binary"`
	Releases         []Release     `toml:"Release" json:"releases"`
	MagicCookieValue string        `toml:"MagicCookieValue" json:"magic_cookie_value,omitempty"`
	Commands         []CommandInfo `toml:"Command,omitempty" json:"commands,omitempty"`
}

Plugin contains the plugin properties

func LookUpPlugin 

func LookUpPlugin(_ context.Context, config config.IConfig, fs afero.Fs, pluginName string) (Plugin, error)

LookUpPlugin returns persisted local metadata for an installed plugin, falling back to the legacy cached manifest during the compatibility window.

func (*Plugin) Install 

func (p *Plugin) Install(ctx context.Context, cfg config.IConfig, fs afero.Fs, version string, apiBaseURL, dashboardBaseURL string) error

Install installs the plugin of the given version.

func (*Plugin) InstalledVersion added in v1.40.7 

func (p *Plugin) InstalledVersion(config config.IConfig, fs afero.Fs) string

InstalledVersion returns the currently installed version of the plugin, or empty string if none.

func (*Plugin) IsVersionInstalled added in v1.40.7 

func (p *Plugin) IsVersionInstalled(config config.IConfig, fs afero.Fs, version string) bool

IsVersionInstalled returns true if the given version of the plugin is already installed on disk.

func (*Plugin) LookUpLatestVersion 

func (p *Plugin) LookUpLatestVersion() string

LookUpLatestVersion gets latest CLI version note: assumes versions are listed in asc order

func (*Plugin) Run 

func (p *Plugin) Run(ctx context.Context, config *config.Config, fs afero.Fs, args []string, cwd string, versionOverride string) error

Run boots up the binary and then sends the command to it via RPC. cwd sets the working directory for the plugin process; an empty string uses the current directory. versionOverride, when non-empty, forces the plugin to run at that specific installed version, bypassing the automatic version resolution (including local.build.dev priority).

func (*Plugin) Uninstall added in v1.9.0 

func (p *Plugin) Uninstall(ctx context.Context, config config.IConfig, fs afero.Fs) error

Uninstall removes a plugin from the disk and from the config's installed plugins list

type PluginClient 

type PluginClient struct {
	// contains filtered or unexported fields
}

PluginClient is an implementation that talks over RPC

func (*PluginClient) RunCommand 

func (g *PluginClient) RunCommand(args []string) (string, error)

RunCommand is the main plugin command that can be invoked remotely by the Stripe CLI we expose the command here for the CLI to call, which then calls the method directly on the RPCServer

type PluginList 

type PluginList struct {
	Plugins []Plugin `toml:"Plugin" json:"plugins"`
}

PluginList contains a list of plugins

func ListPlugins added in v1.42.2 

func ListPlugins(ctx context.Context, config config.IConfig, apiBaseURL, dashboardBaseURL string) (PluginList, error)

ListPlugins fetches the live plugin list visible to the current caller for the current platform using the list-plugins API endpoints.

type Release 

type Release struct {
	Arch    string `toml:"Arch" json:"arch"`
	OS      string `toml:"OS" json:"os"`
	Version string `toml:"Version" json:"version"`
	Sum     string `toml:"Sum" json:"sum,omitempty"`
}

Release is the type that holds release data for a specific build of a plugin

type ResolvedPluginVersion added in v1.42.0 

type ResolvedPluginVersion struct {
	Plugin    *Plugin
	Version   string
	BinaryURL string
}

ResolvedPluginVersion contains the resolved plugin metadata needed to install a specific plugin version, including a resolved download URL when the metadata endpoint already returned one.

func ResolvePluginForInstall added in v1.41.0 

func ResolvePluginForInstall(ctx context.Context, config config.IConfig, fs afero.Fs, pluginName, version, apiBaseURL, dashboardBaseURL string) (*ResolvedPluginVersion, error)

ResolvePluginForInstall resolves the plugin metadata needed by `stripe plugin install` using the metadata endpoint first and cached plugin metadata as fallback.

func ResolvePluginForUpgrade added in v1.41.0 

func ResolvePluginForUpgrade(ctx context.Context, config config.IConfig, fs afero.Fs, pluginName, apiBaseURL, dashboardBaseURL string) (*ResolvedPluginVersion, error)

ResolvePluginForUpgrade resolves the latest plugin metadata for `stripe plugin upgrade` using the plugin metadata endpoint first and cached plugin metadata as fallback.

func (*ResolvedPluginVersion) Install added in v1.42.0 

func (r *ResolvedPluginVersion) Install(ctx context.Context, config config.IConfig, fs afero.Fs, apiBaseURL, dashboardBaseURL string) error

Install installs the resolved plugin version. If the metadata lookup already resolved a concrete binary URL, it reuses that result and skips a second metadata request. Otherwise it retries metadata during install so cached local metadata can still recover fresh release details.

type TestConfig 

type TestConfig struct {
	config.Config
}

TestConfig Implementations out several methods

func (*TestConfig) GetConfigFolder 

func (c *TestConfig) GetConfigFolder(xdgPath string) string

GetConfigFolder returns the absolute path for the TestConfig

func (*TestConfig) GetInstalledPlugins added in v1.9.0 

func (c *TestConfig) GetInstalledPlugins() []string

GetInstalledPlugins returns the mocked out list of installed plugins

func (*TestConfig) InitConfig 

func (c *TestConfig) InitConfig()

InitConfig initializes the config with the values we need

func (*TestConfig) WriteConfigField added in v1.9.0 

func (c *TestConfig) WriteConfigField(field string, value interface{}) error

WriteConfigField mocks out the method so that we can ensure installed plugins data is written

type TestServers 

type TestServers struct {
	ArtifactoryServer *httptest.Server
	StripeServer      *httptest.Server
}

TestServers is a struct containing test servers that will be useful for unit testing plugin logic

func (*TestServers) CloseAll 

func (ts *TestServers) CloseAll()

CloseAll calls Close() on each of the httptest servers.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.