sdk

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 23, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EventUserCreated     = auth.EventUserCreated
	EventUserSignedIn    = auth.EventUserSignedIn
	EventUserSignedOut   = auth.EventUserSignedOut
	EventSessionCreated  = auth.EventSessionCreated
	EventSessionRevoked  = auth.EventSessionRevoked
	EventPasswordChanged = auth.EventPasswordChanged
	EventEmailVerified   = auth.EventEmailVerified
)

Common core event names re-exported for plugin convenience.

Variables

View Source 
var (
	// ErrNotFound is returned when a requested capability or module is not found.
	ErrNotFound = errors.New("plugin-sdk: not found")
	// ErrDuplicate is returned when a module or capability is registered more than once.
	ErrDuplicate = errors.New("plugin-sdk: duplicate registration")
	// ErrPluginDependency is returned when a required plugin dependency is missing or cyclic.
	ErrPluginDependency = errors.New("plugin-sdk: dependency error")
)
View Source 
var (
	// ErrAdapterNotConfigured is returned when attempting to access the database without an active adapter.
	ErrAdapterNotConfigured = errors.New("sdk db: adapter not configured")
)

Functions

func Adapt 

func Adapt(m Module) auth.PluginModule

Adapt converts an sdk.Module into an auth.PluginModule acceptable by core auth.New.

func Provide 

func Provide[T any](ctx *Context, impl T) error

Provide registers impl as the strongly typed capability T exposed by the module. T is usually an interface exported by the plugin; applications retrieve it with auth.Get[T](engine).

Types

type Context 

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

Context provides the host runtime environment and services to a plugin module. It acts as the isolation boundary so plugins only interact with public infrastructure contracts and never private core internals.

func NewContext 

func NewContext(host *auth.Host) *Context

NewContext creates a new plugin context wrapping the host runtime.

func NewTestContext 

func NewTestContext(ad adapter.Adapter, c cache.Cache, em email.Sender) *Context

NewTestContext creates a standalone test Context with injected adapters.

func (*Context) Adapter 

func (c *Context) Adapter() adapter.Adapter

Adapter returns the generic schema-driven storage adapter, or nil if none is configured.

func (*Context) Cache 

func (c *Context) Cache() cache.Cache

Cache returns the shared cache adapter, or nil when none is configured. Plugins must namespace their cache keys.

func (*Context) Core 

func (c *Context) Core() *auth.Auth

Core returns the Auth engine instance.

func (*Context) DB 

func (c *Context) DB() *DB

DB returns the typed database access facade.

func (*Context) Email 

func (c *Context) Email() email.Sender

Email returns the transactional email sender, or nil when none is configured.

func (*Context) Events 

func (c *Context) Events() *auth.Events

Events returns the event dispatcher for subscribing to or emitting events.

func (*Context) Get 

func (c *Context) Get(key string) (any, bool)

Get retrieves a value by key from the contextual execution bag. It is safe for concurrent use.

func (*Context) Hooks 

func (c *Context) Hooks() *auth.Hooks

Hooks returns the workflow hooks registry for intercepting auth workflows.

func (*Context) Host 

func (c *Context) Host() *auth.Host

Host returns the underlying core Host instance.

func (*Context) Logger 

func (c *Context) Logger() *slog.Logger

Logger returns a structured logger scoped and tagged with the module ID.

func (*Context) ModuleID 

func (c *Context) ModuleID() string

ModuleID returns the ID of the plugin module.

func (*Context) Now 

func (c *Context) Now() time.Time

Now returns the current time according to the host clock.

func (*Context) Schema 

func (c *Context) Schema() *schema.Schema

Schema returns the compiled database schema, or nil if none is active.

func (*Context) Set 

func (c *Context) Set(key string, val any)

Set stores a key-value pair in the contextual execution bag. It is safe for concurrent use.

func (*Context) StandardContext 

func (c *Context) StandardContext() context.Context

StandardContext returns a background context.Context.

func (*Context) Store 

func (c *Context) Store() store.Store

Store returns the core store (bridged from adapter when necessary).

type DB 

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

DB is the database access client exposed to plugin modules.

func (*DB) Adapter 

func (db *DB) Adapter() adapter.Adapter

Adapter returns the underlying generic storage adapter.

type Dependent 

type Dependent interface {
	Dependencies() []string
}

Dependent is implemented by plugins that declare dependencies on other plugin modules.

type Error 

type Error struct {
	Kind    ErrorKind
	Message string
	Err     error
}

Error represents a categorized plugin error that transport adapters can map to HTTP/gRPC codes.

func NewError 

