config

package
v0.40.0 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2026 License: Apache-2.0 Imports: 61 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var AddTopicPrefixTransform = function.New(&function.Spec{
	Params: []function.Parameter{
		{Name: "prefix", Type: cty.String},
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		capsule := NewMessageTransformCapsule(vbxform.AddTopicPrefix(args[0].AsString()))
		return capsule, nil
	},
})
View Source 
var ChainTransformsTransform = function.New(&function.Spec{
	Params: []function.Parameter{},
	VarParam: &function.Parameter{
		Name: "transforms",
		Type: cty.List(MessageTransformCapsuleType),
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		var transforms []vbxform.MessageTransformFunc
		for _, arg := range args {
			transform, err := GetMessageTransformFromCapsule(arg)
			if err != nil {
				return cty.NullVal(retType), err
			}
			transforms = append(transforms, transform)
		}
		capsule := NewMessageTransformCapsule(vbxform.ChainTransforms(transforms...))
		return capsule, nil
	},
})
View Source 
var ClientCapsuleType = cty.CapsuleWithOps("client", reflect.TypeOf((*any)(nil)).Elem(), &cty.CapsuleOps{
	GoString: func(val interface{}) string {
		return fmt.Sprintf("client(%p)", val)
	},
	TypeGoString: func(_ reflect.Type) string {
		return "client"
	},
})

ClientCapsuleType is a cty capsule type for wrapping Client instances.

View Source 
var Cty2GoTransform = vbxform.ModifyPayload(cty2goSimpleTransform)

Cty2GoTransform converts cty values to native Go types in message payloads.

View Source 
var Cty2GoTransformFunc = function.New(&function.Spec{
	Params: []function.Parameter{},
	Type:   function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		return NewMessageTransformCapsule(Cty2GoTransform), nil
	},
})
View Source 
var DiffTransform = function.New(&function.Spec{
	Params: []function.Parameter{
		{Name: "oldKey", Type: cty.String},
		{Name: "newKey", Type: cty.String},
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		capsule := NewMessageTransformCapsule(vbxform.ModifyPayload(vbxform.DiffTransform(args[0].AsString(), args[1].AsString())))
		return capsule, nil
	},
})
View Source 
var DropTopicPatternTransform = function.New(&function.Spec{
	Params: []function.Parameter{
		{Name: "pattern", Type: cty.String},
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		capsule := NewMessageTransformCapsule(vbxform.DropTopicPattern(args[0].AsString()))
		return capsule, nil
	},
})
View Source 
var DropTopicPrefixTransform = function.New(&function.Spec{
	Params: []function.Parameter{
		{Name: "prefix", Type: cty.String},
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		capsule := NewMessageTransformCapsule(vbxform.DropTopicPrefix(args[0].AsString()))
		return capsule, nil
	},
})
View Source 
var EventBusCapsuleType = cty.CapsuleWithOps("eventbus", reflect.TypeOf((*any)(nil)).Elem(), &cty.CapsuleOps{
	GoString: func(val interface{}) string {
		return fmt.Sprintf("eventbus(%p)", val)
	},
	TypeGoString: func(_ reflect.Type) string {
		return "eventbus"
	},
})

EventBusCapsuleType is a cty capsule type for wrapping EventBus instances

View Source 
var IfElsePatternTransform = function.New(&function.Spec{
	Params: []function.Parameter{
		{Name: "pattern", Type: cty.String},
		{Name: "ifTransform", Type: MessageTransformCapsuleType},
		{Name: "elseTransform", Type: MessageTransformCapsuleType},
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		ifTransform, err := GetMessageTransformFromCapsule(args[1])
		if err != nil {
			return cty.NullVal(retType), err
		}
		elseTransform, err := GetMessageTransformFromCapsule(args[2])
		if err != nil {
			return cty.NullVal(retType), err
		}
		capsule := NewMessageTransformCapsule(vbxform.IfElsePattern(args[0].AsString(), ifTransform, elseTransform))
		return capsule, nil
	},
})
View Source 
var IfElsePrefixTransform = function.New(&function.Spec{
	Params: []function.Parameter{
		{Name: "prefix", Type: cty.String},
		{Name: "ifTransform", Type: MessageTransformCapsuleType},
		{Name: "elseTransform", Type: MessageTransformCapsuleType},
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		ifTransform, err := GetMessageTransformFromCapsule(args[1])
		if err != nil {
			return cty.NullVal(retType), err
		}
		elseTransform, err := GetMessageTransformFromCapsule(args[2])
		if err != nil {
			return cty.NullVal(retType), err
		}
		capsule := NewMessageTransformCapsule(vbxform.IfElsePrefix(args[0].AsString(), ifTransform, elseTransform))
		return capsule, nil
	},
})
View Source 
var IfPatternTransform = function.New(&function.Spec{
	Params: []function.Parameter{
		{Name: "pattern", Type: cty.String},
		{Name: "transform", Type: MessageTransformCapsuleType},
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		transformFunc, err := GetMessageTransformFromCapsule(args[1])
		if err != nil {
			return cty.NullVal(retType), err
		}
		capsule := NewMessageTransformCapsule(vbxform.IfPattern(args[0].AsString(), transformFunc))
		return capsule, nil
	},
})
View Source 
var IfPrefixTransform = function.New(&function.Spec{
	Params: []function.Parameter{
		{Name: "prefix", Type: cty.String},
		{Name: "transform", Type: MessageTransformCapsuleType},
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		transformFunc, err := GetMessageTransformFromCapsule(args[1])
		if err != nil {
			return cty.NullVal(retType), err
		}
		capsule := NewMessageTransformCapsule(vbxform.IfPrefix(args[0].AsString(), transformFunc))
		return capsule, nil
	},
})
View Source 
var MessageTransformCapsuleType = cty.CapsuleWithOps("transform", reflect.TypeOf((*MessageTransformWrapper)(nil)).Elem(), &cty.CapsuleOps{
	GoString: func(val interface{}) string {
		return fmt.Sprintf("transform(%p)", val)
	},
	TypeGoString: func(_ reflect.Type) string {
		return "MessageTransform"
	},
})

MessageTransformCapsuleType is a cty capsule type for wrapping MessageTransformFunc instances

View Source 
var ReplaceInTopicTransform = function.New(&function.Spec{
	Params: []function.Parameter{
		{Name: "old", Type: cty.String},
		{Name: "new", Type: cty.String},
	},
	Type: function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		capsule := NewMessageTransformCapsule(vbxform.ReplaceInTopic(args[0].AsString(), args[1].AsString()))
		return capsule, nil
	},
})
View Source 
var ServerCapsuleType = cty.CapsuleWithOps("server", reflect.TypeOf((*any)(nil)).Elem(), &cty.CapsuleOps{
	GoString: func(val interface{}) string {
		return fmt.Sprintf("server(%p)", val)
	},
	TypeGoString: func(_ reflect.Type) string {
		return "server"
	},
})

ServerCapsuleType is a cty capsule type for wrapping Server instances

View Source 
var StopTransforms = function.New(&function.Spec{
	Params: []function.Parameter{},
	Type:   function.StaticReturnType(MessageTransformCapsuleType),
	Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) {
		capsule := NewMessageTransformCapsule(vbxform.StopTransforms())
		return capsule, nil
	},
})
View Source 
var SubscriberCapsuleType = cty.CapsuleWithOps("subscriber", reflect.TypeOf((*any)(nil)).Elem(), &cty.CapsuleOps{
	GoString: func(val interface{}) string {
		return fmt.Sprintf("subscriber(%p)", val)
	},
	TypeGoString: func(_ reflect.Type) string {
		return "subscriber"
	},
})

Subscriber is a cty capsule type for wrapping Susbcriber instances

View Source 
var WireFormatCapsuleType = cty.CapsuleWithOps("wire_format", reflect.TypeOf(wireFormatHolder{}), &cty.CapsuleOps{
	GoString: func(val interface{}) string {
		h := val.(*wireFormatHolder)
		return fmt.Sprintf("wire_format(%s)", h.WireFormat.Name())
	},
	TypeGoString: func(_ reflect.Type) string {
		return "wire_format"
	},
})

WireFormatCapsuleType is the cty capsule type for wire.WireFormat values. Used to pass wire formats as cty values in VCL expressions (e.g. wire_format.myproto).

Functions

func CtyObjectOrEmpty added in v0.19.0 

func CtyObjectOrEmpty(m map[string]cty.Value) cty.Value

