Address comments about plugin system

Author: alexandre-daubois

README.md

@@ -101,6 +101,19 @@ Ember polls the Caddy admin API and Prometheus metrics endpoint at a regular int
 
 Ember supports a plugin system that lets third-party developers add custom tabs for visualizing metrics from additional Caddy modules (e.g., rate limiters, WAF modules, custom middleware). Plugins are compiled into the binary using Go's blank import pattern, the same approach used by Caddy itself.
 
+Building a custom Ember binary with plugins is simple:
+
+```go
+import (
+    "github.com/alexandre-daubois/ember"
+    _ "github.com/myorg/ember-myplugin"
+)
+
+func main() { ember.Run() }
+```
+
+Plugins can provide multiple tabs, subscribe to core metrics, conditionally hide their tabs, and reuse Ember's Prometheus parser via the `pkg/metrics` package.
+
 See the [Plugin Development Guide](docs/plugins.md) for details on building and integrating plugins.
 
 ## Documentation

cmd/ember/main.go

@@ -4,13 +4,14 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/alexandre-daubois/ember/internal/app"
+	"github.com/alexandre-daubois/ember"
 )
 
 var version = "1.0.0-dev"
 
 func main() {
-	if err := app.Run(os.Args[1:], version); err != nil {
+	ember.Version = version
+	if err := ember.Run(); err != nil {
 		fmt.Fprintf(os.Stderr, "error: %v\n", err)
 		os.Exit(1)
 	}

docs/plugins.md

@@ -76,13 +76,13 @@ import (
     "fmt"
     "os"
 
-    "github.com/alexandre-daubois/ember/internal/app"
+    "github.com/alexandre-daubois/ember"
 
     _ "github.com/example/ember-stats" // your plugin
 )
 
 func main() {
-    if err := app.Run(os.Args[1:], "custom"); err != nil {
+    if err := ember.Run(); err != nil {
         fmt.Fprintln(os.Stderr, err)
         os.Exit(1)
     }
@@ -363,6 +363,62 @@ type Closer interface {
 }
 ```
 
+### MetricsSubscriber (optional)
+
+```go
+type MetricsSubscriber interface {
+    OnMetrics(snap *metrics.Snapshot)
+}
+```
+
+Called synchronously after each successful core fetch, before plugin `Fetch` calls. The snapshot contains Caddy and FrankenPHP metrics already parsed by Ember. The snapshot must not be modified.
+
+Import `"github.com/alexandre-daubois/ember/pkg/metrics"` to access the `Snapshot` and `MetricsSnapshot` types.
+
+This avoids the need for plugins to make their own `/metrics` requests to Caddy when they need access to the same core metrics Ember already collects.
+
+### MultiRenderer (optional)
+
+```go
+type TabDescriptor struct {
+    Key  string
+    Name string
+}
+
+type MultiRenderer interface {
+    Tabs() []TabDescriptor
+    RendererForTab(key string) Renderer
+}
+```
+
+Implement `MultiRenderer` instead of `Renderer` when your plugin needs multiple TUI tabs. Each tab gets its own `Renderer`, but all tabs share a single `Fetch` call. `Tabs()` is called once after `Init()` to determine the number and order of tabs. `RendererForTab` is called once per tab to create its initial `Renderer`.
+
+If a plugin implements both `Renderer` and `MultiRenderer`, `MultiRenderer` takes priority.
+
+### Availability (optional)
+
+```go
+type Availability interface {
+    Available() bool
+}
+```
+
+Implement `Availability` when your plugin's tab(s) should be shown or hidden based on runtime conditions. For example, a plugin compiled into a custom build but talking to a Caddy instance that does not have the corresponding module enabled.
+
+`Available()` is checked after each successful `Fetch`. When it returns `false`, the plugin's tab(s) are removed from the tab bar. When it returns `true`, they are re-added. If `Available()` panics, the tab stays visible (fail-open).
+
+## Reusing Prometheus Parsing
+
+The `pkg/metrics` package exposes the same Prometheus text parser that Ember uses internally:
+
+```go
+import "github.com/alexandre-daubois/ember/pkg/metrics"
+
+snap, err := metrics.ParsePrometheus(reader)
+```
+
+This returns a `MetricsSnapshot` with all Caddy and FrankenPHP metrics parsed. The package also exposes all the data types (`Snapshot`, `MetricsSnapshot`, `HostMetrics`, `WorkerMetrics`, etc.) for plugins that need to work with core metrics.
+
 ## Reserved Keybindings
 
 The following keys are handled by Ember core and **never** reach your plugin's `HandleKey`:

ember.go

@@ -0,0 +1,35 @@
+// Package ember provides the public entry point for running Ember,
+// a real-time monitoring tool for Caddy and FrankenPHP.
+//
+// Plugin authors use this package to build custom Ember binaries:
+//
+//	import (
+//	    "github.com/alexandre-daubois/ember"
+//	    _ "github.com/myorg/ember-myplugin"
+//	)
+//
+//	func main() {
+//	    ember.Run()
+//	}
+package ember
+
+import (
+	"os"
+
+	"github.com/alexandre-daubois/ember/internal/app"
+)
+
+// Version is set at build time via -ldflags.
+// When empty, it defaults to "dev".
+var Version = "dev"
+
+// Run starts Ember with command-line arguments from os.Args.
+func Run() error {
+	return app.Run(os.Args[1:], Version)
+}
+
+// RunWithArgs starts Ember with the given arguments and version string.
+// This is useful for testing or embedding Ember with custom arguments.
+func RunWithArgs(args []string, version string) error {
+	return app.Run(args, version)
+}

internal/app/daemon.go

@@ -104,6 +104,7 @@ func runDaemon(ctx context.Context, f fetcher.Fetcher, cfg *config, plugins []pl
 		}
 		errThrottle.recover(log)
 		state.Update(snap)
+		notifyDaemonSubscribers(dPlugins, snap)
 		fetchDaemonPlugins(ctx, dPlugins, log)
 		holder.StoreAll(state.CopyForExport(), daemonPluginExports(dPlugins))
 	}
@@ -137,6 +138,7 @@ func runDaemon(ctx context.Context, f fetcher.Fetcher, cfg *config, plugins []pl
 }
 
 type daemonPlugin struct {
+	p        plugin.Plugin
 	name     string
 	fetcher  plugin.Fetcher
 	exporter plugin.Exporter
@@ -146,7 +148,7 @@ type daemonPlugin struct {
 func newDaemonPlugins(plugins []plugin.Plugin) []daemonPlugin {
 	var dps []daemonPlugin
 	for _, p := range plugins {
-		dp := daemonPlugin{name: p.Name()}
+		dp := daemonPlugin{p: p, name: p.Name()}
 		if f, ok := p.(plugin.Fetcher); ok {
 			dp.fetcher = f
 		}
@@ -184,6 +186,21 @@ func fetchDaemonPlugins(ctx context.Context, dps []daemonPlugin, log *slog.Logge
 	wg.Wait()
 }
 
+func notifyDaemonSubscribers(dps []daemonPlugin, snap *fetcher.Snapshot) {
+	for _, dp := range dps {
+		if sub, ok := dp.p.(plugin.MetricsSubscriber); ok {
+			safeOnMetrics(sub, snap)
+		}
+	}
+}
+
+func safeOnMetrics(sub plugin.MetricsSubscriber, snap *fetcher.Snapshot) {
+	defer func() {
+		recover() //nolint:errcheck // fire-and-forget: don't crash Ember if a subscriber panics
+	}()
+	sub.OnMetrics(snap)
+}
+
 func daemonPluginExports(dps []daemonPlugin) []plugin.PluginExport {
 	var exports []plugin.PluginExport
 	for _, dp := range dps {

internal/fetcher/fetcher.go

@@ -2,106 +2,25 @@ package fetcher
 
 import (
 	"context"
-	"time"
-)
-
-type ThreadDebugState struct {
-	Index                    int    `json:"Index"`
-	Name                     string `json:"Name"`
-	State                    string `json:"State"`
-	IsWaiting                bool   `json:"IsWaiting"`
-	IsBusy                   bool   `json:"IsBusy"`
-	WaitingSinceMilliseconds int64  `json:"WaitingSinceMilliseconds"`
-
-	CurrentURI       string `json:"CurrentURI,omitempty"`
-	CurrentMethod    string `json:"CurrentMethod,omitempty"`
-	RequestStartedAt int64  `json:"RequestStartedAt,omitempty"`
-	MemoryUsage      int64  `json:"MemoryUsage,omitempty"`
-	RequestCount     int64  `json:"RequestCount,omitempty"`
-}
 
-type ThreadsResponse struct {
-	ThreadDebugStates   []ThreadDebugState `json:"ThreadDebugStates"`
-	ReservedThreadCount int                `json:"ReservedThreadCount"`
-}
-
-type WorkerMetrics struct {
-	Worker       string  `json:"worker"`
-	Total        float64 `json:"total"`
-	Busy         float64 `json:"busy"`
-	Ready        float64 `json:"ready"`
-	RequestTime  float64 `json:"requestTime"`
-	RequestCount float64 `json:"requestCount"`
-	Crashes      float64 `json:"crashes"`
-	Restarts     float64 `json:"restarts"`
-	QueueDepth   float64 `json:"queueDepth"`
-}
+	"github.com/alexandre-daubois/ember/pkg/metrics"
+)
 
-type HostMetrics struct {
-	Host              string             `json:"host"`
-	RequestsTotal     float64            `json:"requestsTotal"`
-	DurationSum       float64            `json:"durationSum"`
-	DurationCount     float64            `json:"durationCount"`
-	InFlight          float64            `json:"inFlight"`
-	DurationBuckets   []HistogramBucket  `json:"durationBuckets,omitempty"`
-	StatusCodes       map[int]float64    `json:"statusCodes,omitempty"`
-	Methods           map[string]float64 `json:"methods,omitempty"`
-	ResponseSizeSum   float64            `json:"responseSizeSum"`
-	ResponseSizeCount float64            `json:"responseSizeCount"`
-	RequestSizeSum    float64            `json:"requestSizeSum"`
-	RequestSizeCount  float64            `json:"requestSizeCount"`
-	ErrorsTotal       float64            `json:"errorsTotal"`
-	TTFBSum           float64            `json:"ttfbSum"`
-	TTFBCount         float64            `json:"ttfbCount"`
-	TTFBBuckets       []HistogramBucket  `json:"ttfbBuckets,omitempty"`
-}
+type ThreadDebugState = metrics.ThreadDebugState
 
-type MetricsSnapshot struct {
-	// FrankenPHP-specific (require frankenphp metrics)
-	TotalThreads float64                   `json:"totalThreads"`
-	BusyThreads  float64                   `json:"busyThreads"`
-	QueueDepth   float64                   `json:"queueDepth"`
-	Workers      map[string]*WorkerMetrics `json:"workers"`
+type ThreadsResponse = metrics.ThreadsResponse
 
-	// Caddy HTTP metrics (require `metrics` directive in Caddyfile)
-	HTTPRequestErrorsTotal   float64           `json:"httpRequestErrorsTotal"`
-	HTTPRequestsTotal        float64           `json:"httpRequestsTotal"`
-	HTTPRequestDurationSum   float64           `json:"httpRequestDurationSum"`
-	HTTPRequestDurationCount float64           `json:"httpRequestDurationCount"`
-	HTTPRequestsInFlight     float64           `json:"httpRequestsInFlight"`
-	DurationBuckets          []HistogramBucket `json:"durationBuckets,omitempty"`
-	HasHTTPMetrics           bool              `json:"hasHttpMetrics"`
+type WorkerMetrics = metrics.WorkerMetrics
 
-	// Per-host Caddy HTTP metrics
-	Hosts map[string]*HostMetrics `json:"hosts,omitempty"`
+type HostMetrics = metrics.HostMetrics
 
-	// Go runtime process metrics (from standard Prometheus collector)
-	ProcessCPUSecondsTotal  float64 `json:"processCpuSecondsTotal,omitempty"`
-	ProcessRSSBytes         float64 `json:"processRssBytes,omitempty"`
-	ProcessStartTimeSeconds float64 `json:"processStartTimeSeconds,omitempty"`
-}
+type MetricsSnapshot = metrics.MetricsSnapshot
 
-type HistogramBucket struct {
-	UpperBound      float64 `json:"upperBound"`
-	CumulativeCount float64 `json:"cumulativeCount"`
-}
+type HistogramBucket = metrics.HistogramBucket
 
-type ProcessMetrics struct {
-	PID        int32         `json:"pid"`
-	CPUPercent float64       `json:"cpuPercent"`
-	RSS        uint64        `json:"rss"`
-	CreateTime int64         `json:"createTime"`
-	Uptime     time.Duration `json:"uptime"`
-}
+type ProcessMetrics = metrics.ProcessMetrics
 
-type Snapshot struct {
-	Threads       ThreadsResponse `json:"threads"`
-	Metrics       MetricsSnapshot `json:"metrics"`
-	Process       ProcessMetrics  `json:"process"`
-	FetchedAt     time.Time       `json:"fetchedAt"`
-	Errors        []string        `json:"errors,omitempty"`
-	HasFrankenPHP bool            `json:"hasFrankenPHP"`
-}
+type Snapshot = metrics.Snapshot
 
 type Fetcher interface {
 	Fetch(ctx context.Context) (*Snapshot, error)