plugin

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Apr 24, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package plugin provides the shared contract between scafctl (host) and plugin binaries. Plugin authors implement ProviderPlugin and/or AuthHandlerPlugin, then call Serve() or ServeAuthHandler() from main().

Index

Constants

View Source
const (
	PluginName            = "provider"
	AuthHandlerPluginName = "auth-handler"
)
View Source
const PluginProtocolVersion int32 = 2

PluginProtocolVersion is the current plugin protocol version.

Variables

View Source
var ErrStreamingNotSupported = errors.New("streaming execution not supported")

ErrStreamingNotSupported is returned by ExecuteProviderStream when the plugin does not support streaming execution.

Functions

func ProtoToDescriptor

func ProtoToDescriptor(pd *proto.ProviderDescriptor) (*provider.Descriptor, error)

ProtoToDescriptor converts proto.ProviderDescriptor to provider.Descriptor.

func Serve

func Serve(impl ProviderPlugin)

Serve is a helper function for plugin implementers to serve their provider plugins.

func ServeAuthHandler

func ServeAuthHandler(impl AuthHandlerPlugin)

ServeAuthHandler is a helper function for plugin implementers to serve their auth handler plugins.

Types

type AuthHandlerGRPCClient

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

AuthHandlerGRPCClient is a minimal stub auth handler client.

func (*AuthHandlerGRPCClient) Client

Client returns the underlying AuthHandlerServiceClient for host-side wrapping.

type AuthHandlerGRPCPlugin

type AuthHandlerGRPCPlugin struct {
	goplugin.Plugin
	Impl AuthHandlerPlugin
}

AuthHandlerGRPCPlugin implements plugin.GRPCPlugin for auth handler plugins.

func (*AuthHandlerGRPCPlugin) GRPCClient

GRPCClient returns a minimal stub client for auth handler plugins.

func (*AuthHandlerGRPCPlugin) GRPCServer

func (p *AuthHandlerGRPCPlugin) GRPCServer(broker *goplugin.GRPCBroker, s *grpc.Server) error

GRPCServer registers the auth handler gRPC server.

type AuthHandlerGRPCServer

type AuthHandlerGRPCServer struct {
	proto.UnimplementedAuthHandlerServiceServer
	Impl AuthHandlerPlugin
	// contains filtered or unexported fields
}

AuthHandlerGRPCServer implements the gRPC server for auth handler plugins.

func (*AuthHandlerGRPCServer) ConfigureAuthHandler

func (*AuthHandlerGRPCServer) GetAuthHandlers

func (*AuthHandlerGRPCServer) GetStatus

func (*AuthHandlerGRPCServer) GetToken

func (*AuthHandlerGRPCServer) ListCachedTokens

func (*AuthHandlerGRPCServer) Login

func (*AuthHandlerGRPCServer) Logout

func (*AuthHandlerGRPCServer) PurgeExpiredTokens

func (*AuthHandlerGRPCServer) StopAuthHandler

type AuthHandlerInfo

type AuthHandlerInfo struct {
	Name         string            `json:"name" yaml:"name"`
	DisplayName  string            `json:"displayName" yaml:"displayName"`
	Flows        []auth.Flow       `json:"flows" yaml:"flows"`
	Capabilities []auth.Capability `json:"capabilities" yaml:"capabilities"`
}

AuthHandlerInfo holds static metadata about an auth handler exposed by a plugin.

type AuthHandlerPlugin

type AuthHandlerPlugin interface {
	GetAuthHandlers(ctx context.Context) ([]AuthHandlerInfo, error)
	ConfigureAuthHandler(ctx context.Context, handlerName string, cfg ProviderConfig) error
	Login(ctx context.Context, handlerName string, req LoginRequest, deviceCodeCb func(DeviceCodePrompt)) (*LoginResponse, error)
	Logout(ctx context.Context, handlerName string) error
	GetStatus(ctx context.Context, handlerName string) (*auth.Status, error)
	GetToken(ctx context.Context, handlerName string, req TokenRequest) (*TokenResponse, error)
	ListCachedTokens(ctx context.Context, handlerName string) ([]*auth.CachedTokenInfo, error)
	PurgeExpiredTokens(ctx context.Context, handlerName string) (int, error)
	StopAuthHandler(ctx context.Context, handlerName string) error
}

