base

package
v0.1.0-rc.3 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 47 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultRequestBodyMaxBytes  = 1 << 20
	DefaultResponseBodyMaxBytes = 4 << 20
)
View Source 
const (
	MAX_REQ_BODY  = 524288 // 512 KiB
	MAX_RESP_BODY = 524288 // 512 KiB
)
View Source 
const DefaultBufferedResponseMaxBytes int64 = DefaultResponseBodyMaxBytes
View Source 
const DefaultRequestBodySnapshotMemoryLimit int64 = 1024 * 1024

Variables

View Source 
var ErrCacheHitResponseAlreadyConsumed = errors.New("cache hit response already consumed")
View Source 
var ErrLogQueueFull = errors.New("logger batch processor queue full")

ErrLogQueueFull is returned when a detached log callback cannot enqueue its payload without blocking the request lifecycle.

View Source 
var ErrLogQueueUnavailable = errors.New("logger batch processor unavailable")

ErrLogQueueUnavailable reports a logger that has not initialized its bounded processor yet. It is deliberately distinct from capacity drops so callers can surface configuration/lifecycle errors.

View Source 
var ErrRequestBodyTooLarge = errors.New("request body too large")
View Source 
var RequestVariablePattern = regexp.MustCompile(`\$[A-Za-z0-9_]+`)

RequestVariablePattern matches $name and ${name}-less APISIX/NGINX variable references in interpolation templates.

Functions

func AdaptRequestPhase 

func AdaptRequestPhase(plugin RequestPhasePlugin, next http.Handler) http.Handler

func AppendVaryToken 

func AppendVaryToken(header http.Header, token string)

AppendVaryToken adds token to all existing Vary field-values once, using a case-insensitive comparison while retaining unrelated tokens and order.

func ApplyBatchDefaults 

func ApplyBatchDefaults(d *BatchDefaults)

ApplyBatchDefaults fills zero batch values with logger_batch defaults. RetryDelaySec is only defaulted when RetryDelaySet is false.

func ApplyMatchedRouteFields 

func ApplyMatchedRouteFields(fields map[string]any, routeID string, serviceID string)

ApplyMatchedRouteFields mirrors APISIX 3.17 custom log formatting: a matched route overwrites the configured route_id and either overwrites or removes service_id according to the matched route.

func ApplySnapshotMatchedRouteFields 

func ApplySnapshotMatchedRouteFields(fields map[string]any, snapshot LogSnapshot, fallbackRouteID string)

ApplySnapshotMatchedRouteFields resolves the same identifiers from the detached log-phase snapshot.

func AttachExternalUser 

func AttachExternalUser(r *http.Request, userinfo map[string]any, setHeader *bool)

AttachExternalUser publishes userinfo into the $external_user request variable and the X-Userinfo header unless setHeader is non-nil and false.

func AttachRequestBodySnapshot 

func AttachRequestBodySnapshot(
	request *http.Request,
	snapshot *RequestBodySnapshot,
	closeSnapshot bool,
) error

func BuildAccessLogFromSnapshot 

func BuildAccessLogFromSnapshot(snapshot LogSnapshot, routeID string, serverAddr ...string) map[string]any

BuildAccessLogFromSnapshot preserves the default access-log payload after the live request and response writer have been detached.

func CallbackPath 

func CallbackPath(callbackURI string) string

CallbackPath returns the request path of an absolute callback URI, the original value for relative or unparsable URIs, and "/" when an absolute URI has no path.

func CodeFromRequest 

func CodeFromRequest(r *http.Request, headerName, queryName string) string

CodeFromRequest reads an authorization code from the named header first, falling back to the named query parameter.

func CollapseAccessLogHeaderValues 

func CollapseAccessLogHeaderValues(values http.Header) map[string]any

CollapseAccessLogHeaderValues normalizes default access-log headers the same way APISIX log-util.lua copies ngx.req.get_headers() with no omit list.

func CollapseHeaderValues 

func CollapseHeaderValues(values http.Header) map[string]any

CollapseHeaderValues normalizes header names to lowercase and collapses single-value headers to plain strings.

func CollapseQueryValues 

func CollapseQueryValues(values map[string][]string) map[string]any

CollapseQueryValues collapses single-value query parameters to plain strings.

func EncodeLogBatch 

func EncodeLogBatch(entries []map[string]any, batchMaxSize int, originKey string) ([]byte, error)

EncodeLogBatch encodes either a single entry or an entry array according to the logger batch boundary. When originKey is set and every entry contains a raw origin string, those strings are encoded instead of their envelopes.

func EnqueueLog 

func EnqueueLog(processor *logger_batch.Processor, entry map[string]any) error

EnqueueLog is the standalone form for logger implementations that cannot embed BaseLoggerPlugin (for example metric and file loggers).

func ExprMatched 

func ExprMatched(r *http.Request, expressions any, status int) bool

func ExtractResponseTrailers 

func ExtractResponseTrailers(header http.Header) http.Header

ExtractResponseTrailers removes trailer declarations and values from a detached header map and returns them as a separate canonical trailer map.

func GetFieldsFromSnapshot 

func GetFieldsFromSnapshot(snapshot LogSnapshot, logFormat map[string]string) map[string]any

GetFieldsFromSnapshot keeps field expansion in the detached snapshot layer while giving plugin packages a base-level entry point.

