plugin

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Feb 4, 2026 License: Apache-2.0 Imports: 15 Imported by: 1

Documentation

Overview

Package plugin provides the entry point for tfbreak plugins.

Plugins use this package to register their RuleSet with tfbreak-core. The Serve function is called from main() and handles all communication with the tfbreak host process using gRPC via HashiCorp's go-plugin library.

Example plugin main.go: 

package main

import (
    "github.com/jokarl/tfbreak-plugin-sdk/plugin"
    "github.com/jokarl/tfbreak-plugin-sdk/tflint"
)

func main() {
    plugin.Serve(&plugin.ServeOpts{
        RuleSet: &AzurermRuleSet{
            BuiltinRuleSet: tflint.BuiltinRuleSet{
                Name:    "azurerm",
                Version: "0.1.0",
                Rules:   rules.Rules,
            },
        },
    })
}

Index

Constants

View Source 
const MagicCookieKey = "TFBREAK_PLUGIN_MAGIC_COOKIE"

MagicCookieKey is the environment variable name for the magic cookie.

View Source 
const MagicCookieValue = "tfbreak-plugin-v1"

MagicCookieValue is the expected value of the magic cookie. This prevents plugins from being executed directly (outside of tfbreak).

View Source 
const PluginName = "ruleset"

PluginName is the name used to identify the RuleSet plugin.

View Source 
const ProtocolVersion = 1

ProtocolVersion is the plugin protocol version. Increment this when making breaking changes to the plugin interface.

View Source 
const RunnerBrokerID uint32 = 1

RunnerBrokerID is the broker ID used for the Runner callback service. The host starts a server with this ID, and the plugin connects to it.

Variables

View Source 
var Handshake = plugin.HandshakeConfig{
	ProtocolVersion:  ProtocolVersion,
	MagicCookieKey:   MagicCookieKey,
	MagicCookieValue: MagicCookieValue,
}

Handshake is the HandshakeConfig used to configure go-plugin. The host and plugin must agree on these values to communicate.

View Source 
var PluginMap = map[string]plugin.Plugin{
	PluginName: &RuleSetPlugin{},
}

PluginMap is the map of plugins we can dispense. Used by both the host and plugin.

Functions

func Serve 

func Serve(opts *ServeOpts)

Serve starts the plugin server.

This function registers the plugin's RuleSet and handles communication with the tfbreak host process. It should be called from the plugin's main() function.

The function blocks until the host disconnects. When invoked directly (outside of tfbreak), the plugin will print a message and exit.

Communication uses gRPC with HashiCorp's go-plugin library, which provides: - Magic cookie handshake to prevent direct execution - Protocol versioning for compatibility - Bidirectional gRPC for Runner callbacks

Example: 

func main() {
    plugin.Serve(&plugin.ServeOpts{
        RuleSet: &MyRuleSet{...},
    })
}

Types

type GRPCRuleSetClient added in v0.3.0 

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

GRPCRuleSetClient wraps the gRPC client to implement tflint.RuleSet. This runs in the host process (tfbreak-core) and calls the plugin.

func (*GRPCRuleSetClient) ApplyConfig added in v0.3.0 

func (c *GRPCRuleSetClient) ApplyConfig(content *hclext.BodyContent) error

ApplyConfig applies plugin-specific configuration.

func (*GRPCRuleSetClient) ApplyGlobalConfig added in v0.3.0 

func (c *GRPCRuleSetClient) ApplyGlobalConfig(config *tflint.Config) error

ApplyGlobalConfig applies global tfbreak configuration.

func (*GRPCRuleSetClient) BuiltinImpl added in v0.3.0 

func (c *GRPCRuleSetClient) BuiltinImpl() *tflint.BuiltinRuleSet

BuiltinImpl returns nil on the client side. The actual implementation is on the plugin side.

func (*GRPCRuleSetClient) Check added in v0.3.0 

func (c *GRPCRuleSetClient) Check(runner tflint.Runner) error

Check executes all enabled rules via the plugin. The host must provide a Runner implementation that the plugin can call back to.

func (*GRPCRuleSetClient) ConfigSchema added in v0.3.0 

func (c *GRPCRuleSetClient) ConfigSchema() *hclext.BodySchema

ConfigSchema returns the schema for plugin-specific configuration.

func (*GRPCRuleSetClient) NewRunner added in v0.3.0 

func (c *GRPCRuleSetClient) NewRunner(runner tflint.Runner) (tflint.Runner, error)