CtyObjectOrEmpty returns cty.ObjectVal(m) when m is non-empty, or cty.EmptyObjectVal when m has no entries (cty.ObjectVal panics on empty maps).

func ExtractBlockDependencies added in v0.12.0 

func ExtractBlockDependencies(block *hcl.Block, excludeAttrs ...string) []string

ExtractBlockDependencies extracts config-time variable references from a block, excluding the named runtime-only attributes at all levels.

func ExtractReferencesFromAttribute 

func ExtractReferencesFromAttribute(attr *hcl.Attribute) []string

func ExtractReferencesFromBlock 

func ExtractReferencesFromBlock(block *hcl.Block) []string

func ExtractReferencesFromBody 

func ExtractReferencesFromBody(body hcl.Body, excludeAttrs map[string]bool) []string

ExtractReferencesFromBody extracts all variable references from an HCL body, excluding attributes listed in excludeAttrs. The exclusion applies at all levels (top-level and nested blocks). Returns nil for non-hclsyntax bodies.

func GetBlockHandlers 

func GetBlockHandlers() map[string]BlockHandler

func GetEventBusFromCapsule 

func GetEventBusFromCapsule(val cty.Value) (bus.EventBus, error)

GetEventBusFromCapsule extracts an EventBus from a cty capsule value

func GetEventBusFromExpression 

func GetEventBusFromExpression(config *Config, busExpr hcl.Expression) (bus.EventBus, hcl.Diagnostics)

func GetMessageTransformFromCapsule 

func GetMessageTransformFromCapsule(val cty.Value) (vbxform.MessageTransformFunc, error)

GetMessageTransformFromCapsule extracts a MessageTransformFunc from a cty capsule value

func GetSubscriberFromCapsule 

func GetSubscriberFromCapsule(val cty.Value) (bus.Subscriber, error)

GetSubscriberFromCapsule extracts a Subscriber from a cty capsule value. Any capsule whose encapsulated value implements bus.Subscriber can be used (buses, clients, FSM instances, subscriber capsules, etc.).

func GetSubscriberFromExpression 

func GetSubscriberFromExpression(config *Config, subscriberExpr hcl.Expression) (bus.Subscriber, hcl.Diagnostics)

func GetTargetFromExpression added in v0.10.0 

func GetTargetFromExpression(config *Config, targetExpr hcl.Expression) (any, hcl.Diagnostics)

func GetWireFormatFromValue added in v0.30.0 

func GetWireFormatFromValue(val cty.Value) (wire.WireFormat, error)

GetWireFormatFromValue extracts a wire.WireFormat from a cty value. The value can be:

  • A string naming a built-in wire format (resolved via wire.ByName)
  • A capsule wrapping a wire.WireFormat

func IsConstantExpression 

func IsConstantExpression(expr hcl.Expression) (cty.Value, bool)

IsConstantExpression checks if an expression is a constant (evaluatable with nil context). Returns the value and true if constant, or cty.NilVal and false otherwise.

func IsExpressionProvided 

func IsExpressionProvided(expr hcl.Expression) bool

IsExpressionProvided checks if an HCL expression was actually provided in the configuration. HCL creates empty expression objects for optional fields that aren't specified, but empty expressions have Start.Byte == End.Byte (zero-length range). Real expressions have End.Byte > Start.Byte (non-zero length range).

func NewActionSubscriber added in v0.19.0 

func NewActionSubscriber(config *Config, expr hcl.Expression) bus.Subscriber

NewActionSubscriber creates an ActionSubscriber for use by plugin sub-packages.

func NewClientCapsule added in v0.10.0 

func NewClientCapsule(client Client) cty.Value

NewClientCapsule creates a new cty capsule value wrapping a Client.

func NewEventBusCapsule 

func NewEventBusCapsule(eventBus bus.EventBus) cty.Value

NewEventBusCapsule creates a new cty capsule value wrapping an EventBus

func NewMessageTransformCapsule 

func NewMessageTransformCapsule(transformFunc vbxform.MessageTransformFunc) cty.Value

NewMessageTransformCapsule creates a new cty capsule value wrapping a MessageTransformFunc

func NewServerCapsule 

func NewServerCapsule(server Listener) cty.Value

NewEventBusCapsule creates a new cty capsule value wrapping an EventBus

func NewSubscriberCapsule 

func NewSubscriberCapsule(subscriber bus.Subscriber) cty.Value

NewSubscriberCapsule creates a new cty capsule value wrapping an Subscriber

func NewWireFormatCapsule added in v0.30.0 

func NewWireFormatCapsule(wf wire.WireFormat) cty.Value

NewWireFormatCapsule wraps a wire.WireFormat in a cty capsule value.

func ParseConfigFiles 

func ParseConfigFiles(sources ...any) ([]hcl.Body, hcl.Diagnostics)

func ParseDurationFromValue added in v0.19.0 

func ParseDurationFromValue(val cty.Value) (time.Duration, error)

ParseDurationFromValue converts an already-evaluated cty.Value to a time.Duration. Supports numbers (seconds), strings (Go or ISO 8601), and duration capsules. Used when the expression must be evaluated against a dynamic context before conversion.

func ParseVinitFiles added in v0.37.0 

func ParseVinitFiles(sources ...any) ([]hcl.Body, hcl.Diagnostics)

ParseVinitFiles enumerates *.vinit files from directory and embed.FS sources, plus any string source whose path ends in ".vinit". Byte-slice and []string sources are ignored — vinit content is always discovered from files on disk (or an embedded FS), never from in-memory bytes.

func RegisterAmbientProvider added in v0.19.0 

func RegisterAmbientProvider(name string, p AmbientProvider)

RegisterAmbientProvider registers a named provider that contributes a top-level value to the HCL evaluation context. Sub-packages call this from init().

func RegisterClientType added in v0.19.0 

func RegisterClientType(typeName string, p ClientProcessor)

RegisterClientType registers a processor for a named client type. Sub-packages call this from their init() function.

func RegisterConditionSubtype added in v0.27.0 

func RegisterConditionSubtype(typeName string, reg ConditionRegistration)

RegisterConditionSubtype registers a condition subtype ("timer", "threshold", "counter"). Sub-packages call this from init().

func RegisterConditionalTriggerType added in v0.21.0 

func RegisterConditionalTriggerType(factory ConditionalTriggerTypePlugin)

RegisterConditionalTriggerType registers a trigger type whose availability depends on config state (e.g. a feature flag). Unlike RegisterTriggerType, it does NOT call recordPlugin at init time; the plugin name is recorded only when the factory returns a non-nil result during Build().

func RegisterEditorType added in v0.23.0 

func RegisterEditorType(typeName string, p EditorProcessor)

RegisterEditorType registers an editor type. Sub-packages call this from init().

func RegisterFunctionPlugin added in v0.19.0 

func RegisterFunctionPlugin(name string, getter FunctionPlugin)

RegisterFunctionPlugin registers a named function plugin. Sub-packages call this from their init() function.

func RegisterServerType added in v0.19.0 

func RegisterServerType(typeName string, p ServerProcessor)

RegisterServerType registers a processor for a named server type. Sub-packages call this from their init() function.

func RegisterTransformPlugin added in v0.37.0 

func RegisterTransformPlugin(name string, getter FunctionPlugin)

RegisterTransformPlugin registers a named getter that contributes transform-context functions. Each function in the returned map must produce a value of type MessageTransformCapsuleType.

Sub-packages (and Go plugins) call this from their init() function, or from a plugin's VinculumPluginInit. The getter is invoked when Config builds the transform-only eval context.

Names that collide with a built-in transform or with another registered transform plugin produce a fatal diagnostic at Build() time, naming the offending plugin and the conflicting function name.

func RegisterTriggerType added in v0.19.0 

func RegisterTriggerType(typeName string, reg TriggerRegistration)

RegisterTriggerType registers an unconditional trigger type. Sub-packages call this from their init() function.

func RegisterWireFormatType added in v0.30.0 

func RegisterWireFormatType(typeName string, p WireFormatProcessor)

RegisterWireFormatType registers a processor for a named wire format type. Sub-packages call this from their init() function.

func RegisteredPlugins added in v0.19.0 

func RegisteredPlugins() []string

RegisteredPlugins returns a sorted copy of all registered plugin names, e.g. "ambient.sys", "client.kafka", "functions.stdlib", "server.mcp", "trigger.start".

func ResolveMeterProvider added in v0.24.0 

func ResolveMeterProvider(config *Config, expr hcl.Expression) (metric.MeterProvider, hcl.Diagnostics)