func HostWithoutPort 

func HostWithoutPort(address string) string

HostWithoutPort strips the port from a host or address.

func Hostname 

func Hostname() string

Hostname returns the process hostname, cached once per process so logger transports never re-read it per entry.

func InvalidateBodyDerivedHeaders 

func InvalidateBodyDerivedHeaders(header http.Header)

InvalidateBodyDerivedHeaders removes representation metadata that no longer describes the body after a semantic replacement. Iterate the actual map keys because Header.Del only removes the canonical key.

func IsBodyTooLarge 

func IsBodyTooLarge(err error) bool

func IsHopByHopHeader 

func IsHopByHopHeader(field string) bool

IsHopByHopHeader reports whether field is a connection-scoped hop-by-hop header from the RFC 7230 set, plus Proxy-Connection.

func LogSnapshotValue 

func LogSnapshotValue(snapshot LogSnapshot, name string) any

func MaterializeScopedCompositeChildSecrets 

func MaterializeScopedCompositeChildSecrets(
	ctx context.Context,
	access ScopedSecretAccess,
	p any,
) error

MaterializeScopedCompositeChildSecrets runs the same scoped-only body for a child whose authority was derived with ScopedSecretAccess.Child. It never crosses into the transitional process-global materializer.

func MaterializeScopedPluginSecrets 

func MaterializeScopedPluginSecrets(
	ctx context.Context,
	baseScope secret.Scope,
	secrets secret.GenerationSecrets,
	p any,
) error

MaterializeScopedPluginSecrets runs the generation-bound secret phase.

func NestedLogMap 

func NestedLogMap(fields map[string]any, key string) map[string]any

func NewBatchProcessor 

func NewBatchProcessor(
	name string,
	tasks *runtime.TaskOwner,
	d BatchDefaults,
	routeID, serverAddr string,
	deliver logger_batch.ContextDeliveryFunc,
) (*logger_batch.Processor, error)

NewBatchProcessor constructs a logger batch processor from second-based batch defaults.

func NumberClaim 

func NumberClaim(value any) (int64, bool)

NumberClaim converts a JSON-decoded numeric claim to an int64.

func OpenOAuthSession 

func OpenOAuthSession(
	encoded string,
	secret string,
	fallbacks []string,
	fingerprint string,
	now time.Time,
) ([]byte, error)

OpenOAuthSession decrypts a bounded OAuth session with the primary secret or one of its rotation fallbacks and validates its version, expiry, and config.

func OriginLogEntries 

func OriginLogEntries(entries []map[string]any, originKey string) ([]string, bool)

OriginLogEntries unwraps raw origin entries only when every batch entry contains a string under originKey.

func PrepareExprRegexps 

func PrepareExprRegexps(expressionSets ...any) error

PrepareExprRegexps compiles configured logger expression patterns before they enter the request path. An invalid pattern fails plugin initialization so a malformed expression never reaches request handling.

func ProtocolVersion 

func ProtocolVersion(r *http.Request) string

ProtocolVersion returns the request protocol version as major.minor.

func ReadRequestBody 

func ReadRequestBody(r *http.Request) ([]byte, error)

func ReadRequestBodyLimited 

func ReadRequestBodyLimited(r *http.Request, maxSize int) ([]byte, error)

ReadRequestBodyLimited reads and restores the request body while rejecting bodies larger than maxSize with a size-exceeded error.

func ReadResponseBodyLimited 

func ReadResponseBodyLimited(reader io.Reader, maxSize int64) ([]byte, error)

func RemoteIP 

func RemoteIP(remoteAddr string) string

func RemoveHTTP2ConnectionHeaders 

func RemoveHTTP2ConnectionHeaders(header http.Header)

RemoveHTTP2ConnectionHeaders removes response headers that cannot be forwarded on an HTTP/2 downstream connection.

func ReplaceRequestBody 

func ReplaceRequestBody(r *http.Request, body []byte)

func RequestVar 

func RequestVar(r *http.Request, name string, status int) string

func RequestVarFromNginx 

func RequestVarFromNginx(r *http.Request, key string) string

func RequireStringLogFormat 

func RequireStringLogFormat(pluginName string, route, metadata map[string]string) (map[string]string, error)

RequireStringLogFormat selects a non-empty route log format, falling back to plugin metadata when the route does not provide one. The returned map is owned by the caller and is safe to update without mutating either input.

func ResolveLogFormat 

func ResolveLogFormat(format map[string]any, resolve func(string) any) map[string]any

ResolveLogFormat recursively resolves string leaves while preserving maps and non-string values.

func ResolveRequestVariables 

func ResolveRequestVariables(value string, lookup func(name string) string) string

ResolveRequestVariables replaces each $name variable reference in value with the lookup result for name. Lookup receives the name without the leading dollar sign.

func ResolveStringLogFormat 

func ResolveStringLogFormat(format map[string]string, resolve func(string) any) map[string]any

ResolveStringLogFormat resolves every value in a flat string log format.

func ResponseAllowsBody 

func ResponseAllowsBody(method string, status int) bool

ResponseAllowsBody reports whether method/status permits response body bytes. 101 is a final switching-protocols response and is bodyless here.

func SealOAuthSession 

func SealOAuthSession(
	payload []byte,
	secret string,
	fingerprint string,
	issuedAt time.Time,
	expiresAt time.Time,
) (string, error)