AuthHandlerPlugin is the interface that auth handler plugins must implement.

type DeviceCodePrompt

type DeviceCodePrompt struct {
	UserCode        string `json:"userCode" yaml:"userCode"`
	VerificationURI string `json:"verificationUri" yaml:"verificationUri"`
	Message         string `json:"message" yaml:"message"`
}

DeviceCodePrompt is sent over streaming Login to relay device-code info to the host.

type GRPCClient

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

GRPCClient is a minimal stub provider plugin client.

func (*GRPCClient) Client

func (c *GRPCClient) Client() proto.PluginServiceClient

Client returns the underlying PluginServiceClient for host-side wrapping.

type GRPCPlugin

type GRPCPlugin struct {
	goplugin.Plugin
	Impl ProviderPlugin
}

GRPCPlugin implements plugin.GRPCPlugin from hashicorp/go-plugin.

func (*GRPCPlugin) GRPCClient

func (p *GRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)

GRPCClient returns a minimal stub client. The host wraps this with its own extended GRPCClient that adds broker wiring and HostService startup.

func (*GRPCPlugin) GRPCServer

func (p *GRPCPlugin) GRPCServer(broker *goplugin.GRPCBroker, s *grpc.Server) error

GRPCServer registers the gRPC server (plugin side).

type GRPCServer

type GRPCServer struct {
	proto.UnimplementedPluginServiceServer
	Impl ProviderPlugin
	// contains filtered or unexported fields
}

GRPCServer implements the gRPC server for the plugin.

func (*GRPCServer) ConfigureProvider

func (*GRPCServer) DescribeWhatIf

func (*GRPCServer) ExecuteProvider

func (*GRPCServer) ExecuteProviderStream

func (*GRPCServer) GetProviders

func (*GRPCServer) StopProvider

type HandshakeConfigData

type HandshakeConfigData struct {
	ProtocolVersion  uint   `json:"protocolVersion" yaml:"protocolVersion"`
	MagicCookieKey   string `json:"magicCookieKey" yaml:"magicCookieKey"`
	MagicCookieValue string `json:"magicCookieValue" yaml:"magicCookieValue"`
}

HandshakeConfigData contains the handshake configuration.

func AuthHandlerHandshakeConfig

func AuthHandlerHandshakeConfig() HandshakeConfigData

AuthHandlerHandshakeConfig returns the handshake configuration for auth handler plugin compatibility. Returns a copy to prevent mutation of shared state.

func HandshakeConfig

func HandshakeConfig() HandshakeConfigData

HandshakeConfig returns the handshake configuration for provider plugin compatibility. Returns a copy to prevent mutation of shared state.

type HostServiceClient

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

HostServiceClient wraps the HostService gRPC client (used by plugins).

func NewHostServiceClient

func NewHostServiceClient(conn *grpc.ClientConn) *HostServiceClient

NewHostServiceClient creates a HostServiceClient from a gRPC connection.

func (*HostServiceClient) DeleteSecret

func (c *HostServiceClient) DeleteSecret(ctx context.Context, name string) error

DeleteSecret removes a secret from the host's secret store.

func (*HostServiceClient) GetAuthIdentity

func (c *HostServiceClient) GetAuthIdentity(ctx context.Context, handler, scope string) (*proto.Claims, error)

GetAuthIdentity retrieves identity claims from the host's auth registry.

func (*HostServiceClient) GetAuthToken

func (c *HostServiceClient) GetAuthToken(ctx context.Context, handler, scope string, minValidFor int64, forceRefresh bool) (*proto.GetAuthTokenResponse, error)

GetAuthToken retrieves a valid access token from the host's auth registry.

func (*HostServiceClient) GetSecret

func (c *HostServiceClient) GetSecret(ctx context.Context, name string) (string, bool, error)

GetSecret retrieves a secret from the host's secret store.

func (*HostServiceClient) ListAuthHandlers

func (c *HostServiceClient) ListAuthHandlers(ctx context.Context) (handlers []string, defaultHandler string, err error)

ListAuthHandlers lists available auth handlers on the host.

func (*HostServiceClient) ListSecrets

func (c *HostServiceClient) ListSecrets(ctx context.Context, pattern string) ([]string, error)

ListSecrets lists secret names from the host's secret store.

func (*HostServiceClient) SetSecret