NewRunner optionally wraps the runner with custom behavior. On the client side, this is a no-op since wrapping happens on the plugin side.

func (*GRPCRuleSetClient) RuleNames added in v0.3.0 

func (c *GRPCRuleSetClient) RuleNames() []string

RuleNames returns the names of all rules in this ruleset.

func (*GRPCRuleSetClient) RuleSetName added in v0.3.0 

func (c *GRPCRuleSetClient) RuleSetName() string

RuleSetName returns the name of the ruleset.

func (*GRPCRuleSetClient) RuleSetVersion added in v0.3.0 

func (c *GRPCRuleSetClient) RuleSetVersion() string

RuleSetVersion returns the version of the ruleset.

func (*GRPCRuleSetClient) VersionConstraint added in v0.3.0 

func (c *GRPCRuleSetClient) VersionConstraint() string

VersionConstraint returns the tfbreak version constraint.

type GRPCRuleSetServer added in v0.3.0 

type GRPCRuleSetServer struct {
	pb.UnimplementedRuleSetServer
	// contains filtered or unexported fields
}

GRPCRuleSetServer wraps a tflint.RuleSet to implement the gRPC server. This runs in the plugin process and handles requests from the host.

func (*GRPCRuleSetServer) ApplyConfig added in v0.3.0 

func (s *GRPCRuleSetServer) ApplyConfig(ctx context.Context, req *pb.ApplyConfig_Request) (*pb.ApplyConfig_Response, error)

ApplyConfig applies plugin-specific configuration.

func (*GRPCRuleSetServer) ApplyGlobalConfig added in v0.3.0 

func (s *GRPCRuleSetServer) ApplyGlobalConfig(ctx context.Context, req *pb.ApplyGlobalConfig_Request) (*pb.ApplyGlobalConfig_Response, error)

ApplyGlobalConfig applies global tfbreak configuration.

func (*GRPCRuleSetServer) Check added in v0.3.0 

func (s *GRPCRuleSetServer) Check(ctx context.Context, req *pb.Check_Request) (*pb.Check_Response, error)

Check executes all enabled rules. All rules are executed even if some fail - errors are collected and returned together.

func (*GRPCRuleSetServer) GetConfigSchema added in v0.3.0 

func (s *GRPCRuleSetServer) GetConfigSchema(ctx context.Context, req *pb.GetConfigSchema_Request) (*pb.GetConfigSchema_Response, error)

GetConfigSchema returns the schema for plugin-specific configuration.

func (*GRPCRuleSetServer) GetRuleNames added in v0.3.0 

func (s *GRPCRuleSetServer) GetRuleNames(ctx context.Context, req *pb.GetRuleNames_Request) (*pb.GetRuleNames_Response, error)

GetRuleNames returns the names of all rules in this ruleset.

func (*GRPCRuleSetServer) GetRuleSetName added in v0.3.0 

func (s *GRPCRuleSetServer) GetRuleSetName(ctx context.Context, req *pb.GetRuleSetName_Request) (*pb.GetRuleSetName_Response, error)

GetRuleSetName returns the name of the ruleset.

func (*GRPCRuleSetServer) GetRuleSetVersion added in v0.3.0 

func (s *GRPCRuleSetServer) GetRuleSetVersion(ctx context.Context, req *pb.GetRuleSetVersion_Request) (*pb.GetRuleSetVersion_Response, error)

GetRuleSetVersion returns the version of the ruleset.

func (*GRPCRuleSetServer) GetVersionConstraint added in v0.3.0 

func (s *GRPCRuleSetServer) GetVersionConstraint(ctx context.Context, req *pb.GetVersionConstraint_Request) (*pb.GetVersionConstraint_Response, error)

GetVersionConstraint returns the tfbreak version constraint.

type GRPCRunnerClient added in v0.3.0 

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

GRPCRunnerClient implements tflint.Runner by calling back to the host. This runs in the plugin process and makes gRPC calls to the host's Runner server.

func (*GRPCRunnerClient) DecodeRuleConfig added in v0.3.0 

func (r *GRPCRunnerClient) DecodeRuleConfig(ruleName string, target any) error

DecodeRuleConfig retrieves and decodes the rule's configuration.

func (*GRPCRunnerClient) EmitIssue added in v0.3.0 

func (r *GRPCRunnerClient) EmitIssue(rule tflint.Rule, message string, issueRange hcl.Range) error

EmitIssue reports a finding from the rule.

