caddy

package module
v2.0.0-beta10 Latest Latest
Warning

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

 Go to latest Published: Nov 18, 2019 License: Apache-2.0 Imports: 31 Imported by: 1,617

README

Caddy 2 Development Branch

Build Status fuzzit

This is the development branch for Caddy 2. This code (version 2) is not yet feature-complete or production-ready, but is already being used in production, and we encourage you to deploy it today on sites that are not very visible or important so that it can obtain crucial experience in the field.

Please file issues to propose new features and report bugs, and after the bug or feature has been discussed, submit a pull request! We need your help to build this web server into what you want it to be. (Caddy 2 issues and pull requests receive priority over Caddy 1 issues and pull requests.)

Caddy 2 is the web server of the Go community. We are looking for maintainers to represent the community! Please become involved (issues, PRs, our forum etc.) and express interest if you are committed to being a collaborator on the Caddy project.

Menu

Build from source

Requirements:

Download the v2 source code:

$ git clone -b v2 "https://github.com/caddyserver/caddy.git"

Build:

$ cd caddy/cmd/caddy/
$ go build

That will put a caddy(.exe) binary into the current directory. You can move it into your PATH or use go install to do that automatically (assuming $GOPATH/bin is already in your PATH). You can also use go run main.go for quick, temporary builds while developing.

The initial build may be slow as dependencies are downloaded. Subsequent builds should be very fast. If you encounter any Go-module-related errors, try clearing your Go module cache ($GOPATH/pkg/mod) and Go package cache ($GOPATH/pkg) and read the Go wiki page about modules for help. If you have issues with Go modules, please consult the Go community for help. But if there is an actual error in Caddy, please report it to us.

Quick Start

(Until the stable 2.0 release, there may be breaking changes in v2, please be aware!)

These instructions assume an executable build of Caddy 2 is named caddy in the current folder. If it's in your PATH, you may omit the path to the binary (./).

Start Caddy:

$ ./caddy start

There are no config files with Caddy 2. Instead, you POST configuration to it:

$ curl -X POST "http://localhost:2019/load" \
    -H "Content-Type: application/json" \
    -d @- << EOF
    {
        "apps": {
            "http": {
                "servers": {
                    "example": {
                        "listen": ["127.0.0.1:2080"],
                        "routes": [
                            {
                                "handle": [{
                                    "handler": "file_server",
                                    "browse": {}
                                }]
                            }
                        ]
                    }
                }
            }
        }
    }
EOF

Now visit http://localhost:2080 in your browser and you will see the contents of the current directory displayed.

To change Caddy's configuration, simply POST a new payload to that endpoint. Config changes are extremely lightweight and efficient, and should be graceful on all platforms -- even Windows.

Updating configuration using heredoc can be tedious, so you can still use a config file if you prefer. Put your configuration in any file (caddy.json for example) and then POST that instead:

$ curl -X POST "http://localhost:2019/load" \
    -H "Content-Type: application/json" \
    -d @caddy.json

Or you can tell Caddy to load its configuration from a file in the first place (this simply does the work of the above curl command for you):

$ ./caddy start --config caddy.json

To stop Caddy:

$ ./caddy stop

Note that this will stop any process named the same as os.Args[0].

For other commands, please see the Caddy 2 documentation.

Caddyfile

Caddy 2 can be configured with a Caddyfile, much like in v1, for example:

example.com

try_files {path}.html {path}
encode gzip zstd
reverse_proxy /api  localhost:9005
php_fastcgi   /blog unix//path/to/socket
file_server

Instead of being its primary mode of configuration, an internal config adapter adapts the Caddyfile to Caddy's native JSON structure. You can see it in action with the adapt command:

$ ./caddy adapt --config path/to/Caddyfile --adapter caddyfile --pretty

If you just want to run Caddy with your Caddyfile directly, the CLI wraps this up for you nicely. Either of the following commands:

$ ./caddy start
$ ./caddy run

will use your Caddyfile if it is called Caddyfile in the current directory.

If your Caddyfile is somewhere else, you can still use it:

$ ./caddy start|run --config path/to/Caddyfile --adapter caddyfile

Learn more about the Caddyfile in v2.

Configuration

Caddy 2 exposes an unprecedented level of control compared to any web server in existence. In Caddy 2, you are usually setting the actual values of the initialized types in memory that power everything from your HTTP handlers and TLS handshakes to your storage medium. Caddy 2 is also ridiculously extensible, with a module system that makes vast improvements over Caddy 1's plugin system.

Nearly all of Caddy 2's configuration is contained in a single config document, rather than being spread across CLI flags and env variables and a configuration file as with other web servers (and Caddy 1).

To wield the power of this design, you need to know how the config document is structured. Please see the the Caddy 2 documentation in our wiki for details about Caddy's config structure.

Configuration is normally given to Caddy through an API endpoint, which is likewise documented in the wiki pages. However, you can also use config files of various formats with config adapters.

Full Documentation

Caddy 2 is very much in development, so the documentation is an ongoing WIP, but the latest will be in our wiki for now:

