dynamichandler

README

dynamichandler

A Caddy v2 extension to execute plugins (written in Go) dynamically by Yaegi.

This means plugins do not need to be pre-compiled and linked into Caddy.

Installation

$ xcaddy build --with github.com/RussellLuo/caddy-ext/dynamichandler

Caddyfile Syntax

dynamic_handler <name> {
	root <root>
	config <config>
}

Parameters:

• <name>: The plugin name (as well as the Go package name).
• <root>: The root path of the plugin code. Defaults to the directory of the Caddyfile.
  • <root> is an absolute path: <root>/<name>/<name>.go
  • <root> is a relative path: <dir_to_caddyfile>/<root>/<name>/<name>.go
• <config>: The plugin configuration in JSON format.

Example

Take the plugin visitorip as an example, with the following Caddyfile:

localhost:8080 {
	route /foo {
		dynamic_handler visitorip {
			root plugins
			config `{
				"output": "stdout"
			}`
		}
	}
}

Access the /foo endpoint:

$ curl 'https://localhost:8080/foo'

Then see the output of Caddy server:

...
127.0.0.1:55255
...

Best Practices

Using snippets to simplify Caddyfile

Directory structure:

├── Caddyfile
└── plugins
    ├── plugin1
    │   └── plugin1.go
    └── plugin2
        └── plugin2.go

Caddyfile:

(dynamic) {
	dynamic_handler {args.0} {
		root plugins
		config {args.1}
	}
}

localhost:8080 {
	route /foo {
		import dynamic plugin1 `{
			"arg1": "value1",
			"arg2": "value2"
		}`
	}

	route /bar {
		import dynamic plugin2 `` # no config
	}
}

Documentation

Index

• type DynamicHandler
  • func (DynamicHandler) CaddyModule() caddy.ModuleInfo
  • func (dh *DynamicHandler) Cleanup() error
  • func (dh *DynamicHandler) Provision(ctx caddy.Context) error
  • func (dh *DynamicHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (dh *DynamicHandler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (dh *DynamicHandler) Validate() error

Types

type DynamicHandler

type DynamicHandler struct {
	// The plugin name (as well as the Go package name).
	Name string `json:"name,omitempty"`

	// The root path of the plugin code. Defaults to the directory of the Caddyfile.
	//
	// The full path of the plugin code:
	//
	// - Root is an absolute path: `<root>/<name>/<name>.go`
	// - Root is a relative path: `<dir_to_caddyfile>/<root>/<name>/<name>.go`
	Root string `json:"root,omitempty"`

	// The plugin configuration in JSON format.
	Config string `json:"config,omitempty"`
	// contains filtered or unexported fields
}

DynamicHandler implements a handler that can execute plugins (written in Go) dynamically.

func (DynamicHandler) CaddyModule

func (DynamicHandler) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*DynamicHandler) Cleanup

func (dh *DynamicHandler) Cleanup() error

Cleanup implements caddy.CleanerUpper.

func (*DynamicHandler) Provision

func (dh *DynamicHandler) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*DynamicHandler) ServeHTTP

func (dh *DynamicHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*DynamicHandler) UnmarshalCaddyfile

func (dh *DynamicHandler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler. Syntax:

dynamic_handler <name> {
    root <root>
    config <config>
}

func (*DynamicHandler) Validate

func (dh *DynamicHandler) Validate() error

Validate implements caddy.Validator.