SealOAuthSession encrypts a bounded OAuth session using the primary secret.

func Sha256Hex 

func Sha256Hex(value string) string

Sha256Hex returns the lowercase hex SHA-256 digest of value.

func SignRawSessionValue 

func SignRawSessionValue(payload []byte, secret string) string

SignRawSessionValue signs a payload as base64url(payload) + "." + base64url(HMAC-SHA256(payload, secret)). Unlike SignSessionValue, the HMAC covers the raw payload bytes, not the encoded payload.

func SignSessionValue 

func SignSessionValue(value []byte, secret string) string

SignSessionValue signs a payload for a session cookie as base64url(payload) + "." + base64url(HMAC-SHA256(base64url(payload), secret)).

func SnapshotExpressionMatches 

func SnapshotExpressionMatches(snapshot LogSnapshot, expressions any) bool

SnapshotExpressionMatches preserves the legacy logger expression grammar while resolving every variable from the detached snapshot.

func SnapshotRequestBody 

func SnapshotRequestBody(snapshot LogSnapshot, limit int) string

SnapshotRequestBody returns a bounded detached request body.

func SnapshotResponseBody 

func SnapshotResponseBody(snapshot LogSnapshot, limit int) string

SnapshotResponseBody returns a bounded response body, decoding the same gzip/brotli encodings handled by the legacy response recorder.

func SnapshotUpstreamAddress 

func SnapshotUpstreamAddress(snapshot LogSnapshot) string

func SnapshotValue 

func SnapshotValue(snapshot LogSnapshot, expression string) any

SnapshotValue resolves one access-log expression without consulting a live request. Literal values are preserved as strings, matching legacy format resolution.

func TruncateLogFormat 

func TruncateLogFormat(format map[string]any, maxDepth int) (map[string]any, bool)

TruncateLogFormat copies format and replaces nested objects at maxDepth with empty maps. The returned bool reports whether any non-empty object was truncated.

func UseConsumerCredential 

func UseConsumerCredential(
	ctx context.Context,
	lookup ConsumerLookup,
	plugin string,
	key string,
	use ConsumerCredentialUse,
) (bool, error)

UseConsumerCredential resolves a credential only for the duration of use. Legacy lookup implementations without request-scoped secret support retain the existing in-memory lookup behavior used by focused plugin tests.

func ValidateLogCapturePolicy 

func ValidateLogCapturePolicy(policy LogCapturePolicy) error

ValidateLogCapturePolicy enforces the existing hard body ceilings. Zero is intentional and means that the corresponding body is not captured.

func VerifyRawSessionValue 

func VerifyRawSessionValue(signed, secret string, fallbacks []string) ([]byte, bool)

VerifyRawSessionValue verifies a raw-payload signed value against secret and fallbacks and returns the decoded payload.

func VerifySessionValue 

func VerifySessionValue(signed, secret string, fallbacks []string) ([]byte, bool)

VerifySessionValue verifies a signed value against secret and fallbacks and returns the decoded payload.

func WithCacheHitResponseHolder 

func WithCacheHitResponseHolder(r *http.Request, holder *CacheHitResponseHolder) *http.Request

func WithResponseCapture 

func WithResponseCapture(r *http.Request, capture *ResponseCapture) *http.Request

func WithTransformPipeline 

func WithTransformPipeline(count int) func(http.Handler) http.Handler

WithTransformPipeline marks a handler chain containing response-transform plugins. Chains with zero or one transform preserve standalone buffering; chains with multiple transforms share one response body buffer.

func WriteJSONMessage 

func WriteJSONMessage(w http.ResponseWriter, status int, message string)

WriteJSONMessage preserves the plugin-base API for existing callers while using the canonical response writer in util.

Types

type APISIXPluginContext 

type APISIXPluginContext struct {
	Provider          string
	EtcdPrefix        string
	SourceKind        string
	SourceID          string
	SourceResourceKey string
	ModifiedIndex     string
	ConfigType        string
	ConfigVersion     string
	SourceConfig      map[string]any
	WorkflowVID       int
	ConsumerOverride  bool
}

APISIXPluginContext is the compiler-owned source identity used by plugins whose observable behavior depends on the APISIX resource that supplied their effective configuration. Callers must derive changes from Clone or WithWorkflowVID instead of sharing SourceConfig across plugin instances.

func (APISIXPluginContext) Clone 

func (pluginContext APISIXPluginContext) Clone() APISIXPluginContext

Clone returns an independently owned context value.

func (APISIXPluginContext) ParentResourceKey 

func (pluginContext APISIXPluginContext) ParentResourceKey() (string, error)

ParentResourceKey returns the APISIX 3.17 parent resource identity. Etcd prefixes are intentionally kept literal because APISIX includes the configured prefix in limiter counter identity.

func (APISIXPluginContext) WithWorkflowVID 

func (pluginContext APISIXPluginContext) WithWorkflowVID(vid int) APISIXPluginContext

WithWorkflowVID derives the one-based APISIX workflow action identity without aliasing the parent plugin document.

type AuthorizationFacts 

