plugins

type Aegis ¶

type Aegis interface {
	GetAuthService() *core.AuthService                                                      // Returns the auth service for user operations
	GetLogger() config.Logger                                                               // Returns the configured logger (may be nil)
	GetRateLimiter() *core.RateLimiter                                                      // Returns the rate limiter (may be nil)
	DeriveSecret(purpose string) []byte                                                     // Derives a purpose-specific secret from the master secret
	DB() *sql.DB                                                                            // Returns the database connection for schema validation
	ValidateSchemaRequirements(ctx context.Context, requirements []SchemaRequirement) error // Validates schema requirements
	GetPlugin(name string) (Plugin, bool)                                                   // Returns a registered plugin by name (for inter-plugin communication)
}

Aegis is the interface that plugins use to interact with the Aegis framework. Uses one generic parameter for the User model (U). Account, Session, and Verification models are standard across the framework.

type Dependency ¶

type Dependency struct {
	Package string // Go package import path
	Version string // Required version (e.g., "v1.2.3" or "latest")
	Purpose string // Why this dependency is needed
}

Dependency represents an external package dependency.

type Dialect ¶

type Dialect = config.Dialect

Dialect is an alias for config.Dialect.

type EnrichedUser ¶

type EnrichedUser = core.EnrichedUser

EnrichedUser is re-exported from core for plugin convenience

func GetEnrichedUser(ctx context.Context) *EnrichedUser

type HealthChecker ¶ added in v1.5.0

type HealthChecker interface {
	Health(ctx context.Context) error
}

HealthChecker is an optional interface for plugins that can report their own health. Aegis itself does not poll this automatically; it is intended for use by readiness / liveness handlers or monitoring integrations.

Example:

func (p *Plugin) Health(ctx context.Context) error {
    return p.store.Ping(ctx)
}

type Migration ¶

type Migration struct {
	Version     int    // Migration version (e.g., 001, 002)
	Description string // Human-readable description
	Up          string // SQL for applying migration
	Down        string // SQL for reverting migration
}

Migration represents a database migration for a plugin.

type Plugin ¶

type Plugin interface {
	// Identity
	Name() string        // Plugin identifier (e.g., "sms", "oauth", "email")
	Version() string     // Plugin version
	Description() string // Human-readable description

	// Lifecycle
	Init(ctx context.Context, a Aegis) error // Initialize plugin with Aegis instance
	GetMigrations() []Migration              // Return plugin-specific migrations

	// Routing
	MountRoutes(router router.Router, prefix string) // Register HTTP routes

	// Metadata
	Dependencies() []Dependency    // External Go package dependencies (library-level, not inter-plugin)
	RequiresTables() []string      // Core tables this plugin reads from (used for schema validation in Init)
	ProvidesAuthMethods() []string // Auth method identifiers this plugin enables (e.g. "oauth_google", "jwt")
}

Plugin is the interface that all plugins must implement. Simplified to one generic parameter (U).

func Get(name string) (Plugin, bool)

func List() []Plugin

type PluginData ¶

type PluginData = core.PluginData

PluginData is re-exported from core for plugin convenience

func GetPluginData(ctx context.Context) *PluginData

type PluginMinAegisVersion ¶ added in v1.5.0

type PluginMinAegisVersion interface {
	MinAegisVersion() string
}

PluginMinAegisVersion is an optional interface for plugins that require a minimum version of the Aegis framework itself. Aegis checks this at Use/UseWithPriority time and returns an error if the running aegis.Version is below the declared minimum.

Example:

func (p *Plugin) MinAegisVersion() string { return "1.1.0" }

type PluginRequires ¶ added in v1.5.0

type PluginRequires interface {
	Requires() []string
}

PluginRequires is an optional interface for plugins that depend on other plugins being registered first. When a plugin implementing this interface is registered via Aegis.Use / Aegis.UseWithPriority, Aegis validates that every name returned by Requires is already registered.

Example:

func (a *Plugin) Requires() []string {
    return []string{"organizations"}
}

type PluginShutdown ¶ added in v1.5.0

type PluginShutdown interface {
	Shutdown(ctx context.Context) error
}

PluginShutdown is an optional interface for plugins that hold resources requiring cleanup (goroutines, connections, timers). Aegis calls Shutdown on all plugins that implement this interface when Aegis.Shutdown is invoked, in reverse priority order (highest priority number first).

Example implementation (JWT key-rotation goroutine):

func (p *Plugin) Shutdown(ctx context.Context) error {
    p.stopKeyRotation()
    return nil
}

type PluginVersionRequires ¶ added in v1.5.0

type PluginVersionRequires interface {
	VersionedRequires() []VersionedRequirement
}

PluginVersionRequires is an optional interface for plugins that need a specific minimum version of another plugin. Aegis checks this at Use/UseWithPriority time: the required plugin must already be registered AND its Version() must satisfy the declared MinVersion.

Use this instead of (or alongside) PluginRequires when the API contract of the required plugin changed between versions and you need to enforce compatibility.

Example:

func (p *Plugin) VersionedRequires() []plugins.VersionedRequirement {
    return []plugins.VersionedRequirement{
        {Plugin: "oauth", MinVersion: "2.0.0"},
    }
}

type RequestMeta ¶

type RequestMeta = core.RequestMeta

RequestMeta is re-exported from core for plugin convenience

func GetRequestMeta(ctx context.Context) *RequestMeta

type SchemaRequirement ¶

type SchemaRequirement = core.SchemaRequirement

SchemaRequirement defines a schema validation requirement

type UserEnricher ¶

type UserEnricher interface {
	// EnrichUser adds plugin-specific data to the enriched user.
	// Called after authentication to populate extension fields.
	// Use simple field names (e.g., "role", not "admin:role").
	EnrichUser(ctx context.Context, user *core.EnrichedUser) error
}

UserEnricher is an optional interface that plugins can implement to add extension fields to the EnrichedUser. Plugins that implement this interface will have their EnrichUser method called after authentication to populate user-specific data (role, permissions, organizations, etc.).

Example implementation:

func (a *Admin) EnrichUser(ctx context.Context, user *core.EnrichedUser) error {
    role, err := a.store.GetRole(ctx, user.ID)
    if err == nil && role != "" {
        user.Set("role", role)
    }
    return nil
}

func GetUserEnricher(p Plugin) (UserEnricher, bool)

type VersionedRequirement ¶ added in v1.5.0

type VersionedRequirement struct {
	Plugin     string // Name of the required plugin (matches Plugin.Name())
	MinVersion string // Minimum acceptable semver, e.g. "2.0.0"
}

VersionedRequirement specifies a plugin dependency with a minimum version constraint. Used by PluginVersionRequires to declare version-aware inter-plugin dependencies.