authlite

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

authlite

The shape of a library that owns tables. A deliberately small stand-in for a real one, small enough to read in a sitting and complete enough that every extension mechanism is visible.

It owns auth_user and auth_identity, renders SQL for whatever dialect it is given, and executes only through the DBTX the caller hands it — so the recipes run without a driver.

What a library exports

Four things, and they are the whole public contract:

  • Tables and typed columns, as package-level values. sqlb.Col[string](TableUser, ColID) is an Expr[string]; another package can compare it, join on it and bind it, and can do nothing else with it. Adding a column is a minor version; renaming one is a major version.
  • A bindings function, UserBindings(dst *User) []sqlb.Binding. A function rather than a slice, because each binding captures a pointer into dst.
  • Name constants, so the migration file and the column declarations spell auth_user once, and a rename is one edit.
  • Query methods that accept sqlb.Option, so the application can add a join, a filter or a column the library has never heard of.

The three mechanisms worth reading

A rule no option can remove. NotBanned() is the single definition of "which users are visible", written into the WHERE before Apply(opts...) runs. Options only ever add, so there is no option that takes it back out. That is the property a library needs before it can safely accept extensions at all.

A destination the application declares. Composite is an interface with Joins() and Bindings(). LoadUserQuery takes one and builds a statement over whatever tables the application named — so the library joins to tables it cannot see, and the compiler still checks every condition. app is the implementation.

Hooks inside the transaction. SignUp takes the caller's DBTX and passes that same DBTX to AfterSignUp, so the application's row and the library's row commit or roll back together. The caller owns the transaction; the library never begins one.

What it is not

Not an auth library. There is no password handling, no session, no token, and the one INSERT is a raw string because the recipe it serves is about the hook, not about the write. Read ubgo/auth for the real thing; read this for the shape.

Documentation

Overview

Package authlite is a deliberately small stand-in for a ubgo library that owns tables, for the cookbook. It shows the library-author side of every extension mechanism: exported tables and columns, a bindings function, queries that accept sqlb.Option, a Composite destination, mandatory predicates that options cannot remove, and hooks that receive the transaction. It renders SQL and executes only through the DBTX it is given, so the cookbook runs without a driver.

Index

Constants

View Source
const (
	TableNameUser     = "auth_user"
	TableAliasUser    = "u"
	TableNameIdentity = "auth_identity"
	TableAliasIdent   = "i"

	ColID        = "id"
	ColEmail     = "primary_email"
	ColBannedAt  = "banned_at"
	ColCreatedAt = "created_at"

	ColIdentUserID = "user_id"
	ColIdentKind   = "kind"
	ColIdentValue  = "value"
)

Table and column names. Constants so a rename is one edit and the migration file can reference the same names.

Variables

View Source
var (
	TableUser     = sqlb.Table{Name: TableNameUser, Alias: TableAliasUser}
	TableIdentity = sqlb.Table{Name: TableNameIdentity, Alias: TableAliasIdent}
)

Tables owned by the core. Package-level because a plugin in another module declares its join against them at init time.

View Source
var (
	UserID        = sqlb.Col[string](TableUser, ColID)
	UserEmail     = sqlb.Col[string](TableUser, ColEmail)
	UserBannedAt  = sqlb.Col[*time.Time](TableUser, ColBannedAt)
	UserCreatedAt = sqlb.Col[time.Time](TableUser, ColCreatedAt)
)

Typed columns on auth_user. These, with UserBindings, are the public API. Adding one is a minor version; renaming or removing one is a major version.

Typed columns on auth_identity.

Functions

func NotBanned

func NotBanned() sqlb.Predicate

NotBanned is the single definition of the rule. Every listing query includes it and no Option can remove it, because options only add.

func UserBindings

func UserBindings(dst *User) []sqlb.Binding

UserBindings binds every core column to dst. A function, not a slice, because each binding holds a pointer into dst.

Types

type Auth

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

Auth is the library handle: dialect, hooks, and the query methods.

func New

func New(opts ...Option) *Auth

New wires the handle. In the real library this is where plugin aliases are checked for collisions and configuration is validated.

func (*Auth) AdminUserListQuery

func (a *Auth) AdminUserListQuery(limit, offset int, dst *User, opts ...sqlb.Option) (sqlb.Query, error)

AdminUserListQuery is the paginated listing, open to the application through opts. NotBanned is written before Apply and survives every option.

func (*Auth) LoadUserQuery

func (a *Auth) LoadUserQuery(userID string, dst Composite) (sqlb.Query, error)

LoadUserQuery returns the core user plus every column the composite adds, in one statement.

func (*Auth) Select

func (a *Auth) Select() *sqlb.AnySelect

Select starts a statement in the configured dialect.

func (*Auth) SignUp

func (a *Auth) SignUp(ctx context.Context, tx sqlb.DBTX, id, email string) (*User, error)

SignUp writes the user through tx, then runs AfterSignUp through the same tx. The caller owns the transaction: it began it and it commits or rolls back on the returned error.

func (*Auth) UserByEmailQuery

func (a *Auth) UserByEmailQuery(email string, dst *User) (sqlb.Query, error)

UserByEmailQuery is the login lookup. Both sides go through lower() to match the uniqueness index.

type Composite

type Composite interface {
	Joins() []sqlb.Join
	Bindings() []sqlb.Binding
}

Composite is a destination whose shape the application declares: the core user plus whatever plugins and application tables it composes.

type Hooks

type Hooks struct {
	AfterSignUp func(ctx context.Context, tx sqlb.DBTX, e *SignUpEvent) error
}

Hooks are the application's write points inside the library's transaction. Each receives the DBTX the library is writing through, so the application's row and the library's row commit or roll back together.

type IdentifierKind

type IdentifierKind string

IdentifierKind names the kind of an identity row. A named string type so a plugin cannot pass an arbitrary string variable as a kind.

const (
	KindEmail IdentifierKind = "email"
	KindPhone IdentifierKind = "phone"
)

The identifier kinds the core knows. A plugin adding a kind adds it here, so the closed set stays in one place.

type Option

type Option func(*Auth)

Option configures New.

func WithDialect

func WithDialect(d sqlb.Dialect) Option

WithDialect sets the engine. Required.

func WithHooks

func WithHooks(h Hooks) Option

WithHooks installs the application's hooks.

type SignUpEvent

type SignUpEvent struct {
	User *User
}

SignUpEvent is passed to the AfterSignUp hook.

type User

type User struct {
	ID        string
	Email     string
	BannedAt  *time.Time
	CreatedAt time.Time
}

User is the core's own columns and nothing reached by a join.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL