api

type ClientTLS struct {
	CertBundle certutil.CertBundle
	AuthType   tls.ClientAuthType
}

type Encoding string

type Endpoint struct {
	Protocol string
	Host     string
	Port     uint
	Path     string
}

type ErrorBody struct {
	Origin  error      `json:"-"`                // keep the original error to trace the stack
	Source  string     `json:"source,omitempty"` // source
	Status  int        `json:"status,omitempty"` // http status code
	Code    string     `json:"code,omitempty"`   // customized error code
	Kind    string     `json:"kind,omitempty"`   // error category
	Message string     `json:"message,omitempty"`
	Details labels.Set `json:"details,omitempty"`
}

type Middleware interface {
	common.Service
	// Func returns the middleware function for one attachment point.
	//
	// enabled is the resolved switch for the attachment: booleans written
	// under the middleware's name are switches, not config, and the most
	// specific one wins - a handler entry over its group's over the server's
	// mapping. With no boolean anywhere, a route attachment is enabled by
	// the router.yaml entry's presence, and a server-level attachment
	// (WithMiddlewares) is enabled by its entry in the server's middleware
	// configs - no entry leaves it dormant. The standard first line is
	// `if !enabled { return nil, nil }`.
	//
	// config is the most specific non-boolean YAML written under the
	// middleware's name, nil when there is none - config and switch resolve
	// independently, so a handler's `true` can re-enable an attachment while
	// still inheriting the group's block. Called once per attachment at
	// registration time - and again on restart, when routes are rebuilt - so
	// per-route state lives in the returned closure. An error fails
	// registration; returning no function and no error declines the
	// attachment, and the server skips it.
	Func(enabled bool, config []byte) (func(echo.HandlerFunc) echo.HandlerFunc, error)
}

type RequestInfo struct {
	Server     string
	URI        string
	Method     string
	Path       string
	RawPath    string
	TraceID    string
	IP         string
	StartedAt  time.Time
	Permission string
	Poll       bool
}

type ResponseInfo struct {
	Status  int
	Took    time.Duration
	Size    uint64
	TraceID string
	Error   *ErrorBody
}

type Router interface {
	common.Service
	Config() []byte
	Handlers() map[string]any // echo.HandlerFunc or WebSocketHandlerFunc
}

type ServerTLS struct {
	CertBundle  certutil.CertBundle
	AuthEnabled bool
}

type Stats struct {
	RequestInfo
	ResponseInfo
}