ResolveMeterProvider resolves a metric.MeterProvider from an optional HCL expression. If the expression is provided it must reference a server "metrics" or client "otlp" block. If omitted, the default metrics backend is used. Returns nil, nil when no metrics backend is configured (metrics disabled).

func SafeResolvePath added in v0.23.0 

func SafeResolvePath(baseDir, path string) (string, error)

SafeResolvePath resolves path relative to baseDir and verifies the result is contained within baseDir, rejecting directory traversal and home directory expansion.

func SendFunction 

func SendFunction(config *Config) function.Function

SendFunction returns a cty function for sending a message to a bus subscriber (original behavior)

func SendGoFunction 

func SendGoFunction(config *Config) function.Function

SendGoFunction returns a cty function for sending a Go native type message to a bus subscriber

func SendJSONFunction 

func SendJSONFunction(config *Config) function.Function

SendJSONFunction returns a cty function for sending a JSON string message to a bus subscriber

func SortAttributesByDependencies 

func SortAttributesByDependencies(attrs hcl.Attributes, known map[string]bool) ([]*hcl.Attribute, hcl.Diagnostics)

SortAttributesByDependencies returns attribute names sorted in dependency order. known contains variable root names that are already available in the evaluation context (e.g. ambient providers like "env", "sys") and should not be treated as missing dependencies.

func ValidateAuthConfig added in v0.20.0 

func ValidateAuthConfig(ac *AuthConfig) hcl.Diagnostics

ValidateAuthConfig checks that the required fields for the selected mode are present and that no conflicting options were set. Returns HCL diagnostics on error.

Types

type ActionSubscriber 

type ActionSubscriber struct {
	bus.BaseSubscriber
	Config     *Config
	ActionExpr hcl.Expression
}

func (*ActionSubscriber) OnEvent 

func (a *ActionSubscriber) OnEvent(ctx context.Context, topic string, message any, fields map[string]string) error

type AmbientProvider added in v0.19.0 

type AmbientProvider func(cfg *Config) cty.Value

AmbientProvider is a function that contributes a named value to the global HCL evaluation context. Providers register themselves via RegisterAmbientProvider in their init() functions; config.Build() loops over all registered providers to populate config.Constants before evaluating any blocks.

type Assert 

type Assert struct {
	Name      string `hcl:"name,label"`
	Condition bool   `hcl:"condition"`
}

The assert block is used to assert a condition at configuration processing runtime. It is mainly intended for testing.

type AssertBlockHandler 

type AssertBlockHandler struct {
	BlockHandlerBase
}

func NewAssertBlockHandler 

func NewAssertBlockHandler() *AssertBlockHandler

func (*AssertBlockHandler) GetBlockDependencyId 

func (h *AssertBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*AssertBlockHandler) Process 

func (h *AssertBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type AuthConfig added in v0.20.0 

type AuthConfig struct {
	Mode string `hcl:",label"` // "basic" | "oidc" | "oauth2" | "custom" | "none"

	// basic — realm shown in WWW-Authenticate header; defaults to server name
	Realm string `hcl:"realm,optional"`
	// basic — map(string) expression; username → plaintext password
	Credentials hcl.Expression `hcl:"credentials,optional"`

	// basic + custom — expression evaluated per request
	Action hcl.Expression `hcl:"action,optional"`

	// oidc + oauth2 — required aud values; token must contain at least one
	Audience hcl.Expression `hcl:"audience,optional"` // list(string)

	// oidc — OIDC issuer URL (used for discovery)
	Issuer string `hcl:"issuer,optional"`
	// oidc — override the JWKS endpoint (disables OIDC discovery)
	JWKSUrl string `hcl:"jwks_url,optional"`
	// oidc — permitted signing algorithms; defaults to ["RS256","ES256"]
	Algorithms hcl.Expression `hcl:"algorithms,optional"` // list(string)
	// oidc — permitted clock skew for exp/nbf; defaults to "30s".
	// Accepts a string ("30s"), a number (seconds), or a duration capsule.
	ClockSkew hcl.Expression `hcl:"clock_skew,optional"`

	// oidc (introspection) + oauth2 — RFC 7662 introspection endpoint
	IntrospectUrl string `hcl:"introspect_url,optional"`

	// oidc introspection — client ID for introspection endpoint
	IntrospectClientID string `hcl:"introspect_client_id,optional"`
	// oidc introspection — client secret for introspection endpoint
	IntrospectClientSecret string `hcl:"introspect_client_secret,optional"`

	// oauth2 — client ID for introspection endpoint (required)
	ClientID string `hcl:"client_id,optional"`
	// oauth2 — client secret (required; use env.VAR)
	ClientSecret string `hcl:"client_secret,optional"`
	// oauth2 — cache TTL for introspection results; defaults to "0s" (no cache).
	// Accepts a string ("60s"), a number (seconds), or a duration capsule.
	CacheTTL hcl.Expression `hcl:"cache_ttl,optional"`

	DefRange hcl.Range `hcl:",def_range"`
}

AuthConfig holds the configuration for an auth block. It is designed to be embedded (as a pointer) in any server or handler block that supports auth, decoded by gohcl.

The block label selects the authentication mode: 

auth "basic"  { realm = "API", credentials = { alice = "s3cr3t" } }
auth "oidc"   { issuer = "https://accounts.example.com", audience = ["api.example.com"] }
auth "oauth2" { introspect_url = "...", client_id = "...", client_secret = env.SECRET }
auth "custom" { action = lookup_session(ctx.request.cookie("session")) }
auth "none"   {}   # explicitly opt out of inherited server-level auth

type BaseBusClient added in v0.14.0 

type BaseBusClient struct {
	BaseClient
	Subscriber bus.Subscriber
	Client     bus.Client
}

BaseBusClient is the base struct for bus-backed clients (VWS, etc.).

func (*BaseBusClient) GetClient added in v0.14.0 

func (s *BaseBusClient) GetClient() bus.Client

func (*BaseBusClient) GetSubscriber added in v0.14.0 

func (s *BaseBusClient) GetSubscriber() bus.Subscriber

func (*BaseBusClient) SetSubscriber added in v0.14.0 

func (s *BaseBusClient) SetSubscriber(subscriber bus.Subscriber)

type BaseClient added in v0.10.0 

type BaseClient struct {
	Name     string
	DefRange hcl.Range
}

BaseClient holds the minimal fields common to all client types.

func (*BaseClient) GetDefRange added in v0.10.0 

func (s *BaseClient) GetDefRange() hcl.Range

func (*BaseClient) GetName added in v0.10.0 

func (s *BaseClient) GetName() string

func (*BaseClient) SetDefRange added in v0.34.0 

func (s *BaseClient) SetDefRange(r hcl.Range)

type BaseServer 

type BaseServer struct {
	Name     string
	DefRange hcl.Range
}

func (*BaseServer) GetDefRange 

func (s *BaseServer) GetDefRange() hcl.Range

func (*BaseServer) GetName 

func (s *BaseServer) GetName() string

type BlockHandler 

type BlockHandler interface {
	Preprocess(block *hcl.Block) hcl.Diagnostics
	FinishPreprocessing(config *Config) hcl.Diagnostics
	GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)
	GetBlockDependencies(block *hcl.Block) ([]string, hcl.Diagnostics)
	Process(config *Config, block *hcl.Block) hcl.Diagnostics
	FinishProcessing(config *Config) hcl.Diagnostics
}

type BlockHandlerBase 

type BlockHandlerBase struct {
}

func (*BlockHandlerBase) FinishPreprocessing 

func (b *BlockHandlerBase) FinishPreprocessing(config *Config) hcl.Diagnostics

func (*BlockHandlerBase) FinishProcessing 

func (b *BlockHandlerBase) FinishProcessing(config *Config) hcl.Diagnostics

func (*BlockHandlerBase) GetBlockDependencies 

func (b *BlockHandlerBase) GetBlockDependencies(block *hcl.Block) ([]string, hcl.Diagnostics)

func (*BlockHandlerBase) GetBlockDependencyId 

func (b *BlockHandlerBase) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*BlockHandlerBase) Preprocess 

func (b *BlockHandlerBase) Preprocess(block *hcl.Block) hcl.Diagnostics

func (*BlockHandlerBase) Process 

func (b *BlockHandlerBase) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type BusBlockHandler 

type BusBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

func NewBusBlockHandler 

func NewBusBlockHandler() *BusBlockHandler

func (*BusBlockHandler) BuildEventBus 

func (h *BusBlockHandler) BuildEventBus(config *Config, busDef *BusDefinition, defRange *hcl.Range) hcl.Diagnostics