type AuthorizationFacts struct {
	Version    int                   `json:"version"`
	Scheme     string                `json:"scheme"`
	Method     string                `json:"method"`
	Host       string                `json:"host"`
	Path       string                `json:"path"`
	RawQuery   string                `json:"raw_query,omitempty"`
	RequestURI string                `json:"request_uri,omitempty"`
	Headers    map[string][]string   `json:"headers"`
	ClientIP   string                `json:"client_ip"`
	ClientPort string                `json:"client_port,omitempty"`
	ServerAddr string                `json:"server_addr,omitempty"`
	ServerPort string                `json:"server_port,omitempty"`
	Route      AuthorizationResource `json:"route,omitempty"`   //nolint:modernize // fixed external-authorization interface
	Service    AuthorizationResource `json:"service,omitempty"` //nolint:modernize // fixed external-authorization interface
}

AuthorizationFacts is the immutable request snapshot shared by external authorization plugins.

func CaptureAuthorizationFacts 

func CaptureAuthorizationFacts(
	r *http.Request,
	serverAddr string,
	route AuthorizationResource,
	service AuthorizationResource,
) AuthorizationFacts

CaptureAuthorizationFacts captures only the request and safe resource identity fields needed by external authorization plugins.

type AuthorizationResource 

type AuthorizationResource struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
	URI  string `json:"uri,omitempty"`
}

AuthorizationResource is the safe identity subset of an APISIX resource that may be included in an external-authorization input.

type BaseLoggerPlugin 

type BaseLoggerPlugin struct {
	BasePlugin

	LogFormat map[string]string
	// SnapshotLogFormat is used by plugins whose public log format supports
	// nested values. LogFormat remains the compatibility representation for
	// flat APISIX logger formats.
	SnapshotLogFormat      map[string]any
	SnapshotLogFormatExtra map[string]any
	RequestBodyExpr        any
	ResponseBodyExpr       any
	RequestBodyBytes       int
	ResponseBodyBytes      int

	BatchProcessor *logger_batch.Processor
	RouteID        string
	ServerAddr     string

	IncludeRequestBody  bool
	IncludeResponseBody bool
	// contains filtered or unexported fields
}

func (*BaseLoggerPlugin) EnqueueLog 

func (p *BaseLoggerPlugin) EnqueueLog(entry map[string]any) error

EnqueueLog exposes the non-blocking delivery boundary used by detached log callbacks. BatchProcessor.Push is the only permitted production path.

func (*BaseLoggerPlugin) Handler 

func (p *BaseLoggerPlugin) Handler(next http.Handler) http.Handler

func (*BaseLoggerPlugin) LogCapturePolicy 

func (p *BaseLoggerPlugin) LogCapturePolicy() LogCapturePolicy

LogCapturePolicy returns the body limits configured on the logger. A zero limit means that body bytes are not required by this logger.

func (*BaseLoggerPlugin) RunLogPhase 

func (p *BaseLoggerPlugin) RunLogPhase(snapshot LogSnapshot) error

RunLogPhase resolves fields from a detached snapshot and enqueues them on the bounded batch processor.

func (*BaseLoggerPlugin) SetLogCapturePolicy 

func (p *BaseLoggerPlugin) SetLogCapturePolicy(
	includeRequest, includeResponse bool,
	requestBytes, responseBytes int,
	requestExpr, responseExpr any,
)

SetLogCapturePolicy wires a logger's bounded body policy into the detached callback implementation.

func (*BaseLoggerPlugin) SetRouteContext 

func (p *BaseLoggerPlugin) SetRouteContext(routeID string, serverAddr string)

func (*BaseLoggerPlugin) SetSnapshotLogFormat 

func (p *BaseLoggerPlugin) SetSnapshotLogFormat(format, extra map[string]any)

func (*BaseLoggerPlugin) Stop 

func (p *BaseLoggerPlugin) Stop()

func (*BaseLoggerPlugin) StopWithCleanup 

func (p *BaseLoggerPlugin) StopWithCleanup(cleanup func())

StopWithCleanup retains sink resources until every batch delivery callback has returned, while preserving the processor's bounded caller-facing stop.

type BasePlugin 

type BasePlugin struct {
	Name           string
	Priority       int
	Schema         string
	MetadataSchema string
	// contains filtered or unexported fields
}

func (*BasePlugin) CompositeChildPreparer 

func (p *BasePlugin) CompositeChildPreparer() CompositeChildPreparer

func (*BasePlugin) ConsumerLookup 

func (p *BasePlugin) ConsumerLookup() ConsumerLookup

func (*BasePlugin) GetMetadataSchema 

func (p *BasePlugin) GetMetadataSchema() string

func (*BasePlugin) GetName 

func (p *BasePlugin) GetName() string

func (*BasePlugin) GetPriority 

func (p *BasePlugin) GetPriority() int

func (*BasePlugin) GetSchema 

func (p *BasePlugin) GetSchema() string

func (*BasePlugin) MetadataView 

func (p *BasePlugin) MetadataView() runtime.MetadataView

func (*BasePlugin) SetDependencies 

func (p *BasePlugin) SetDependencies(deps Dependencies)

func (*BasePlugin) StaticConfig 

func (p *BasePlugin) StaticConfig() *config.EffectiveConfig

func (*BasePlugin) TaskOwner 

func (p *BasePlugin) TaskOwner() *runtime.TaskOwner

func (*BasePlugin) WithHTTPPublication 

func (p *BasePlugin) WithHTTPPublication(action func() error) error

WithHTTPPublication admits process maintenance only while this instance owns the published HTTP domain. Retirement waits for an admitted action to finish.

