plugin

type ConsumerPlugin ¶

type ConsumerPlugin interface {
	Plugin
	// Consumes returns the data keys consumed by this plugin, split into Required and Optional.
	// Required keys: the framework errors at init time if no producer exists.
	// Optional keys: the framework logs a warning but does not error; the plugin must handle absence.
	Consumes() DataDependencies
}

ConsumerPlugin defines the interface for a consumer.

type DataDependencies ¶

type DataDependencies struct {
	// Required keys — the framework will error at init time if no producer exists for any of these.
	Required map[DataKey]any
	// Optional keys — the framework logs a warning at init time but does NOT error if no producer exists.
	// The plugin must handle the case where this data is absent at runtime.
	Optional map[DataKey]any
}

DataDependencies holds the data keys a plugin consumes, split by whether they are required (framework errors if no producer exists) or optional (framework logs a warning but continues if no producer exists).

type DataKey ¶

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

DataKey uniquely identifies the data for data producer/consumer.

func NewDataKey(dataType, defaultProducerName string) DataKey

func (dk DataKey) String() string

func (dk DataKey) WithNonEmptyProducerName(name string) DataKey

type EvictableStateData ¶

type EvictableStateData interface {
	StateData
	// OnEvicted is called when the data is removed from PluginState,
	// either manually or by the janitor.
	//
	// Implementations MUST be thread-safe and non-blocking, as OnEvicted
	// may be called from background goroutines and can race with other
	// request handlers. It must also tolerate being called concurrently
	// and potentially after partial cleanup.
	OnEvicted(requestID string, key StateKey)
}

EvictableStateData is an optional interface for StateData that needs to perform cleanup logic when it is removed or expires.

type FactoryFunc ¶

type FactoryFunc func(name string, parameters *json.Decoder, handle Handle) (Plugin, error)

Factory is the definition of the factory functions that are used to instantiate plugins specified in a configuration. The framework provides a strict decoder (DisallowUnknownFields) over the plugin's raw parameters, or nil when the plugin was instantiated without parameters (e.g., as a default producer). Factories that ignore parameters can take the decoder as `_ *json.Decoder`.

type Handle ¶

type Handle interface {
	// Context returns a context the plugins can use, if they need one
	Context() context.Context

	HandlePlugins

	// PodList lists pods. Returns nil if no pod source was configured on the handle.
	PodList() []types.NamespacedName

	// Metrics returns a recorder plugins can use to register metrics. It may return
	// nil when no recorder is configured.
	Metrics() MetricsRecorder
}

Handle provides plugins a set of standard data and tools to work with

func NewEppHandle(ctx context.Context, podList PodListFunc, opts ...HandleOption) Handle

type HandleOption ¶

type HandleOption func(*eppHandle)

HandleOption configures an eppHandle constructed via NewEppHandle.

func WithMetricsRecorder(recorder MetricsRecorder) HandleOption

type HandlePlugins ¶

type HandlePlugins interface {
	// Plugin returns the named plugin instance
	Plugin(name string) Plugin

	// AddPlugin adds a plugin to the set of known plugin instances
	AddPlugin(name string, plugin Plugin)

	// GetAllPlugins returns all of the known plugins
	GetAllPlugins() []Plugin

	// GetAllPluginsWithNames returns all of the known plugins with their names
	GetAllPluginsWithNames() map[string]Plugin
}

HandlePlugins defines a set of APIs to work with instantiated plugins

type MetricsRecorder ¶

type MetricsRecorder interface {
	prometheus.Registerer
}

MetricsRecorder provides plugins access to metric registration without depending on package-level metric recording functions.

type Plugin ¶

type Plugin interface {
	// TypedName returns the type and name tuple of this plugin instance.
	TypedName() TypedName
}

Plugin defines the interface for a plugin. This interface should be embedded in all plugins across the code.

type PluginState ¶

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

PluginState is per-plugin scratch storage scoped to a single request. A plugin's extension points (e.g. PreRequest, ResponseBody) can write, read, and alter entries here to coordinate within that plugin. Entries are keyed by RequestID and reaped after "stalenessThreshold" of inactivity.

PluginState is not a cross-plugin handoff channel. Data shared between plugins must flow through the Producer/Consumer DAG: write to Endpoint AttributeMap for per-endpoint data, or to the InferenceRequest attribute store for per-request data. The DAG validates type compatibility and execution ordering; PluginState does not.

Note: PluginState uses a sync.Map to back the storage, because it is thread safe. It's aimed to optimize for the "write once and read many times" scenarios.

func NewPluginState(ctx context.Context) *PluginState

func (s *PluginState) Delete(requestID string)

func (s *PluginState) DeleteKey(requestID string, key StateKey)

func (s *PluginState) LastAccessTime(requestID string) (time.Time, bool)

func (s *PluginState) Read(requestID string, key StateKey) (StateData, error)

func (s *PluginState) Touch(requestID string)

func (s *PluginState) Write(requestID string, key StateKey, val StateData)

type PodListFunc ¶

type PodListFunc func() []types.NamespacedName

PodListFunc is a function type that filters and returns a list of pod metrics

type ProducerPlugin ¶

type ProducerPlugin interface {
	Plugin
	// Produces returns data produced by the producer.
	// This is a map from DataKey produced to
	// the data type of the key (represented as data with default value casted as any field).
	Produces() map[DataKey]any
}

ProducerPlugin defines the interface for a producer.

type StateData ¶

type StateData interface {
	// Clone is an interface to make a copy of StateData.
	Clone() StateData
}

StateData is a generic type for arbitrary data stored in PluginState.

type StateDumper ¶

type StateDumper interface {
	// DumpState returns a JSON-encoded representation of plugin state.
	// Implementations own serialization and must not include request payloads,
	// credentials, or other sensitive values.
	DumpState() (json.RawMessage, error)
}

StateDumper is an optional interface for plugins that can expose sanitized, bounded internal state through operational debug endpoints.

DumpState is intended for on-demand debugging snapshots of dynamic runtime state that is difficult to understand from metrics alone. Prefer metrics for numeric time series, alerting, dashboards, and aggregation over time. Dumped state should stay reasonably small; large or high-cardinality state should be summarized, capped, or omitted.

type StateKey ¶

type StateKey string

StateKey is the type of keys stored in PluginState.

type TypedName ¶

type TypedName struct {
	// Type returns the type of a plugin.
	Type string
	// Name returns the name of a plugin instance.
	Name string
}

TypedName is a utility struct providing a type and a name to plugins.

func (tn TypedName) String() string