adapter

README

Olaf's Declarative Configuration

Declarative Configuration

Overview

Olaf's declarative configuration is inspired by Kong, and the configuration must be written in YAML.

For the core idea of the declarative configuration, see Kong's Declarative Configuration.

Entities

While following the same idea as Kong, Olaf's declarative configuration and the entities it contains are different in details.

The top-level entries:

Entry	Required	Description
services	√	A list of Services. Similar to Kong's Service Object.
plugins		A list of global Plugins. Default: []. Similar to Kong's Plugin Object.

The Service entity:

Attribute	Required	Description
name		The name of this Service. Default: "service_<i>" (<i> is the index of this service in the array).
upstream	√	The Upstream associated to this Service. Similar to Kong's Upstream Object.
routes	√	A list of Routes associated to this Service. Similar to Kong's Route Object.
plugins		A list of Plugins applied to this Service. Default: []. Similar to Kong's Plugin Object.

The Upstream entity:

Attribute	Required	Description
backends	√	See descriptions of reverse_proxy.upstreams.
max_requests		See descriptions of reverse_proxy.lb_policy.
dial_timeout		The duration string, which indicates how long to wait before timing out trying to connect to this Service. Default: "" (no timeout).
lb_policy		See descriptions of reverse_proxy.lb_policy.
lb_try_duration		See descriptions of reverse_proxy.lb_try_duration.
lb_try_interval		See descriptions of reverse_proxy.lb_try_interval.
health_uri		See descriptions of reverse_proxy.health_uri.
health_port		See descriptions of reverse_proxy.health_port.
health_interval		See descriptions of reverse_proxy.health_interval.
health_timeout		See descriptions of reverse_proxy.health_timeout.
health_status		See descriptions of reverse_proxy.health_status.
header_up		Set, add or remove header fields in a request going upstream to the backend (see docs). Default: {} (no header manipulation).
header_down		Set, add or remove header fields in a response coming downstream from the backend (see docs). Default: {} (no header manipulation).

The Route entity:

Attribute	Required	Description
name		The name of this Route. Default: "<service_name>_route_<i>" (<i> is the index of this route in the array).
protocol		The request protocol that matches this Route. Default: "" (any protocol).
methods		A list of HTTP methods that match this Route. Default: [] (any HTTP method).
hosts		A list of hosts that match this Route. Default: [] (any host).
paths	√	A list of URI paths that match this Route. A special prefix ~: means a regexp path.
headers		A list of headers that match this Route. Default: [] (any header).
strip_prefix		The prefix that needs to be stripped from the request path. Default: "" (no stripping).
strip_suffix		The suffix that needs to be stripped from the request path. Default: "" (no stripping).
target_path		The final path when the request is proxied to the target service (using $ as a placeholder for the request path, which may have been stripped). Default: "" (leave the request path as is, i.e. "$").
add_prefix		The prefix that needs to be added to the final path. Default: "" (no adding).
priority		The priority of this Route. Default: 0. All the services' routes will be matched from highest priority to lowest.
plugins		A list of Plugins applied to this Route. Default: []. Similar to Kong's Plugin Object.
response		The static response (see StaticResponse) for this Route, which indicates that the request will not be proxied to the target service. Default: {} (no static response).

The StaticResponse entity:

Attribute	Required	Description
status_code		The HTTP status code to respond with. Default: 200.
headers		The header fields to set on the response. Default: {} (no extra header fields).
body		The response body to respond with. Default: "" (no response body).
close		Whether to close the client's connection to the server after writing the response. Default: false.

The Plugin entity:

Attribute	Required	Description
disabled		Whether this Plugin is disabled. Default: false.
name		The name of this Plugin. Default: "plugin_<i>" for global plugins, "<service_name>_plugin_<i>" for service plugins, or "<route_name>_plugin_<i>" for route plugins (<i> is the index of this plugin in the array).
type	√	The type of this Plugin. Available plugin types: "canary" (built-in), or "request_body_var" (requires the caddy-ext/requestbodyvar extension), or "rate_limit" (requires the caddy-ext/ratelimit extension).
order_after		The order of this Plugin. Default: "" (the type of the previous Plugin, if any, in the Plugin array).
config		The configuration of this Plugin.

