httpsrv

type App interface {
	Router

	// Run starts the HTTP server and blocks until it stops. Each optional arg
	// may be:
	//   - a string "host:port" or ":port" listen address (default ":8080"), or
	//   - a pre-bound net.Listener.
	// http.ErrServerClosed from a graceful stop is not reported as an error.
	Run(args ...any) error

	// Shutdown gracefully stops the server (see http.Server.Shutdown), waiting
	// for active connections to finish or ctx to expire. Call it from another
	// goroutine while Run is blocking.
	Shutdown(ctx context.Context) error
}

type Config struct {
	// Addr is the listen address (default ":8080"; a string passed to Run
	// overrides it).
	Addr string

	// Timeouts; defaults are Read/Write 60s, ReadHeader 10s. Set WriteTimeout
	// to a large value (or use streaming) for long responses.
	ReadTimeout       time.Duration
	WriteTimeout      time.Duration
	ReadHeaderTimeout time.Duration

	// MaxHeaderBytes caps request header size (default 1 MiB).
	MaxHeaderBytes int
}

type Ctx interface {
	// Request / Response
	Request() *http.Request
	Response() http.ResponseWriter
	// SetResponse replaces the response writer for the remainder of the chain.
	// Intended for middleware that wraps the writer (e.g. compression); route
	// handlers normally do not need it.
	SetResponse(w http.ResponseWriter)

	// Identity
	Method() string
	Path() string
	IP() string
	// BaseURL returns (protocol + host + base path).
	BaseURL() string
	// Locale returns the request locale (set by the AcceptLanguage middleware),
	// falling back to the i18n default, then "".
	Locale() string

	// Input
	Params(key string) string
	Query(key string, def ...string) string
	Header(key string, def ...string) string // request header
	Body() []byte
	FormValue(key string, def ...string) string // body form field (urlencoded or multipart)
	Bind(out any) error                         // JSON body -> out (json.Unmarshal)

	//
	Translate(locale, key string, args ...any) string // i18n lookup (requires WithI18n)

	// Output (SetHeader/Status chain before the body is written)
	SetHeader(key, value string) Ctx
	Status(code int) Ctx
	JSON(v any) error
	Send(b []byte) error
	SendString(s string) error
	Redirect(status int, url string) error
	Render(name string, bind any, layouts ...string) error // html template render

	// Next runs the next handler in the middleware chain. Middleware call it to
	// continue; route handlers are terminal and ignore it.
	Next() error
}

type ErrorHandler func(c Ctx, err error)

type Handler func(ctx Ctx) error

type I18n struct {
	// contains filtered or unexported fields
}

type Option func(*app)

type Router interface {
	// Get/Post/.../All accept a Handler (func(Ctx) error, the typical form) or an
	// http.Handler (for direct stdlib interop); a Handler receives a request
	// context (Ctx).
	Get(path string, handler any) Router
	Head(path string, handler any) Router
	Post(path string, handler any) Router
	Put(path string, handler any) Router
	Patch(path string, handler any) Router
	Delete(path string, handler any) Router
	Options(path string, handler any) Router
	All(path string, handler any) Router

	// Use registers middleware. With a leading string argument it scopes the
	// middleware to that path prefix (segment-aware, all methods); without one
	// it runs for every request.
	Use(args ...any) Router

	// Group returns a sub-router whose routes are prefixed with prefix.
	// Groups nest: a group created from another group inherits its prefix.
	Group(prefix string) Router
}

type Views interface {
	// Load is called once to load/parse templates. The built-in engine
	// parses at construction, so its Load is a no-op.
	Load() error

	// Render writes the named template (with optional layouts) to w.
	Render(w io.Writer, name string, bind any, layout ...string) error
}