type BatchDefaults 

type BatchDefaults struct {
	BatchMaxSize       int
	MaxRetryCount      int
	RetryDelaySec      int
	RetryDelaySet      bool
	BufferDurationSec  int
	InactiveTimeoutSec int
	MaxPendingEntries  int
	PluginID           string

	// Resource overrides are internal until each logger schema exposes them.
	MaxConcurrentDeliveries int
	DeliveryTimeoutSec      int
	ShutdownTimeoutSec      int
}

BatchDefaults carries the per-plugin batch configuration values in seconds.

type BindingPhaseDescriber 

type BindingPhaseDescriber interface {
	DescribeBindingPhases() (BindingPhaseDescriptor, error)
}

BindingPhaseDescriber lets config-aware plugins describe the one request stage and response phases selected by their initialized configuration.

type BindingPhaseDescriptor 

type BindingPhaseDescriptor struct {
	RequestStage    string
	Header          bool
	StreamingHeader bool
	BufferedBody    bool
	Log             bool
}

BindingPhaseDescriptor is the config-derived part of a checked plugin binding. The root plugin package validates the exact request-stage strings and response capability mask for each factory identity.

type BodyTooLargeError 

type BodyTooLargeError struct {
	Limit int64
}

BodyTooLargeError reports a bounded read that retained at most Limit+1 bytes. Callers can map this error to the protocol-specific 413/502 status.

func (*BodyTooLargeError) Error 

func (e *BodyTooLargeError) Error() string

type BufferedBodyFilterPlugin 

type BufferedBodyFilterPlugin interface {
	RunBufferedBodyFilter(*http.Request, *ResponseState) error
}

type BufferedResponseConfig 

type BufferedResponseConfig struct {
	MaxBytes int64
}

BufferedResponseConfig controls the bounded response capture.

type BufferedResponseWriter 

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

BufferedResponseWriter delays header and body commitment until Commit, allowing the response to be inspected, rewritten and replayed. It is separate from the immediate response path used by observers.

In pipeline mode (bodyPtr != nil) multiple BufferedResponseWriter instances share the same underlying bytes.Buffer; Commit detects this and skips the body copy when committing between pipeline writers.

func GetOrCreateTransformResponseWriter 

func GetOrCreateTransformResponseWriter(r *http.Request) *BufferedResponseWriter

GetOrCreateTransformResponseWriter returns a BufferedResponseWriter for transform plugins. When multiple transform plugins are present in the handler chain, all returned writers share a single underlying bytes.Buffer via a pipelineBuffer stored in request context. This eliminates O(N) copies of the response body.

Each writer still has its own header map and status code; Commit copies headers between writers and only the final commit writes to the real http.ResponseWriter.

func NewBufferedResponseWriter 

func NewBufferedResponseWriter() *BufferedResponseWriter

func (*BufferedResponseWriter) Body 

func (w *BufferedResponseWriter) Body() []byte

func (*BufferedResponseWriter) Commit 

func (w *BufferedResponseWriter) Commit(dst http.ResponseWriter)

Commit writes the buffered headers, status and body to dst. When dst is another BufferedResponseWriter that shares the same pipeline buffer, the body copy is skipped (the buffer is already shared).

func (*BufferedResponseWriter) CommitCaptured 

func (w *BufferedResponseWriter) CommitCaptured(dst http.ResponseWriter) bool

CommitCaptured replays captured informational responses and commits the final response only when one was actually written. It lets an undecided request become transparent without manufacturing a default 200 response.

func (*BufferedResponseWriter) CommitFinalResponse 

func (w *BufferedResponseWriter) CommitFinalResponse(
	dst http.ResponseWriter,
	state ResponseState,
)

CommitFinalResponse replaces only the final canonical representation before using the existing commit path. In particular, private informational responses captured before the final response are retained; Reset must not be used here because it deliberately clears that history.

func (*BufferedResponseWriter) Header 

func (w *BufferedResponseWriter) Header() http.Header

func (*BufferedResponseWriter) ReplaceBody 

func (w *BufferedResponseWriter) ReplaceBody(body []byte)

ReplaceBody replaces the buffered body and invalidates metadata derived from the previous representation. SetBody intentionally remains a raw operation for callers that already own representation metadata.

func (*BufferedResponseWriter) Reset 

func (w *BufferedResponseWriter) Reset()

Reset discards all buffered response state so an error response can replace a failed transformation cleanly, including in a shared transform pipeline.

func (*BufferedResponseWriter) SetBody 

func (w *BufferedResponseWriter) SetBody(body []byte)

SetBody replaces the buffered body content.

func (*BufferedResponseWriter) SetStatusCode 

func (w *BufferedResponseWriter) SetStatusCode(statusCode int)

SetStatusCode overrides the buffered status, used by response-transform plugins that rewrite the status after capture.

func (*BufferedResponseWriter) StatusCode 

func (w *BufferedResponseWriter) StatusCode() int

func (*BufferedResponseWriter) Write 

func (w *BufferedResponseWriter) Write(body []byte) (int, error)

func (*BufferedResponseWriter) WriteBodyTo 

func (w *BufferedResponseWriter) WriteBodyTo(dst http.ResponseWriter)

WriteBodyTo writes the buffered body to dst. When dst is another BufferedResponseWriter that shares the same pipeline buffer, the body write is a no-op (the data is already shared).