https://github.com/caddyserver/caddy/wiki/v2:-Documentation

Note that breaking changes are expected until the stable 2.0 release.

List of Improvements

The following is a non-comprehensive list of significant improvements over Caddy 1. Not everything in this list is finished yet, but they will be finished or at least will be possible with Caddy 2:

  • Centralized configuration. No more disparate use of environment variables, config files (potentially multiple!), CLI flags, etc.
  • REST API. Control Caddy with HTTP requests to an administration endpoint. Changes are applied immediately and efficiently.
  • Dynamic configuration. Any and all specific config values can be modified directly through the admin API with a REST endpoint.
    • Change only specific configuration settings instead of needing to specify the whole config each time. This makes it safe and easy to change Caddy's config with manually-crafted curl commands, for example.
  • No configuration files. Except optionally to bootstrap its configuration at startup. You can still use config files if you wish, and we expect that most people will.
  • Export the current Caddy configuration with an API GET request.
  • Silky-smooth graceful reloads. Update the configuration up to dozens of times per second with no dropped requests and very little memory cost. Our unique graceful reload technology is lighter and faster and works on all platforms, including Windows.
  • An embedded scripting language! Caddy2 has native Starlark integration. Do things you never thought possible with higher performance than Lua, JavaScript, and other VMs. Starlark is expressive, familiar (dialect of Python), almost Turing-complete, and highly efficient. (We're still improving performance here.)
  • Using XDG standards instead of dumping all assets in $HOME/.caddy.
  • Caddy plugins are now called "Caddy modules" (although the terms "plugin" and "module" may be used interchangably). Caddy modules are a concept unrelated Go modules, except that Caddy modules may be implemented by Go modules. Caddy modules are centrally-registered, properly namespaced, and generically loaded & configured, as opposed to how scattered and unorganized Caddy 1-era plugins are.
  • Modules are easier to write, since they do not have to both deserialize their own configuration from a configuration DSL and provision themselves like plugins did. Modules are initialized pre-configured and have the ability to validate the configuration and perform provisioning steps if necessary.
  • Can specify different storage mechanisms in different parts of the configuration, if more than one is needed.
  • "Top-level" Caddy modules are simply called "apps" because literally any long-lived application can be served by Caddy 2.
  • Even more of Caddy is made of modules, allowing for unparalleled extensibility, flexibility, and control. Caddy 2 is arguably the most flexible, extensible, programmable web server ever made.
  • TLS improvements!
    • TLS configuration is now centralized and decoupled from specific sites
    • A single certificate cache is used process-wide, reducing duplication and improving memory use
    • Customize how to manage each certificate ("automation policies") based on the hostname
    • Automation policy doesn't have to be limited to just ACME - could be any way to manage certificates
    • Fine-grained control over TLS handshakes
    • If an ACME challenge fails, other enabled challenges will be tried (no other web server does this)
    • TLS Session Ticket Ephemeral Keys (STEKs) can be rotated in a cluster for increased performance (no other web server does this either!)
    • Ability to select a specific certificate per ClientHello given multiple qualifying certificates
    • Provide TLS certificates without persisting them to disk; keep private keys entirely in memory
    • Certificate management at startup is now asynchronous and much easier to use through machine reboots and in unsupervised settings
  • All-new HTTP server core
    • Listeners can be configured for any network type, address, and port range
    • Customizable TLS connection policies
    • HTTP handlers are configured by "routes" which consist of matcher and handler components. Match matches an HTTP request, and handle defines the list of handlers to invoke as a result of the match.
    • Some matchers are regular expressions, which expose capture groups to placeholders.
    • New matchers include negation and matching based on remote IP address / CIDR ranges.
    • Placeholders are vastly improved generally
    • Placeholders (variables) are more properly namespaced.
    • Multiple routes may match an HTTP request, creating a "composite route" quickly on the fly.
    • The actual handler for any given request is its composite route.
    • User defines the order of middlewares (careful! easy to break things).
    • Adding middlewares no longer requires changes to Caddy's code base (there is no authoritative list).
    • Routes may be marked as terminal, meaning no more routes will be matched.
    • Routes may be grouped so that only the first matching route in a group is applied.
    • Requests may be "re-handled" if they are modified and need to be sent through the chain again (internal redirect).
    • Vastly more powerful static file server, with native content-negotiation abilities
    • Done away with URL-rewriting hacks often needed in Caddy 1
    • Highly descriptive/traceable errors
    • Very flexible error handling, with the ability to specify a whole list of routes just for error cases
    • The proxy has numerous improvements, including dynamic backends and more configurable health checks
    • FastCGI support integrated with the reverse proxy
    • More control over automatic HTTPS: disable entirely, disable only HTTP->HTTPS redirects, disable only cert management, and for certain names, etc.
    • Use Starlark to build custom, dynamic HTTP handlers at request-time
      • We are finding that -- on average -- Caddy 2's Starlark handlers are ~1.25-2x faster than NGINX+Lua.

And a few major features still being worked on:

  • Logging
  • Kubernetes ingress controller (mostly done, just polishing it -- and it's amazing)
  • More config adapters. Caddy's native JSON config structure is powerful and complex. Config adapters upsample various formats to Caddy's native config. There are already adapters for Caddyfile, JSON 5, and JSON-C. Planned are NGINX config, YAML, and TOML. The community might be interested in building Traefik and Apache config adapters!

FAQ

How do I configure Caddy 2?

Caddy's primary mode of configuration is a REST API, which accepts a JSON document. The JSON structure is described in the wiki. The advantages of exposing this low-level structure are 1) it has near-parity with actual memory initialization, 2) it allows us to offer wrappers over this configuration to any degree of convenience that is needed, and 3) it performs very well under rapid config changes.

Basically, you will start Caddy, then POST a JSON config to its API endpoint.

Although this makes Caddy 2 highly programmable, not everyone will want to configure Caddy via JSON with an API. Sometimes we just want to give Caddy a simple, static config file and have it do its thing. That's what config adapters are for! You can configure Caddy more ways than one, depending on your needs and preferences. See the next questions that explain this more.

Caddy 2 feels harder to use. How is this an improvement over Caddy 1?

Caddy's ease of use is one of the main reasons it is special. We are not taking that away in Caddy 2, but first we had to be sure to tackle the fundamental design limitations with Caddy 1. Usability can then be layered on top. This approach has several advantages which we discuss in the next question.

What about the Caddyfile; are there easier ways to configure Caddy 2?

Yes! Caddy's native JSON configuration via API is nice when you are automating config changes at scale, but if you just have a simple, static configuration in a file, you can do that too with the Caddyfile.

The v2 Caddyfile is very similar to the v1 Caddyfile, but they are not compatible. Several improvements have been made to request matching and directives in v2, giving you more power with less complexity and fewer inconsistencies.

Caddy's default config adapter is the Caddyfile adapter. This takes a Caddyfile as input and outputs the JSON config. You can even run Caddy directly without having to see or think about the underlying JSON config.

The following config adapters are already being built or plan to be built:

  • Caddyfile
  • JSON 5
  • JSON-C
  • nginx
  • YAML
  • TOML
  • any others that the community would like to contribute

Config adapters allow you to configure Caddy not just one way but any of these ways. For example, you'll be able to bring your existing NGINX config to Caddy and it will spit out the Caddy config JSON you need (to the best of its ability). How cool is that! You can then easily tweak the resulting config by hand, if necessary.

All config adapters vary in their theoretical expressiveness; that is, if you need more advanced configuration you'll have to drop down to the JSON config, because the Caddyfile or an nginx config may not be expressive enough.

However, we expect that most users will be able to use the Caddyfile (or another easy config adapter) exclusively for their sites.

Why JSON for configuration? Why not <any other serialization format>?

We know there might be strong opinions on this one. Regardless, for Caddy 2, we've decided to go with JSON. If that proves to be a fatal mistake, then Caddy 3 probably won't use JSON.

JSON may not be the fastest, the most compact, the easiest to write, serialization format that exists. But those aren't our goals. It has withstood the test of time and checks all our boxes.

  • It is almost entirely ubiquitous. JSON works natively in web browsers and has mature libraries in pretty much every language.
  • It is human-readable (as opposed to a binary format).
  • It is easy to tweak by hand. Although composing raw JSON by hand is not awesome, this will not be mainstream once our config adapters are done.
  • It is generally easy to convert other serializations or config formats into JSON, as opposed to the other way around.
  • Even though JSON deserialization is not fast per-se, that kind of performance is not really a concern since config reloads are not the server's hottest path like HTTP request handling or TLS handshakes are. Even with JSON, Caddy 2 can handle dozens of config changes per second, which is probably plenty for now.
  • It maps almost 1:1 to the actual, in-memory values that power your HTTP handlers and other parts of the server (no need to parse a config file with some arbitrary DSL and do a bunch of extra pre-processing).

Ultimately, we think all these properties are appropriate -- if not ideal -- for a web server configuration.

If you're still not happy with the choice of JSON, feel free to contribute a config adapter of your own choice!

Or just use YAML or TOML, which seamlessly translate to JSON.

JSON is declarative; what if I need more programmability (i.e. imperative syntax)?

NGINX also realized the need for imperative logic in declarative configs, so they tried "if" statements, but it was a bad idea.

We have good news. Caddy 2 can give you the power of imperative logic without the perils of mixing declarative and imperative config such as befell NGINX. We do this by allowing embedded imperative syntax awithin the Caddy's declarative config.

Caddy 2's configuration is declarative because configuration is very much declarative in nature. Configuration is a tricky medium, as it is read and written by both computers and humans. Computers use it, but humans constantly refer to it and update it. Declarative syntaxes are fairly straightforward to make sense of, whereas it is difficult to reason about imperative logic.

However, sometimes computation is useful, and in some cases, the only way to express what you need. This can be illustrated really well in the simple case of trying to decide whether a particular HTTP middleware should be invoked as part of an HTTP request. A lot of the time, such logic is as simple as: "GET requests for any path starting with /foo/bar", which can be expressed declaratively in JSON:

{
	"method": "GET",
	"path": "/foo/bar"
}

But what if you need to match /foo/bar OR /topaz? How do you express that OR clause? Maybe an array:

{
	"method": ["GET"],
	"path": ["/foo/bar", "/topaz"]
}

Now what if you need add a NOT or AND clause? JSON quickly tires out. As you learn about Caddy 2's request matching, you will see how we handled this. Caddy 2's JSON gives you the ability to express moderately-complex logic such as:

// this is not actual Caddy config, just logic pseudocode
IF (Host = "example.com")
	OR (Host = "sub.example.com" AND Path != "/foo/bar")

Already, this is more expressive power than most web servers offer with their native config, yet Caddy 2 offers this in JSON.

But in most web servers, to make logic this complex feasible, you'll generally call out to Lua or some extra DSL. For example, in NGINX you could use a Lua module to express this logic. Traefik 2.0 has yet another kind of clunky-looking custom DSL just for this.

Caddy 2 solves this in a novel way with Starlark expressions. Starlark is a familiar dialect of Python! So, no new DSLs to learn and no VMs to slow things down:

req.host == 'example.com' ||
	(req.host == 'sub.example.com' && req.path != '/foo/bar')

Starlark performs at least as well as NGINX+Lua (more performance tests ongoing, as well as optimizations to make it even faster!) and because it's basically Python, it's familiar and easy to use.

In summary: Caddy 2 config is declarative, but can be imperative where that is useful.

What is Caddy 2 licensed as?

Caddy 2 is licensed under the Apache 2.0 open source license. There are no official Caddy 2 distributions that are proprietary.

Does Caddy 2 have telemetry?

No. There was not enough academic interest to continue supporting it. If telemetry does get added later, it will not be on by default or will be vastly reduced in its scope.

Does Caddy 2 use HTTPS by default?

Yes. HTTPS is automatic and enabled by default when possible, just like in Caddy 1. Basically, if your HTTP routes specify a host matcher with qualifying domain names, those names will be enabled for automatic HTTPS. Automatic HTTPS is disabled for domains which match certificates that are manually loaded by your config.

How do I avoid Let's Encrypt rate limits with Caddy 2?

As you are testing and developing with Caddy 2, you should use test ("staging") certificates from Let's Encrypt to avoid rate limits. By default, Caddy 2 uses Let's Encrypt's production endpoint to get real certificates for your domains, but their rate limits forbid testing and development use of this endpoint for good reasons. You can switch to their staging endpoint by adding the staging CA to your automation policy in the tls app:

"tls": {
	"automation": {
		"policies": [
			{
				"management": {
					"module": "acme",
					"ca": "https://acme-staging-v02.api.letsencrypt.org/directory"
				}
			}
		]
	}
}

Or with the Caddyfile, using a global options block at the top:

{
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

Can we get some access controls on the admin endpoint?

Yeah, that's coming. For now, you can use a permissioned unix socket for some basic security.

Documentation

Index

Constants

View Source 
const (
	ExitCodeSuccess = iota
	ExitCodeFailedStartup
	ExitCodeForceQuit
	ExitCodeFailedQuit
)

Exit codes. Generally, you should NOT automatically restart the process if the exit code is ExitCodeFailedStartup (1).

Variables

View Source 
var (
	// DefaultAdminListen is the address for the admin
	// listener, if none is specified at startup.
	DefaultAdminListen = "localhost:2019"

	// ErrInternalRedir indicates an internal redirect
	// and is useful when admin API handlers rewrite
	// the request; in that case, authentication and
	// authorization needs to happen again for the
	// rewritten request.
	ErrInternalRedir = fmt.Errorf("internal redirect; re-authorization required")

	// DefaultAdminConfig is the default configuration
	// for the administration endpoint.
	DefaultAdminConfig = &AdminConfig{
		Listen: DefaultAdminListen,
	}
)

Functions

func GetModuleID 

func GetModuleID(instance interface{}) string

GetModuleID returns a module's ID (the last element of its name) from an instance of its value. If the value is not a module, an empty string will be returned.

func GetModuleName 

func GetModuleName(instance interface{}) string

GetModuleName returns a module's name from an instance of its value. If the value is not a module, an empty name will be returned.

func GoModule 

func GoModule() *debug.Module

GoModule returns the build info of this Caddy build from debug.BuildInfo (requires Go modules). If no version information is available, a non-nil value will still be returned, but with an unknown version.

func JoinNetworkAddress 

func JoinNetworkAddress(network, host, port string) string

JoinNetworkAddress combines network, host, and port into a single address string of the form accepted by ParseNetworkAddress(). For unix sockets, the network should be "unix" and the path to the socket should be given as the host parameter.

func Listen 

func Listen(network, addr string) (net.Listener, error)

Listen returns a listener suitable for use in a Caddy module. Always be sure to close listeners when you are done with them.

func ListenPacket 

func ListenPacket(network, addr string) (net.PacketConn, error)

ListenPacket returns a net.PacketConn suitable for use in a Caddy module. Always be sure to close the PacketConn when you are done.

func Load 

func Load(cfgJSON []byte, forceReload bool) error

Load loads the given config JSON and runs it only if it is different from the current config or forceReload is true.

func Log 

func Log() *zap.Logger

Log returns the current default logger.

func Modules 

func Modules() []string

Modules returns the names of all registered modules in ascending lexicographical order.

func RegisterModule 

func RegisterModule(instance Module) error

RegisterModule registers a module by receiving a plain/empty value of the module. For registration to be properly recorded, this should be called in the init phase of runtime. Typically, the module package will do this as a side-effect of being imported. This function returns an error if the module's info is incomplete or invalid, or if the module is already registered.

func Run 

func Run(cfg *Config) error

Run runs the given config, replacing any existing config.

func SplitNetworkAddress 

func SplitNetworkAddress(a string) (network, host, port string, err error)

SplitNetworkAddress splits a into its network, host, and port components. Note that port may be a port range (:X-Y), or omitted for unix sockets.

func Stop 

func Stop() error

Stop stops running the current configuration. It is the antithesis of Run(). This function will log any errors that occur during the stopping of individual apps and continue to stop the others. Stop should only be called if not replacing with a new config.

func TrapSignals 

func TrapSignals()

TrapSignals create signal/interrupt handlers as best it can for the current OS. This is a rather invasive function to call in a Go program that captures signals already, so in that case it would be better to implement these handlers yourself.

func Validate 

func Validate(cfg *Config) error

Validate loads, provisions, and validates cfg, but does not start running it.

Types

type APIError 

type APIError struct {
	Code    int    `json:"-"`
	Err     error  `json:"-"`
	Message string `json:"error"`
}

APIError is a structured error that every API handler should return for consistency in logging and client responses. If Message is unset, then Err.Error() will be serialized in its place.

func (APIError) Error 

func (e APIError) Error() string

type AdminConfig 

type AdminConfig struct {
	Disabled      bool     `json:"disabled,omitempty"`
	Listen        string   `json:"listen,omitempty"`
	EnforceOrigin bool     `json:"enforce_origin,omitempty"`
	Origins       []string `json:"origins,omitempty"`
}

AdminConfig configures the admin endpoint.

type AdminHandler 

type AdminHandler interface {
	ServeHTTP(http.ResponseWriter, *http.Request) error
}

AdminHandler is like http.Handler except ServeHTTP may return an error.

If any handler encounters an error, it should be returned for proper handling.

type AdminHandlerFunc 

type AdminHandlerFunc func(http.ResponseWriter, *http.Request) error

AdminHandlerFunc is a convenience type like http.HandlerFunc.

func (AdminHandlerFunc) ServeHTTP 

func (f AdminHandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) error

ServeHTTP implements the Handler interface.

type AdminRoute 

type AdminRoute struct {
	Pattern string
	Handler AdminHandler
}

AdminRoute represents a route for the admin endpoint.

type AdminRouter 

type AdminRouter interface {
	Routes() []AdminRoute
}

AdminRouter is a type which can return routes for the admin API.

type App 

type App interface {
	Start() error
	Stop() error
}

App is a thing that Caddy runs.

type CleanerUpper 

type CleanerUpper interface {
	Cleanup() error
}

CleanerUpper is implemented by modules which may have side-effects such as opened files, spawned goroutines, or allocated some sort of non-stack state when they were provisioned. This method should deallocate/cleanup those resources to prevent memory leaks. Cleanup should be fast and efficient. Cleanup should work even if Provision returns an error, to allow cleaning up from partial provisionings.

type Config 

type Config struct {
	Admin      *AdminConfig               `json:"admin,omitempty"`
	Logging    *Logging                   `json:"logging,omitempty"`
	StorageRaw json.RawMessage            `json:"storage,omitempty"`
	AppsRaw    map[string]json.RawMessage `json:"apps,omitempty"`
	// contains filtered or unexported fields
}

Config represents a Caddy configuration. It is the top of the module structure: all Caddy modules will be loaded, starting with this struct. In order to be loaded and run successfully, a Config and all its modules must be JSON-encodable; i.e. when filling a Config struct manually, its JSON-encodable fields (the ones with JSON struct tags, usually ending with "Raw" if they decode into a separate field) must be set so that they can be unmarshaled and provisioned. Setting the fields for the decoded values instead will result in those values being overwritten at unmarshaling/provisioning.

type Constructor 

type Constructor func() (Destructor, error)

Constructor is a function that returns a new value that can destruct itself when it is no longer needed.

type Context 

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

Context is a type which defines the lifetime of modules that are loaded and provides access to the parent configuration that spawned the modules which are loaded. It should be used with care and wrapped with derivation functions from the standard context package only if you don't need the Caddy specific features. These contexts are cancelled when the lifetime of the modules loaded from it is over.

Use NewContext() to get a valid value (but most modules will not actually need to do this).

func NewContext 

func NewContext(ctx Context) (Context, context.CancelFunc)

NewContext provides a new context derived from the given context ctx. Normally, you will not need to call this function unless you are loading modules which have a different lifespan than the ones for the context the module was provisioned with. Be sure to call the cancel func when the context is to be cleaned up so that modules which are loaded will be properly unloaded. See standard library context package's documentation.

func (Context) App 

func (ctx Context) App(name string) (interface{}, error)

App returns the configured app named name. If no app with that name is currently configured, a new empty one will be instantiated. (The app module must still be registered.)

func (Context) LoadModule 

func (ctx Context) LoadModule(name string, rawMsg json.RawMessage) (interface{}, error)

LoadModule decodes rawMsg into a new instance of mod and returns the value. If mod.New() does not return a pointer value, it is converted to one so that it is unmarshaled into the underlying concrete type. If mod.New is nil, an error is returned. If the module implements Validator or Provisioner interfaces, those methods are invoked to ensure the module is fully configured and valid before being used.

func (Context) LoadModuleInline 

func (ctx Context) LoadModuleInline(moduleNameKey, moduleScope string, raw json.RawMessage) (interface{}, error)

LoadModuleInline loads a module from a JSON raw message which decodes to a map[string]interface{}, where one of the keys is moduleNameKey and the corresponding value is the module name as a string, which can be found in the given scope.

This allows modules to be decoded into their concrete types and used when their names cannot be the unique key in a map, such as when there are multiple instances in the map or it appears in an array (where there are no custom keys). In other words, the key containing the module name is treated special/separate from all the other keys.

func (Context) Logger 

func (ctx Context) Logger(mod Module) *zap.Logger

Logger returns a logger that can be used by mod.

func (*Context) OnCancel 

func (ctx *Context) OnCancel(f func())

OnCancel executes f when ctx is cancelled.

func (Context) Storage 

func (ctx Context) Storage() certmagic.Storage

Storage returns the configured Caddy storage implementation.

type CtxKey 

type CtxKey string

CtxKey is a value type for use with context.WithValue. 

const ReplacerCtxKey CtxKey = "replacer"

ReplacerCtxKey is the context key for a replacer.

type CustomLog 

type CustomLog struct {
	WriterRaw  json.RawMessage `json:"writer,omitempty"`
	EncoderRaw json.RawMessage `json:"encoder,omitempty"`
	Level      string          `json:"level,omitempty"`
	Sampling   *LogSampling    `json:"sampling,omitempty"`
	Include    []string        `json:"include,omitempty"`
	Exclude    []string        `json:"exclude,omitempty"`
	// contains filtered or unexported fields
}

CustomLog represents a custom logger configuration.

type Destructor 

type Destructor interface {
	Destruct() error
}

Destructor is a value that can clean itself up when it is deallocated.

type DiscardWriter 

type DiscardWriter struct{}

DiscardWriter discards all writes.

func (DiscardWriter) CaddyModule 

func (DiscardWriter) CaddyModule() ModuleInfo

CaddyModule returns the Caddy module information.

func (DiscardWriter) OpenWriter 

func (DiscardWriter) OpenWriter() (io.WriteCloser, error)

OpenWriter returns ioutil.Discard that can't be closed.

func (DiscardWriter) String 

func (DiscardWriter) String() string

func (DiscardWriter) WriterKey 

func (DiscardWriter) WriterKey() string

WriterKey returns a unique key representing discard.

type Duration 

type Duration time.Duration

Duration is a JSON-string-unmarshable duration type.

func (*Duration) UnmarshalJSON 

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies json.Unmarshaler.

type LogSampling 

type LogSampling struct {
	Interval   time.Duration `json:"interval,omitempty"`
	First      int           `json:"first,omitempty"`
	Thereafter int           `json:"thereafter,omitempty"`
}

LogSampling configures log entry sampling.

type Logging 

type Logging struct {
	Sink *StandardLibLog       `json:"sink,omitempty"`
	Logs map[string]*CustomLog `json:"logs,omitempty"`
	// contains filtered or unexported fields
}

Logging facilitates logging within Caddy.

func (*Logging) Logger 

func (logging *Logging) Logger(mod Module) *zap.Logger

Logger returns a logger that is ready for the module to use.

type Module 

type Module interface {
	// This method indicates the type is a Caddy
	// module. The returned ModuleInfo must have
	// both a name and a constructor function.
	// This method must not have any side-effects.
	CaddyModule() ModuleInfo
}

Module is a type that is used as a Caddy module.

type ModuleInfo 

type ModuleInfo struct {
	// Name is the full name of the module. It
	// must be unique and properly namespaced.
	Name string

	// New returns a pointer to a new, empty
	// instance of the module's type. The host
	// module which instantiates this module will
	// likely type-assert and invoke methods on
	// the returned value. This function must not
	// have any side-effects.
	New func() Module
}

ModuleInfo represents a registered Caddy module.

func GetModule 

func GetModule(name string) (ModuleInfo, error)

GetModule returns module information from its full name.

func GetModules 

func GetModules(scope string) []ModuleInfo

GetModules returns all modules in the given scope/namespace. For example, a scope of "foo" returns modules named "foo.bar", "foo.loo", but not "bar", "foo.bar.loo", etc. An empty scope returns top-level modules, for example "foo" or "bar". Partial scopes are not matched (i.e. scope "foo.ba" does not match name "foo.bar").

Because modules are registered to a map, the returned slice will be sorted to keep it deterministic.

func (ModuleInfo) ID 

func (mi ModuleInfo) ID() string

ID returns a module's ID, which is the last element of its name.

func (ModuleInfo) Namespace 

func (mi ModuleInfo) Namespace() string

Namespace returns the module's namespace (scope) which is all but the last element of its name. If there is no explicit namespace in the name, the whole name is considered the namespace.

func (ModuleInfo) String 

func (mi ModuleInfo) String() string

type ParsedAddress 

type ParsedAddress struct {
	Network   string
	Host      string
	StartPort uint
	EndPort   uint
}

ParsedAddress contains the individual components for a parsed network address of the form accepted by ParseNetworkAddress(). Network should be a network value accepted by Go's net package. Port ranges are given by [StartPort, EndPort].

func ParseNetworkAddress 

func ParseNetworkAddress(addr string) (ParsedAddress, error)

ParseNetworkAddress parses addr into its individual components. The input string is expected to be of the form "network/host:port-range" where any part is optional. The default network, if unspecified, is tcp. Port ranges are inclusive.

Network addresses are distinct from URLs and do not use URL syntax.

func (ParsedAddress) JoinHostPort 

func (pa ParsedAddress) JoinHostPort(offset uint) string

JoinHostPort is like net.JoinHostPort, but where the port is StartPort + offset.

func (ParsedAddress) PortRangeSize 

func (pa ParsedAddress) PortRangeSize() uint

PortRangeSize returns how many ports are in pa's port range. Port ranges are inclusive, so the size is the difference of start and end ports plus one.

func (ParsedAddress) String 

func (pa ParsedAddress) String() string

String reconstructs the address string to the form expected by ParseNetworkAddress().

type Provisioner 

type Provisioner interface {
	Provision(Context) error
}

Provisioner is implemented by modules which may need to perform some additional "setup" steps immediately after being loaded. Provisioning should be fast (imperceptible running time). If any side-effects result in the execution of this function (e.g. creating global state, any other allocations which require garbage collection, opening files, starting goroutines etc.), be sure to clean up properly by implementing the CleanerUpper interface to avoid leaking resources.

type ReplacementFunc 

type ReplacementFunc func(key string) (val string, ok bool)

ReplacementFunc is a function that returns a replacement for the given key along with true if the function is able to service that key (even if the value is blank). If the function does not recognize the key, false should be returned.

type Replacer 

type Replacer interface {
	Set(variable, value string)
	Delete(variable string)
	Map(ReplacementFunc)
	ReplaceAll(input, empty string) string
	ReplaceKnown(input, empty string) string
	ReplaceOrErr(input string, errOnEmpty, errOnUnknown bool) (string, error)
}

Replacer can replace values in strings.

func NewReplacer 

func NewReplacer() Replacer

NewReplacer returns a new Replacer.

type StandardLibLog 

type StandardLibLog struct {
	WriterRaw json.RawMessage `json:"writer,omitempty"`
	// contains filtered or unexported fields
}

StandardLibLog configures the default Go standard library global logger in the log package. This is necessary because module dependencies which are not built specifically for Caddy will use the standard logger.

type StderrWriter 

type StderrWriter struct{}

StderrWriter can write logs to stdout.

func (StderrWriter) CaddyModule 

func (StderrWriter) CaddyModule() ModuleInfo

CaddyModule returns the Caddy module information.

func (StderrWriter) OpenWriter 

func (StderrWriter) OpenWriter() (io.WriteCloser, error)

OpenWriter returns os.Stderr that can't be closed.

func (StderrWriter) String 

func (StderrWriter) String() string

func (StderrWriter) WriterKey 

func (StderrWriter) WriterKey() string

WriterKey returns a unique key representing stderr.

type StdoutWriter 

type StdoutWriter struct{}

StdoutWriter can write logs to stdout.

func (StdoutWriter) CaddyModule 

func (StdoutWriter) CaddyModule() ModuleInfo

CaddyModule returns the Caddy module information.

func (StdoutWriter) OpenWriter 

func (StdoutWriter) OpenWriter() (io.WriteCloser, error)

OpenWriter returns os.Stdout that can't be closed.

func (StdoutWriter) String 

func (StdoutWriter) String() string

func (StdoutWriter) WriterKey 

func (StdoutWriter) WriterKey() string

WriterKey returns a unique key representing stdout.

type StorageConverter 

type StorageConverter interface {
	CertMagicStorage() (certmagic.Storage, error)
}

StorageConverter is a type that can convert itself to a valid, usable certmagic.Storage value. (The value might be short-lived.) This interface allows us to adapt any CertMagic storage implementation into a consistent API for Caddy configuration.

type UsagePool 

type UsagePool struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

UsagePool is a thread-safe map that pools values based on usage (reference counting). Values are only inserted if they do not already exist. There are two ways to add values to the pool:

  1. LoadOrStore will increment usage and store the value immediately if it does not already exist.
  2. LoadOrNew will atomically check for existence and construct the value immediately if it does not already exist, or increment the usage otherwise, then store that value in the pool. When the constructed value is finally deleted from the pool (when its usage reaches 0), it will be cleaned up by calling Destruct().

The use of LoadOrNew allows values to be created and reused and finally cleaned up only once, even though they may have many references throughout their lifespan. This is helpful, for example, when sharing thread-safe io.Writers that you only want to open and close once.

There is no way to overwrite existing keys in the pool without first deleting it as many times as it was stored. Deleting too many times will panic.

The implementation does not use a sync.Pool because UsagePool needs additional atomicity to run the constructor functions when creating a new value when LoadOrNew is used. (We could probably use sync.Pool but we'd still have to layer our own additional locks on top.)

An empty UsagePool is NOT safe to use; always call NewUsagePool() to make a new one.

func NewUsagePool 

func NewUsagePool() *UsagePool

NewUsagePool returns a new usage pool that is ready to use.

func (*UsagePool) Delete 

func (up *UsagePool) Delete(key interface{}) (deleted bool, err error)

Delete decrements the usage count for key and removes the value from the underlying map if the usage is 0. It returns true if the usage count reached 0 and the value was deleted. It panics if the usage count drops below 0; always call Delete precisely as many times as LoadOrStore.

func (*UsagePool) LoadOrNew 

func (up *UsagePool) LoadOrNew(key interface{}, construct Constructor) (value interface{}, loaded bool, err error)

LoadOrNew loads the value associated with key from the pool if it already exists. If the key doesn't exist, it will call construct to create a new value and then stores that in the pool. An error is only returned if the constructor returns an error. The loaded or constructed value is returned. The loaded return value is true if the value already existed and was loaded, or false if it was newly constructed.

func (*UsagePool) LoadOrStore 

func (up *UsagePool) LoadOrStore(key, val interface{}) (value interface{}, loaded bool)

LoadOrStore loads the value associated with key from the pool if it already exists, or stores it if it does not exist. It returns the value that was either loaded or stored, and true if the value already existed and was

func (*UsagePool) Range 

func (up *UsagePool) Range(f func(key, value interface{}) bool)

Range iterates the pool similarly to how sync.Map.Range() does: it calls f for every key in the pool, and if f returns false, iteration is stopped. Ranging does not affect usage counts.

This method is somewhat naive and acquires a read lock on the entire pool during iteration, so do your best to make f() really fast, m'kay?

type Validator 

type Validator interface {
	Validate() error
}

Validator is implemented by modules which can verify that their configurations are valid. This method will be called after Provision() (if implemented). Validation should always be fast (imperceptible running time) and an error should be returned only if the value's configuration is invalid.

type WriterOpener 

type WriterOpener interface {
	fmt.Stringer

	// WriterKey is a string that uniquely identifies this
	// writer configuration. It is not shown to humans.
	WriterKey() string

	// OpenWriter opens a log for writing. The writer
	// should be safe for concurrent use but need not
	// be synchronous.
	OpenWriter() (io.WriteCloser, error)
}

WriterOpener is a module that can open a log writer. It can return a human-readable string representation of itself so that operators can understand where the logs are going.

Source Files

View all Source files

Directories

Path Synopsis
caddyfile
httpcaddyfile
json5
jsonc
cmd
caddy
Package main is the entry point of the Caddy application.
 Package main is the entry point of the Caddy application.
modules
caddyhttp
caddyhttp/caddyauth
caddyhttp/encode
Package encode implements an encoder middleware for Caddy.
 Package encode implements an encoder middleware for Caddy.
caddyhttp/encode/brotli
caddyhttp/encode/gzip
caddyhttp/encode/zstd
caddyhttp/fileserver
caddyhttp/headers
caddyhttp/httpcache
caddyhttp/markdown
caddyhttp/requestbody
caddyhttp/reverseproxy
caddyhttp/reverseproxy/fastcgi
caddyhttp/rewrite
caddyhttp/standard
caddyhttp/starlarkmw
caddyhttp/starlarkmw/internal/lib
caddyhttp/templates
caddytls
caddytls/distributedstek
Package distributedstek provides TLS session ticket ephemeral keys (STEKs) in a distributed fashion by utilizing configured storage for locking and key sharing.
 Package distributedstek provides TLS session ticket ephemeral keys (STEKs) in a distributed fashion by utilizing configured storage for locking and key sharing.
caddytls/standardstek
filestorage
logging
standard
pkg
caddyscript
caddyscript/lib

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.