Documentation
¶
Overview ¶
Package verb provides definitions and utilities for effect verbs
Package verb provides the verb registry and specification for Effectus
Index ¶
- Constants
- func FormatAnalysisResult(result *AnalysisResult) string
- func ResourceConflict(a, b ResourceCapability) bool
- type AnalysisResult
- type AnalyzerVerbRegistry
- type Capability
- func (c Capability) CanAccess(required Capability) bool
- func (c Capability) IsCommutative() bool
- func (c Capability) IsCommutativeWith(other Capability) bool
- func (c Capability) IsExclusive() bool
- func (c Capability) IsIdempotent() bool
- func (c Capability) RuntimeCapability() types.Capability
- func (c Capability) String() string
- type CapabilityAnalyzer
- type Conflict
- type Executor
- type FunctionExecutor
- type Plugin
- type PluginBuilder
- type Registry
- func (r *Registry) Count() int
- func (r *Registry) DuplicatePolicy() string
- func (r *Registry) GetAllVerbs() []*Spec
- func (r *Registry) GetTypeSystem() interface{}
- func (r *Registry) GetVerb(name string) (*Spec, bool)
- func (r *Registry) GetVerbHash() string
- func (r *Registry) GetVerbSource(name string) (SourceInfo, bool)
- func (r *Registry) LoadFromJSON(filepath string) error
- func (r *Registry) LoadPlugins(dir string) error
- func (r *Registry) RegisterDefaults() error
- func (r *Registry) RegisterDirectory(dirPath string) error
- func (r *Registry) RegisterVerb(spec *Spec) error
- func (r *Registry) RequireInverseForMutating() bool
- func (r *Registry) Reset()
- func (r *Registry) SaveToJSON(filepath string) error
- func (r *Registry) SetDuplicatePolicy(policy string) error
- func (r *Registry) SetExecutor(name string, executor Executor) error
- func (r *Registry) SetRequireInverseForMutating(value bool)
- func (r *Registry) SetStrictArgs(value *bool)
- func (r *Registry) SetStrictReturn(value *bool)
- func (r *Registry) SetVerbSource(name string, source SourceInfo)
- func (r *Registry) StrictArgs() *bool
- func (r *Registry) StrictReturn() *bool
- func (r *Registry) VerbSources() map[string]SourceInfo
- type ResourceCapability
- type ResourceSet
- type SimpleVerbPlugin
- type SourceInfo
- type SourceProvider
- type Spec
- func (s *Spec) WithDescription(desc string) *Spec
- func (s *Spec) WithExecutor(executor Executor) *Spec
- func (s *Spec) WithInverse(inverse string) *Spec
- func (s *Spec) WithRequiredArgs(args []string) *Spec
- func (s *Spec) WithResources(resources ResourceSet) *Spec
- func (s *Spec) WithStrictArgs(strict bool) *Spec
- func (s *Spec) WithStrictReturn(strict bool) *Spec
- func (s *Spec) WithStrictTypes(strict bool) *Spec
Constants ¶
const ( SourceUnknown = "unknown" SourceInternal = "internal" SourcePlugin = "plugin" SourceHTTP = "http" SourceGRPC = "grpc" SourceStream = "stream" SourceOCI = "oci" SourceMock = "mock" SourceNoop = "noop" )
Variables ¶
This section is empty.
Functions ¶
func FormatAnalysisResult ¶
func FormatAnalysisResult(result *AnalysisResult) string
FormatAnalysisResult formats the analysis result as a string
func ResourceConflict ¶
func ResourceConflict(a, b ResourceCapability) bool
ResourceConflict checks if two resource capabilities conflict
Types ¶
type AnalysisResult ¶
type AnalysisResult struct {
Conflicts []Conflict
Resources map[string]Capability
VerbsCalled []string
}
AnalysisResult represents the result of a static analysis
type AnalyzerVerbRegistry ¶
AnalyzerVerbRegistry defines the interface needed by the analyzer.
type Capability ¶
type Capability uint64
Capability represents a capability flag for a verb
const ( // Basic capability types CapNone Capability = 0 CapRead Capability = 1 << iota // Read-only capability CapWrite // Write capability CapCreate // Create resource capability CapDelete // Delete resource capability // Semantic properties CapIdempotent // Operation can be repeated without side effects CapExclusive // Operation should be exclusive (no concurrent operations) CapCommutative // Operation order doesn't matter with other commutative ops CapDefault // Default capability for verbs with no specific requirements // Common combinations CapReadWrite = CapRead | CapWrite CapAll = CapRead | CapWrite | CapCreate | CapDelete )
func (Capability) CanAccess ¶
func (c Capability) CanAccess(required Capability) bool
CanAccess checks if one capability can access resources protected by another Following the principle of least privilege
func (Capability) IsCommutative ¶
func (c Capability) IsCommutative() bool
IsCommutative returns whether the capability is commutative
func (Capability) IsCommutativeWith ¶
func (c Capability) IsCommutativeWith(other Capability) bool
IsCommutativeWith checks if two operations can be reordered
func (Capability) IsExclusive ¶
func (c Capability) IsExclusive() bool
IsExclusive returns whether the capability requires exclusive access
func (Capability) IsIdempotent ¶
func (c Capability) IsIdempotent() bool
IsIdempotent returns whether the capability is idempotent
func (Capability) RuntimeCapability ¶
func (c Capability) RuntimeCapability() types.Capability
RuntimeCapability returns the strongest access capability in the flag set. Semantic flags do not weaken the lock required by access flags.
func (Capability) String ¶
func (c Capability) String() string
String returns a string representation of the capability
type CapabilityAnalyzer ¶
type CapabilityAnalyzer struct {
// contains filtered or unexported fields
}
CapabilityAnalyzer analyzes effects for capability conflicts
func NewCapabilityAnalyzer ¶
func NewCapabilityAnalyzer(registry AnalyzerVerbRegistry) *CapabilityAnalyzer
NewCapabilityAnalyzer creates a new capability analyzer
func (*CapabilityAnalyzer) Analyze ¶
func (a *CapabilityAnalyzer) Analyze(file *ast.File) (*AnalysisResult, error)
Analyze performs static analysis on a rule file
type Executor ¶
type Executor interface {
// Execute executes the verb with the given arguments
Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)
}
Executor defines the interface for verb implementations
type FunctionExecutor ¶
type FunctionExecutor struct {
Fn func(ctx context.Context, args map[string]interface{}) (interface{}, error)
}
FunctionExecutor is a simple executor that wraps a function
func NewFunctionExecutor ¶
func NewFunctionExecutor(fn func(ctx context.Context, args map[string]interface{}) (interface{}, error)) *FunctionExecutor
NewFunctionExecutor creates a new function executor
type Plugin ¶
type Plugin interface {
// GetVerbs returns the verbs provided by this plugin
GetVerbs() []*Spec
}
Plugin is the interface that plugins must implement
func ExportPlugin ¶
func ExportPlugin(plugin *SimpleVerbPlugin) Plugin
ExportPlugin exports a SimpleVerbPlugin as a plugin symbol This is used by plugin implementations
type PluginBuilder ¶
type PluginBuilder struct {
// contains filtered or unexported fields
}
PluginBuilder helps build verb plugins
func NewPluginBuilder ¶
func NewPluginBuilder() *PluginBuilder
NewPluginBuilder creates a new plugin builder
func (*PluginBuilder) AddVerb ¶
func (b *PluginBuilder) AddVerb(spec *Spec) *PluginBuilder
AddVerb adds a verb to the plugin
func (*PluginBuilder) GetVerbs ¶
func (b *PluginBuilder) GetVerbs() []*Spec
GetVerbs implements the Plugin interface
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages verb specifications and their implementations
func NewRegistry ¶
func NewRegistry(typeSystem interface{}) *Registry
NewRegistry creates a new verb registry
func (*Registry) DuplicatePolicy ¶
DuplicatePolicy returns the configured duplicate policy.
func (*Registry) GetAllVerbs ¶
GetAllVerbs returns all registered verbs
func (*Registry) GetTypeSystem ¶
func (r *Registry) GetTypeSystem() interface{}
GetTypeSystem returns the type system
func (*Registry) GetVerbHash ¶
GetVerbHash returns a hash of all registered verbs
func (*Registry) GetVerbSource ¶
func (r *Registry) GetVerbSource(name string) (SourceInfo, bool)
GetVerbSource returns source metadata for a verb if available.
func (*Registry) LoadFromJSON ¶
LoadFromJSON loads verb specifications from a JSON file
func (*Registry) LoadPlugins ¶
LoadPlugins loads verb plugins from a directory
func (*Registry) RegisterDefaults ¶
RegisterDefaults registers default verbs in the registry
func (*Registry) RegisterDirectory ¶
RegisterDirectory loads all JSON files in a directory
func (*Registry) RegisterVerb ¶
RegisterVerb registers a verb specification
func (*Registry) RequireInverseForMutating ¶
RequireInverseForMutating returns whether inverse enforcement is enabled.
func (*Registry) Reset ¶
func (r *Registry) Reset()
Reset clears all registered verbs while preserving registry settings.
func (*Registry) SaveToJSON ¶
SaveToJSON saves verb specifications to a JSON file
func (*Registry) SetDuplicatePolicy ¶
SetDuplicatePolicy sets the verb duplicate handling policy (error, replace, ignore).
func (*Registry) SetExecutor ¶
SetExecutor sets the executor for a registered verb
func (*Registry) SetRequireInverseForMutating ¶
SetRequireInverseForMutating enforces inverse verbs for mutating verbs.
func (*Registry) SetStrictArgs ¶
SetStrictArgs sets the registry-level strict argument validation setting.
func (*Registry) SetStrictReturn ¶
SetStrictReturn sets the registry-level strict return validation setting.
func (*Registry) SetVerbSource ¶
func (r *Registry) SetVerbSource(name string, source SourceInfo)
SetVerbSource sets the source metadata for a verb.
func (*Registry) StrictArgs ¶
StrictArgs returns the registry-level strict argument setting.
func (*Registry) StrictReturn ¶
StrictReturn returns the registry-level strict return setting.
func (*Registry) VerbSources ¶
func (r *Registry) VerbSources() map[string]SourceInfo
VerbSources returns a copy of all source metadata.
type ResourceCapability ¶
type ResourceCapability struct {
Resource string // Resource identifier (e.g., "order", "customer")
Cap Capability // Capabilities required for this resource
}
ResourceCapability pairs a resource name with capabilities
type ResourceSet ¶
type ResourceSet []ResourceCapability
ResourceSet represents multiple resources with capabilities
func (ResourceSet) ConflictsWith ¶
func (rs ResourceSet) ConflictsWith(other ResourceSet) bool
ConflictsWith checks if two resource sets have conflicts
func (ResourceSet) String ¶
func (rs ResourceSet) String() string
String returns a string representation of the resource set
type SimpleVerbPlugin ¶
type SimpleVerbPlugin struct {
// contains filtered or unexported fields
}
SimpleVerbPlugin is a basic implementation of the Plugin interface
func NewSimpleVerbPlugin ¶
func NewSimpleVerbPlugin(verbs ...*Spec) *SimpleVerbPlugin
NewSimpleVerbPlugin creates a new simple verb plugin
func (*SimpleVerbPlugin) GetVerbs ¶
func (p *SimpleVerbPlugin) GetVerbs() []*Spec
GetVerbs implements the Plugin interface
type SourceInfo ¶
type SourceInfo struct {
Type string `json:"type"`
Ref string `json:"ref,omitempty"`
Detail string `json:"detail,omitempty"`
}
SourceInfo describes where a verb executor comes from.
type SourceProvider ¶
type SourceProvider interface {
SourceInfo() SourceInfo
}
SourceProvider exposes source metadata for an executor.
type Spec ¶
type Spec struct {
// Name is the verb name
Name string `json:"name"`
// ArgTypes defines the types for verb arguments
ArgTypes map[string]string `json:"arg_types"`
// ReturnType is the verb's return type
ReturnType string `json:"return_type"`
// Capability is the required capability
Capability Capability `json:"capability"`
// RequiredArgs is the list of required arguments
RequiredArgs []string `json:"required_args,omitempty"`
// Resources defines resource-level capability requirements
Resources ResourceSet `json:"resources,omitempty"`
// Inverse is the name of the verb that reverses this one
Inverse string `json:"inverse,omitempty"`
// Description is a human-readable description
Description string `json:"description,omitempty"`
// Executor is the implementation of the verb
Executor Executor `json:"-"`
// StrictArgs enforces argument presence and type checks at runtime.
StrictArgs *bool `json:"strict_args,omitempty"`
// StrictReturn enforces return type checks at runtime.
StrictReturn *bool `json:"strict_return,omitempty"`
}
Spec represents a verb specification
func (*Spec) WithDescription ¶
WithDescription adds a description to the specification
func (*Spec) WithExecutor ¶
WithExecutor adds an executor to the specification
func (*Spec) WithInverse ¶
WithInverse adds an inverse verb to the specification
func (*Spec) WithRequiredArgs ¶
WithRequiredArgs adds required arguments to the specification.
func (*Spec) WithResources ¶
func (s *Spec) WithResources(resources ResourceSet) *Spec
WithResources adds resource capability requirements to the specification.
func (*Spec) WithStrictArgs ¶
WithStrictArgs configures strict argument validation for this verb.
func (*Spec) WithStrictReturn ¶
WithStrictReturn configures strict return validation for this verb.
func (*Spec) WithStrictTypes ¶
WithStrictTypes configures strict argument + return validation for this verb.