mux

type Middleware interface {
	Intercept(ctx context.Context, request plow.Request, next NextFunc) plow.Response
}

type MiddlewareFunc func(ctx context.Context, request plow.Request, next NextFunc) plow.Response

type Mux interface {
	plow.Handler

	// Use adds a middleware function to the mux's middleware chain.
	// Middleware functions are executed in the order they are added.
	Use(middleware Middleware) Mux

	// Route creates a new route with the specified HTTP method, URL pattern,
	// handler function, and optional flags. Returns the mux for method chaining.
	//
	// Supported formats:
	//   - /users/{id} - string parameter
	//   - /files/{name}/raw/{id} - many parameters
	//   - /posts/{id:<regex pattern>} - regex parameter
	//   - /static/{*:.*} - wildcard parameter for "at the end" (also support regex)
	//
	// Everything outside {…} is safely regex-escaped
	// Trailing slash is ignored at compile-time; both /path and /path/ are accepted at match-time
	// Wildcard parameters (*) can match any characters including slashes
	Route(method specs.HttpMethod, pattern string, handler plow.Handler, flags ...any) Mux

	// Include incorporates all routes from a RouterBuilder into this mux.
	// This allows for modular router composition and reuse.
	Include(router RouterBuilder) Mux

	// NotFoundHandler sets a custom handler for requests that don't match any routes.
	// If not set, a default 404 response is returned.
	NotFoundHandler(handler plow.Handler) Mux

	// Routes returns an iterator over all routes configured in this mux.
	// The routes include both the route information and matching capabilities.
	Routes() iter.Seq[MuxRoute]
}

type MuxRoute interface {
	Route

	// Match checks if the given path matches this route's pattern.
	// Returns true if there's a match, along with any extracted path parameters.
	// The parameters are returned as key-value pairs in a sequence.
	Match(path string) (bool, iter.Seq2[string, string])
}

type NextFunc func(ctx context.Context) plow.Response

type Route interface {
	// Method returns the HTTP method (GET, POST, PUT, etc.) that this route handles.
	Method() specs.HttpMethod

	// Pattern returns the URL path pattern that this route matches against.
	Pattern() string

	// Handler returns the function that will process requests matching this route.
	Handler() plow.Handler

	// Flags returns an iterator over all flags associated with this route.
	// Flags can provide additional configuration or metadata for the route.
	Flags() iter.Seq[any]
}

type RouteBuilder interface {
	// AddFlag adds one or more flags to the route for additional configuration.
	// Flags can be used to modify route behavior or provide metadata.
	AddFlag(flags ...any) RouteBuilder
}

type RouterBuilder interface {
	// Route adds a new route to the router with the specified HTTP method,
	// URL pattern, handler function, and optional flags.
	// Returns a RouteBuilder for further configuration of the route.
	//
	// Does not compile the pattern only stores it before placing it in the [Mux].
	// For more information about the available formats in Mux.Route
	Route(method specs.HttpMethod, pattern string, handler plow.Handler, flags ...any) RouteBuilder

	// Include incorporates all routes from another RouterBuilder into this one.
	// This allows for modular router composition and reuse.
	Include(router RouterBuilder) RouterBuilder

	// Routes returns an iterator over all routes configured in this router.
	// The routes are returned as a sequence that can be iterated over.
	Routes() iter.Seq[Route]
}