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

2026-10-02 06:56:36 +08:00 · 2026-08-27 23:47:57 +08:00
parent d853a41eae
commit c53a5461ab
11 changed files with 1625 additions and 9 deletions
@@ -0,0 +1,277 @@
+package extpoints_test
+
+import (
+	"context"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/Rain-kl/Wavelet/core"
+	"github.com/Rain-kl/Wavelet/core/extpoints"
+)
+
+func TestRouterExtension(t *testing.T) {
+	r := extpoints.NewRouterRegistry()
+	require.NotNil(t, r)
+
+	mGlobal := "global_middleware"
+	r.Use(mGlobal)
+	assert.Equal(t, []any{mGlobal}, r.Middlewares())
+
+	// Test root methods
+	hRoot := "root_handler"
+	r.GET("/", hRoot)
+	r.POST("/root_post", hRoot)
+	r.PUT("/root_put", hRoot)
+	r.DELETE("/root_del", hRoot)
+	r.PATCH("/root_patch", hRoot)
+	r.HEAD("/root_head", hRoot)
+	r.OPTIONS("/root_opt", hRoot)
+	anyRootDefs := r.Any("/root_any", hRoot)
+	assert.Len(t, anyRootDefs, 7)
+
+	// Group and Group.Use
+	mAPI := "api_middleware"
+	api := r.Group("/api/v1", mAPI)
+	api.Use("api_extra_middleware")
+	assert.Len(t, api.Middlewares(), 2)
+
+	hList := "list_orders_handler"
+	hCreate := "create_order_handler"
+	api.GET("/orders", hList)
+	api.POST("/orders", hCreate)
+
+	mAdmin := "admin_middleware"
+	admin := api.Group("admin", mAdmin)
+
+	hUserGet := "get_user_handler"
+	hUserPut := "put_user_handler"
+	hUserDel := "del_user_handler"
+	hUserPatch := "patch_user_handler"
+	hUserHead := "head_user_handler"
+	hUserOptions := "options_user_handler"
+	admin.GET("/users/:id", hUserGet)
+	admin.PUT("/users/:id", hUserPut)
+	admin.DELETE("/users/:id", hUserDel)
+	admin.PATCH("/users/:id", hUserPatch)
+	admin.HEAD("/users/:id", hUserHead)
+	admin.OPTIONS("/users/:id", hUserOptions)
+
+	hCustom := "custom_handler"
+	admin.Handle("CUSTOM", "/custom", hCustom)
+
+	hAny := "any_handler"
+	anyRoutes := admin.Any("/all", hAny)
+	assert.NotEmpty(t, anyRoutes)
+
+	// Group.Routes() returns root routes
+	assert.Equal(t, r.Routes(), admin.Routes())
+
+	routes := r.Routes()
+
+	// Verify route paths and middlewares
+	var foundOrderGet bool
+	var foundUserPut bool
+	for _, route := range routes {
+		if route.Method == "GET" && route.Path == "/api/v1/orders" {
+			foundOrderGet = true
+			assert.Equal(t, []any{mGlobal, mAPI, "api_extra_middleware"}, route.Middlewares)
+			assert.Equal(t, []any{hList}, route.Handlers)
+		}
+		if route.Method == "PUT" && route.Path == "/api/v1/admin/users/:id" {
+			foundUserPut = true
+			assert.Equal(t, []any{mGlobal, mAPI, "api_extra_middleware", mAdmin}, route.Middlewares)
+			assert.Equal(t, []any{hUserPut}, route.Handlers)
+		}
+	}
+	assert.True(t, foundOrderGet)
+	assert.True(t, foundUserPut)
+}
+
+func TestMigrationExtension(t *testing.T) {
+	m := extpoints.NewMigrationRegistry()
+	require.NotNil(t, m)
+
+	fs1 := fstest.MapFS{
+		"migrations/001_init.sql": &fstest.MapFile{Data: []byte("CREATE TABLE t1(id int);")},
+	}
+	fs2 := fstest.MapFS{
+		"custom/001_order.sql": &fstest.MapFile{Data: []byte("CREATE TABLE t2(id int);")},
+	}
+
+	m.Register("auth", fs1)
+	m.Register("order", fs2, "custom")
+
+	// Update existing entry
+	fs1Updated := fstest.MapFS{
+		"migrations/002_update.sql": &fstest.MapFile{Data: []byte("ALTER TABLE t1 ADD col int;")},
+	}
+	m.Register("auth", fs1Updated, "")
+
+	entries := m.Entries()
+	require.Len(t, entries, 2)
+	assert.Equal(t, "auth", entries[0].PluginID)
+	assert.Equal(t, "migrations", entries[0].Dir)
+	assert.Equal(t, "order", entries[1].PluginID)
+	assert.Equal(t, "custom", entries[1].Dir)
+
+	authEntry, ok := m.Get("auth")
+	assert.True(t, ok)
+	assert.Equal(t, "auth", authEntry.PluginID)
+
+	_, ok = m.Get("non_existent")
+	assert.False(t, ok)
+}
+
+func TestTaskExtension(t *testing.T) {
+	tr := extpoints.NewTaskRegistry()
+	require.NotNil(t, tr)
+
+	handler := func(ctx context.Context, payload []byte) error { return nil }
+
+	tr.Register("order:cancel_timeout", handler,
+		extpoints.WithTaskConcurrency(5),
+		extpoints.WithTaskRetry(3),
+		extpoints.WithTaskTimeout(10*time.Second),
+		extpoints.WithTaskMetadata("queue", "critical"),
+		nil, // test nil option
+	)
+
+	// Re-register to test update
+	tr.Register("order:cancel_timeout", handler,
+		extpoints.WithTaskConcurrency(10),
+		extpoints.WithTaskMetadata("queue", "high"),
+	)
+
+	tasks := tr.Tasks()
+	require.Len(t, tasks, 1)
+	assert.Equal(t, "order:cancel_timeout", tasks[0].Pattern)
+	assert.Equal(t, 10, tasks[0].Concurrency)
+	assert.Equal(t, "high", tasks[0].Metadata["queue"])
+
+	task, ok := tr.Get("order:cancel_timeout")
+	assert.True(t, ok)
+	assert.Equal(t, "order:cancel_timeout", task.Pattern)
+
+	_, ok = tr.Get("unknown")
+	assert.False(t, ok)
+}
+
+func TestScheduleExtension(t *testing.T) {
+	sr := extpoints.NewScheduleRegistry()
+	require.NotNil(t, sr)
+
+	type ReportPayload struct {
+		Type string `json:"type"`
+	}
+
+	sr.RegisterCron("0 2 * * *", "report:daily_summary", ReportPayload{Type: "daily"})
+	sr.Register("@every 1h", "cleanup:expired_sessions", nil,
+		extpoints.WithScheduleOption("retry", 2),
+		nil, // test nil option
+	)
+
+	// Re-register to test update
+	sr.RegisterCron("0 3 * * *", "report:daily_summary", ReportPayload{Type: "all"})
+
+	schedules := sr.Schedules()
+	require.Len(t, schedules, 2)
+
+	assert.Equal(t, "0 3 * * *", schedules[0].Spec)
+	assert.Equal(t, "report:daily_summary", schedules[0].TaskType)
+	assert.Equal(t, ReportPayload{Type: "all"}, schedules[0].Payload)
+
+	assert.Equal(t, "@every 1h", schedules[1].Spec)
+	assert.Equal(t, "cleanup:expired_sessions", schedules[1].TaskType)
+	assert.Equal(t, 2, schedules[1].Options["retry"])
+
+	sched, ok := sr.Get("report:daily_summary")
+	assert.True(t, ok)
+	assert.Equal(t, "0 3 * * *", sched.Spec)
+
+	_, ok = sr.Get("unknown")
+	assert.False(t, ok)
+}
+
+func TestSettingExtension(t *testing.T) {
+	sr := extpoints.NewSettingRegistry()
+	require.NotNil(t, sr)
+
+	assert.Panics(t, func() {
+		sr.Register(extpoints.SettingSchema{}) // empty key panics
+	})
+
+	sr.Register(extpoints.SettingSchema{
+		Key:         "order.auto_cancel_mins",
+		Default:     15,
+		Description: "Order auto cancellation timeout in minutes",
+		Category:    "order",
+		Public:      true,
+	})
+
+	// Re-register to test update
+	sr.Register(extpoints.SettingSchema{
+		Key:         "order.auto_cancel_mins",
+		Default:     30,
+		Description: "Updated timeout",
+	})
+
+	sr.Register(extpoints.SettingSchema{
+		Key:         "auth.jwt_secret",
+		Default:     "default-secret",
+		Description: "JWT secret key",
+		Category:    "auth",
+		ReadOnly:    true,
+	})
+
+	schemas := sr.Schemas()
+	require.Len(t, schemas, 2)
+
+	schema, ok := sr.Get("order.auto_cancel_mins")
+	assert.True(t, ok)
+	assert.Equal(t, 30, schema.Default)
+
+	_, ok = sr.Get("unknown")
+	assert.False(t, ok)
+}
+
+func TestContextExtensionPointsIntegration(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+
+	require.NotNil(t, ctx.Events())
+	require.NotNil(t, ctx.Router())
+	require.NotNil(t, ctx.Migrations())
+	require.NotNil(t, ctx.Tasks())
+	require.NotNil(t, ctx.Task())
+	require.NotNil(t, ctx.Schedules())
+	require.NotNil(t, ctx.Schedule())
+	require.NotNil(t, ctx.Settings())
+	require.NotNil(t, ctx.Setting())
+
+	// Register from child context and verify shared application registry
+	child := ctx.Fork()
+	child.Router().GET("/ping", "pong_handler")
+	child.Task().Register("sample:task", "handler")
+	child.Schedule().RegisterCron("@hourly", "sample:cron", nil)
+	child.Settings().Register(extpoints.SettingSchema{
+		Key:     "app.name",
+		Default: "Wavelet",
+	})
+
+	assert.Len(t, ctx.Router().Routes(), 1)
+	assert.Len(t, ctx.Tasks().Tasks(), 1)
+	assert.Len(t, ctx.Schedules().Schedules(), 1)
+	assert.Len(t, ctx.Settings().Schemas(), 1)
+
+	// Child and root events
+	var eventReceived bool
+	child.Events().On("app:ready", func() {
+		eventReceived = true
+	})
+	err := ctx.Events().Emit(context.Background(), "app:ready", nil)
+	assert.NoError(t, err)
+	assert.True(t, eventReceived)
+}
@@ -0,0 +1,83 @@
+package extpoints
+
+import (
+	"io/fs"
+	"sync"
+)
+
+// MigrationEntry contains the migration filesystem and configuration for a plugin.
+type MigrationEntry struct {
+	PluginID string
+	FS       fs.FS
+	Dir      string
+}
+
+// MigrationExtension defines the interface for registering and querying plugin migrations.
+type MigrationExtension interface {
+	Register(pluginID string, fsys fs.FS, dir ...string)
+	Entries() []MigrationEntry
+	Get(pluginID string) (MigrationEntry, bool)
+}
+
+// MigrationRegistry collects and stores migration entries from plugins.
+type MigrationRegistry struct {
+	mu      sync.RWMutex
+	entries []MigrationEntry
+	lookup  map[string]MigrationEntry
+}
+
+// NewMigrationRegistry creates a new migration registry.
+func NewMigrationRegistry() *MigrationRegistry {
+	return &MigrationRegistry{
+		lookup: make(map[string]MigrationEntry),
+	}
+}
+
+// Register adds a migration entry for a plugin.
+// If dir is not specified, it defaults to "migrations".
+func (m *MigrationRegistry) Register(pluginID string, fsys fs.FS, dir ...string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	migrationDir := "migrations"
+	if len(dir) > 0 && dir[0] != "" {
+		migrationDir = dir[0]
+	}
+
+	entry := MigrationEntry{
+		PluginID: pluginID,
+		FS:       fsys,
+		Dir:      migrationDir,
+	}
+
+	// If entry already exists, update in-place; otherwise append
+	if _, exists := m.lookup[pluginID]; exists {
+		for i, e := range m.entries {
+			if e.PluginID == pluginID {
+				m.entries[i] = entry
+				break
+			}
+		}
+	} else {
+		m.entries = append(m.entries, entry)
+	}
+
+	m.lookup[pluginID] = entry
+}
+
+// Entries returns a copy of all registered migration entries in registration order.
+func (m *MigrationRegistry) Entries() []MigrationEntry {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	res := make([]MigrationEntry, len(m.entries))
+	copy(res, m.entries)
+	return res
+}
+
+// Get retrieves the migration entry for a specific plugin ID.
+func (m *MigrationRegistry) Get(pluginID string) (MigrationEntry, bool) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	e, ok := m.lookup[pluginID]
+	return e, ok
+}
@@ -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)
+}
@@ -0,0 +1,100 @@
+package extpoints
+
+import "sync"
+
+// ScheduleDefinition holds the configuration for a scheduled/cron task.
+type ScheduleDefinition struct {
+	Spec     string
+	TaskType string
+	Payload  any
+	Options  map[string]any
+}
+
+// ScheduleOption configures a ScheduleDefinition.
+type ScheduleOption func(*ScheduleDefinition)
+
+// WithScheduleOption adds a custom option to the schedule definition.
+func WithScheduleOption(key string, val any) ScheduleOption {
+	return func(sd *ScheduleDefinition) {
+		if sd.Options == nil {
+			sd.Options = make(map[string]any)
+		}
+		sd.Options[key] = val
+	}
+}
+
+// ScheduleExtension defines the interface for registering and querying cron/scheduled tasks.
+type ScheduleExtension interface {
+	Register(spec string, taskType string, payload any, opts ...ScheduleOption)
+	RegisterCron(spec string, taskType string, payload any, opts ...ScheduleOption)
+	Schedules() []ScheduleDefinition
+	Get(taskType string) (ScheduleDefinition, bool)
+}
+
+// ScheduleRegistry collects and manages schedule registrations.
+type ScheduleRegistry struct {
+	mu        sync.RWMutex
+	schedules []ScheduleDefinition
+	lookup    map[string]ScheduleDefinition
+}
+
+// NewScheduleRegistry creates a new schedule registry.
+func NewScheduleRegistry() *ScheduleRegistry {
+	return &ScheduleRegistry{
+		lookup: make(map[string]ScheduleDefinition),
+	}
+}
+
+// Register adds a schedule definition.
+func (s *ScheduleRegistry) Register(spec string, taskType string, payload any, opts ...ScheduleOption) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	sd := ScheduleDefinition{
+		Spec:     spec,
+		TaskType: taskType,
+		Payload:  payload,
+		Options:  make(map[string]any),
+	}
+
+	for _, opt := range opts {
+		if opt != nil {
+			opt(&sd)
+		}
+	}
+
+	if _, exists := s.lookup[taskType]; exists {
+		for i, item := range s.schedules {
+			if item.TaskType == taskType {
+				s.schedules[i] = sd
+				break
+			}
+		}
+	} else {
+		s.schedules = append(s.schedules, sd)
+	}
+
+	s.lookup[taskType] = sd
+}
+
+// RegisterCron is an alias for Register.
+func (s *ScheduleRegistry) RegisterCron(spec string, taskType string, payload any, opts ...ScheduleOption) {
+	s.Register(spec, taskType, payload, opts...)
+}
+
+// Schedules returns a copy of all registered ScheduleDefinitions.
+func (s *ScheduleRegistry) Schedules() []ScheduleDefinition {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	res := make([]ScheduleDefinition, len(s.schedules))
+	copy(res, s.schedules)
+	return res
+}
+
+// Get retrieves a schedule definition by its task type.
+func (s *ScheduleRegistry) Get(taskType string) (ScheduleDefinition, bool) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	sd, ok := s.lookup[taskType]
+	return sd, ok
+}
@@ -0,0 +1,77 @@
+package extpoints
+
+import "sync"
+
+// SettingSchema defines the configuration schema and metadata for a system or plugin setting.
+type SettingSchema struct {
+	Key         string `json:"key"`
+	Default     any    `json:"default"`
+	Description string `json:"description"`
+	Type        string `json:"type,omitempty"`
+	ReadOnly    bool   `json:"read_only,omitempty"`
+	Public      bool   `json:"public,omitempty"`
+	Category    string `json:"category,omitempty"`
+	Validation  string `json:"validation,omitempty"`
+}
+
+// SettingExtension defines the interface for registering and querying setting configuration schemas.
+type SettingExtension interface {
+	Register(schema SettingSchema)
+	Schemas() []SettingSchema
+	Get(key string) (SettingSchema, bool)
+}
+
+// SettingRegistry collects and manages setting configuration schemas.
+type SettingRegistry struct {
+	mu      sync.RWMutex
+	schemas []SettingSchema
+	lookup  map[string]SettingSchema
+}
+
+// NewSettingRegistry creates a new setting schema registry.
+func NewSettingRegistry() *SettingRegistry {
+	return &SettingRegistry{
+		lookup: make(map[string]SettingSchema),
+	}
+}
+
+// Register registers a SettingSchema into the registry.
+// Panics if the schema Key is empty.
+func (s *SettingRegistry) Register(schema SettingSchema) {
+	if schema.Key == "" {
+		panic("core/extpoints: setting schema key cannot be empty")
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if _, exists := s.lookup[schema.Key]; exists {
+		for i, item := range s.schemas {
+			if item.Key == schema.Key {
+				s.schemas[i] = schema
+				break
+			}
+		}
+	} else {
+		s.schemas = append(s.schemas, schema)
+	}
+
+	s.lookup[schema.Key] = schema
+}
+
+// Schemas returns a copy of all registered SettingSchemas.
+func (s *SettingRegistry) Schemas() []SettingSchema {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	res := make([]SettingSchema, len(s.schemas))
+	copy(res, s.schemas)
+	return res
+}
+
+// Get retrieves a SettingSchema by its key.
+func (s *SettingRegistry) Get(key string) (SettingSchema, bool) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	schema, ok := s.lookup[key]
+	return schema, ok
+}
@@ -0,0 +1,119 @@
+package extpoints
+
+import (
+	"sync"
+	"time"
+)
+
+// TaskDefinition holds the definition and runtime options for an asynchronous background task.
+type TaskDefinition struct {
+	Pattern     string
+	Handler     any
+	Concurrency int
+	Retry       int
+	Timeout     time.Duration
+	Metadata    map[string]any
+}
+
+// TaskOption configures a TaskDefinition.
+type TaskOption func(*TaskDefinition)
+
+// WithTaskConcurrency sets the concurrency limit for the task.
+func WithTaskConcurrency(concurrency int) TaskOption {
+	return func(td *TaskDefinition) {
+		td.Concurrency = concurrency
+	}
+}
+
+// WithTaskRetry sets the maximum retry count for the task.
+func WithTaskRetry(retry int) TaskOption {
+	return func(td *TaskDefinition) {
+		td.Retry = retry
+	}
+}
+
+// WithTaskTimeout sets the execution timeout for the task.
+func WithTaskTimeout(timeout time.Duration) TaskOption {
+	return func(td *TaskDefinition) {
+		td.Timeout = timeout
+	}
+}
+
+// WithTaskMetadata adds a key-value pair to the task metadata.
+func WithTaskMetadata(key string, val any) TaskOption {
+	return func(td *TaskDefinition) {
+		if td.Metadata == nil {
+			td.Metadata = make(map[string]any)
+		}
+		td.Metadata[key] = val
+	}
+}
+
+// TaskExtension defines the interface for registering and querying background task handlers.
+type TaskExtension interface {
+	Register(pattern string, handler any, opts ...TaskOption)
+	Tasks() []TaskDefinition
+	Get(pattern string) (TaskDefinition, bool)
+}
+
+// TaskRegistry collects and manages task registrations.
+type TaskRegistry struct {
+	mu     sync.RWMutex
+	tasks  []TaskDefinition
+	lookup map[string]TaskDefinition
+}
+
+// NewTaskRegistry creates a new task registry.
+func NewTaskRegistry() *TaskRegistry {
+	return &TaskRegistry{
+		lookup: make(map[string]TaskDefinition),
+	}
+}
+
+// Register registers a task pattern and its handler with optional configuration.
+func (t *TaskRegistry) Register(pattern string, handler any, opts ...TaskOption) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	td := TaskDefinition{
+		Pattern:  pattern,
+		Handler:  handler,
+		Metadata: make(map[string]any),
+	}
+
+	for _, opt := range opts {
+		if opt != nil {
+			opt(&td)
+		}
+	}
+
+	if _, exists := t.lookup[pattern]; exists {
+		for i, item := range t.tasks {
+			if item.Pattern == pattern {
+				t.tasks[i] = td
+				break
+			}
+		}
+	} else {
+		t.tasks = append(t.tasks, td)
+	}
+
+	t.lookup[pattern] = td
+}
+
+// Tasks returns a copy of all registered TaskDefinitions.
+func (t *TaskRegistry) Tasks() []TaskDefinition {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+	res := make([]TaskDefinition, len(t.tasks))
+	copy(res, t.tasks)
+	return res
+}
+
+// Get retrieves a task definition by its pattern.
+func (t *TaskRegistry) Get(pattern string) (TaskDefinition, bool) {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+	td, ok := t.lookup[pattern]
+	return td, ok
+}