func (*BusBlockHandler) FinishPreprocessing 

func (h *BusBlockHandler) FinishPreprocessing(config *Config) hcl.Diagnostics

func (*BusBlockHandler) GetBlockDependencyId 

func (h *BusBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*BusBlockHandler) Preprocess 

func (h *BusBlockHandler) Preprocess(block *hcl.Block) hcl.Diagnostics

func (*BusBlockHandler) Process 

func (h *BusBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type BusClient added in v0.14.0 

type BusClient interface {
	Client
	Build() (bus.Client, error)
	GetClient() bus.Client
	GetSubscriber() bus.Subscriber
	SetSubscriber(subscriber bus.Subscriber)
}

BusClient is a client backed by the vinculum-bus pub/sub system (e.g. VWS).

type BusDefinition 

type BusDefinition struct {
	Name      string         `hcl:",label"`
	Type      *string        `hcl:"type,optional"`
	QueueSize *int           `hcl:"queue_size,optional"`
	Metrics   hcl.Expression `hcl:"metrics,optional"`
	Tracing   hcl.Expression `hcl:"tracing,optional"`
	Options   hcl.Body       `hcl:",remain"`
}

type Client added in v0.10.0 

type Client interface {
	GetName() string
	GetDefRange() hcl.Range
}

Client is the base identity interface for all client types.

func GetClientFromCapsule added in v0.10.0 

func GetClientFromCapsule(val cty.Value) (Client, error)

GetClientFromCapsule extracts a Client from a cty capsule value.

func GetClientFromExpression added in v0.10.0 

func GetClientFromExpression(config *Config, clientExpr hcl.Expression) (Client, hcl.Diagnostics)

type ClientBlockHandler added in v0.10.0 

type ClientBlockHandler struct {
	BlockHandlerBase
}

func NewClientBlockHandler added in v0.10.0 

func NewClientBlockHandler() *ClientBlockHandler

func (*ClientBlockHandler) GetBlockDependencies added in v0.16.0 

func (h *ClientBlockHandler) GetBlockDependencies(block *hcl.Block) ([]string, hcl.Diagnostics)

func (*ClientBlockHandler) GetBlockDependencyId added in v0.10.0 

func (h *ClientBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*ClientBlockHandler) Process added in v0.10.0 

func (h *ClientBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type ClientDefinition added in v0.10.0 

type ClientDefinition struct {
	Type string `hcl:",label"`
	Name string `hcl:",label"`

	Disabled      bool      `hcl:"disabled,optional"`
	DefRange      hcl.Range `hcl:",def_range"`
	RemainingBody hcl.Body  `hcl:",remain"`
}

type ClientProcessor added in v0.19.0 

type ClientProcessor func(config *Config, block *hcl.Block, body hcl.Body) (Client, hcl.Diagnostics)

ClientProcessor is a function that processes a client block and returns a Client.

type ConditionBlockHandler added in v0.27.0 

type ConditionBlockHandler struct {
	BlockHandlerBase
}

func NewConditionBlockHandler added in v0.27.0 

func NewConditionBlockHandler() *ConditionBlockHandler

func (*ConditionBlockHandler) GetBlockDependencyId added in v0.27.0 

func (h *ConditionBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

GetBlockDependencyId returns "condition.<name>" so blocks referencing the condition are ordered after it.

func (*ConditionBlockHandler) Process added in v0.27.0 

func (h *ConditionBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type ConditionDefinition added in v0.27.0 

type ConditionDefinition struct {
	Type          string
	Name          string
	DefRange      hcl.Range
	RemainingBody hcl.Body
}

ConditionDefinition is the common envelope for every condition subtype. Subtype-specific attributes live in RemainingBody and are decoded by the registered ConditionProcessor.

type ConditionProcessor added in v0.27.0 

type ConditionProcessor func(config *Config, block *hcl.Block, def *ConditionDefinition) hcl.Diagnostics

ConditionProcessor processes a single condition block of a given subtype.

type ConditionRegistration added in v0.27.0 

type ConditionRegistration struct {
	Process         ConditionProcessor
	HasDependencyId bool
}

ConditionRegistration holds the processor and metadata for a condition subtype. HasDependencyId is true when the subtype publishes a cty value at condition.<name> (all current subtypes do; the flag exists for symmetry with TriggerRegistration).

type ConditionalTriggerTypePlugin added in v0.21.0 

type ConditionalTriggerTypePlugin func(cfg *Config) map[string]TriggerRegistration

ConditionalTriggerTypePlugin is evaluated once per Build(). It returns a map of trigger type names to registrations when the required feature is enabled, or nil when the type should not be available for this config.

type Config 

type Config struct {
	Logger *zap.Logger
	// UserLogger is Logger with Go caller and stacktrace suppressed. Use it
	// at sites that report errors caused by user-supplied VCL (expression
	// eval failures, assertion failures, action errors, etc.) where the Go
	// source location and stack are noise rather than signal.
	UserLogger *zap.Logger
	Functions  map[string]function.Function
	Constants  map[string]cty.Value

	Features map[string]string
	BaseDir  string
	WriteDir string

	SigActions       *SignalActionHandler
	Startables       []Startable
	PostStartables   []PostStartable
	PreStoppables    []PreStoppable
	Stoppables       []Stoppable
	BusCapsuleType   cty.Type
	CtyBusMap        map[string]cty.Value
	Buses            map[string]bus.EventBus
	CtyClientMap     map[string]cty.Value
	Clients          map[string]map[string]Client
	CtyServerMap     map[string]cty.Value
	Servers          map[string]map[string]Listener
	CtyVarMap        map[string]cty.Value
	CtyTriggerMap    map[string]cty.Value
	TriggerDefRanges map[string]hcl.Range
	CtyConditionMap  map[string]cty.Value
	CtyFsmMap        map[string]cty.Value
	CtyWireFormatMap map[string]cty.Value

	MetricsServers map[string]MetricsRegistrar
	OtlpClients    map[string]OtlpClient
	// contains filtered or unexported fields
}

func (*Config) CreateReconnector added in v0.10.0 

func (c *Config) CreateReconnector(def ReconnectDefinition) (*bus.AutoReconnector, hcl.Diagnostics)

func (*Config) EnabledFeatureNames added in v0.19.0 

func (c *Config) EnabledFeatureNames() []string

EnabledFeatureNames returns the names of all enabled features, sorted.

func (*Config) EvalCtx added in v0.19.0 

func (c *Config) EvalCtx() *hcl.EvalContext

EvalCtx returns the HCL evaluation context for use by plugin sub-packages.

func (*Config) ExtractUserFunctions 

func (c *Config) ExtractUserFunctions(bodies []hcl.Body) (map[string]function.Function, []hcl.Body, hcl.Diagnostics)

ExtractUserFunctions wraps the functions package ExtractUserFunctions

func (*Config) GetDefaultInstrumentMetrics added in v0.24.0 

func (c *Config) GetDefaultInstrumentMetrics() (InstrumentMetrics, hcl.Diagnostics)

GetDefaultInstrumentMetrics returns the default InstrumentMetrics backend by searching both MetricsServers and OtlpClients. Selection rules:

  1. Exactly one candidate total → use it
  2. Multiple, exactly one with IsDefaultMetricsBackend()=true → use it
  3. Multiple with IsDefaultMetricsBackend()=true → config error
  4. Multiple, none default → return nil (explicit wiring required)
  5. Zero → return nil

func (*Config) GetDefaultMetricsRegistrar added in v0.20.0 

func (c *Config) GetDefaultMetricsRegistrar() (MetricsRegistrar, hcl.Diagnostics)

GetDefaultMetricsRegistrar returns the default MetricsRegistrar per these rules:

  1. Exactly one metrics server → use it
  2. Multiple, exactly one with IsDefaultServer()=true → use it
  3. Multiple with IsDefaultServer()=true → config error
  4. Multiple, none default → return nil (explicit wiring required)
  5. Zero → return nil

func (*Config) GetDefaultOtlpClient added in v0.22.0 

func (c *Config) GetDefaultOtlpClient() (OtlpClient, hcl.Diagnostics)

GetDefaultOtlpClient returns the default OtlpClient using these rules:

  1. Exactly one OTLP client → use it
  2. Multiple, exactly one with IsDefaultClient()=true → use it
  3. Multiple with IsDefaultClient()=true → config error
  4. Multiple, none default → return nil (explicit wiring required)
  5. Zero → return nil

func (*Config) GetFeature added in v0.19.0 

func (c *Config) GetFeature(name string) string

GetFeature returns the value associated with a named feature flag, or empty string if the feature is not enabled.

func (*Config) GetFunctions 

func (c *Config) GetFunctions(userFuncs map[string]function.Function) (map[string]function.Function, hcl.Diagnostics)

GetFunctions builds the function map from all registered function plugins, then adds user-defined functions with duplicate detection.

func (*Config) GetMessageTransforms 

func (config *Config) GetMessageTransforms(expr hcl.Expression) (transforms []vbxform.MessageTransformFunc, diags hcl.Diagnostics)

func (*Config) ParseDuration 

func (c *Config) ParseDuration(expr hcl.Expression) (time.Duration, hcl.Diagnostics)

ParseDuration parses a duration from an HCL expression. It supports three formats: 1. Numbers (interpreted as seconds) 2. Strings starting with "P" (ISO 8601 durations using github.com/sosodev/duration) 3. Other strings (Go's native duration parsing)

func (*Config) ResolveOtlpClient added in v0.22.0 

func (c *Config) ResolveOtlpClient(expr hcl.Expression) (OtlpClient, hcl.Diagnostics)

ResolveOtlpClient returns the OtlpClient selected by expr (explicit wiring) or the default OTLP client (auto-wire). Returns nil with no error when no OTLP client is configured and no explicit tracing = is set.

func (*Config) ResolveTracerProvider added in v0.22.0 

func (c *Config) ResolveTracerProvider(expr hcl.Expression) (trace.TracerProvider, hcl.Diagnostics)

ResolveTracerProvider returns the TracerProvider selected by expr (explicit wiring) or the default OTLP client (auto-wire). Returns nil with no error when no OTLP client is configured and no explicit tracing = is set.

func (*Config) SetSignalAction 

func (config *Config) SetSignalAction(sigName string, action hcl.Expression) hcl.Diagnostics

type ConfigBuilder 

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

func NewConfig 

func NewConfig() *ConfigBuilder

func (*ConfigBuilder) Build 

func (cb *ConfigBuilder) Build() (*Config, hcl.Diagnostics)

func (*ConfigBuilder) GetBlocks 

func (cb *ConfigBuilder) GetBlocks(bodies []hcl.Body) (hcl.Blocks, hcl.Diagnostics)

func (*ConfigBuilder) SortBlocksByDependencies 

func (cb *ConfigBuilder) SortBlocksByDependencies(blocks hcl.Blocks, handlers map[string]BlockHandler) (hcl.Blocks, hcl.Diagnostics)

SortBlocksByDependencies returns blocks sorted in dependency order using Kahn's algorithm. When multiple blocks are available (no ordering constraint between them), they are emitted in their original source order. Blocks without a dependency ID (const, signals, function) are appended at the end unchanged. handlers must be the same BlockHandler instances that had FinishPreprocessing called on them, so per-build handler state (e.g. conditional trigger registry) is visible during dependency resolution.

func (*ConfigBuilder) WithFeature added in v0.19.0 

func (c *ConfigBuilder) WithFeature(name, value string) *ConfigBuilder

WithFeature enables a named feature flag with the given value. Use an empty value to disable a previously set feature. Known features: "readfiles" (value = --file-path dir), 

"writefiles" (value = --write-path dir),
"allowkill"  (value = "true").

func (*ConfigBuilder) WithLogger 

func (c *ConfigBuilder) WithLogger(logger *zap.Logger) *ConfigBuilder

func (*ConfigBuilder) WithPluginPath added in v0.37.0 

func (c *ConfigBuilder) WithPluginPath(path string) *ConfigBuilder

WithPluginPath sets the directory from which `plugin "<label>" { ... }` blocks resolve their .so files. The empty string (default) means plugins are not permitted: any `plugin` block encountered in a .vinit file will produce a fatal diagnostic.

func (*ConfigBuilder) WithSources 

func (c *ConfigBuilder) WithSources(sources ...any) *ConfigBuilder

type ConstBlockHandler 

type ConstBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

func NewConstBlockHandler 

func NewConstBlockHandler() *ConstBlockHandler

func (*ConstBlockHandler) FinishPreprocessing 

func (b *ConstBlockHandler) FinishPreprocessing(config *Config) hcl.Diagnostics

func (*ConstBlockHandler) Preprocess 

func (b *ConstBlockHandler) Preprocess(block *hcl.Block) hcl.Diagnostics

type CtyValuer added in v0.16.0 

type CtyValuer interface {
	CtyValue() cty.Value
}

CtyValuer is an optional interface that Client implementations may satisfy to provide a custom cty value for the eval context. If not implemented, the client is wrapped in a plain ClientCapsule.

type CtyWireFormat added in v0.30.0 

type CtyWireFormat struct {
	Inner wire.WireFormat
}

CtyWireFormat wraps a WireFormat with cty conversion.

On the serialize side, if the input is a cty.Value it is converted to native Go types via go2cty2go.CtyToAny before delegating; any other type passes straight through to the inner WireFormat.

On the deserialize side, the inner WireFormat's native Go output is converted to a cty.Value via go2cty2go.AnyToCty.

CtyWireFormat itself satisfies the WireFormat interface (Serialize takes any, Deserialize returns any), so it composes transparently.

func (*CtyWireFormat) Deserialize added in v0.30.0 

func (f *CtyWireFormat) Deserialize(b []byte) (any, error)

func (*CtyWireFormat) Name added in v0.30.0 

func (f *CtyWireFormat) Name() string

func (*CtyWireFormat) Serialize added in v0.30.0 

func (f *CtyWireFormat) Serialize(v any) ([]byte, error)

func (*CtyWireFormat) SerializeString added in v0.30.0 

func (f *CtyWireFormat) SerializeString(v any) (string, error)

type EditorDefinition added in v0.23.0 

type EditorDefinition struct {
	Type          string
	Name          string
	Params        []string // parameter names extracted from params expression
	VariadicParam string   // optional variadic parameter name
	Body          hcl.Body // remaining body for type-specific parsing
	DefRange      hcl.Range
}

EditorDefinition holds the parsed outer editor block, common across all editor types.

type EditorProcessor added in v0.23.0 

type EditorProcessor func(
	config *Config,
	evalCtxFn func() *hcl.EvalContext,
	def *EditorDefinition,
) (function.Function, hcl.Diagnostics)

EditorProcessor compiles an editor block's type-specific body into a cty function. It is called once per editor block during early config processing.

type ErrorlessStartable 

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

func (ErrorlessStartable) Start 

func (e ErrorlessStartable) Start() error

type FsmBlockHandler added in v0.33.0 

type FsmBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

FsmBlockHandler processes fsm blocks.

func NewFsmBlockHandler added in v0.33.0 

func NewFsmBlockHandler() *FsmBlockHandler

func (*FsmBlockHandler) FinishPreprocessing added in v0.33.0 

func (h *FsmBlockHandler) FinishPreprocessing(config *Config) hcl.Diagnostics

FinishPreprocessing creates placeholder instances and populates the capsule map so that fsm.<name> references can be resolved during dependency analysis. Process() later calls inst.Configure() to replace the placeholder definition with the real one -- this works because the capsule wraps a pointer to the Instance, so all resolved references see the updated state.

func (*FsmBlockHandler) GetBlockDependencies added in v0.33.0 

func (h *FsmBlockHandler) GetBlockDependencies(block *hcl.Block) ([]string, hcl.Diagnostics)

func (*FsmBlockHandler) GetBlockDependencyId added in v0.33.0 

func (h *FsmBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*FsmBlockHandler) Preprocess added in v0.33.0 

func (h *FsmBlockHandler) Preprocess(block *hcl.Block) hcl.Diagnostics

Preprocess validates the block and registers the FSM name for duplicate detection. The actual instance is created in FinishPreprocessing.

func (*FsmBlockHandler) Process added in v0.33.0 

func (h *FsmBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type FsmTopLevel added in v0.33.0 

type FsmTopLevel struct {
	Name          string         `hcl:",label"`
	Initial       string         `hcl:"initial"`
	QueueSize     *int           `hcl:"queue_size,optional"`
	ShutdownEvent *string        `hcl:"shutdown_event,optional"`
	Disabled      bool           `hcl:"disabled,optional"`
	Tracing       hcl.Expression `hcl:"tracing,optional"`
	OnChange      hcl.Expression `hcl:"on_change,optional"`
	OnError       hcl.Expression `hcl:"on_error,optional"`
	RemainingBody hcl.Body       `hcl:",remain"`
}

FsmTopLevel is the gohcl-decoded envelope for an fsm block. Sub-blocks (state, event, storage) are parsed manually from RemainingBody because we need declaration-order iteration and raw hcl.Expression access.

type FunctionPlugin added in v0.19.0 

type FunctionPlugin func(cfg *Config) map[string]function.Function

FunctionPlugin returns a map of functions for the given config. Plugins that don't need config can ignore the cfg parameter. Conditional plugins (e.g. filesystem, filewrite) return nil when their required feature is not enabled.

type GitAuth added in v0.39.0 

type GitAuth struct {
	Token                 string    `hcl:"token,optional"`
	Username              string    `hcl:"username,optional"`
	Password              string    `hcl:"password,optional"`
	PrivateKey            string    `hcl:"private_key,optional"`
	PrivateKeyFile        string    `hcl:"private_key_file,optional"`
	Passphrase            string    `hcl:"passphrase,optional"`
	KnownHosts            string    `hcl:"known_hosts,optional"`
	InsecureIgnoreHostKey bool      `hcl:"insecure_ignore_host_key,optional"`
	DefRange              hcl.Range `hcl:",def_range"`
}

GitAuth holds the optional credentials for a git block. Which attributes are valid depends on the transport inferred from the repo URL scheme (HTTP(S) vs SSH); see validateGitAuth.

type GitDefinition added in v0.39.0 

type GitDefinition struct {
	Label      string     `hcl:",label"`
	Disabled   bool       `hcl:"disabled,optional"`
	Repo       string     `hcl:"repo"`
	Branch     string     `hcl:"branch,optional"`
	Tag        string     `hcl:"tag,optional"`
	Commit     string     `hcl:"commit,optional"`
	Depth      *int       `hcl:"depth,optional"`
	Submodules bool       `hcl:"submodules,optional"`
	Auth       *GitAuth   `hcl:"auth,block"`
	Fetches    []GitFetch `hcl:"fetch,block"`
	DefRange   hcl.Range  `hcl:",def_range"`
}

GitDefinition is the structural decode of a `git "<label>" { ... }` block in a .vinit file. It clones a remote repository during bootstrap pass 1 and materializes one or more subtrees onto the local filesystem before any .vcl is parsed.

type GitFetch added in v0.39.0 

type GitFetch struct {
	Name      string    `hcl:",label"`
	From      string    `hcl:"from,optional"`
	Into      string    `hcl:"into"`
	Overwrite bool      `hcl:"overwrite,optional"`
	DefRange  hcl.Range `hcl:",def_range"`
}

GitFetch copies one subtree of the cloned repository to one local destination. A git block has one or more fetch sub-blocks sharing a single clone.

type HandlerServer 

type HandlerServer interface {
	Listener
	GetHandler() http.Handler
}

HandlerServer is a Listener that can serve HTTP requests when mounted into an HTTP server block via a handle block.

type InstrumentMetrics added in v0.24.0 

type InstrumentMetrics interface {
	GetMeterProvider() metric.MeterProvider
	IsDefaultMetricsBackend() bool
}

InstrumentMetrics is satisfied by both server "metrics" and client "otlp". Used to resolve the metrics MeterProvider for metric blocks and server auto-instrumentation.

func GetInstrumentMetricsFromExpression added in v0.24.0 

func GetInstrumentMetricsFromExpression(config *Config, expr hcl.Expression) (InstrumentMetrics, hcl.Diagnostics)

GetInstrumentMetricsFromExpression evaluates an HCL expression and returns it as an InstrumentMetrics. The expression may reference either a server "metrics" block or a client "otlp" block.

type Listener 

type Listener interface {
	GetName() string
	GetDefRange() hcl.Range
}

func GetServerFromCapsule 

func GetServerFromCapsule(val cty.Value) (Listener, error)

GetServerFromCapsule extracts an Server from a cty capsule value

func GetServerFromExpression 

func GetServerFromExpression(config *Config, busExpr hcl.Expression) (Listener, hcl.Diagnostics)

type MessageConverter 

type MessageConverter func(cty.Value) (any, error)

MessageConverter defines how to convert a cty.Value message before sending

type MessageTransformWrapper 

type MessageTransformWrapper struct {
	Func vbxform.MessageTransformFunc
}

MessageTransformWrapper wraps a MessageTransformFunc for use in cty capsules

type MetricBlockHandler added in v0.13.0 

type MetricBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

func NewMetricBlockHandler added in v0.13.0 

func NewMetricBlockHandler() *MetricBlockHandler

func (*MetricBlockHandler) FinishPreprocessing added in v0.13.0 

func (h *MetricBlockHandler) FinishPreprocessing(config *Config) hcl.Diagnostics

func (*MetricBlockHandler) GetBlockDependencies added in v0.13.0 

func (h *MetricBlockHandler) GetBlockDependencies(block *hcl.Block) ([]string, hcl.Diagnostics)

func (*MetricBlockHandler) GetBlockDependencyId added in v0.13.0 

func (h *MetricBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*MetricBlockHandler) Preprocess added in v0.13.0 

func (h *MetricBlockHandler) Preprocess(block *hcl.Block) hcl.Diagnostics

func (*MetricBlockHandler) Process added in v0.13.0 

func (h *MetricBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

func (*MetricBlockHandler) SetImplicitBackendDeps added in v0.26.0 

func (h *MetricBlockHandler) SetImplicitBackendDeps(ids []string)

SetImplicitBackendDeps records the dependency IDs of server "metrics" and client "otlp" blocks so that metric blocks without an explicit server attribute are ordered after them.

type MetricDefinition added in v0.13.0 

type MetricDefinition struct {
	Help             string         `hcl:"help"`
	LabelNames       []string       `hcl:"label_names,optional"`
	Namespace        string         `hcl:"namespace,optional"`
	Buckets          []float64      `hcl:"buckets,optional"`
	Server           hcl.Expression `hcl:"server,optional"`
	Value            hcl.Expression `hcl:"value,optional"`
	ComputedInterval *string        `hcl:"computed_interval,optional"`
	DefRange         hcl.Range      `hcl:",def_range"`
}

MetricDefinition holds the decoded HCL body of a metric block.

type MetricsRegistrar added in v0.20.0 

type MetricsRegistrar interface {
	Listener
	InstrumentMetrics
	GetRegistry() *prometheus.Registry
	IsDefaultServer() bool
}

MetricsRegistrar is implemented by server types that provide a Prometheus registry for metric blocks to register against.

func GetMetricsRegistrarFromExpression added in v0.20.0 

func GetMetricsRegistrarFromExpression(config *Config, expr hcl.Expression) (MetricsRegistrar, hcl.Diagnostics)

GetMetricsRegistrarFromExpression evaluates an HCL expression expecting a server capsule and returns it as a MetricsRegistrar. Returns an error if the server does not implement MetricsRegistrar.

type OtlpClient added in v0.22.0 

type OtlpClient interface {
	Client
	// GetTracerProvider returns the OTel SDK TracerProvider for span extraction
	// (e.g. to call tracer.Start() or trace.SpanFromContext()).
	GetTracerProvider() trace.TracerProvider
	// IsDefaultClient returns true if this client should be used when no
	// explicit tracing = attribute is specified.
	IsDefaultClient() bool
	// GetMeterProvider returns the OTel SDK MeterProvider for creating
	// metric instruments (counters, histograms, gauges).
	GetMeterProvider() metric.MeterProvider
	// IsDefaultMetricsBackend returns true if this client should be used
	// as the default metrics backend when no explicit metrics = is specified.
	IsDefaultMetricsBackend() bool
}

OtlpClient is implemented by client "otlp" blocks. It provides both tracing and push metrics via the o11y abstractions, so it can satisfy metrics = and tracing = attributes on servers.

func GetOtlpClientFromExpression added in v0.22.0 

func GetOtlpClientFromExpression(config *Config, expr hcl.Expression) (OtlpClient, hcl.Diagnostics)

GetOtlpClientFromExpression evaluates an HCL expression expecting a client capsule and returns it as an OtlpClient. Returns an error if the client does not implement OtlpClient.

type PluginContext added in v0.37.0 

type PluginContext struct {
	// Block is the `plugin "<label>" { ... }` block as parsed from the
	// .vinit file. Block.Labels[0] is the plugin label. Block.Body is the
	// full block body; the plugin decodes its own schema from it. The
	// `disabled` attribute has already been consumed by Vinculum but is
	// still syntactically present in the body.
	Block *hcl.Block

	// EvalContext is the minimal .vinit eval context: env.* and the cty
	// standard library. No const, no user functions, no contributions from
	// other plugins.
	EvalContext *hcl.EvalContext

	// Logger is a zap logger pre-bound with `plugin=<label>` as a
	// structured field. Plugins should use this rather than constructing
	// their own logger so plugin output is consistent with Vinculum's.
	// May be nil if Vinculum was started without a logger.
	Logger *zap.Logger
}

PluginContext is the single argument passed to a Go plugin's VinculumPluginInit entry point. New fields may be appended in future releases to grow the surface without breaking existing plugins; existing fields will not change type.

type PluginDefinition added in v0.37.0 

type PluginDefinition struct {
	Label    string   `hcl:",label"`
	Disabled bool     `hcl:"disabled,optional"`
	Body     hcl.Body `hcl:",remain"`
}

PluginDefinition is the structural decode of a `plugin "<label>" { ... }` block in a .vinit file. Disabled is consumed by Vinculum; the remaining body is handed to the plugin's VinculumPluginInit for its own decoding.

type PostStartable added in v0.21.0 

type PostStartable interface {
	PostStart() error
}

PostStartable is implemented by components that need to run logic after all Startable components have completed their Start() calls. PostStart() is called once, in the same order as Start(), after the full startup sequence completes.

type PreStoppable added in v0.22.0 

type PreStoppable interface {
	PreStop() error
}

PreStoppable is implemented by components that need to run logic before any Stoppable components have their Stop() called. PreStop() is called in reverse registration order, before the full teardown sequence begins. This guarantees that the full runtime environment (clients, buses, subscriptions) is still available when PreStop() executes.

type ReactiveExpr added in v0.27.0 

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

ReactiveExpr wraps an HCL expression that must be re-evaluated whenever any Watchable it references changes — the mechanism behind condition block input = and inhibit = attributes.

Unlike a one-shot gohcl.DecodeBody, ReactiveExpr extracts every Watchable referenced by the expression at construction time, subscribes to each as a Watcher on Start(), and invokes a callback with the re-evaluated value on every change. Stop() unsubscribes. Construction is cheap; Start() is the point at which the caller commits to receiving callbacks.

Circular references between blocks are rejected at config load time by the existing block-level dependency DAG (ExtractBlockDependencies walks the block body and Kahn's sort fails on cycles), so ReactiveExpr itself does not need additional cycle detection.

func NewReactiveExpr added in v0.27.0 

func NewReactiveExpr(expr hcl.Expression, evalCtx *hcl.EvalContext, callback func(ctx context.Context, value cty.Value)) (*ReactiveExpr, hcl.Diagnostics)

NewReactiveExpr constructs a ReactiveExpr by extracting every Watchable referenced by expr against evalCtx. callback is invoked with the current value on Start(), and again whenever any source Watchable's value changes.

References that do not resolve to a Watchable capsule (constants, plain cty values, env references, etc.) are silently ignored — the expression may freely mix reactive and static inputs. If a reference cannot be resolved at all, a diagnostic is returned; the returned ReactiveExpr is still usable (it just won't fire for that branch).

func (*ReactiveExpr) Eval added in v0.27.0 

func (r *ReactiveExpr) Eval() (cty.Value, hcl.Diagnostics)

Eval re-evaluates the expression against the current eval context and returns the resulting value.

func (*ReactiveExpr) OnChange added in v0.27.0 

func (r *ReactiveExpr) OnChange(ctx context.Context, _ richcty.Watchable, _, _ cty.Value)

OnChange implements richcty.Watcher. When any source Watchable changes, the expression is re-evaluated and the callback is invoked with the new value. Evaluation errors are swallowed here (the previous value remains in effect from the caller's perspective); config-time errors surface at Start().

func (*ReactiveExpr) Sources added in v0.27.0 

func (r *ReactiveExpr) Sources() []richcty.Watchable

Sources returns the list of Watchables this expression depends on. Useful for tests and introspection.

func (*ReactiveExpr) Start added in v0.27.0 

func (r *ReactiveExpr) Start(ctx context.Context) hcl.Diagnostics

Start subscribes to every source Watchable and invokes the callback with the expression's current value. Idempotent.

func (*ReactiveExpr) Stop added in v0.27.0 

func (r *ReactiveExpr) Stop()

Stop unsubscribes from every source Watchable. Idempotent.

type ReconnectDefinition added in v0.10.0 

type ReconnectDefinition struct {
	InitialDelay  hcl.Expression `hcl:"initial_delay,optional"`
	MaxDelay      hcl.Expression `hcl:"max_delay,optional"`
	BackoffFactor *float64       `hcl:"backoff_factor,optional"`
	MaxRetries    *int           `hcl:"max_retries,optional"`
	DefRange      hcl.Range      `hcl:",def_range"`
}

type ServerBlockHandler 

type ServerBlockHandler struct {
	BlockHandlerBase
}

func NewServerBlockHandler 

func NewServerBlockHandler() *ServerBlockHandler

func (*ServerBlockHandler) GetBlockDependencyId 

func (h *ServerBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*ServerBlockHandler) Process 

func (h *ServerBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type ServerDefinition 

type ServerDefinition struct {
	Type string `hcl:",label"`
	Name string `hcl:",label"`

	Disabled      bool      `hcl:"disabled,optional"`
	DefRange      hcl.Range `hcl:",def_range"`
	RemainingBody hcl.Body  `hcl:",remain"`
}

type ServerProcessor added in v0.19.0 

type ServerProcessor func(config *Config, block *hcl.Block, body hcl.Body) (Listener, hcl.Diagnostics)

ServerProcessor is a function that processes a server block and returns a Listener.

type SignalActionHandler 

type SignalActionHandler struct {
	Ctx            context.Context
	Logger         *zap.Logger
	UserLogger     *zap.Logger
	SignalActions  map[platform.Signal]hcl.Expression
	SignalCtx      map[platform.Signal]*hcl.EvalContext
	SigChannel     chan os.Signal
	AddedStartable bool
	TracerProvider trace.TracerProvider
}

func NewSignalActionHandler 

func NewSignalActionHandler(logger, userLogger *zap.Logger) *SignalActionHandler

func (*SignalActionHandler) Start 

func (sa *SignalActionHandler) Start() error

type SignalsDefinition 

type SignalsDefinition struct {
	SigHup   hcl.Expression `hcl:"SIGHUP,optional"`
	SigInfo  hcl.Expression `hcl:"SIGINFO,optional"`
	SigUsr1  hcl.Expression `hcl:"SIGUSR1,optional"`
	SigUsr2  hcl.Expression `hcl:"SIGUSR2,optional"`
	Disabled bool           `hcl:"disabled,optional"`
	DefRange hcl.Range      `hcl:",def_range"`
}

type Startable 

type Startable interface {
	Start() error
}

func NewErrorlessStartable 

func NewErrorlessStartable(startable errorlessStartable) Startable

type Stoppable added in v0.16.0 

type Stoppable interface {
	Stop() error
}

Stoppable is implemented by components that need graceful shutdown. Stop is called in reverse-start order on SIGINT/SIGTERM.

type SubscriberSource added in v0.35.0 

type SubscriberSource struct {
	Subscriber hcl.Expression
	Action     hcl.Expression
	Transforms hcl.Expression
	QueueSize  *int
}

SubscriberSource groups the four HCL attributes that together specify where a block delivers events: a destination (a named subscriber or an inline action) plus an optional transform pipeline and an optional async queue.

Every block that accepts this pattern should declare the four attributes on its own definition struct with these exact HCL names: 

Subscriber hcl.Expression `hcl:"subscriber,optional"`
Action     hcl.Expression `hcl:"action,optional"`
Transforms hcl.Expression `hcl:"transforms,optional"`
QueueSize  *int           `hcl:"queue_size,optional"`

After decoding, populate a SubscriberSource from those fields and call Resolve to obtain the final bus.Subscriber.

Example VCL: 

subscriber = bus.main                    // XOR
action     = log_info(topic, msg)
transforms = [ jq(".payload") ]          // optional
queue_size = 100                         // optional — enables async queue

func (SubscriberSource) Resolve added in v0.35.0 

func (s SubscriberSource) Resolve(
	config *Config,
	defRange hcl.Range,
	name string,
	tp trace.TracerProvider,
) (bus.Subscriber, hcl.Diagnostics)

Resolve produces the bus.Subscriber specified by the source. Wrappers are applied in order: action|subscriber → transforms → async queue. Exactly one of Subscriber or Action must be provided.

`name` is used as the AsyncQueueingSubscriber instrumentation name (tracer scope + span attribute). `tp` (if non-nil) is forwarded to the async queue so background processing emits new-root SpanKindConsumer spans linked to the caller's span (vinculum-bus v0.13.0+).

type SubscriptionBlockHandler 

type SubscriptionBlockHandler struct {
	BlockHandlerBase
}

func NewSubscriptionBlockHandler 

func NewSubscriptionBlockHandler() *SubscriptionBlockHandler

func (*SubscriptionBlockHandler) GetBlockDependencies added in v0.12.0 

func (h *SubscriptionBlockHandler) GetBlockDependencies(block *hcl.Block) ([]string, hcl.Diagnostics)

func (*SubscriptionBlockHandler) GetBlockDependencyId 

func (h *SubscriptionBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*SubscriptionBlockHandler) Process 

func (h *SubscriptionBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type SubscriptionDefinition 

type SubscriptionDefinition struct {
	Name       string         `hcl:",label"`
	TargetExpr hcl.Expression `hcl:"target,optional"`
	Topics     []string       `hcl:"topics"`
	QueueSize  *int           `hcl:"queue_size,optional"`
	Transforms hcl.Expression `hcl:"transforms,optional"`
	Subscriber hcl.Expression `hcl:"subscriber,optional"`
	ActionExpr hcl.Expression `hcl:"action,optional"`
	Disabled   bool           `hcl:"disabled,optional"`
}

type TLSConfig added in v0.16.0 

type TLSConfig struct {
	Enabled            bool      `hcl:"enabled,optional"`
	CACert             string    `hcl:"ca_cert,optional"`
	Cert               string    `hcl:"cert,optional"`
	Key                string    `hcl:"key,optional"`
	InsecureSkipVerify bool      `hcl:"insecure_skip_verify,optional"`
	RequireClientCert  bool      `hcl:"require_client_cert,optional"`
	SelfSigned         bool      `hcl:"self_signed,optional"`
	DefRange           hcl.Range `hcl:",def_range"`
}

TLSConfig holds TLS configuration for client or server connections. It is designed to be embedded in any block that needs TLS and decoded by gohcl.

For clients: 

tls {
  enabled              = true
  ca_cert              = "/etc/certs/ca.crt"   # verify server cert
  cert                 = "/etc/certs/client.crt"  # optional, for mTLS
  key                  = "/etc/certs/client.key"  # optional, for mTLS
  insecure_skip_verify = false
}

For servers: 

tls {
  enabled             = true
  cert                = "/etc/certs/server.crt"
  key                 = "/etc/certs/server.key"
  ca_cert             = "/etc/certs/ca.crt"  # optional, require client certs
  require_client_cert = true                  # optional, enforce mTLS
}

func (*TLSConfig) BuildTLSClientConfig added in v0.16.0 

func (t *TLSConfig) BuildTLSClientConfig(baseDir string) (*tls.Config, error)

BuildTLSClientConfig constructs a *tls.Config for use as a TLS client. Returns nil if Enabled is false. Relative paths are resolved against baseDir.

ca_cert sets the trusted CA pool (verifies the server certificate). cert + key provide a client certificate for mTLS. insecure_skip_verify disables server certificate verification.

func (*TLSConfig) BuildTLSServerConfig added in v0.16.0 

func (t *TLSConfig) BuildTLSServerConfig(baseDir string) (*tls.Config, error)

BuildTLSServerConfig constructs a *tls.Config for use as a TLS server. Returns nil if Enabled is false. Relative paths are resolved against baseDir.

cert + key are required (the server's certificate). ca_cert sets the CA pool used to verify client certificates. require_client_cert enables mTLS (RequireAndVerifyClientCert).

type TriggerBlockHandler added in v0.17.0 

type TriggerBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

TriggerBlockHandler processes trigger blocks. A fresh instance is created per Build() call; its registry is populated during FinishPreprocessing.

func NewTriggerBlockHandler added in v0.17.0 

func NewTriggerBlockHandler() *TriggerBlockHandler

func (*TriggerBlockHandler) FinishPreprocessing added in v0.21.0 

func (h *TriggerBlockHandler) FinishPreprocessing(config *Config) hcl.Diagnostics

FinishPreprocessing builds the per-build trigger registry by merging unconditional types with any conditional types whose features are enabled.

func (*TriggerBlockHandler) GetBlockDependencies added in v0.33.0 

func (h *TriggerBlockHandler) GetBlockDependencies(block *hcl.Block) ([]string, hcl.Diagnostics)

func (*TriggerBlockHandler) GetBlockDependencyId added in v0.17.0 

func (h *TriggerBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

GetBlockDependencyId returns "trigger.<name>" for trigger types that produce a cty value, enabling correct dependency ordering for blocks that reference trigger.<name>. Other trigger types return "" (no ordering needed). Falls back to the global (unconditional) registry when called before FinishPreprocessing.

func (*TriggerBlockHandler) Process added in v0.17.0 

func (h *TriggerBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type TriggerDefinition added in v0.17.0 

type TriggerDefinition struct {
	Type          string         `hcl:",label"`
	Name          string         `hcl:",label"`
	Disabled      bool           `hcl:"disabled,optional"`
	Tracing       hcl.Expression `hcl:"tracing,optional"`
	DefRange      hcl.Range      `hcl:",def_range"`
	RemainingBody hcl.Body       `hcl:",remain"`

	// TracerProvider is resolved from Tracing (or auto-wired) during Process()
	// and is available to trigger-type processors via triggerDef.TracerProvider.
	TracerProvider trace.TracerProvider
}

type TriggerProcessor added in v0.19.0 

type TriggerProcessor func(config *Config, block *hcl.Block, def *TriggerDefinition) hcl.Diagnostics

TriggerProcessor is a function that processes a trigger block.

type TriggerRegistration added in v0.19.0 

type TriggerRegistration struct {
	Process         TriggerProcessor
	HasDependencyId bool // true if this trigger type produces a cty value at trigger.<name>
}

TriggerRegistration holds the processor and metadata for a trigger type.

type VariableBlockHandler added in v0.11.0 

type VariableBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

func NewVariableBlockHandler added in v0.11.0 

func NewVariableBlockHandler() *VariableBlockHandler

func (*VariableBlockHandler) FinishPreprocessing added in v0.11.0 

func (h *VariableBlockHandler) FinishPreprocessing(config *Config) hcl.Diagnostics

func (*VariableBlockHandler) GetBlockDependencyId added in v0.11.0 

func (h *VariableBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*VariableBlockHandler) Preprocess added in v0.11.0 

func (h *VariableBlockHandler) Preprocess(block *hcl.Block) hcl.Diagnostics

func (*VariableBlockHandler) Process added in v0.11.0 

func (h *VariableBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type VinculumPluginInitFunc added in v0.37.0 

type VinculumPluginInitFunc = func(*PluginContext) hcl.Diagnostics

VinculumPluginInitFunc is the required signature of the entry point that every Go plugin must export under the name VinculumPluginInit. Returning a non-empty error diagnostics value aborts startup.

type WireFormatBlockHandler added in v0.30.0 

type WireFormatBlockHandler struct {
	BlockHandlerBase
}

WireFormatBlockHandler implements BlockHandler for wire_format blocks.

func NewWireFormatBlockHandler added in v0.30.0 

func NewWireFormatBlockHandler() *WireFormatBlockHandler

func (*WireFormatBlockHandler) GetBlockDependencyId added in v0.30.0 

func (h *WireFormatBlockHandler) GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)

func (*WireFormatBlockHandler) Process added in v0.30.0 

func (h *WireFormatBlockHandler) Process(config *Config, block *hcl.Block) hcl.Diagnostics

type WireFormatDefinition added in v0.30.0 

type WireFormatDefinition struct {
	Type          string    `hcl:",label"`
	Name          string    `hcl:",label"`
	DefRange      hcl.Range `hcl:",def_range"`
	RemainingBody hcl.Body  `hcl:",remain"`
}

WireFormatDefinition is the common HCL structure for wire_format blocks.

type WireFormatProcessor added in v0.30.0 

type WireFormatProcessor func(config *Config, block *hcl.Block, body hcl.Body) (cty.Value, hcl.Diagnostics)

WireFormatProcessor processes a wire_format block of a given type and returns a cty.Value to expose in the evaluation context. The value is typically a capsule wrapping a wire.WireFormat, but may also be an object with multiple capsule attributes (e.g. a protobuf plugin returning one capsule per message type).

Source Files

View all Source files

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.