Documentation
¶
Overview ¶
Package plugin defines the engine-independent contract for local render plugins.
Index ¶
- Constants
- func Object(resource Resource) (map[string]any, error)
- func ObjectID(object map[string]any) (string, error)
- func Serve(ctx context.Context, socket string, service Service) (result error)
- type Client
- func (c *Client) Close() error
- func (c *Client) CloseRender(ctx context.Context, request *CloseRequest) (*CloseResponse, error)
- func (c *Client) Describe(ctx context.Context, request *DescribeRequest) (*DescribeResponse, error)
- func (c *Client) Expand(ctx context.Context, request *ExpandRequest) (*ExpandResponse, error)
- func (c *Client) OpenRender(ctx context.Context, request *OpenRequest) (*OpenResponse, error)
- type CloseRequest
- type CloseResponse
- type Command
- type DescribeRequest
- type DescribeResponse
- type Diagnostic
- type ExpandRequest
- type ExpandResponse
- type Expansion
- type OpenRequest
- type OpenResponse
- type Options
- type Provenance
- type Resource
- type Service
Constants ¶
const MaxMessageBytes = 64 << 20
MaxMessageBytes bounds each serialized protobuf request and response (64 MiB).
const ProtocolVersion = 1
Variables ¶
This section is empty.
Functions ¶
func Serve ¶
Serve serves one persistent engine on a Unix socket until cancellation or a termination signal. Engines must honor RPC cancellation and support concurrent calls. Shutdown cancels outstanding calls before releasing engine resources. An engine implementing Close() error is closed exactly once, including on listener setup failure. Existing socket paths are never removed on startup.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client owns a persistent connection and its executable. Close is idempotent and must be called by the owner; cancellation of Start's context also closes the client. Failed/uncertain RPCs invalidate the complete engine process.
func Start ¶
Start launches a trusted executable, appending --socket and a private socket path to its arguments, and verifies Describe before returning it.
func StartWithOptions ¶
StartWithOptions is Start with configurable transport timeouts.
func (*Client) Close ¶
Close disconnects, signals the whole child process group, then kills it after the shutdown bound. It also kills surviving descendants after the leader exits.
func (*Client) CloseRender ¶
func (c *Client) CloseRender(ctx context.Context, request *CloseRequest) (*CloseResponse, error)
func (*Client) Describe ¶
func (c *Client) Describe(ctx context.Context, request *DescribeRequest) (*DescribeResponse, error)
func (*Client) Expand ¶
func (c *Client) Expand(ctx context.Context, request *ExpandRequest) (*ExpandResponse, error)
func (*Client) OpenRender ¶
func (c *Client) OpenRender(ctx context.Context, request *OpenRequest) (*OpenResponse, error)
type CloseRequest ¶
type CloseRequest struct {
Session string `json:"session"`
}
type CloseResponse ¶
type CloseResponse struct{}
type Command ¶
type Command struct {
Name string `json:"name" yaml:"name"`
Command string `json:"command" yaml:"command"`
Args []string `json:"args,omitempty" yaml:"args,omitempty"`
Config json.RawMessage `json:"config,omitempty" yaml:"-"`
}
Command selects an executable from trusted startup configuration.
type DescribeRequest ¶
type DescribeRequest struct {
ProtocolVersion int `json:"protocolVersion"`
}
type DescribeResponse ¶
type Diagnostic ¶
type ExpandRequest ¶
type ExpandResponse ¶
type ExpandResponse struct {
Expansions []Expansion `json:"expansions"`
Diagnostics []Diagnostic `json:"diagnostics"`
Evidence []json.RawMessage `json:"evidence,omitempty"`
}
ExpandResponse exhaustively describes all producers and current diagnostics. Evidence is informational and must never be fed back as observed cluster state.
type Expansion ¶
type Expansion struct {
ID string `json:"id"`
Trigger string `json:"trigger"`
Resources []Resource `json:"resources"`
}
Expansion is a complete replacement of one producer's current desired output. Trigger is an inventory identity, or "root" for the configured source roots.
type OpenRequest ¶
type OpenRequest struct {
RunID string `json:"runId,omitempty"`
Root string `json:"root"`
Paths []string `json:"paths"`
Recursive bool `json:"recursive"`
LocalOnly bool `json:"localOnly"`
StrictInputs bool `json:"strictInputs"`
Cluster string `json:"cluster,omitempty"`
Fresh bool `json:"fresh,omitempty"`
Config json.RawMessage `json:"config,omitempty"`
}
OpenRequest is trusted invocation configuration, never an instruction derived from Kubernetes annotations. A session belongs to one cluster and evaluation.
type OpenResponse ¶
type OpenResponse struct {
Session string `json:"session"`
}
type Options ¶
type Options struct {
StartupTimeout time.Duration // Default 10 seconds.
RPCTimeout time.Duration // Default 2 minutes, including render calls.
ShutdownTimeout time.Duration // Default 10 seconds before SIGKILL, allowing runtime cleanup.
}
Options configures transport bounds. Zero durations select defaults; negative durations are invalid. Caller deadlines are always respected when shorter.
type Provenance ¶
type Resource ¶
type Resource struct {
ID string `json:"id"`
YAML string `json:"yaml"`
Logical bool `json:"logical,omitempty"`
Provenance Provenance `json:"provenance"`
}
Resource is desired YAML and its stable preview identity. Logical identities identify unnamed composition outputs without inventing Kubernetes names.
func ParseResource ¶
func ParseResource(data []byte, provenance Provenance) (Resource, error)
ParseResource validates named YAML and attaches out-of-band provenance.
type Service ¶
type Service interface {
Describe(context.Context, *DescribeRequest) (*DescribeResponse, error)
OpenRender(context.Context, *OpenRequest) (*OpenResponse, error)
Expand(context.Context, *ExpandRequest) (*ExpandResponse, error)
CloseRender(context.Context, *CloseRequest) (*CloseResponse, error)
}
Service is implemented by engines and by the persistent gRPC client Adapter.
Source Files