debug

Documentation

Overview

Package debug provides a debug/introspection middleware for celeris.

The middleware intercepts requests under a configurable prefix (default "/debug/celeris") and serves JSON endpoints for server introspection. Non-matching requests pass through with zero overhead.

Basic usage:

server.Use(debug.New(debug.Config{
    Server:    server,
    Collector: collector,
}))

Endpoints: {prefix}/ (index), /status, /metrics, /config, /routes, /memory, /build, /runtime.

Use Config.Endpoints to selectively enable/disable endpoints (nil = all enabled). Disabled endpoints return 404; the index reflects only enabled ones.

By default, access is restricted to loopback addresses (127.0.0.1, ::1) via Config.AuthFunc. This uses the raw TCP peer address, NOT X-Forwarded-For. Behind a reverse proxy, set AuthFunc to a scheme that does not rely on RemoteAddr (e.g., shared secret header).

Config.MemStatsTTL controls /memory caching (default 1s, floor 100ms) to avoid repeated stop-the-world pauses from ReadMemStats.

Config.Skip defines a function to bypass the debug middleware for specific requests matching the debug prefix. It is only consulted for requests under the prefix; non-debug paths always pass through.

The /config endpoint returns Go runtime information (go_version, go_os, go_arch, num_cpu, goroutines), not application-level configuration.

Server and Collector are optional; when nil, /routes returns [] and /metrics returns 501.

Index

• func New(config ...Config) celeris.HandlerFunc
• type Config

Examples

• New
• New (CustomPrefix)
• New (PublicAccess)
• New (WithAuth)

Functions

func New

func New(config ...Config) celeris.HandlerFunc

New creates a debug middleware with the given config.

Example

package main

import (
	"github.com/goceleris/celeris"
	"github.com/goceleris/celeris/observe"

	"github.com/goceleris/celeris/middleware/debug"
)

func main() {
	server := celeris.New(celeris.Config{})
	collector := observe.NewCollector()

	// Default config: localhost-only access.
	server.Use(debug.New(debug.Config{
		Server:    server,
		Collector: collector,
	}))
}

Example (CustomPrefix)

package main

import (
	"github.com/goceleris/celeris"

	"github.com/goceleris/celeris/middleware/debug"
)

func main() {
	server := celeris.New(celeris.Config{})

	server.Use(debug.New(debug.Config{
		Server: server,
		Prefix: "/_internal",
	}))
}

Example (PublicAccess)

package main

import (
	"github.com/goceleris/celeris"

	"github.com/goceleris/celeris/middleware/debug"
)

func main() {
	server := celeris.New(celeris.Config{})

	server.Use(debug.New(debug.Config{
		Server:   server,
		AuthFunc: func(*celeris.Context) bool { return true },
	}))
}

Example (WithAuth)

package main

import (
	"os"

	"github.com/goceleris/celeris"
	"github.com/goceleris/celeris/observe"

	"github.com/goceleris/celeris/middleware/debug"
)

func main() {
	server := celeris.New(celeris.Config{})
	collector := observe.NewCollector()

	server.Use(debug.New(debug.Config{
		Server:    server,
		Collector: collector,
		AuthFunc: func(c *celeris.Context) bool {
			return c.Header("x-debug-token") == os.Getenv("DEBUG_TOKEN")
		},
	}))
}

Types

type Config

type Config struct {
	// Skip defines a function to skip this middleware for certain requests.
	Skip func(c *celeris.Context) bool

	// Prefix is the URL path prefix for debug endpoints.
	// Default: "/debug/celeris".
	Prefix string

	// AuthFunc is an authentication check executed before any debug endpoint.
	// If it returns false, the middleware responds with 403 Forbidden.
	// Default: allows only loopback IPs (127.0.0.1 and ::1).
	// Set to func(*celeris.Context) bool { return true } to allow public access.
	AuthFunc func(c *celeris.Context) bool

	// Server provides access to registered routes via Server.Routes().
	// Nil is safe; the /routes endpoint returns an empty list.
	Server *celeris.Server

	// Collector provides metrics via Collector.Snapshot().
	// Nil is safe; the /metrics endpoint returns 501 Not Implemented.
	Collector *observe.Collector

	// SkipPaths is a list of URL paths for which the debug middleware is
	// bypassed entirely. Unlike Skip (which is only consulted for debug
	// prefixed requests), SkipPaths is checked before any other logic.
	SkipPaths []string

	// Endpoints selectively enables or disables individual debug endpoints.
	// Keys are endpoint names: "status", "metrics", "config", "routes",
	// "memory", "build", "runtime". A true value enables the endpoint;
	// false disables it. When nil (default), all endpoints are enabled.
	Endpoints map[string]bool

	// MemStatsTTL controls how long the /memory endpoint caches
	// runtime.ReadMemStats results. ReadMemStats is expensive (it STWs the
	// runtime), so caching avoids hammering under load.
	//
	// Default: 1s. Set to 0 to disable caching (not recommended).
	// Negative values are treated as "not set" and fall back to the default.
	MemStatsTTL time.Duration
}

Config defines the debug middleware configuration.