Admin API purge/invalidation still panics with nil pointer on v0.16.0 (same root cause as #140)

cache-handler version(s) affected: v0.16.0

Description

Every call to the Souin admin API (purge, group-invalidation, etc.) panics with a nil pointer dereference — confirmed on a real deployment (FrankenPHP + github.com/caddyserver/cache-handler), not just in isolation. This looks like the same root cause as #140, still reproducing on v0.16.0.

Root cause

adminAPI.Provision() (in admin.go) resolves a.app (the *SouinApp instance) and returns. The handler map (InternalEndpointHandlers), which is built from a.app.Storers and a.app.SurrogateStorage, is constructed once, also inside Provision().

The problem: a.app.SurrogateStorage is populated by the per-route SouinCaddyMiddleware's own Provision() — a separate module, provisioned in an order Caddy doesn't guarantee relative to adminAPI.Provision(). When adminAPI.Provision() runs first (or the middleware simply hasn't provisioned yet for whatever route ordering reason), the handler map gets built with a nil SurrogateStorage baked in — permanently, since it's only ever built once, at Provision() time. Every subsequent admin API call then panics trying to use it.

How to reproduce

1. Configure cache-handler with Cache-Tags/Surrogate-Key invalidation enabled (a purger hitting the Souin admin API).
2. Start Caddy/FrankenPHP fresh (cold start matters — the provisioning-order race is timing-dependent, not always reproducible on every boot).
3. Send any purge/invalidation request to the admin API (/souin-api/souin, PURGE method or group-invalidation endpoint).
4. Nil pointer panic in the admin API handler, request fails.

Possible Solution

Defer building InternalEndpointHandlers until the first actual admin API request instead of at Provision() time, guarded by a sync.Once. By the time any real HTTP request reaches the admin API, both modules are guaranteed fully provisioned, so a.app.SurrogateStorage is populated correctly.

type adminAPI struct {
	ctx                      caddy.Context
	logger                   core.Logger
	app                      *SouinApp
	InternalEndpointHandlers *api.MapHandler
	handlersOnce             sync.Once
}

// ensureHandlers builds InternalEndpointHandlers on first use rather than at
// Provision time. adminAPI.Provision() and the per-route SouinCaddyMiddleware's
// Provision() (which populates app.SurrogateStorage) run in an unspecified
// order — building the handler map here at Provision time can capture a nil
// SurrogateStorage forever, crashing every purge call. Deferring the build
// until the first actual admin API request guarantees the app is fully
// provisioned by then.
func (a *adminAPI) ensureHandlers() {
	a.handlersOnce.Do(func() {
		config := Configuration{
			API: a.app.API,
			DefaultCache: DefaultCache{
				TTL: configurationtypes.Duration{
					Duration: 120 * time.Second,
				},
			},
		}
		a.InternalEndpointHandlers = api.GenerateHandlerMap(&config, a.app.Storers, a.app.SurrogateStorage)
	})
}

func (a *adminAPI) handleAPIEndpoints(writer http.ResponseWriter, request *http.Request) error {
	a.ensureHandlers()

	if a.InternalEndpointHandlers != nil {
		for k, handler := range *a.InternalEndpointHandlers.Handlers {
			if strings.Contains(request.RequestURI, k) {
				handler(writer, request)
				return nil
			}
		}
	}

	return caddy.APIError{
		HTTPStatus: http.StatusNotFound,
		Err:        fmt.Errorf("resource not found: %v", request.URL.Path),
	}
}

func (a *adminAPI) Provision(ctx caddy.Context) error {
	a.ctx = ctx
	a.logger = ctx.Logger(a).Sugar()

	app, err := ctx.App(moduleName)
	if err != nil {
		return err
	}

	a.app = app.(*SouinApp)

	return nil
}

Removed from Provision(): the eager InternalEndpointHandlers = api.GenerateHandlerMap(...) call. Everything else in Provision() stays the same.

Patched and running this in production (built via a local xcaddy override on top of the v0.16.0 tag) without further panics since.

Additional Context

Related to #140 — same symptom (nil pointer panic in the admin API), and the fix here is the same shape (lazy-init instead of eager-init at Provision() time). Flagging as its own issue since it's still present on v0.16.0 and #140 seems to have gone quiet — happy to close this in favor of #140 or open a PR directly if that's more useful.

Start in admin.go at adminAPI.Provision and handleAPIEndpoints, then trace how the per-route SouinCaddyMiddleware populates app.SurrogateStorage. Reproduce with a cold Caddy/FrankenPHP start and an admin purge or group-invalidation request; done means those requests complete without a nil-pointer panic.