Skip to content

Commit 1a46852

Browse files
author
mirkobrombin
committed
docs: update Plugins section in README
1 parent 36b4142 commit 1a46852

File tree

1 file changed

+42
-31
lines changed

1 file changed

+42
-31
lines changed

README.md

Lines changed: 42 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,9 @@ handling, and cleanup:
179179

180180
- **OnInit()**: Called once when GoUP! starts (useful for global setup).
181181
- **OnInitForSite(conf config.SiteConfig, logger *log.Logger)**: Called for
182-
each site configuration (site-specific setup).
182+
each site configuration (site-specific setup). Within this, you usually call
183+
a helper like `p.SetupLoggers(conf, p.Name(), logger)` if you’re using the
184+
built-in \`BasePlugin\` approach for loggers.
183185
- **BeforeRequest(r *http.Request)**: Invoked before every request, letting
184186
you examine or modify the incoming request.
185187
- **HandleRequest(w http.ResponseWriter, r *http.Request) bool**: If your
@@ -230,13 +232,41 @@ the site’s JSON configuration file. For example:
230232
}
231233
```
232234

235+
### Example: NodeJSPlugin
236+
237+
Below is an **excerpt** from the built-in **NodeJSPlugin**. Notice how it embeds
238+
a `BasePlugin` for convenient log handling:
239+
240+
```go
241+
type NodeJSPlugin struct {
242+
plugin.BasePlugin // provides DomainLogger + PluginLogger
243+
mu sync.Mutex
244+
process *os.Process
245+
246+
siteConfigs map[string]NodeJSPluginConfig
247+
}
248+
249+
func (p *NodeJSPlugin) OnInitForSite(conf config.SiteConfig, domainLogger *log.Logger) error {
250+
// Initialize domain + plugin loggers (for console vs plugin-specific logs)
251+
if err := p.SetupLoggers(conf, p.Name(), domainLogger); err != nil {
252+
return err
253+
}
254+
// Parse plugin-specific JSON config, etc.
255+
...
256+
}
257+
```
258+
259+
Inside the code, we have **two** loggers:
260+
- **`p.DomainLogger`** for messages shown in the console + domain log file
261+
(e.g., "Delegating path=... to Node.js").
262+
- **`p.PluginLogger`** for plugin-specific logs only (in the dedicated `NodeJSPlugin.log`).
263+
233264
### Pre-Installed Plugins
234265

235-
- **Custom Header Plugin**: Adds custom headers to HTTP responses, configured
236-
per domain.
266+
- **Custom Header Plugin**: Adds custom headers to HTTP responses.
237267
- **PHP Plugin**: Handles `.php` requests using PHP-FPM.
238268
- **Auth Plugin**: Protects routes with basic authentication.
239-
- **NodeJS Plugin**: Handles Node.js applications using `node`.
269+
- **NodeJS Plugin**: Handles Node.js applications with Node.
240270

241271
Each plugin can have its own JSON configuration under `plugin_configs`, which it
242272
reads in `OnInitForSite`.
@@ -264,51 +294,32 @@ package myplugin
264294

265295
import (
266296
"net/http"
267-
268297
"github.com/mirkobrombin/goup/internal/config"
298+
"github.com/mirkobrombin/goup/internal/plugin"
269299
log "github.com/sirupsen/logrus"
270300
)
271301

272-
type MyPlugin struct{}
302+
type MyPlugin struct {
303+
plugin.BasePlugin // optional embedding if you want domain + plugin logs
304+
}
273305

274-
// Name returns the plugin's name.
275306
func (p *MyPlugin) Name() string {
276307
return "MyPlugin"
277308
}
278-
279-
// OnInit is called once globally on startup.
280309
func (p *MyPlugin) OnInit() error {
281-
// Perform any global setup here.
282310
return nil
283311
}
284-
285-
// OnInitForSite is called for each site configuration.
286312
func (p *MyPlugin) OnInitForSite(conf config.SiteConfig, logger *log.Logger) error {
287-
// Site-specific setup (e.g. reading plugin config).
288-
logger.Infof("MyPlugin initialized for site: %s", conf.Domain)
313+
// If you want domain + plugin logs:
314+
p.SetupLoggers(conf, p.Name(), logger)
289315
return nil
290316
}
291-
292-
// BeforeRequest is invoked before handling every request.
293-
func (p *MyPlugin) BeforeRequest(r *http.Request) {
294-
// Optionally inspect or modify the request.
295-
}
296-
297-
// HandleRequest can take over the request entirely if desired.
298-
// Return true if you want to finalize the response here.
317+
func (p *MyPlugin) BeforeRequest(r *http.Request) {}
299318
func (p *MyPlugin) HandleRequest(w http.ResponseWriter, r *http.Request) bool {
300-
// Example: Just log and let GoUP! continue.
301319
return false
302320
}
303-
304-
// AfterRequest is invoked after the request is served (or handled by this plugin).
305-
func (p *MyPlugin) AfterRequest(w http.ResponseWriter, r *http.Request) {
306-
// Any post-processing goes here.
307-
}
308-
309-
// OnExit is called when GoUP! is shutting down.
321+
func (p *MyPlugin) AfterRequest(w http.ResponseWriter, r *http.Request) {}
310322
func (p *MyPlugin) OnExit() error {
311-
// Cleanup resources if needed.
312323
return nil
313324
}
314325
```

0 commit comments

Comments
 (0)