This is useful for plugins that write headers/status/body manually instead of using Commit.

func (*BufferedResponseWriter) WriteHeader 

func (w *BufferedResponseWriter) WriteHeader(statusCode int)

type CacheHitResponseHolder 

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

CacheHitResponseHolder transports one cache-hit response without making writer calls in the request phase. Publication and consumption deep-copy all mutable response values and consumption is exactly once.

func CacheHitResponseHolderFromRequest 

func CacheHitResponseHolderFromRequest(r *http.Request) *CacheHitResponseHolder

func NewCacheHitResponseHolder 

func NewCacheHitResponseHolder() *CacheHitResponseHolder

func (*CacheHitResponseHolder) Consume 

func (h *CacheHitResponseHolder) Consume() (CachedResponseState, error)

func (*CacheHitResponseHolder) ConsumePublished 

func (h *CacheHitResponseHolder) ConsumePublished() (CachedResponseState, bool, error)

ConsumePublished distinguishes a missing publication from a consumed hit; both remain exactly-once operations, while callers can fail closed when the lifecycle source claims CacheHit without a published representation.

func (*CacheHitResponseHolder) Publish 

func (h *CacheHitResponseHolder) Publish(state CachedResponseState)

func (*CacheHitResponseHolder) Published 

func (h *CacheHitResponseHolder) Published() bool

type CachedResponseState 

type CachedResponseState struct {
	Status  int
	Header  http.Header
	Trailer http.Header
	Body    []byte
}

CachedResponseState is the immutable representation handed from a cache lookup to the response executor. It intentionally mirrors only the canonical response fields.

type CompositeChildPreparer 

type CompositeChildPreparer interface {
	Prepare(context.Context, ScopedSecretAccess, CompositeChildSpec) (PreparedCompositeChild, error)
}

CompositeChildPreparer constructs generation-owned children without exposing registry, descriptor, or binding internals to composite plugin packages.

type CompositeChildSpec 

type CompositeChildSpec struct {
	Factory  string
	Config   map[string]any
	Position string
}

CompositeChildSpec describes one child selected by a composite plugin. Position is the stable structural path within the outer plugin config.

type ConsumerCredentialLookup 

type ConsumerCredentialLookup interface {
	UseConsumerCredential(
		context.Context,
		string,
		string,
		ConsumerCredentialUse,
	) (bool, error)
}

type ConsumerCredentialUse 

type ConsumerCredentialUse func(resource.Consumer, resource.PluginConfig) error

type ConsumerLookup 

type ConsumerLookup interface {
	ConsumerByPluginKey(plugin, key string) (resource.Consumer, bool)
	ConsumerByID(id string) (resource.Consumer, bool)
	ConsumerGroupByID(id string) (resource.ConsumerGroup, bool)
}

type Dependencies 

type Dependencies struct {
	Config              *config.EffectiveConfig
	Secrets             secret.GenerationSecrets
	Metadata            runtime.MetadataView
	Consumers           ConsumerLookup
	Tasks               *runtime.TaskOwner
	WithHTTPPublication func(func() error) error
	CompositeChildren   CompositeChildPreparer
}

type ExclusiveProtocolTerminal 

type ExclusiveProtocolTerminal interface {
	RunExclusiveProtocol(
		http.ResponseWriter,
		*http.Request,
		http.Handler,
	) (ProtocolDisposition, *http.Request, apisixctx.ResponseSource, error)
}

ExclusiveProtocolTerminal owns one protocol response. The continuation is supplied so protocol translators can frame a normal upstream response while terminal-only owners can ignore it. The source must be selected before the owner writes, flushes, or hijacks.

type FinalResponseStorePlugin 

type FinalResponseStorePlugin interface {
	RunFinalResponseStore(*http.Request, ResponseState) error
}

type HeaderFilterPlugin 

type HeaderFilterPlugin interface {
	RunHeaderFilter(*http.Request, *ResponseState) error
}

type JWTToken 

type JWTToken struct {
	Header    map[string]any
	Payload   map[string]any
	Signing   string
	Signature []byte
}

JWTToken is the parsed representation of an unverified JWT.

func ParseJWT 

func ParseJWT(raw string) (JWTToken, error)

ParseJWT splits and decodes a three-part JWT without verifying it.

type LogCapturePolicy 

type LogCapturePolicy struct {
	RequestBodyBytes  int
	ResponseBodyBytes int
}

func LogCapturePolicyForFormats 

func LogCapturePolicyForFormats(requestBytes, responseBytes int, formats ...any) LogCapturePolicy

LogCapturePolicyForFormats derives bounded body capture requirements from the configured logger formats without retaining plugin configuration in the detached callback.

type LogCapturePolicyPlugin 

type LogCapturePolicyPlugin interface {
	LogCapturePolicy() LogCapturePolicy
}

type LogPhasePlugin 

type LogPhasePlugin interface {
	RunLogPhase(LogSnapshot) error
}

type LogSnapshot 

type LogSnapshot = apisixlog.LogSnapshot

LogSnapshot is the plugin-facing alias for the detached canonical snapshot.

func BuildLogSnapshotFromOwnedInputs 

func BuildLogSnapshotFromOwnedInputs(
	r *http.Request,
	response ResponseCaptureSnapshot,
	requestBody []byte,
	requestBodyTruncated bool,
	outcome apisixctx.ResponseOutcome,
	source apisixctx.ResponseSource,
	started,
	finished time.Time,
) LogSnapshot

