mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-24 05:56:15 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Update old links on extending caddy page

Browse source
This commit is contained in:
Matthew Holt 2020-05-12 12:25:33 -06:00
parent 6664f03039
commit a5dee98892
No known key found for this signature in database
GPG key ID: 2A349DD577D586A5
1 changed files with 11 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

22
src/docs/markdown/extending-caddy.md
View file

@ -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. 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: 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
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: 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: 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. 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. 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@v2.0.0-beta11?tab=doc#Validator), the `Validate()` 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. 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 ### 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. 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 ```go
// Provision sets up the module. // 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 ### 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 ```go
// Validate validates that the module has a usable config. // 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 `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 ### 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 ```go
// Provision sets up g and loads its gadget. // Provision sets up g and loads its gadget.