plugin

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Apr 27, 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.

func WithHostClient added in v0.3.0 

func WithHostClient(ctx context.Context, client *HostServiceClient) context.Context

WithHostClient returns a new context with the given HostServiceClient attached.

Types

type AuthHandlerGRPCClient 

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

AuthHandlerGRPCClient is a minimal stub auth handler client.

func (*AuthHandlerGRPCClient) Client 

func (c *AuthHandlerGRPCClient) Client() proto.AuthHandlerServiceClient

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 

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

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 (s *AuthHandlerGRPCServer) ConfigureAuthHandler(ctx context.Context, req *proto.ConfigureAuthHandlerRequest) (*proto.ConfigureAuthHandlerResponse, error)

func (*AuthHandlerGRPCServer) GetAuthHandlers 

func (s *AuthHandlerGRPCServer) GetAuthHandlers(ctx context.Context, _ *proto.GetAuthHandlersRequest) (*proto.GetAuthHandlersResponse, error)

func (*AuthHandlerGRPCServer) GetStatus 

func (s *AuthHandlerGRPCServer) GetStatus(ctx context.Context, req *proto.GetStatusRequest) (*proto.GetStatusResponse, error)

func (*AuthHandlerGRPCServer) GetToken 

func (s *AuthHandlerGRPCServer) GetToken(ctx context.Context, req *proto.GetTokenRequest) (*proto.GetTokenResponse, error)

func (*AuthHandlerGRPCServer) ListCachedTokens 

func (s *AuthHandlerGRPCServer) ListCachedTokens(ctx context.Context, req *proto.ListCachedTokensRequest) (*proto.ListCachedTokensResponse, error)

func (*AuthHandlerGRPCServer) Login 

func (s *AuthHandlerGRPCServer) Login(req *proto.LoginRequest, stream grpc.ServerStreamingServer[proto.LoginStreamMessage]) error

func (*AuthHandlerGRPCServer) Logout 

func (s *AuthHandlerGRPCServer) Logout(ctx context.Context, req *proto.LogoutRequest) (*proto.LogoutResponse, error)

func (*AuthHandlerGRPCServer) PurgeExpiredTokens 

func (s *AuthHandlerGRPCServer) PurgeExpiredTokens(ctx context.Context, req *proto.PurgeExpiredTokensRequest) (*proto.PurgeExpiredTokensResponse, error)

func (*AuthHandlerGRPCServer) StopAuthHandler 

func (s *AuthHandlerGRPCServer) StopAuthHandler(ctx context.Context, req *proto.StopAuthHandlerRequest) (*proto.StopAuthHandlerResponse, error)

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 (s *GRPCServer) ConfigureProvider(ctx context.Context, req *proto.ConfigureProviderRequest) (*proto.ConfigureProviderResponse, error)

func (*GRPCServer) DescribeWhatIf 

func (s *GRPCServer) DescribeWhatIf(ctx context.Context, req *proto.DescribeWhatIfRequest) (*proto.DescribeWhatIfResponse, error)

func (*GRPCServer) ExecuteProvider 

func (s *GRPCServer) ExecuteProvider(ctx context.Context, req *proto.ExecuteProviderRequest) (*proto.ExecuteProviderResponse, error)

func (*GRPCServer) ExecuteProviderStream 

func (s *GRPCServer) ExecuteProviderStream(req *proto.ExecuteProviderRequest, stream proto.PluginService_ExecuteProviderStreamServer) error

func (*GRPCServer) ExtractDependencies 

func (s *GRPCServer) ExtractDependencies(ctx context.Context, req *proto.ExtractDependenciesRequest) (*proto.ExtractDependenciesResponse, error)

func (*GRPCServer) GetProviderDescriptor 

func (s *GRPCServer) GetProviderDescriptor(ctx context.Context, req *proto.GetProviderDescriptorRequest) (*proto.GetProviderDescriptorResponse, error)

func (*GRPCServer) GetProviders 

func (s *GRPCServer) GetProviders(ctx context.Context, _ *proto.GetProvidersRequest) (*proto.GetProvidersResponse, error)

func (*GRPCServer) StopProvider 

func (s *GRPCServer) StopProvider(ctx context.Context, req *proto.StopProviderRequest) (*proto.StopProviderResponse, error)

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 HostClientFromContext added in v0.3.0 

func HostClientFromContext(ctx context.Context) *HostServiceClient

HostClientFromContext retrieves the HostServiceClient from the context. Returns nil if no host client is available (e.g. the host did not start a HostService broker).

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.

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.