pluggablevalidator

type CacheKey ¶

type CacheKey struct {
	ValidatorName string
	Path          string
	ContentSHA256 string // hex-encoded sha256 of the file content
}

CacheKey identifies a cache entry. Keyed per-(validator, file-path, content-hash) so:

• the same file routed to two validators caches independently (each validator may decide differently);
• the same validator handling multiple files caches each file independently (changing one file doesn't invalidate the others);
• identical content at different paths is NOT collapsed (the wire-protocol response carries the path, so the cached response is path-specific).

The wire-protocol contract requires validators to be pure functions of their input — under that contract, this key is sufficient and safe.

func NewCacheKey(validatorName, path string, content []byte) CacheKey

type Client ¶

type Client struct {
	// Name is the operator-facing validator name from
	// spec.validators[i].name. Surfaced in synthetic protocol-level
	// diagnostics so users can identify which validator failed.
	Name string

	// SocketPath is the absolute filesystem path to the validator's
	// unix domain socket.
	SocketPath string

	// Timeout is the per-call deadline for one request-response
	// cycle (acquire + write + read). Zero falls back to
	// DefaultTimeout.
	Timeout time.Duration

	// MaxConnections caps the pool size. Zero falls back to
	// DefaultMaxConnections; values < 1 are clamped up to 1.
	MaxConnections int
	// contains filtered or unexported fields
}

Client speaks the HAPTIC validator wire protocol over a unix socket. One Client maps to one configured validator: one socket path, one timeout budget, one connection pool. Clients are safe for concurrent use; the pool serialises within-connection traffic and parallelises across connections.

Pool semantics (adaptive):

• Start small (zero connections; lazy open on first use).
• Grow on contention up to MaxConnections (acquires that find no free connection and have headroom open a fresh one).
• Shrink on idleness (connections checked back into the pool past `idleClose` are closed instead of returned, so the pool deflates when traffic dies down).
• Connections that error on read/write are discarded (poisoned) and replaced lazily on next acquire.

func NewClient(name, socketPath string, timeout time.Duration, maxConnections int) *Client

func (c *Client) Close()

func (c *Client) Validate(ctx context.Context, req *Request) (*Response, error)

type Diagnostic ¶

type Diagnostic struct {
	Path    string `json:"path"`
	Line    uint32 `json:"line"`
	Column  uint32 `json:"column"`
	Message string `json:"message"`
}

Diagnostic is one finding in a Response.

Line and Column are 1-based; 0 means "unknown / file-level". For protocol-level diagnostics (frame errors, version mismatch, missing fields), Path is the empty string.

type File ¶

type File struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

File is one entry in a Request's files array.

Path is an opaque identifier echoed back in diagnostics — the validator MUST NOT open it from disk. Content is the file's UTF-8 bytes (TOML text for hub configs).

type Manager ¶

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

Manager is the controller-side entry point for the validator- sidecar feature. It owns one Client per configured validator plus a shared content-hash result cache. Concurrent calls are safe; per-validator pools handle in-process parallelism.

Routing model: the webhook hands the Manager every rendered file produced by the dry-run. For each (file, validator) pair where the validator's globs match the file's path, the Manager either returns the cached Response or sends a single-file request frame over the socket. All resulting diagnostics are concatenated and returned as one slice. The webhook surfaces the warnings via `AdmissionResponse.Warnings` (kubectl prints them as soft warnings) and the errors as the admission denial reason.

Construction validates that validator names are unique. Configs with duplicate names cause New to fail; the CRD's OpenAPI schema enforces uniqueness too, so this is a defensive check rather than a primary validation surface.

func NewManager(logger *slog.Logger, configs []ManagerConfig) (*Manager, error)

func (m *Manager) Close()

func (m *Manager) Configured() bool

func (m *Manager) Healthy() (ok bool, failures []string)

func (m *Manager) Names() []string

func (m *Manager) ValidateAll(ctx context.Context, files []File) *ValidationOutcome

type ManagerConfig ¶

type ManagerConfig struct {
	// Name is the operator-facing validator identifier.
	Name string
	// SocketPath is the absolute filesystem path to the validator's
	// unix domain socket.
	SocketPath string
	// Files is the list of glob patterns matched against rendered
	// file paths to decide which files to send to this validator.
	// Patterns follow Go's `path/filepath.Match` rules; absolute
	// paths only.
	Files []string
	// Timeout is the per-call deadline for one (file, validator)
	// request-response cycle. Zero falls back to DefaultTimeout.
	Timeout time.Duration
	// MaxConnections caps the controller-side pool to this
	// validator's socket. Zero falls back to DefaultMaxConnections.
	MaxConnections int
}

ManagerConfig captures one entry from `spec.validators` on HAProxyTemplateConfig. Validation of these values (RFC 1123 name, absolute socket path, valid globs, positive timeout) is performed by the CRD's OpenAPI schema before this struct is built; the Manager treats the fields as already-clean.

type Request ¶

type Request struct {
	ProtocolVersion int    `json:"protocol_version"`
	Files           []File `json:"files"`
}

Request is the JSON payload the controller writes onto a validator socket.

type Response ¶

type Response struct {
	ProtocolVersion int          `json:"protocol_version"`
	Result          Result       `json:"result"`
	Warnings        []Diagnostic `json:"warnings"`
	Errors          []Diagnostic `json:"errors"`
	// contains filtered or unexported fields
}

Response is the JSON payload a validator returns. Result is computed from the warning/error counts per the wire-protocol contract.

The unexported `synthetic` field marks responses produced by ProtocolError as transport-level failures. Real validator responses (parsed via DecodeResponse) leave it false. The cache uses this marker to decide whether to memoise the response — synthetic ones represent transient sidecar outages and must NOT be cached, while real validator responses (including those with `path: ""` diagnostics, e.g. plugin panics or file-level errors) are deterministic functions of the input and SHOULD be cached.

`synthetic` is unexported so JSON encoders skip it — the wire format is unchanged.

func DecodeResponse(r io.Reader) (*Response, error)

func ProtocolError(message string) *Response

func (r *Response) IsSynthetic() bool

type Result ¶

type Result string

Result is the aggregate outcome string returned in a Response.

const (
	// ResultValid is "no errors and no warnings".
	ResultValid Result = "valid"
	// ResultWarning is "warnings but no errors".
	ResultWarning Result = "warning"
	// ResultError is "at least one error".
	ResultError Result = "error"
)

type ResultCache ¶

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

ResultCache is a process-local LRU cache mapping CacheKey to *Response. Concurrent access is serialised via an internal mutex; the cache is safe for use by multiple goroutines.

func NewResultCache(capacity int) *ResultCache

func (c *ResultCache) Get(key CacheKey) (*Response, bool)

func (c *ResultCache) Len() int

func (c *ResultCache) Put(key CacheKey, response *Response)

type Severity ¶

type Severity string

Severity is the diagnostic severity in the wire format.

const (
	// SeverityWarning is a non-blocking finding.
	SeverityWarning Severity = "warning"
	// SeverityError blocks admission.
	SeverityError Severity = "error"
)

type ValidationOutcome ¶

type ValidationOutcome struct {
	Warnings []Diagnostic
	Errors   []Diagnostic
}

ValidationOutcome bundles the warnings + errors collected across all (file, validator) round-trips for one ValidateAll call. The caller maps these to the admission webhook's response shape: warnings → `AdmissionResponse.Warnings`, errors → admission denial reason. A non-nil ValidationOutcome with zero entries in both lists is the equivalent of `result: "valid"`.

func (o *ValidationOutcome) Result() Result