The Config of the Canary Plugin:

Attribute	Required	Description
upstream	√	The name of the upstream service for this Plugin.
key	√	The variable used to differentiate one client from another. Currently supported variables: "{path.*}", "{query.*}", "{header.*}", "{cookie.*}" or "{body.*}" (requires the caddy-ext/requestbodyvar extension).
type		The type of key. Default: "" (string).
whitelist	√	The whitelist defined in a CEL expression (using $ as a placeholder for the value of key). If the key value is in the whitelist, the corresponding request will be routed to the service specified by upstream.
matcher		The advanced matcher, which can consist of various Caddy matchers or your own ones. NOTE: matcher and (key, type, whitelist) are mutually exclusive.
strip_prefix		The prefix that needs to be stripped from the request path. Default: "" (no stripping).
strip_suffix		The suffix that needs to be stripped from the request path. Default: "" (no stripping).
target_path		The final path when the request is proxied to the upstream service (using $ as a placeholder for the request path, which may have been stripped). Default: "" (leave the request path as is, i.e. "$").
add_prefix		The prefix that needs to be added to the final path. Default: "" (no adding).

Example

See apis.yaml.

Embedding Olaf in Caddyfile

Serving your APIs

{
    order olaf last
}

example.com {
    olaf apis.yaml
}

Serving both a website and your APIs

{
    order olaf last
}

example.com {
    handle_path /api/* {
        olaf apis.yaml
    }

    handle {
        root * /home/user/public_html
        try_files {path} /index.html
        file_server
    }
}

Usage

Build Caddy

Install xcaddy:

$ go get -u github.com/caddyserver/xcaddy/cmd/xcaddy

Build Caddy:

$ xcaddy build \
    --with github.com/RussellLuo/olaf/caddyconfig/adapter \
    --with github.com/RussellLuo/olaf/caddymodule \
    --with github.com/RussellLuo/caddy-ext/requestbodyvar \
    --with github.com/RussellLuo/caddy-ext/ratelimit

Run Caddy

$ ./caddy run --config Caddyfile --adapter olaf

Reload Config

Don't run, just test the configuration:

$ ./caddy adapt --config Caddyfile --adapter olaf --validate > /dev/null

Reload the configuration:

$ ./caddy reload --config Caddyfile --adapter olaf

Documentation

Index

• type Adapter
  • func (Adapter) Adapt(body []byte, options map[string]interface{}) ([]byte, []caddyconfig.Warning, error)
• type Apps
• type Expander
  • func NewExpander(loader Loader) *Expander
  • func (e *Expander) Expand(config map[string]interface{}) error
• type Loader

Types

type Adapter

type Adapter struct{}

Adapter adapts Olaf's configuration to Caddy JSON.

func (Adapter) Adapt

func (Adapter) Adapt(body []byte, options map[string]interface{}) ([]byte, []caddyconfig.Warning, error)

Adapt converts the Olaf's configuration in body to Caddy JSON.

type Apps

type Apps struct {
	HTTP struct {
		Servers map[string]struct {
			Listen []string                 `json:"listen"`
			Routes []map[string]interface{} `json:"routes"`
		} `json:"servers"`
	} `json:"http"`
}

type Expander

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

func NewExpander

func NewExpander(loader Loader) *Expander

func (*Expander) Expand

func (e *Expander) Expand(config map[string]interface{}) error

Expand expands all `olaf` handlers in config. This is done by replacing each `olaf` handler with a `subroute` handler, whose routes are built by parsing the Olaf's configuration.

type Loader

type Loader interface {
	Load(mod *caddymodule.Olaf) (*olaf.Data, error)
}