func (*GRPCRunnerClient) GetNewModuleContent added in v0.3.0 

func (r *GRPCRunnerClient) GetNewModuleContent(schema *hclext.BodySchema, opts *tflint.GetModuleContentOption) (*hclext.BodyContent, error)

GetNewModuleContent retrieves module content from the NEW configuration.

func (*GRPCRunnerClient) GetNewResourceContent added in v0.3.0 

func (r *GRPCRunnerClient) GetNewResourceContent(resourceType string, schema *hclext.BodySchema, opts *tflint.GetModuleContentOption) (*hclext.BodyContent, error)

GetNewResourceContent retrieves resources of a specific type from the NEW configuration.

func (*GRPCRunnerClient) GetOldModuleContent added in v0.3.0 

func (r *GRPCRunnerClient) GetOldModuleContent(schema *hclext.BodySchema, opts *tflint.GetModuleContentOption) (*hclext.BodyContent, error)

GetOldModuleContent retrieves module content from the OLD (baseline) configuration.

func (*GRPCRunnerClient) GetOldResourceContent added in v0.3.0 

func (r *GRPCRunnerClient) GetOldResourceContent(resourceType string, schema *hclext.BodySchema, opts *tflint.GetModuleContentOption) (*hclext.BodyContent, error)

GetOldResourceContent retrieves resources of a specific type from the OLD configuration.

type GRPCRunnerServer added in v0.3.0 

type GRPCRunnerServer struct {
	pb.UnimplementedRunnerServer
	// contains filtered or unexported fields
}

GRPCRunnerServer wraps a tflint.Runner to implement the gRPC server. This runs in the host process and handles requests from the plugin.

func (*GRPCRunnerServer) DecodeRuleConfig added in v0.3.0 

func (s *GRPCRunnerServer) DecodeRuleConfig(ctx context.Context, req *pb.DecodeRuleConfig_Request) (*pb.DecodeRuleConfig_Response, error)

DecodeRuleConfig handles the gRPC call to decode rule configuration.

func (*GRPCRunnerServer) EmitIssue added in v0.3.0 

func (s *GRPCRunnerServer) EmitIssue(ctx context.Context, req *pb.EmitIssue_Request) (*pb.EmitIssue_Response, error)

EmitIssue handles the gRPC call to emit an issue.

func (*GRPCRunnerServer) GetNewModuleContent added in v0.3.0 

func (s *GRPCRunnerServer) GetNewModuleContent(ctx context.Context, req *pb.GetModuleContent_Request) (*pb.GetModuleContent_Response, error)

GetNewModuleContent handles the gRPC call for new module content.

func (*GRPCRunnerServer) GetNewResourceContent added in v0.3.0 

func (s *GRPCRunnerServer) GetNewResourceContent(ctx context.Context, req *pb.GetResourceContent_Request) (*pb.GetResourceContent_Response, error)

GetNewResourceContent handles the gRPC call for new resource content.

func (*GRPCRunnerServer) GetOldModuleContent added in v0.3.0 

func (s *GRPCRunnerServer) GetOldModuleContent(ctx context.Context, req *pb.GetModuleContent_Request) (*pb.GetModuleContent_Response, error)

GetOldModuleContent handles the gRPC call for old module content.

func (*GRPCRunnerServer) GetOldResourceContent added in v0.3.0 

func (s *GRPCRunnerServer) GetOldResourceContent(ctx context.Context, req *pb.GetResourceContent_Request) (*pb.GetResourceContent_Response, error)

GetOldResourceContent handles the gRPC call for old resource content.

type RuleSetPlugin added in v0.3.0 

type RuleSetPlugin struct {
	plugin.Plugin
	// Impl is the concrete implementation of the RuleSet interface.
	// Only used when serving (plugin side).
	Impl tflint.RuleSet
}

RuleSetPlugin is the implementation of plugin.GRPCPlugin for the RuleSet service. This is used by both the host (to create a client) and the plugin (to create a server).

func (*RuleSetPlugin) GRPCClient added in v0.3.0 

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

GRPCClient is called by the host to create a gRPC client. This is called on the host side (tfbreak-core).

func (*RuleSetPlugin) GRPCServer added in v0.3.0 

func (p *RuleSetPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

GRPCServer is called by the plugin to register the gRPC server. This is called on the plugin side.

type ServeOpts 

type ServeOpts struct {
	// RuleSet is the plugin's rule set implementation.
	RuleSet tflint.RuleSet
}

ServeOpts contains options for serving the plugin.

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.