diff --git a/src/docs/markdown/extending-caddy.md b/src/docs/markdown/extending-caddy.md index 1b9403c..92473d1 100644 --- a/src/docs/markdown/extending-caddy.md +++ b/src/docs/markdown/extending-caddy.md @@ -12,7 +12,7 @@ Caddy is easy to extend because of its modular architecture. Most kinds of Caddy A Caddy module is any named type that registers itself as a Caddy module when its package is imported. -Crucially, a module always implements the [caddy.Module](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#Module) interface, which provides its name and a constructor function. +Crucially, a module always implements the [caddy.Module](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Module) interface, which provides its name and a constructor function. Here's a template you can copy & paste: @@ -89,7 +89,7 @@ The name within a namespace is not particularly important, as long as it is uniq ### Apps -Apps are modules with an empty namespace, and which conventionally become their own top-level namespace. App modules implement the [caddy.App](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#App) interface. +Apps are modules with an empty namespace, and which conventionally become their own top-level namespace. App modules implement the [caddy.App](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#App) interface. These modules appear in the [`"apps"`](/docs/json/#apps) property of the top-level of Caddy's config: @@ -128,20 +128,20 @@ When a module is initialized, it will already have its configuration filled out. A module's life begins when it is loaded by a host module. The following happens: -1. [`New()`](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#ModuleInfo.New) is called to get an instance of the module's value. +1. [`New()`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#ModuleInfo.New) is called to get an instance of the module's value. 2. The module's configuration is unmarshaled into that instance. -3. If the module is a [caddy.Provisioner](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#Provisioner), the `Provision()` method is called. -4. If the module is a [caddy.Validator](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#Validator), the `Validate()` method is called. +3. If the module is a [caddy.Provisioner](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Provisioner), the `Provision()` method is called. +4. If the module is a [caddy.Validator](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Validator), the `Validate()` method is called. 5. At this point, the host module is given the loaded guest module as an `interface{}` value, so the host module will usually type-assert the guest module into a more useful type. Check the documentation for the host module to know what is required of a guest module in its namespace, e.g. what methods need to be implemented. -6. When a module is no longer needed, and if it is a [caddy.CleanerUpper](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#CleanerUpper), the `Cleanup()` method is called. +6. When a module is no longer needed, and if it is a [caddy.CleanerUpper](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#CleanerUpper), the `Cleanup()` method is called. -Note that multiple loaded instances of your module may overlap at a given time! During config changes, new modules are started before the old ones are stopped. Be sure to use global state carefully. Use the [caddy.UsagePool](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#UsagePool) type to help manage global state across module loads. +Note that multiple loaded instances of your module may overlap at a given time! During config changes, new modules are started before the old ones are stopped. Be sure to use global state carefully. Use the [caddy.UsagePool](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#UsagePool) type to help manage global state across module loads. ### Provisioning A module's configuration will be unmarshaled into its value automatically. This means, for example, that struct fields will be filled out for you. -However, if your module requires additional provisioning steps, you can implement the [caddy.Provisioner](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#Provisioner) interface: +However, if your module requires additional provisioning steps, you can implement the [caddy.Provisioner](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Provisioner) interface: ```go // Provision sets up the module. @@ -174,7 +174,7 @@ Then you can emit structured, leveled logs using `g.logger`. See [zap's godoc](h ### Validating -Modules which would like to validate their configuration may do so by satisfying the [`caddy.Validator`](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#Validator) interface: +Modules which would like to validate their configuration may do so by satisfying the [`caddy.Validator`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Validator) interface: ```go // Validate validates that the module has a usable config. @@ -246,12 +246,12 @@ For module fields, the struct tag will look like: The `namespace=` part is required. It defines the namespace in which to look for the module. -The `inline_key=` part is only used if the module's name will be found _inline_ with the module itself; this implies that the value is an object where one of the keys is the _inline key_, and its value is the name of the module. If omitted, then the field type must be a [`caddy.ModuleMap`](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#ModuleMap) or `[]caddy.ModuleMap`, where the map key is the module name. +The `inline_key=` part is only used if the module's name will be found _inline_ with the module itself; this implies that the value is an object where one of the keys is the _inline key_, and its value is the name of the module. If omitted, then the field type must be a [`caddy.ModuleMap`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#ModuleMap) or `[]caddy.ModuleMap`, where the map key is the module name. ### Loading guest modules -To load a guest module, call [`ctx.LoadModule()`](https://pkg.go.dev/github.com/caddyserver/caddy/v2@v2.0.0-beta11?tab=doc#Context.LoadModule) during the provision phase: +To load a guest module, call [`ctx.LoadModule()`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#Context.LoadModule) during the provision phase: ```go // Provision sets up g and loads its gadget.