Documentation
¶
Index ¶
- Constants
- func WriteError(w http.ResponseWriter, code, message, requestID string, status int)
- type AggregatedResponse
- type AggregationConfig
- type CircuitBreakerConfig
- type CircuitBreakerPolicy
- type Config
- type Context
- type DashboardConfig
- type FeatureConfig
- type JSONError
- type JSONResponse
- type MetricsConfig
- type Middleware
- type MiddlewareConfig
- type Plugin
- type PluginConfig
- type PluginInfo
- type PluginType
- type Policy
- type PolicyConfig
- type RetryConfig
- type RetryPolicy
- type Route
- type RouteConfig
- type Router
- type RouterConfigSet
- type ServerConfig
- type Upstream
- type UpstreamConfig
- type UpstreamError
- type UpstreamErrorKind
- type UpstreamResponse
- type VictoriaMetricsConfig
Constants ¶
const ( ErrorCodeRateLimitExceeded = "RATE_LIMIT_EXCEEDED" ErrorCodePayloadTooLarge = "PAYLOAD_TOO_LARGE" ErrorCodeUpstreamError = "UPSTREAM_ERROR" ErrorCodeUpstreamMalformed = "UPSTREAM_MALFORMED" ErrorCodeInternal = "INTERNAL" )
const ( PluginTypeRequest = iota PluginTypeResponse )
Variables ¶
This section is empty.
Functions ¶
func WriteError ¶
func WriteError(w http.ResponseWriter, code, message, requestID string, status int)
Types ¶
type AggregatedResponse ¶
type AggregatedResponse struct {
Data json.RawMessage
Errors []JSONError
Partial bool
}
type AggregationConfig ¶
type CircuitBreakerConfig ¶
type CircuitBreakerPolicy ¶
CircuitBreakerPolicy configures a per-upstream circuit breaker, including maximum consecutive failures, and the reset timeout after which the breaker will allow attempts again.
type Config ¶
type Config struct {
ConfigVersion string `json:"config_version" yaml:"config_version" toml:"config_version" validate:"required,oneof=v1"`
Name string `json:"name" yaml:"name" toml:"name" validate:"required"`
Version string `json:"version" yaml:"version" toml:"version" validate:"required"`
Debug bool `json:"debug" yaml:"debug" toml:"debug"`
Server ServerConfig `json:"server" yaml:"server" toml:"server"`
Dashboard DashboardConfig `json:"dashboard" yaml:"dashboard" toml:"dashboard"`
Features []FeatureConfig `json:"features" yaml:"features" toml:"features"`
Middlewares []MiddlewareConfig `json:"middlewares" yaml:"middlewares" toml:"middlewares"`
Routes []RouteConfig `json:"routes" yaml:"routes" toml:"routes" validate:"min=1,dive"`
}
func LoadConfig ¶
type Context ¶
type Context interface {
Request() *http.Request
Response() *http.Response
SetRequest(req *http.Request)
SetResponse(resp *http.Response)
}
Context is the internal interface that holds the request and response objects.
type DashboardConfig ¶
type FeatureConfig ¶
type JSONResponse ¶
type JSONResponse struct {
Data json.RawMessage `json:"data,omitempty"`
Errors []JSONError `json:"errors,omitempty"`
}
JSONResponse is an output structure that wraps the final response from the gateway to the client.
type MetricsConfig ¶
type MetricsConfig struct {
Enabled bool `json:"enabled" yaml:"enabled" toml:"enabled"`
Provider string `json:"provider" yaml:"provider" toml:"provider"`
VictoriaMetrics VictoriaMetricsConfig `json:"victoria_metrics" yaml:"victoria_metrics" toml:"victoria_metrics"`
}
type Middleware ¶
type MiddlewareConfig ¶
type MiddlewareConfig struct {
Name string `json:"name" yaml:"name" toml:"name"`
Path string `json:"path,omitempty" yaml:"path,omitempty" toml:"path,omitempty"`
Config map[string]interface{} `json:"config" yaml:"config" toml:"config"`
CanFailOnLoad bool `json:"can_fail_on_load" yaml:"can_fail_on_load" toml:"can_fail_on_load"`
Override bool `json:"override" yaml:"override" toml:"override"`
}
type Plugin ¶
type Plugin interface {
Info() PluginInfo
Init(cfg map[string]interface{})
Type() PluginType
Execute(ctx Context) error
}
Plugin is an interface that describes the implementation of plugins for modifying the request or response. Any custom plugin must implement this interface.
type PluginConfig ¶
type PluginInfo ¶
type PluginType ¶
type PluginType int
type Policy ¶
type Policy struct {
AllowedStatuses []int
RequireBody bool
MapStatusCodes map[int]int
MaxResponseBodySize int64
RetryPolicy RetryPolicy
CircuitBreaker CircuitBreakerPolicy
}
Policy defines the per-upstream configuration for handling HTTP responses, retries, and fault tolerance. Each upstream can have its own Policy instance.
type PolicyConfig ¶
type PolicyConfig struct {
AllowedStatuses []int `json:"allowed_status_codes" yaml:"allowed_status_codes" toml:"allowed_status_codes"`
RequireBody bool `json:"allow_empty_body" yaml:"allow_empty_body" toml:"allow_empty_body"`
MapStatusCodes map[int]int `json:"map_status_codes" yaml:"map_status_codes" toml:"map_status_codes"`
MaxResponseBodySize int64 `json:"max_response_body_size" yaml:"max_response_body_size" toml:"max_response_body_size"`
RetryConfig RetryConfig `json:"retry" yaml:"retry" toml:"retry"`
CircuitBreakerConfig CircuitBreakerConfig `json:"circuit_breaker" yaml:"circuit_breaker" toml:"circuit_breaker"`
}
type RetryConfig ¶
type RetryPolicy ¶
RetryPolicy specifies retry behavior for an upstream, including max retries, which statuses trigger retries, and backoff delay between attempts.
type Route ¶
type Route struct {
Path string
Method string
Upstreams []Upstream
Aggregation AggregationConfig
MaxParallelUpstreams int64
Plugins []Plugin
Middlewares []Middleware
}
type RouteConfig ¶
type RouteConfig struct {
Path string `json:"path" yaml:"path" toml:"path" validate:"required"`
Method string `json:"method" yaml:"method" toml:"method" validate:"required"`
Plugins []PluginConfig `json:"plugins" yaml:"plugins" toml:"plugins"`
Middlewares []MiddlewareConfig `json:"middlewares" yaml:"middlewares" toml:"middlewares"`
Upstreams []UpstreamConfig `json:"upstreams" yaml:"upstreams" toml:"upstreams" validate:"required,min=1,dive"`
Aggregation AggregationConfig `json:"aggregation" yaml:"aggregation" toml:"aggregation"`
MaxParallelUpstreams int64 `json:"max_parallel_upstreams" yaml:"max_parallel_upstreams" toml:"max_parallel_upstreams"`
}
type Router ¶
type Router struct {
Routes []Route
// contains filtered or unexported fields
}
func (*Router) ServeHTTP ¶
func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP handles incoming HTTP requests through the full router pipeline.
The processing steps are:
1. Rate limiting (if enabled) – rejects requests exceeding allowed limits. 2. Route matching – finds a Route that matches the request method and path.
- If no route is found, responds with 404.
3. Middleware execution – wraps the route handler with all configured middlewares in reverse order. 4. Request-phase plugins – executed before upstream dispatch. Can modify the request context. 5. Upstream dispatch – sends the request to all configured upstreams via the dispatcher.
- If the dispatch fails (e.g., body too large), responds with an appropriate error. 6. Response aggregation – combines multiple upstream responses according to the route's aggregation strategy ("merge" or "array") and the allowPartialResults flag. 7. Response-phase plugins – executed after aggregation, can modify headers or the response body. 8. Response writing – writes the aggregated response, appropriate HTTP status code, and headers to the client.
Status code determination:
- 200 OK: all upstreams succeeded, no errors. - 206 Partial Content: allowPartialResults=true, at least one upstream failed. - 500 Internal Server Error: allowPartialResults=false, at least one upstream failed.
The final response always includes a JSON body with `data` and `errors` fields, and a `X-Request-ID` header.
type RouterConfigSet ¶
type RouterConfigSet struct {
Version string
Routes []RouteConfig
Middlewares []MiddlewareConfig
Features []FeatureConfig
Metrics MetricsConfig
}
type ServerConfig ¶
type ServerConfig struct {
Port int `json:"port" yaml:"port" toml:"port" validate:"required,min=1,max=65535"`
Timeout time.Duration `json:"timeout" yaml:"timeout" toml:"timeout"`
Metrics MetricsConfig `json:"metrics" yaml:"metrics" toml:"metrics"`
}
type UpstreamConfig ¶
type UpstreamConfig struct {
Name string `json:"name" yaml:"name" toml:"name"`
Hosts []string `json:"hosts" yaml:"hosts" toml:"hosts" validate:"required,hosts"`
Method string `json:"method" yaml:"method" toml:"method" validate:"required"`
Timeout time.Duration `json:"timeout" yaml:"timeout" toml:"timeout"`
ForwardHeaders []string `json:"forward_headers" yaml:"forward_headers" toml:"forward_headers"`
ForwardQueryStrings []string `json:"forward_query_strings" yaml:"forward_query_strings" toml:"forward_query_strings"`
Policy PolicyConfig `json:"policy" yaml:"policy" toml:"policy"`
}
type UpstreamError ¶
type UpstreamError struct {
Kind UpstreamErrorKind // Error kind for aggregator.
Err error // Original error. Not for client!
}
func (*UpstreamError) Error ¶
func (ue *UpstreamError) Error() string
Error returns the upstream error kind. Error kind is a custom string type, not error interface!
func (*UpstreamError) Unwrap ¶
func (ue *UpstreamError) Unwrap() error
Unwrap returns the original error.
type UpstreamErrorKind ¶
type UpstreamErrorKind string
const ( UpstreamTimeout UpstreamErrorKind = "timeout" UpstreamCanceled UpstreamErrorKind = "canceled" UpstreamConnection UpstreamErrorKind = "connection" UpstreamBadStatus UpstreamErrorKind = "bad_status" UpstreamReadError UpstreamErrorKind = "read_error" UpstreamBodyTooLarge UpstreamErrorKind = "body_too_large" UpstreamCircuitOpen UpstreamErrorKind = "circuit_open" UpstreamInternal UpstreamErrorKind = "internal" )
type UpstreamResponse ¶
type UpstreamResponse struct {
Status int
Headers http.Header
Body []byte
Err *UpstreamError
}
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
builtin
|
|
|
middlewares/auth
command
|
|
|
middlewares/compressor
command
|
|
|
middlewares/logger
command
|
|
|
middlewares/recoverer
command
|
|
|
plugins/camelify
command
|
|
|
plugins/snakeify
command
|
|
|
cmd
|
|
|
kono
command
|
|
|
internal
|
|