server

type Cmd interface {
	// Name returns the executable name.
	Name() string

	// Description returns the application description string.
	Description() string

	// Version returns the application version string.
	Version() string

	// Context returns the lifecycle context (cancelled on SIGINT).
	Context() context.Context

	// Logger returns the structured logger.
	Logger() *slog.Logger

	// Tracer returns the OpenTelemetry tracer, or nil if OTel is not configured.
	Tracer() trace.Tracer

	// ClientEndpoint returns the HTTP endpoint URL and client options derived
	// from the global HTTP flags.
	ClientEndpoint() (string, []client.ClientOpt, error)

	// Get retrieves a default value by key. Returns nil if the key does not exist.
	Get(string) any

	// GetString retrieves a default string value by key. Returns empty string if the key
	// does not exist or the value is not a string.
	GetString(string) string

	// Set stores a default value by key and persists the store to disk.
	// Pass nil to remove a key.
	Set(string, any) error

	// Keys returns all keys in the store.
	Keys() []string

	// IsTerm reports whether stderr is an interactive terminal.
	IsTerm() bool

	// IsDebug reports whether debug logging is enabled.
	IsDebug() bool

	// HTTPAddr returns the HTTP listen/connect address.
	HTTPAddr() string

	// HTTPPrefix returns the HTTP path prefix.
	HTTPPrefix() string

	// HTTPOrigin returns the cross-origin protection origin.
	HTTPOrigin() string

	// HTTPTimeout returns the HTTP read/write timeout.
	HTTPTimeout() time.Duration
}

type HTTPFileServer interface {
	// HandlerPath returns the route path relative to the router prefix.
	HandlerPath() string

	// HandlerFS returns the filesystem to serve.
	HandlerFS() fs.FS

	// Spec returns the OpenAPI path-item description for this
	// handler, or nil if no spec is provided.
	Spec() *openapi.PathItem
}

type HTTPHandler interface {
	// HandlerPath returns the route path relative to the router prefix
	// (e.g. "resource", "resource/{id}").
	HandlerPath() string

	// HandlerFunc returns the HTTP handler function.
	HandlerFunc() http.HandlerFunc

	// Spec returns the OpenAPI path-item description for this
	// handler, or nil if no spec is provided.
	Spec() *openapi.PathItem
}

type HTTPMiddleware interface {
	WrapFunc(http.HandlerFunc) http.HandlerFunc
}

type HTTPRouter interface {
	http.Handler

	// Spec returns the OpenAPI specification for this router.
	Spec() *openapi.Spec
}

type HTTPServer interface {
	// Spec returns the OpenAPI server entry for this instance,
	// or nil if not yet available.
	Spec() *openapi.Server
}