func NewError(kind ErrorKind, message string, err error) *Error

NewError creates a categorized plugin error.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type ErrorKind 

type ErrorKind int

ErrorKind classifies domain errors into architectural categories for transport adapters. 

const (
	KindUnknown ErrorKind = iota
	KindValidation
	KindNotFound
	KindConflict
	KindUnauthorized
	KindForbidden
	KindInternal
)

func (ErrorKind) String 

func (k ErrorKind) String() string

type Event 

type Event = auth.Event

Event is the event structure dispatched by the core engine.

type EventHandler 

type EventHandler = auth.EventHandler

EventHandler is the callback invoked when an event is published.

type EventName 

type EventName = auth.EventName

EventName represents the typed event identifier.

type HTTPClient 

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient abstracts outgoing HTTP request execution, allowing custom transports, telemetry decoration, and mock execution in unit tests without starting real network servers. It is satisfied by *http.Client.

type HookFunc 

type HookFunc[T any] func(ctx context.Context, payload T) error

HookFunc is a generic synchronous workflow interception function for plugin-defined hooks.

type HookRegistry 

type HookRegistry[T any] struct {
	// contains filtered or unexported fields
}

HookRegistry provides registration and execution for plugin-defined workflow hooks.

func NewHookRegistry 

func NewHookRegistry[T any]() *HookRegistry[T]

NewHookRegistry creates a new hook registry for payload type T.

func (*HookRegistry[T]) Execute 

func (r *HookRegistry[T]) Execute(ctx context.Context, payload T) error

Execute runs all registered hooks sequentially. Aborts on the first error.

func (*HookRegistry[T]) Register 

func (r *HookRegistry[T]) Register(fn HookFunc[T])

Register appends a hook function to the registry.

type Hooks 

type Hooks = auth.Hooks

Hooks aliases the Core workflow hooks registry.

type Lifecycle 

type Lifecycle = auth.Lifecycle

Lifecycle defines optional lifecycle callbacks that a plugin module can implement. It is an alias to auth.Lifecycle for seamless backward compatibility.

type Migration 

type Migration struct {
	Version     int
	Description string
	Up          func(ctx context.Context) error
	Down        func(ctx context.Context) error
}

Migration represents a single schema or data migration step.

type MigrationProvider 

type MigrationProvider interface {
	Migrations() []Migration
}

MigrationProvider is optionally implemented by modules that require database schema migrations.

type Module 

type Module interface {
	// ID returns the unique identifier for the plugin module.
	ID() string
	// Init initializes the plugin module within the given SDK context.
	Init(ctx *Context) error
}

Module is the interface that every plugin module using the SDK must implement.

func ResolveInitOrder 

func ResolveInitOrder(modules []Module) ([]Module, error)

ResolveInitOrder sorts modules topologically so dependencies initialize before dependents.

type Repository 

type Repository[T any] struct {
	// contains filtered or unexported fields
}

Repository provides a strongly typed generic data access contract over a specific model.

func For 

func For[T any](db *DB, modelName string) *Repository[T]

For creates a typed Repository from a DB instance.

func FromAdapter 

func FromAdapter[T any](a adapter.Adapter, modelName string) *Repository[T]

FromAdapter creates a typed Repository directly from an adapter (e.g. inside a transaction).

func Model 

func Model[T any](c *Context, modelName string) *Repository[T]

Model returns a typed Repository for the specified model using the plugin context.

Usage: 

repo := sdk.Model[FactorRecord](ctx, "two_factors")
record, err := repo.FindOne(ctx, adapter.Eq("user_id", uid))

func (*Repository[T]) Count 

func (r *Repository[T]) Count(ctx context.Context, where ...adapter.Condition) (int64, error)

Count returns the count of matching records.

func (*Repository[T]) Create 

func (r *Repository[T]) Create(ctx context.Context, entity *T) error

Create inserts a typed entity into the model.

func (*Repository[T]) Delete 

func (r *Repository[T]) Delete(ctx context.Context, where ...adapter.Condition) (int64, error)

Delete removes matching records from the model.

func (*Repository[T]) FindMany 

func (r *Repository[T]) FindMany(ctx context.Context, q adapter.Query) ([]T, error)

FindMany returns all entities matching the query.

func (*Repository[T]) FindOne 

func (r *Repository[T]) FindOne(ctx context.Context, where ...adapter.Condition) (*T, error)

FindOne returns the first entity matching all given conditions.

func (*Repository[T]) Update 

func (r *Repository[T]) Update(ctx context.Context, where []adapter.Condition, update map[string]any) (int64, error)

Update modifies matching records in the model.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.