func (c *HostServiceClient) SetSecret(ctx context.Context, name, value string) error

SetSecret stores a secret in the host's secret store.

type LoginRequest

type LoginRequest struct {
	TenantID string        `json:"tenantId,omitempty" yaml:"tenantId,omitempty"`
	Scopes   []string      `json:"scopes,omitempty" yaml:"scopes,omitempty"`
	Flow     auth.Flow     `json:"flow,omitempty" yaml:"flow,omitempty"`
	Timeout  time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
}

LoginRequest contains parameters for a plugin Login call.

type LoginResponse

type LoginResponse struct {
	Claims    *auth.Claims `json:"claims,omitempty" yaml:"claims,omitempty"`
	ExpiresAt time.Time    `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty"`
}

LoginResponse contains the result of a plugin Login call.

type LoginStreamMessage

type LoginStreamMessage struct {
	DeviceCodePrompt *DeviceCodePrompt `json:"deviceCodePrompt,omitempty" yaml:"deviceCodePrompt,omitempty"`
	Result           *LoginResponse    `json:"result,omitempty" yaml:"result,omitempty"`
	Error            string            `json:"error,omitempty" yaml:"error,omitempty"`
}

LoginStreamMessage represents a message in the Login server-stream.

type ProviderConfig

type ProviderConfig struct {
	Quiet         bool                       `json:"quiet" yaml:"quiet"`
	NoColor       bool                       `json:"noColor" yaml:"noColor"`
	BinaryName    string                     `json:"binaryName" yaml:"binaryName"`
	HostServiceID uint32                     `json:"hostServiceId,omitempty" yaml:"hostServiceId,omitempty"`
	Settings      map[string]json.RawMessage `json:"settings,omitempty" yaml:"settings,omitempty"`
}

ProviderConfig holds host-side configuration sent to a provider once after plugin load via the ConfigureProvider RPC.

type ProviderPlugin

type ProviderPlugin interface {
	GetProviders(ctx context.Context) ([]string, error)
	GetProviderDescriptor(ctx context.Context, providerName string) (*provider.Descriptor, error)
	ConfigureProvider(ctx context.Context, providerName string, cfg ProviderConfig) error
	ExecuteProvider(ctx context.Context, providerName string, input map[string]any) (*provider.Output, error)
	ExecuteProviderStream(ctx context.Context, providerName string, input map[string]any, cb func(StreamChunk)) error
	DescribeWhatIf(ctx context.Context, providerName string, input map[string]any) (string, error)
	ExtractDependencies(ctx context.Context, providerName string, inputs map[string]any) ([]string, error)
	StopProvider(ctx context.Context, providerName string) error
}

ProviderPlugin is the interface that plugins must implement.

type StreamChunk

type StreamChunk struct {
	Stdout []byte           `json:"stdout,omitempty" yaml:"stdout,omitempty"`
	Stderr []byte           `json:"stderr,omitempty" yaml:"stderr,omitempty"`
	Result *provider.Output `json:"result,omitempty" yaml:"result,omitempty"`
	Error  string           `json:"error,omitempty" yaml:"error,omitempty"`
}

StreamChunk represents one chunk from a streaming provider execution.

type TokenRequest

type TokenRequest struct {
	Scope        string        `json:"scope,omitempty" yaml:"scope,omitempty"`
	MinValidFor  time.Duration `json:"minValidFor,omitempty" yaml:"minValidFor,omitempty"`
	ForceRefresh bool          `json:"forceRefresh,omitempty" yaml:"forceRefresh,omitempty"`
}

TokenRequest contains parameters for a plugin GetToken call.

type TokenResponse

type TokenResponse struct {
	AccessToken string    `json:"accessToken" yaml:"accessToken"` //nolint:gosec
	TokenType   string    `json:"tokenType" yaml:"tokenType"`
	ExpiresAt   time.Time `json:"expiresAt" yaml:"expiresAt"`
	Scope       string    `json:"scope,omitempty" yaml:"scope,omitempty"`
	CachedAt    time.Time `json:"cachedAt,omitempty" yaml:"cachedAt,omitempty"`
	Flow        auth.Flow `json:"flow,omitempty" yaml:"flow,omitempty"`
	SessionID   string    `json:"sessionId,omitempty" yaml:"sessionId,omitempty"`
}

TokenResponse contains the result of a plugin GetToken call.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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