BuildLogSnapshotFromOwnedInputs transfers detached response capture and a previously captured request body into a canonical snapshot. The request is inspected only for metadata; its live body is never read.

func CloneLogSnapshotForPolicy 

func CloneLogSnapshotForPolicy(snapshot LogSnapshot, policy LogCapturePolicy) LogSnapshot

CloneLogSnapshotForPolicy gives one callback a private bounded view. Every invocation returns a fresh clone, including when both body limits are zero.

type LogSnapshotSanitizerPlugin 

type LogSnapshotSanitizerPlugin interface {
	SanitizeLogSnapshot(*LogSnapshot) error
}

LogSnapshotSanitizerPlugin mutates only the detached canonical logging snapshot. The log executor runs sanitizers before cloning the snapshot for any logger or snapshot finalizer callback.

type LogSnapshotSanitizerSelectorPlugin 

type LogSnapshotSanitizerSelectorPlugin interface {
	ShouldSanitizeLogSnapshot(LogSnapshot) bool
}

LogSnapshotSanitizerSelectorPlugin optionally restricts a sanitizer to a detached snapshot. The log executor evaluates every selector against the same pre-sanitized snapshot before running any sanitizer callback.

type PreparedCompositeChild 

type PreparedCompositeChild interface {
	Factory() string
	Instance() any
	Close()
}

PreparedCompositeChild owns one initialized, generation-bound child.

type ProtocolDisposition 

type ProtocolDisposition uint8
const (
	ProtocolResponded ProtocolDisposition = iota + 1
	ProtocolHijacked
)

type RedisClusterConnConfig 

type RedisClusterConnConfig struct {
	Nodes                                    []string
	Password                                 string
	Timeout, KeepaliveTimeout, KeepalivePool int
	SSL, SSLVerify                           *bool
}

RedisClusterConnConfig is the narrow redis-cluster connection configuration shared by the rate-limit plugins.

func (RedisClusterConnConfig) ClusterOptions 

func (c RedisClusterConnConfig) ClusterOptions() *redis.ClusterOptions

ClusterOptions builds a cluster redis.ClusterOptions. Timeout and KeepaliveTimeout are in milliseconds.

type RedisConnConfig 

type RedisConnConfig struct {
	Host, Username, Password                                 string
	Port, Database, Timeout, KeepaliveTimeout, KeepalivePool int
	SSL, SSLVerify                                           *bool
}

RedisConnConfig is the narrow standalone Redis connection configuration shared by the rate-limit plugins.

func (RedisConnConfig) Options 

func (c RedisConnConfig) Options() *redis.Options

Options builds a standalone redis.Options. Timeout and KeepaliveTimeout are in milliseconds, matching the rate-limit plugin configuration.

type RequestBodySnapshot 

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

func EnsureRequestBodySnapshot 

func EnsureRequestBodySnapshot(
	request *http.Request,
	maxSize int64,
	memoryLimit int64,
) (*RequestBodySnapshot, error)

func RequestBodySnapshotFrom 

func RequestBodySnapshotFrom(request *http.Request) *RequestBodySnapshot

func (*RequestBodySnapshot) Close 

func (snapshot *RequestBodySnapshot) Close() error

func (*RequestBodySnapshot) Open 

func (snapshot *RequestBodySnapshot) Open() (io.ReadCloser, error)

func (*RequestBodySnapshot) SHA256 

func (snapshot *RequestBodySnapshot) SHA256() [sha256.Size]byte

func (*RequestBodySnapshot) Size 

func (snapshot *RequestBodySnapshot) Size() int64

type RequestDecision 

type RequestDecision uint8
const (
	RequestContinue RequestDecision = iota
	RequestStop
)

type RequestPhasePlugin 

type RequestPhasePlugin interface {
	RunRequestPhase(http.ResponseWriter, *http.Request) RequestPhaseResult
}

type RequestPhaseResult 

type RequestPhaseResult struct {
	Request  *http.Request
	Decision RequestDecision
	Source   apisixctx.ResponseSource
}

func ContinueRequest 

func ContinueRequest(r *http.Request) RequestPhaseResult

func StopRequest 

func StopRequest(r *http.Request) RequestPhaseResult

func StopRequestWithSource 

func StopRequestWithSource(r *http.Request, source apisixctx.ResponseSource) RequestPhaseResult

type RequestResponseMode 

type RequestResponseMode uint8

RequestResponseMode is the one concrete response path selected after all request phases have prepared request-local protocol state and before the first terminal response byte is written. 

const (
	RequestResponseModeBounded RequestResponseMode = iota + 1
	RequestResponseModeStreaming
)

type RequestResponseModeSelector 

type RequestResponseModeSelector interface {
	SelectResponseMode(*http.Request) RequestResponseMode
}

RequestResponseModeSelector is required when one binding declares both a bounded and streaming response callback. Selection is request-local; a generation must never execute both callbacks for one response.

type ResponseCapture 

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

ResponseCapture is the sole outer response observer. It records outcome metadata for every response while retaining a bounded body only when a log binding explicitly enables it.

func CaptureResponseOutcomeController 

func CaptureResponseOutcomeController(w http.ResponseWriter) (http.ResponseWriter, *ResponseCapture)

