feat(core): add typed eventbus and domain extension points

core/extpoints/router.go

@@ -0,0 +1,266 @@
+package extpoints
+
+import (
+	"strings"
+	"sync"
+)
+
+// RouteDefinition holds the metadata and handler list for a single HTTP route.
+type RouteDefinition struct {
+	Method      string
+	Path        string
+	Handlers    []any
+	Middlewares []any
+}
+
+// RouterExtension defines the interface for registering routes and middlewares.
+type RouterExtension interface {
+	Use(middlewares ...any)
+	Group(prefix string, middlewares ...any) RouterExtension
+	Handle(method string, path string, handlers ...any) RouteDefinition
+	GET(path string, handlers ...any) RouteDefinition
+	POST(path string, handlers ...any) RouteDefinition
+	PUT(path string, handlers ...any) RouteDefinition
+	DELETE(path string, handlers ...any) RouteDefinition
+	PATCH(path string, handlers ...any) RouteDefinition
+	HEAD(path string, handlers ...any) RouteDefinition
+	OPTIONS(path string, handlers ...any) RouteDefinition
+	Any(path string, handlers ...any) []RouteDefinition
+	Routes() []RouteDefinition
+	Middlewares() []any
+}
+
+// RouterRegistry implements RouterExtension as the root route and middleware collector.
+type RouterRegistry struct {
+	mu          sync.RWMutex
+	routes      []RouteDefinition
+	middlewares []any
+}
+
+// NewRouterRegistry creates a new root router collector.
+func NewRouterRegistry() *RouterRegistry {
+	return &RouterRegistry{}
+}
+
+// Use registers global middlewares to the router.
+func (r *RouterRegistry) Use(middlewares ...any) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.middlewares = append(r.middlewares, middlewares...)
+}
+
+// Middlewares returns a copy of registered root middlewares.
+func (r *RouterRegistry) Middlewares() []any {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	res := make([]any, len(r.middlewares))
+	copy(res, r.middlewares)
+	return res
+}
+
+// Group creates a new RouteGroup under the router.
+func (r *RouterRegistry) Group(prefix string, middlewares ...any) RouterExtension {
+	return &RouterGroup{
+		registry:    r,
+		prefix:      cleanPath(prefix),
+		middlewares: middlewares,
+	}
+}
+
+// Handle registers a route with a custom HTTP method and handlers.
+func (r *RouterRegistry) Handle(method, path string, handlers ...any) RouteDefinition {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	rd := RouteDefinition{
+		Method:      strings.ToUpper(method),
+		Path:        cleanPath(path),
+		Handlers:    handlers,
+		Middlewares: append([]any(nil), r.middlewares...),
+	}
+	r.routes = append(r.routes, rd)
+	return rd
+}
+
+// GET registers a GET route.
+func (r *RouterRegistry) GET(path string, handlers ...any) RouteDefinition {
+	return r.Handle("GET", path, handlers...)
+}
+
+// POST registers a POST route.
+func (r *RouterRegistry) POST(path string, handlers ...any) RouteDefinition {
+	return r.Handle("POST", path, handlers...)
+}
+
+// PUT registers a PUT route.
+func (r *RouterRegistry) PUT(path string, handlers ...any) RouteDefinition {
+	return r.Handle("PUT", path, handlers...)
+}
+
+// DELETE registers a DELETE route.
+func (r *RouterRegistry) DELETE(path string, handlers ...any) RouteDefinition {
+	return r.Handle("DELETE", path, handlers...)
+}
+
+// PATCH registers a PATCH route.
+func (r *RouterRegistry) PATCH(path string, handlers ...any) RouteDefinition {
+	return r.Handle("PATCH", path, handlers...)
+}
+
+// HEAD registers a HEAD route.
+func (r *RouterRegistry) HEAD(path string, handlers ...any) RouteDefinition {
+	return r.Handle("HEAD", path, handlers...)
+}
+
+// OPTIONS registers an OPTIONS route.
+func (r *RouterRegistry) OPTIONS(path string, handlers ...any) RouteDefinition {
+	return r.Handle("OPTIONS", path, handlers...)
+}
+
+// Any registers a route for standard HTTP methods.
+func (r *RouterRegistry) Any(path string, handlers ...any) []RouteDefinition {
+	methods := []string{"GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"}
+	defs := make([]RouteDefinition, 0, len(methods))
+	for _, m := range methods {
+		defs = append(defs, r.Handle(m, path, handlers...))
+	}
+	return defs
+}
+
+// Routes returns a copy of all collected RouteDefinitions.
+func (r *RouterRegistry) Routes() []RouteDefinition {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	res := make([]RouteDefinition, len(r.routes))
+	copy(res, r.routes)
+	return res
+}
+
+// RouterGroup represents a scoped route group with a path prefix and group-level middlewares.
+type RouterGroup struct {
+	registry    *RouterRegistry
+	prefix      string
+	middlewares []any
+}
+
+// Use adds middlewares to this group.
+func (g *RouterGroup) Use(middlewares ...any) {
+	g.middlewares = append(g.middlewares, middlewares...)
+}
+
+// Group creates a nested RouteGroup.
+func (g *RouterGroup) Group(prefix string, middlewares ...any) RouterExtension {
+	combinedPrefix := joinPaths(g.prefix, prefix)
+	combinedMiddlewares := make([]any, 0, len(g.middlewares)+len(middlewares))
+	combinedMiddlewares = append(combinedMiddlewares, g.middlewares...)
+	combinedMiddlewares = append(combinedMiddlewares, middlewares...)
+
+	return &RouterGroup{
+		registry:    g.registry,
+		prefix:      combinedPrefix,
+		middlewares: combinedMiddlewares,
+	}
+}
+
+// Handle registers a route under this group.
+func (g *RouterGroup) Handle(method, path string, handlers ...any) RouteDefinition {
+	g.registry.mu.Lock()
+	defer g.registry.mu.Unlock()
+
+	fullPath := joinPaths(g.prefix, path)
+
+	allMiddlewares := make([]any, 0, len(g.registry.middlewares)+len(g.middlewares))
+	allMiddlewares = append(allMiddlewares, g.registry.middlewares...)
+	allMiddlewares = append(allMiddlewares, g.middlewares...)
+
+	rd := RouteDefinition{
+		Method:      strings.ToUpper(method),
+		Path:        fullPath,
+		Handlers:    handlers,
+		Middlewares: allMiddlewares,
+	}
+	g.registry.routes = append(g.registry.routes, rd)
+	return rd
+}
+
+// GET registers a GET route in this group.
+func (g *RouterGroup) GET(path string, handlers ...any) RouteDefinition {
+	return g.Handle("GET", path, handlers...)
+}
+
+// POST registers a POST route in this group.
+func (g *RouterGroup) POST(path string, handlers ...any) RouteDefinition {
+	return g.Handle("POST", path, handlers...)
+}
+
+// PUT registers a PUT route in this group.
+func (g *RouterGroup) PUT(path string, handlers ...any) RouteDefinition {
+	return g.Handle("PUT", path, handlers...)
+}
+
+// DELETE registers a DELETE route in this group.
+func (g *RouterGroup) DELETE(path string, handlers ...any) RouteDefinition {
+	return g.Handle("DELETE", path, handlers...)
+}
+
+// PATCH registers a PATCH route in this group.
+func (g *RouterGroup) PATCH(path string, handlers ...any) RouteDefinition {
+	return g.Handle("PATCH", path, handlers...)
+}
+
+// HEAD registers a HEAD route in this group.
+func (g *RouterGroup) HEAD(path string, handlers ...any) RouteDefinition {
+	return g.Handle("HEAD", path, handlers...)
+}
+
+// OPTIONS registers an OPTIONS route in this group.
+func (g *RouterGroup) OPTIONS(path string, handlers ...any) RouteDefinition {
+	return g.Handle("OPTIONS", path, handlers...)
+}
+
+// Any registers a route in this group for standard HTTP methods.
+func (g *RouterGroup) Any(path string, handlers ...any) []RouteDefinition {
+	methods := []string{"GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"}
+	defs := make([]RouteDefinition, 0, len(methods))
+	for _, m := range methods {
+		defs = append(defs, g.Handle(m, path, handlers...))
+	}
+	return defs
+}
+
+// Routes returns all routes from the parent registry.
+func (g *RouterGroup) Routes() []RouteDefinition {
+	return g.registry.Routes()
+}
+
+// Middlewares returns a copy of the group's middlewares.
+func (g *RouterGroup) Middlewares() []any {
+	res := make([]any, len(g.middlewares))
+	copy(res, g.middlewares)
+	return res
+}
+
+func cleanPath(p string) string {
+	if p == "" {
+		return "/"
+	}
+	if !strings.HasPrefix(p, "/") {
+		p = "/" + p
+	}
+	if len(p) > 1 && strings.HasSuffix(p, "/") {
+		p = strings.TrimSuffix(p, "/")
+	}
+	return p
+}
+
+func joinPaths(base, relative string) string {
+	if base == "" || base == "/" {
+		return cleanPath(relative)
+	}
+	if relative == "" || relative == "/" {
+		return cleanPath(base)
+	}
+	base = strings.TrimSuffix(base, "/")
+	relative = strings.TrimPrefix(relative, "/")
+	return cleanPath(base + "/" + relative)
+}