transform

Documentation

Overview

Package transform defines the request body-transform extension point: a typed plugin capability that lets providers rewrite the outgoing HTTP body at dispatch time (e.g. from OpenAI-style JSON into multipart/form-data) based on per-message metadata, while leaving the default JSON path untouched when no plugin applies.

It builds on the generic plugin framework in pkg/plugins (EPP-style Plugin, Registry, Handle). Concrete transforms (such as a gcs_uri multipart provider) are separate plugins that register a factory under their own type.

Index

• type Chain
  • func BuildChain(specs []PluginSpec, handle plugins.Handle) (*Chain, error)
  • func NewChain(transforms []RequestTransform) *Chain
  • func (c *Chain) Apply(payload []byte, metadata map[string]string) (body []byte, contentType string, handled bool, err error)
  • func (c *Chain) Len() int
  • func (c *Chain) Validate(payload []byte, metadata map[string]string, reqDeadline int64) error
• type Config
  • func LoadConfig(path string) (Config, error)
• type PluginSpec
• type RequestTransform

Types

type Chain

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

Chain is an ordered set of RequestTransform plugins applied to each outgoing request. A nil *Chain is valid and behaves as a no-op, so callers that have no transforms configured can pass nil and preserve the default JSON path exactly.

func BuildChain

func BuildChain(specs []PluginSpec, handle plugins.Handle) (*Chain, error)

BuildChain instantiates the configured transforms in order, registering each instance on handle, and returns the resulting Chain. Plugin names must be non-empty and unique; each type must be registered with plugins.Register and the instantiated plugin must implement RequestTransform.

An empty spec list returns an empty (no-op) Chain.

func NewChain

func NewChain(transforms []RequestTransform) *Chain

NewChain returns a Chain over the given transforms, in priority order.

func (*Chain) Apply

func (c *Chain) Apply(payload []byte, metadata map[string]string) (body []byte, contentType string, handled bool, err error)

Apply runs transforms in order and returns the body produced by the first one that handles the message (first-handled-wins, short-circuit): once a transform returns handled=true, its body and Content-Type are returned and no further transforms run. If no transform handles the message, handled is false and the caller should send the original payload unchanged. A nil/empty chain returns handled=false. An error from any transform short-circuits and is returned.

func (*Chain) Len

func (c *Chain) Len() int

Len reports the number of transforms in the chain.

func (*Chain) Validate

func (c *Chain) Validate(payload []byte, metadata map[string]string, reqDeadline int64) error

Validate runs every transform's Validate in order and returns the first error. Each transform decides whether it applies to the message; non-applicable transforms return nil. A nil/empty chain validates successfully.

type Config

type Config struct {
	RequestTransforms []PluginSpec `json:"requestTransforms"`
}

Config is the top-level transform plugins configuration. Transforms are keyed by direction so request and (in the future) response plugins can share a single config file. Only requestTransforms is consumed today; responseTransforms is reserved for the symmetric response body-transform extension point (#259).

func LoadConfig

func LoadConfig(path string) (Config, error)

LoadConfig reads and parses a transform plugins configuration JSON file. The file is a JSON object with transforms grouped by direction, e.g. {"requestTransforms": [ ... ]}. Unknown top-level fields are rejected so a typo (or a not-yet-supported direction such as responseTransforms) fails loudly instead of being silently ignored. It does not instantiate plugins; pass the result to BuildChain.

type PluginSpec

type PluginSpec struct {
	Name       string          `json:"name"`
	Type       string          `json:"type"`
	Parameters json.RawMessage `json:"parameters,omitempty"`
}

PluginSpec is one entry in the transform configuration: a uniquely-named instance of a registered plugin type, plus opaque parameters passed verbatim to the plugin's factory. Mirrors EPP's plugin configuration shape.

type RequestTransform

type RequestTransform interface {
	plugins.Plugin

	// Validate runs before dispatch. It returns a non-nil error to reject the
	// message outright (the worker treats this as fatal/non-retryable) — for
	// example, a signed object URL that expires before reqDeadline. Plugins that
	// do not recognize the message must return nil.
	//
	// reqDeadline is the request deadline in Unix seconds.
	Validate(payload []byte, metadata map[string]string, reqDeadline int64) error

	// Transform optionally rewrites the outgoing body. When it recognizes the
	// message it returns the new body, the Content-Type to set on the request,
	// and handled=true. Otherwise it returns handled=false and the default JSON
	// body is used unchanged.
	Transform(payload []byte, metadata map[string]string) (body []byte, contentType string, handled bool, err error)
}

RequestTransform is a dispatch-time body-transform plugin. The worker invokes the configured chain after marshalling the request payload and before sending it to the inference backend. A plugin that does not recognize a message returns handled=false from Transform, preserving the default JSON path.