CaptureResponseOutcomeController installs one response capture controller around w and returns the controller used to observe and finalize it.

func ResponseCaptureFromRequest 

func ResponseCaptureFromRequest(r *http.Request) (*ResponseCapture, bool)

func (*ResponseCapture) CloseHijacked 

func (c *ResponseCapture) CloseHijacked() error

func (*ResponseCapture) EnableBodyCapture 

func (c *ResponseCapture) EnableBodyCapture(limit int) error

func (*ResponseCapture) HTTPWireLength 

func (c *ResponseCapture) HTTPWireLength(r *http.Request) (size int64, known bool)

HTTPWireLength returns the exact buffered HTTP/1.1 response length when the outer response capture retained enough framing information to reconstruct it. Unsupported framing returns known=false.

func (*ResponseCapture) Outcome 

func (c *ResponseCapture) Outcome() ctx.ResponseOutcome

func (*ResponseCapture) RecordFailure 

func (c *ResponseCapture) RecordFailure(reason ctx.ResponseFailureReason) bool

RecordFailure attaches the first bounded transport/application failure to the final response outcome. Raw errors are deliberately excluded.

func (*ResponseCapture) Snapshot 

func (c *ResponseCapture) Snapshot() ResponseCaptureSnapshot

type ResponseCaptureSnapshot 

type ResponseCaptureSnapshot struct {
	Header        http.Header
	Trailer       http.Header
	Body          []byte
	BodyTruncated bool
}

ResponseCaptureSnapshot is the detached bounded response view used by log snapshots. Body capture is disabled until EnableBodyCapture is called.

type ResponseEligibility 

type ResponseEligibility interface {
	AppliesToResponseSource(apisixctx.ResponseSource) bool
}

type ResponseModeDescriber 

type ResponseModeDescriber interface {
	DescribeResponseMode() (ResponseModeDescriptor, error)
}

ResponseModeDescriber is implemented by config-aware plugins whose mode cannot be determined from their factory identity alone.

type ResponseModeDescriptor 

type ResponseModeDescriptor struct {
	Modes ResponseModeMask
}

type ResponseModeMask 

type ResponseModeMask uint8

ResponseModeMask describes the response modes a plugin can select after its configuration has been initialized. A mask is used because a plugin may support both bounded and streaming responses while remaining incompatible with hijacking. 

const (
	ResponseModeNone      ResponseModeMask = 0
	ResponseModeBounded   ResponseModeMask = 1 << 0
	ResponseModeStreaming ResponseModeMask = 1 << 1
	ResponseModeHijack    ResponseModeMask = 1 << 2
)

type ResponseState 

type ResponseState struct {
	Status  int
	Header  http.Header
	Trailer http.Header
	Body    []byte
}

ResponseState is the canonical response representation passed between response callbacks. Keep this deliberately limited to status, headers, trailers and body; request/lifecycle/cache state belongs to their owners.

func CloneResponseState 

func CloneResponseState(state ResponseState) ResponseState

type ScopedSecretAccess 

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

ScopedSecretAccess binds every generation/resource dimension except the declared field. Plugins can select only a field for their own factory.

func (ScopedSecretAccess) Child 

func (access ScopedSecretAccess) Child(factory string) (ScopedSecretAccess, error)

Child derives access for one composite-owned child factory without changing any other authority dimension.

func (ScopedSecretAccess) Materialize 

func (access ScopedSecretAccess) Materialize(
	ctx context.Context,
	field string,
	raw string,
) (secret.Value, error)

func (ScopedSecretAccess) SharedLimiter 

func (access ScopedSecretAccess) SharedLimiter(name string, capacity int) (secret.GenerationLimiter, error)

SharedLimiter returns a generation-owned limiter after validating the same scope used for secret materialization.

func (ScopedSecretAccess) ValidFor 

func (access ScopedSecretAccess) ValidFor(expected secret.GenerationSecrets) bool

ValidFor reports whether access and expected belong to the same generation.

type ScopedSecretMaterializer 

type ScopedSecretMaterializer interface {
	MaterializeScopedSecrets(context.Context, ScopedSecretAccess) error
}

type SnapshotFinalizerPlugin 

type SnapshotFinalizerPlugin interface {
	RunSnapshotFinalizer(LogSnapshot) error
}

type StreamingBodyFilterPlugin 

type StreamingBodyFilterPlugin interface {
	WrapStreamingResponse(http.ResponseWriter, *http.Request) (http.ResponseWriter, error)
}

type StreamingHeaderFilterPlugin 

type StreamingHeaderFilterPlugin interface {
	RunStreamingHeaderFilter(*http.Request, *StreamingResponseState) error
}

type StreamingResponseFinalizer 

type StreamingResponseFinalizer interface {
	FinishStreamingResponse(error) error
}

StreamingResponseFinalizer is optional lifecycle ownership for wrappers that retain encoder or connection state. The executor invokes it exactly once with nil on normal completion or the terminal error/panic.

type StreamingResponseState 

type StreamingResponseState struct {
	Status  int
	Header  http.Header
	Trailer http.Header
}

StreamingResponseState is the mutable response metadata handed to a streaming header phase. Trailer is kept separate from Header so a wrapper can preserve trailer declarations without treating them as ordinary fields.

func CloneStreamingResponseState 

func CloneStreamingResponseState(state StreamingResponseState) StreamingResponseState

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.