Documentation
¶
Overview ¶
Package plugin provides the core Plugin interface and WASM export lifecycle.
Index ¶
- Variables
- func CallHost[Req any, Resp any](hostFunc func(uint64) uint64, req Req) (Resp, error)
- func GenerateExampleTests(t *testing.T, plugin *PluginDefinition, mockClient any)
- func GenerateExampleTestsWithConfig(t *testing.T, plugin *PluginDefinition, defaultClient any, ...)
- func GetClient[T any](ctx context.Context) T
- func MustRegisterService(plugin *PluginDefinition, svc interface{})
- func PackBytes(data []byte) uint64
- func Register(p Plugin)
- func RegisterOp[I, O any](fieldName string, examples ...Example[I, O])
- func RegisterService(plugin *PluginDefinition, svc interface{}) error
- func TryGetClient[T any](ctx context.Context) (T, bool)
- func UnpackBytes(packed uint64) []byte
- func WithClient(ctx context.Context, client any) context.Context
- type Example
- type ExampleTestConfig
- type HandlerFunc
- type Op
- type Plugin
- type PluginDef
- type PluginDefinition
- type Request
- type Service
- type StubPlugin
Constants ¶
This section is empty.
Variables ¶
var Version = "0.1.0"
Version is the SDK version, set at build time.
Functions ¶
func GenerateExampleTests ¶ added in v0.4.0
func GenerateExampleTests(t *testing.T, plugin *PluginDefinition, mockClient any)
GenerateExampleTests creates table-driven tests from registered operation examples. Call this in plugin test files to ensure examples stay valid.
Example usage:
func TestExamples(t *testing.T) {
mockClient := &mockDNSResolver{...}
plugin.GenerateExampleTests(t, core.Plugin, mockClient)
}
func GenerateExampleTestsWithConfig ¶ added in v0.4.0
func GenerateExampleTestsWithConfig( t *testing.T, plugin *PluginDefinition, defaultClient any, config ExampleTestConfig, )
GenerateExampleTestsWithConfig creates tests with custom configuration.
func GetClient ¶ added in v0.4.0
GetClient extracts a typed client from the context. Panics if the client is not present or is the wrong type.
Example:
func (s *DNSService) ResolveHandler(ctx context.Context, in *ResolveInput) (*ResolveOutput, error) {
resolver := plugin.GetClient[ports.DNSResolver](ctx)
records, err := resolver.LookupHost(ctx, in.Hostname)
// ...
}
func MustRegisterService ¶ added in v0.3.0
func MustRegisterService(plugin *PluginDefinition, svc interface{})
MustRegisterService registers a service or panics. Use this in init() functions.
func RegisterOp ¶ added in v0.4.0
RegisterOp captures type parameters and examples for an operation. Must be called in init() BEFORE MustRegisterService for each Op field.
Example:
func init() {
plugin.RegisterOp[ResolveInput, ResolveOutput]("Resolve",
plugin.Example[ResolveInput, ResolveOutput]{
Name: "basic",
Input: ResolveInput{Hostname: "example.com"},
},
)
plugin.MustRegisterService(core.Plugin, &DNSService{})
}
func RegisterService ¶ added in v0.3.0
func RegisterService(plugin *PluginDefinition, svc interface{}) error
RegisterService registers all operations from a service struct.
func TryGetClient ¶ added in v0.4.0
TryGetClient extracts a typed client from the context. Returns the zero value and false if not present or wrong type.
func UnpackBytes ¶
UnpackBytes unpacks a uint64 into a byte slice.
Types ¶
type Example ¶ added in v0.4.0
type Example[I, O any] struct { // Name is a short identifier (e.g., "basic", "with_tls", "error_case") Name string // Description explains what this example demonstrates Description string // Input is the example input data Input I // ExpectedOutput is the expected output (nil if not verifying output) ExpectedOutput *O // ExpectedError is set if this example should produce an error // Used for negative test cases ExpectedError string }
Example defines a sample input/output pair for documentation and testing.
type ExampleTestConfig ¶ added in v0.4.0
type ExampleTestConfig struct {
// SkipExamples lists example names to skip (e.g., "error_case")
SkipExamples []string
// MockClientFactory creates a mock client for each test
// If nil, uses the client passed to GenerateExampleTests
MockClientFactory func(exampleName string) any
}
ExampleTestConfig allows customizing example test behavior.
type HandlerFunc ¶ added in v0.3.0
HandlerFunc is the signature for operation handlers.
type Op ¶ added in v0.3.0
type Op[I, O any] struct{}
Op defines a typed operation with explicit input and output types. I is the input type (parsed from config JSON) O is the output type (serialized to Result.Data)
type Plugin ¶
type Plugin interface {
Manifest(ctx context.Context) (*entities.Manifest, error)
Check(ctx context.Context, config []byte) (*entities.Result, error)
}
Plugin is the interface every Reglet plugin must implement.
type PluginDef ¶ added in v0.3.0
type PluginDef struct {
Name string
Version string
Description string
Config interface{} // Struct for schema generation
Capabilities entities.GrantSet
}
PluginDef defines plugin identity and configuration.
type PluginDefinition ¶ added in v0.3.0
type PluginDefinition struct {
// contains filtered or unexported fields
}
PluginDefinition holds the parsed plugin definition and registered services.
func DefinePlugin ¶ added in v0.3.0
func DefinePlugin(def PluginDef) *PluginDefinition
DefinePlugin creates a new plugin definition. Call this once at package level in your plugin.
func (*PluginDefinition) GetHandler ¶ added in v0.3.0
func (p *PluginDefinition) GetHandler(serviceName, opName string) (HandlerFunc, bool)
GetHandler returns a handler for the given service/operation.
func (*PluginDefinition) Manifest ¶ added in v0.3.0
func (p *PluginDefinition) Manifest() *entities.Manifest
Manifest returns the complete plugin manifest.
func (*PluginDefinition) RegisterHandler ¶ added in v0.3.0
func (p *PluginDefinition) RegisterHandler( serviceName, serviceDesc string, opName, opDesc string, handler HandlerFunc, inputType, outputType reflect.Type, examples []any, )
RegisterHandler registers a handler for a service/operation. Called internally by RegisterService.
type Request ¶ added in v0.3.0
type Request struct {
Client interface{} // Plugin-specific client (e.g., *AWSClient)
Config interface{} // Parsed config struct
Raw []byte // Raw config JSON
}
Request contains the context for a handler invocation.
type Service ¶ added in v0.3.0
type Service struct{}
Service is embedded in service structs to provide metadata. Tag format: `name:"service_name" desc:"Service description"`
type StubPlugin ¶ added in v0.3.0
type StubPlugin struct{}
StubPlugin is a no-op implementation of the Plugin interface for testing or non-WASM environments.
Source Files