maniflex

Annotated Go structs in. A full REST API out.

maniflex is a Go framework that turns a plain struct into a production REST API — filtering, pagination, relations, soft-delete, file uploads, and an OpenAPI 3.1 spec — with no generated code and no per-endpoint boilerplate. Behaviour is declared with mfx: struct tags and customised through a composable six-step middleware pipeline.

type Post struct {
    maniflex.BaseModel
    maniflex.WithDeletedAt
    Title  string `json:"title"  mfx:"required,filterable,sortable"`
    Body   string `json:"body"   mfx:"required"`
    Status string `json:"status" mfx:"required,filterable,enum:draft|published|archived"`
    UserID string `json:"user_id" mfx:"required,filterable"`
}

Register that struct and you get GET/POST /posts, GET/PATCH/DELETE /posts/{id}, ?filter=status:eq:published, ?sort=title:asc, ?page=2&limit=20, ?include=user, soft-delete semantics, and an entry in /openapi.json.

Why maniflex

• Reflection, not codegen. Register a struct at startup; routes, schema, and validation are derived from it at runtime. Nothing to regenerate when a field changes.
• One module, two dependencies. The core maniflex module depends only on chi and uuid. Postgres, Redis, Kafka, NATS, bcrypt and friends live in satellite modules you pull in only if you import them.
• A pipeline you can reach into. Every request flows through six ordered steps — Auth → Deserialize → Validate → Service → DB → Response. Hook middleware Before, After, or Replace at any step, scoped by model or operation.
• Batteries included, swappable. Ready-made middleware for JWT auth, unique validation, password hashing, multi-tenancy, audit logging, CORS, and more — each one just a function you can replace.
• SQLite or Postgres. Both backends share one SQL adapter. Develop against pure-Go SQLite (no CGo, no external service), deploy on Postgres.

Core concepts

Five ideas carry the whole framework. Understand these and the rest of the docs slot into place.

Model

A Go struct that embeds maniflex.BaseModel and declares its fields with mfx: struct tags. The struct is the single source of truth: it defines the database table, the JSON request and response shapes, the validation rules, and which fields are filterable or sortable. Optional embeds add behaviour — maniflex.WithDeletedAt turns on soft-delete — and naming conventions like a UserID field declare relations. → Models & BaseModel, Field Tags Reference, Relations

Registry

The collection of every registered model, built by MustRegister at startup. It is consumed in two places: the HTTP router reads it to mount routes, and the DB adapter reads it to run migrations and resolve relations. This is why MustRegister must run before sqlite.Open / postgres.Open — the adapter is handed the populated registry. → Getting Started

Pipeline

Six ordered steps every request flows through: Auth → Deserialize → Validate → Service → DB → Response. The pipeline is the unit of customisation — instead of writing handlers, you attach middleware to the step where your logic belongs. → Pipeline Overview, ServerContext

Middleware

A func(ctx *maniflex.ServerContext, next func() error) error registered on a pipeline step. Registration is scoped with maniflex.ForModel(...) and maniflex.ForOperation(...), and positioned with maniflex.AtPosition(maniflex.After) (or maniflex.Before, the default, or maniflex.Replace). Set ctx.Response and return without calling next() to short-circuit the request. → Writing Middleware, Middleware Catalogue

Adapter

The database backend implementing the storage interface. Two ship in-tree — db/sqlite (pure-Go, no CGo) and db/postgres — and both share one SQL core. Inject one with server.SetDB(db), which patches the pipeline’s DB step in place. → Database Backends, Transactions

Where to go next

• Getting Started — install, define your first model, run the server.
• Models & Tags — the full mfx: tag reference and relation conventions.
• The Pipeline — how requests flow and where to hook in.
• Middleware Catalogue — ready-made middleware for every step.
• Querying the API — filtering, sorting, pagination, includes.

maniflex requires Go 1.25.12 or newer.

Getting Started

This guide takes you from an empty directory to a running REST API with a filterable, paginated posts resource — in about five minutes and roughly thirty lines of Go.

Prerequisites

• Go 1.25.12 or newer — check with go version.
• That’s it. The first example uses the pure-Go SQLite backend, so there is no database server to install and no CGo toolchain to configure.

1. Create the project

mkdir blog && cd blog
go mod init blog
go get github.com/xaleel/maniflex

maniflex itself pulls in only two dependencies — chi and uuid. The SQLite adapter lives in its own satellite module, so add it explicitly:

go get github.com/xaleel/maniflex/db/sqlite

2. Define a model

A model is a plain struct that embeds maniflex.BaseModel. The mfx: struct tags declare how each field behaves — what’s required, what can be filtered, what can be sorted.

Create main.go:

package main

import (
    "log"

    "github.com/xaleel/maniflex"
    "github.com/xaleel/maniflex/db/sqlite"
)

type Post struct {
    maniflex.BaseModel
    Title  string `json:"title"  mfx:"required,filterable,sortable"`
    Body   string `json:"body"   mfx:"required"`
    Status string `json:"status" mfx:"required,filterable,enum:draft|published|archived"`
}

maniflex.BaseModel contributes the id, created_at, and updated_at fields, so you never declare them yourself. See Field Tags Reference for every tag and Models & BaseModel for the embeds.

3. Wire up the server

Registration order matters: models must be registered before the database is opened, because the SQLite adapter needs the registry to run migrations and resolve relations.

func main() {
    // 1. Create the server — no DB yet.
    server := maniflex.New(maniflex.Config{
        Port:        8080,
        PathPrefix:  "/api",
    })

    // 2. Register models — this populates the registry.
    // BaseModel's columns are readonly and nothing more, so opt created_at
    // into the query surface to sort by it.
    server.MustRegister(Post{}, maniflex.ModelConfig{
        BaseModelTags: map[string]string{"created_at": "filterable,sortable"},
    })

    // 3. Open SQLite with the populated registry.
    db, err := sqlite.Open("./blog.db", server.Registry())
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // 4. Inject the adapter into the pipeline.
    server.SetDB(db)

    // 5. Serve.
    if err := server.Start(); err != nil {
        log.Fatal(err)
    }
}

Migration (on by default) creates and updates tables to match your structs on startup — convenient for development. For an in-memory database that resets on every run, pass ":memory:" to sqlite.Open.

4. Run it

go run .

The server is now listening on :8080, and Post{} has a full set of routes mounted under the /api prefix:

5. Make some requests

Create a post:

curl -X POST localhost:8080/api/posts \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello","body":"First post","status":"published"}'

List, filter, sort, and paginate — all from the query string:

# Only published posts
curl 'localhost:8080/api/posts?filter=status:eq:published'

# Newest first, ten per page
curl 'localhost:8080/api/posts?sort=created_at:desc&page=1&limit=10'

Filtering and sorting only work on fields tagged filterable / sortable — that’s why Title and Status carry those tags above. BaseModel’s id, created_at and updated_at are readonly and nothing more, so they opt in through ModelConfig.BaseModelTags at registration instead of a struct tag — that’s the config passed to MustRegister above. The full filter grammar is in Querying.

What you get for free

From that one struct, maniflex derived:

• Five REST endpoints with JSON request/response handling.
• Field validation (required, enum) on every write.
• Query-string filtering, sorting, and pagination.
• A generated table kept in sync by AutoMigrate.
• An OpenAPI 3.1 document ready to mount explicitly through Config.Documentation.

No generated code, no per-endpoint handlers.

Where to go next

• Quickstart Tutorial — build a small app end to end.
• Models & BaseModel — relations, soft-delete, file fields.
• The Request Pipeline — the six steps every request flows through, and where to hook in your own middleware.
• Querying — the full filter, sort, and include grammar.
• Database Backends — switching from SQLite to PostgreSQL.

App Anatomy

A maniflex app has very little machinery of its own — the framework derives routes, schema, and validation from your structs, so the code you write is mostly models and middleware. This page shows how to lay that code out, starting from a single file and growing into packages as the app gets bigger.

The smallest app

A maniflex app is just a package main that does four things in order:

package main

import (
    "log"

    "github.com/xaleel/maniflex"
    "github.com/xaleel/maniflex/db/sqlite"
)

type Message struct {
    maniflex.BaseModel
    Title string `json:"title" mfx:"required,filterable,sortable"`
}

func main() {
    server := maniflex.New(maniflex.Config{Port: 8080, PathPrefix: "/api"})
    server.MustRegister(Message{})

    if db, err := sqlite.Open("./app.db", server.Registry()); err == nil {
        defer db.Close()
        server.SetDB(db)
    } else {
        log.Fatal(err)
    }

    if err := server.Start(); err != nil {
        log.Fatal(err)
    }
}

Four steps — create server → register models → open and set DB → serve. Everything below is about where the code for each step lives as the app grows. The ordering is load-bearing: MustRegister must run before sqlite.Open, because the adapter is handed the populated registry. See Getting Started.

A typical project layout

Once an app has more than a handful of models, split it into packages by responsibility, not by model. A layout that scales well:

myapp/
├── go.mod
├── main.go               # wiring only: create, register, set DB, serve
├── config.go             # maniflex.Config assembly, env-var reading
├── models/               # one file per model — the structs and their tags
│   ├── user.go
│   ├── post.go
│   └── comment.go
├── middleware/            # custom pipeline middleware
│   ├── auth.go
│   ├── audit.go
│   └── register.go        # attaches all middleware to the pipeline
└── internal/              # non-framework code: services, clients, helpers
    └── mailer/
    └── ...

Nothing here is enforced by the framework — maniflex never scans directories. It is a convention that keeps each file answering one question.

What goes in each file

main.go — wiring, nothing else

main.go should read top-to-bottom as the four-step sequence and contain no business logic. Its whole job is to assemble the pieces and call Start():

func main() {
    server := maniflex.New(config.Load())

    server.MustRegister(
        models.User{},
        models.Post{},
        models.Comment{},
    )

    db, err := sqlite.Open("./app.db", server.Registry())
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()
    server.SetDB(db)

    middleware.Register(server)   // all pipeline hooks, in one place

    if err := server.Start(); err != nil {
        log.Fatal(err)
    }
}

If you can’t see the four steps at a glance, something belongs in another file.

config.go — building maniflex.Config

Keep maniflex.Config construction — and any environment-variable reading — out of main.go. A single Load() function makes the app’s knobs easy to find:

package config

func Load() maniflex.Config {
    return maniflex.Config{
        Port:        envInt("PORT", 8080),
        PathPrefix:  "/api",
        DisableAutoMigrate: env("APP_ENV", "dev") == "production",
    }
}

See Configuration for every maniflex.Config field.

models/ — one file per model

Each file holds one struct, its mfx: tags, and the relation fields that point at other models. This is the heart of the app — the struct is the table, the JSON shape, and the validation rules all at once.

// models/post.go
package models

type Post struct {
    maniflex.BaseModel
    maniflex.WithDeletedAt                       // opt-in soft-delete
    Title  string `json:"title"  mfx:"required,filterable,sortable"`
    Body   string `json:"body"   mfx:"required"`
    Status string `json:"status" mfx:"required,filterable,enum:draft|published|archived"`

    UserID   string    `json:"user_id"  mfx:"required,filterable"` // BelongsTo User
    Comments []Comment `json:"comments,omitempty"`                 // HasMany
}

Put model-spanning relations in whichever file is the “owning” side and let Go’s package scope resolve the rest — all models share the models package, so Post can reference Comment freely. See Models & BaseModel, Field Tags Reference, and Relations.

middleware/ — your pipeline hooks

A middleware is a func(ctx *maniflex.ServerContext, next func() error) error. Group related hooks per file (auth.go, audit.go), and keep one register.go that attaches them all — so there is exactly one place to see how the request pipeline has been customised:

// middleware/register.go
package middleware

func Register(s *maniflex.Server) {
    s.Pipeline.Auth.Register(bearerToken,
        maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete))

    s.Pipeline.Service.Register(hashPassword,
        maniflex.ForModel("User"),
        maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate))

    s.Pipeline.DB.Register(auditLog,
        maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
        maniflex.AtPosition(maniflex.After))
}

The middleware functions themselves live in their topic files. See Writing Middleware and the Middleware Catalogue for hooks that already ship with the framework.

internal/ — everything that isn’t maniflex

Code that has nothing to do with the framework — a mail client, a payment SDK wrapper, domain calculations — goes under internal/. Middleware in the Service step calls into these packages; the packages themselves never import maniflex. This keeps the framework-facing layer thin and your business logic unit-testable on its own.

Structuring a large monolith

The layer-based layout above (models/, middleware/) stays readable up to a few dozen models. Past that, a flat models/ directory with sixty files and a main.go that names every one of them becomes the bottleneck. Large maniflex codebases switch from splitting by layer to splitting by domain.

Domain packages

Give each business domain its own package that owns all of its code — models, middleware, and business logic together:

myapp/
├── main.go
├── domains/
│   ├── auth/
│   │   ├── models.go        # User, Role, Session, ApiKey
│   │   ├── middleware.go    # token auth, password hashing
│   │   └── register.go      # exports Models and Register(s)
│   ├── catalog/
│   │   ├── models.go        # Product, Category, Variant
│   │   ├── middleware.go
│   │   └── register.go
│   └── orders/
│       ├── models.go        # Order, LineItem, Invoice, Refund
│       ├── middleware.go
│       └── register.go
└── internal/

A new feature now touches one directory instead of being smeared across models/, middleware/, and internal/.

Registering models in groups

server.Register (and MustRegister) is variadic and flattens any slice argument — so each domain can export its models as a single slice, and main.go registers the slices side by side:

// domains/auth/register.go
package auth

// Models is every model this domain owns. One list, one place to update.
var Models = []any{
    User{},
    Role{},
    Session{},
    ApiKey{},
}

// main.go
server.MustRegister(
    auth.Models,      // each argument is a []any —
    catalog.Models,   // Register flattens them into individual models
    orders.Models,
)

main.go no longer grows when a domain gains a model; only that domain’s Models slice changes. To register everything as one list instead, concatenate the slices: append(append(auth.Models, catalog.Models...), orders.Models...).

Registering middleware in groups

Apply the same idea to the pipeline. Each domain exposes its own Register(s *maniflex.Server), and the top-level middleware registration just calls each one — exactly the shape in the request from a growing app:

// domains/orders/register.go
package orders

// Register attaches every pipeline hook this domain needs.
func Register(s *maniflex.Server) {
    s.Pipeline.Validate.Register(checkStock, maniflex.ForModel("Order"))
    s.Pipeline.Service.Register(chargePayment,
        maniflex.ForModel("Order"), maniflex.ForOperation(maniflex.OpCreate))
    s.Pipeline.DB.Register(emitOrderEvent,
        maniflex.ForModel("Order"), maniflex.AtPosition(maniflex.After))
}

// main.go (or a thin top-level middleware/register.go)
func registerMiddleware(s *maniflex.Server) {
    auth.Register(s)
    catalog.Register(s)
    orders.Register(s)
}

Each domain controls its own pipeline hooks; the top-level function is just a table of contents.

Co-locating per-model middleware

For middleware that belongs to exactly one model, skip the separate Register call entirely — ModelConfig.Middleware lets you attach hooks at registration time, scoped to that model automatically:

server.MustRegister(
    Order{}, maniflex.ModelConfig{
        Middleware: &maniflex.ModelMiddleware{
            Validate: []maniflex.MiddlewareFunc{checkStock},
            Service:  []maniflex.MiddlewareFunc{chargePayment},
        },
    },
)

This keeps a model and its rules in one declaration — useful when the hook is meaningless without the model.

Conventions that keep a big monolith honest

• One registration point per concern. Exactly one place lists the model groups, and one lists the middleware groups. If you can’t find where a model is registered, the structure has drifted.
• Domains depend inward, never sideways. A domain may import internal/ and maniflex; it should not import a sibling domain. Cross-domain relations are expressed by FK fields (a string UserID), which need no import.
• internal/ holds framework-free logic. Payment, mail, and pricing code lives here and never imports maniflex, so it stays unit-testable in isolation.
• main.go stays a fixed size. Adding a domain adds one line to each registration list and nothing else. If main.go grows with the app, logic has leaked into it.

How a request moves through the files

Tracing one POST /api/posts shows why the layout is split this way:

1. The router (built from the registry in main.go) matches the route.
2. The request enters the pipeline — Auth → Deserialize → Validate → Service → DB → Response.
3. At each step, the hooks from middleware/register.go run, scoped by model and operation.
4. Validate checks the mfx: tags declared in models/post.go.
5. Service middleware may call into internal/ for business logic.
6. The adapter injected via SetDB runs the SQL at the DB step.

Each file owns one stage of that journey — which is exactly why a growing app stays readable.

Where to go next

• Example 1: Simple Blog — this layout filled in for a real three-model app.
• The Request Pipeline — the six steps in depth.
• Configuration — every maniflex.Config field.

Example 1: Simple Blog

This is the first worked example: a small blog API built end to end. It uses only what the previous pages covered — models and mfx: tags, the four-step setup, and SQLite. No relations, no middleware, no pipeline customisation yet; those arrive in later chapters. The goal is to see a complete, runnable app with nothing unexplained in it.

What we’re building

A blog with two independent resources:

• Post — an article with a title, body, and a publication status.
• Subscriber — an email address signed up for the newsletter.

The two are unrelated — each is its own table with its own endpoints — which keeps the example to concepts already introduced.

The whole app

The blog is small enough to live in a single main.go, the smallest-app shape from App Anatomy:

package main

import (
    "log"

    "github.com/xaleel/maniflex"
    "github.com/xaleel/maniflex/db/sqlite"
)

// Post is a blog article.
type Post struct {
    maniflex.BaseModel
    Title  string `json:"title"  mfx:"required,filterable,sortable"`
    Body   string `json:"body"   mfx:"required"`
    Status string `json:"status" mfx:"required,filterable,sortable,enum:draft|published|archived"`
}

// Subscriber is a newsletter sign-up.
type Subscriber struct {
    maniflex.BaseModel
    Email string `json:"email" mfx:"required,filterable"`
    Name  string `json:"name"  mfx:"filterable,sortable"`
}

func main() {
    // 1. Create the server.
    server := maniflex.New(maniflex.Config{
        Port:          8080,
        PathPrefix:    "/api",
        Documentation: maniflex.DocumentationConfig{Public: true},
    })

    // 2. Register both models — populates the registry.
    // Opt created_at into the query surface to sort by it.
    server.MustRegister(
        Post{}, maniflex.ModelConfig{
            BaseModelTags: map[string]string{"created_at": "filterable,sortable"},
        },
        Subscriber{},
    )

    // 3. Open SQLite with the populated registry, then inject it.
    db, err := sqlite.Open("./blog.db", server.Registry())
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()
    server.SetDB(db)

    // 4. Serve.
    if err := server.Start(); err != nil {
        log.Fatal(err)
    }
}

That is the entire blog. Run it:

go run .

Reading the models

Every field choice maps to a tag covered in Getting Started:

maniflex.BaseModel adds id, created_at, and updated_at to both structs, so those are never declared by hand. With migration on by default, the posts and subscribers tables are created to match on startup.

The endpoints you get

Registering the two structs mounts a full REST surface under /api:

Subscriber gets the identical five routes under /api/subscribers.

Using the API

Create a post

curl -X POST localhost:8080/api/posts \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello World","body":"My first post","status":"draft"}'

The response echoes the stored row, including the id and timestamps that BaseModel filled in.

Validation in action

Leave out a required field, or send a status outside the enum, and the write is rejected before it reaches the database:

# Missing body, and status is not in the enum
curl -X POST localhost:8080/api/posts \
  -H 'Content-Type: application/json' \
  -d '{"title":"Broken","status":"weekly"}'
# → 400, the response names the offending fields

Update and delete

# Publish the post — PATCH only sends the fields that change
curl -X PATCH localhost:8080/api/posts/<id> \
  -H 'Content-Type: application/json' \
  -d '{"status":"published"}'

curl -X DELETE localhost:8080/api/posts/<id>

List, filter, sort, paginate

All from the query string, on the fields tagged filterable / sortable:

# Only published posts
curl 'localhost:8080/api/posts?filter=status:eq:published'

# Newest first
curl 'localhost:8080/api/posts?sort=created_at:desc'

# Page two, five per page
curl 'localhost:8080/api/posts?page=2&limit=5'

# Combine them
curl 'localhost:8080/api/posts?filter=status:eq:published&sort=title:asc&limit=5'

Add a couple of subscribers and the same querying works there too:

curl -X POST localhost:8080/api/subscribers \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","name":"Ada"}'

curl 'localhost:8080/api/subscribers?sort=name:asc'

The API documents itself

You never wrote a schema, yet the server already publishes one. Alongside the model routes, maniflex auto-generates an OpenAPI 3.1 specification describing every endpoint, field, and validation rule — derived from the same structs and mfx: tags:

curl localhost:8080/api/openapi.json

The spec updates itself whenever a model changes; there is nothing to regenerate. To browse it as interactive documentation, the framework ships an HTML viewer in static/openapi.html that loads /api/openapi.json — open http://localhost:8080/static/openapi.html while the server is running.

The OpenAPI step is fully customisable later; see OpenAPI Spec.

What this example showed

• A complete, runnable app from two plain structs and a four-step main.
• mfx: tags driving validation (required, enum) and queryability (filterable, sortable).
• Multiple models registered in one call, each with an independent REST surface.
• Filtering, sorting, and pagination with no query code written.
• A self-updating OpenAPI 3.1 spec at /api/openapi.json.

Where to go next

Everything here treated the two models as separate islands. Real apps connect them — a post belongs to an author, a comment belongs to a post. That, and the mfx: tags beyond the basics, are the next chapters:

• Models & BaseModel — the embeds and what they contribute.
• Field Tags Reference — every mfx: tag.
• Relations — connecting models with foreign keys.

Architecture

This page explains how maniflex is put together. The reference pages describe each piece in isolation; here we look at how they fit. A reader who finishes this page should be able to point at any other doc and predict roughly what it covers.

The five pieces

                    ┌──────────────────────┐
        register →  │      Registry        │  ← models discovered here
                    └──────────────────────┘
                            │             │
                            │             ▼
                            │     ┌──────────────────────┐
                            │     │  Database adapter    │
                            │     │  (sqlite | postgres) │
                            │     └──────────────────────┘
                            ▼
                    ┌──────────────────────┐
                    │       Router         │  ← chi v5
                    └──────────────────────┘
                            │
                            ▼
HTTP request  →  ┌──────────────────────────────────────────────────┐
                 │  Pipeline:                                       │
                 │   Auth → Deserialize → Validate →                │
                 │   Service → DB → Response                        │
                 └──────────────────────────────────────────────────┘
                            │
                            ▼
HTTP response ← APIResponse envelope

The framework has five primary moving parts:

Every other concept in the docs sits on top of these five.

Reflection, not codegen

The framework derives everything from the registered structs at startup:

1. ScanModel walks the struct with reflect once per model, builds a *ModelMeta, and inserts it into the registry.
2. The adapter reads the registry to emit CREATE TABLE / ALTER TABLE statements during AutoMigrate.
3. The router reads the registry to mount the five REST routes per model plus /openapi.json.
4. The Validate step reads each request’s model meta to enforce mfx: tag rules.
5. The DB step reads each request’s model meta to assemble the SQL.

Reflection runs once at registration, never per request. The per-request path is allocation-light: a map[string]any for the body, a few string keys, and the slice of registered middleware filtered by ForModel / ForOperation. A model with N fields produces O(N) work at boot and O(N) work per request, both linear in the size of the model.

This is the architectural difference from codegen frameworks: there is no generated file to keep in sync. Changing a mfx: tag changes the runtime behaviour the next time the process starts.

The registry is the contract

Every other piece reads from the registry; nothing writes to it after Start(). That single rule explains several constraints:

• MustRegister must run before sqlite.Open / postgres.Open. The adapter reads the registry during its constructor to learn about tables and relations.
• Models cannot be added or removed at runtime. New models require a process restart.
• Models can be inspected from middleware via ctx.Model, which is the *ModelMeta the router selected for this request.
• Cross-model operations work because middleware reaches into the registry through ctx.GetModel(name) or by name in scoped registration.

The framework’s startup sequence is deliberate:

1. maniflex.New(cfg)            → empty registry
2. server.MustRegister(...) → populated registry
3. sqlite.Open(..., reg)    → adapter built from registry
4. server.SetDB(db)         → adapter wired into the DB step
5. middleware.Register(...) → pipeline customised
6. server.Start()           → router built from registry, listener opens

Start() runs AutoMigrate (if enabled) before opening the listener, so a schema mismatch fails fast instead of corrupting writes.

The pipeline is the unit of customisation

Every HTTP request to a model route is wrapped in a ServerContext and run through six steps in this order:

Each step has its own StepRegistry on server.Pipeline. A registration attaches a MiddlewareFunc at Before (the default), After, or Replace position, scoped by ForModel / ForOperation. At request time the registry returns the matching chain for the (model, operation) pair, the chain runs, and any step can short-circuit by setting ctx.Response and returning without calling next().

The pipeline is the answer to “where do I put X?”:

• Identity checks — Auth.
• Coerce types, strip unknown fields — Validate (Before).
• Hash passwords, set derived fields — Service.
• Bracket the DB call — DB (Before / After).
• Webhooks, events, audit log — DB (After).
• Headers, redactions, metrics — Response.

The same answer applies whether the code lives in a catalogue middleware, a custom function, or a per-model ModelConfig.Middleware.

The adapter is one interface

maniflex.DBAdapter has fewer than a dozen methods — FindByID, FindMany, Create, Update, Delete, BeginTx, Raw, Ping, plus the schema operations called by AutoMigrate. Two implementations ship:

• db/sqlite — pure-Go SQLite for development.
• db/postgres — lib/pq for production.

Both implementations share db/sqlcore, a SQL adapter that knows about filters, sorts, includes, soft delete, and relations. A custom backend — an HTTP data service, a different SQL database — implements the same interface and is injected with server.SetDB(myAdapter). No other code changes.

The same holds for FileStorage and KeyProvider: small interfaces with shipped implementations and obvious extension points.

Satellite modules

maniflex is a multi-module repository. The core module imports only chi and uuid. Everything heavier — a database driver, a JWT library, a Kafka client, bcrypt — lives in its own satellite under the same root, so a consumer pulls in only the dependencies it actually imports.

The split keeps the core small and stable. It also keeps the trust boundary clear: the framework’s surface area is the maniflex package; everything in middleware/*, events/*, jobs/*, db/* is application code that happens to ship alongside the framework.

See Satellite Modules for the full layout and import rules.

Two pipelines, one router

The router actually mounts two pipelines.

The first one — the six-step pipeline described above — handles /<table> and /<table>/{id} for every registered model.

The second is a three-step pipeline for GET /openapi.json:

OpenAPI.Auth → OpenAPI.Generate → OpenAPI.Response

Generate derives the spec from the registry every time the endpoint is hit, then Response serialises it. After-position middleware on Generate can mutate the spec — change titles, add servers, install security schemes, or rewrite arbitrary fields. See OpenAPI Spec and the OpenAPI Middleware catalogue.

A third, trimmed pipeline runs for custom actions:

Auth → [per-action middleware] → handler → Response

The Deserialize, Validate, Service, and DB steps are skipped — actions own their body parsing and database work.

Where each feature lives in the lifecycle

For a single concrete trace of every step running on one request, see the Request Lifecycle walkthrough.

What maniflex is not

To set expectations on the architecture choice:

• Not codegen. No generated files, no separate build step.
• Not a router framework. The HTTP layer is chi; maniflex uses it.
• Not opinionated about JSON shape. The envelope is the default, but response.Envelope lets you replace it. Errors always use the error envelope.
• Not a service mesh. One process, one binary. Multi-process concerns (events, jobs, distributed locks) live in the satellite modules.
• Not magic. Every behaviour is a function in the maniflex package or one of the catalogue middlewares. Read the source when in doubt; the pipeline is small.

Next

• Request Lifecycle — a single POST /api/orders traced end-to-end through every step.
• Glossary — every framework term in one place.
• Pipeline Overview — the per-step reference.

Request Lifecycle

This page traces a single request through every piece of the framework. The example is a POST /api/orders on an authenticated user, with a Service middleware that hashes a derived field, a transaction wrapping the DB step, and an audit-log middleware on DB-After. It exercises the full pipeline without being contrived.

Setup

cfg.HTTPMiddlewares = append(cfg.HTTPMiddlewares,
    response.CORSHeaders("https://app.example.com"))
server := maniflex.New(cfg)

server.MustRegister(models.Order{})

server.Pipeline.Auth.Register(auth.JWTAuth("secret"))
server.Pipeline.Service.Register(
    maniflex.WithTransaction(nil),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
)
server.Pipeline.Service.Register(
    service.SetField("customer_id", func(ctx *maniflex.ServerContext) any {
        return ctx.Auth.UserID
    }),
    maniflex.ForModel("Order"), maniflex.ForOperation(maniflex.OpCreate),
)
server.Pipeline.DB.Register(
    db.AuditLog(sink, db.WithChanges()),
    maniflex.ForModel("Order"),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
)

The request

POST /api/orders HTTP/1.1
Authorization: Bearer eyJ...
Content-Type: application/json
Idempotency-Key: 2af9...

{"total": 42.50, "status": "pending"}

What happens, in order

1. The router selects the route

chi matches POST /api/orders to the sub-router mounted by mountModel for the Order model. The matched handler calls handler.Create(meta), which:

• Allocates a fresh *ServerContext.
• Sets ctx.Request, ctx.Writer, ctx.Ctx.
• Reads the X-Request-Id chi added in the outer middleware and stores it on ctx.RequestID.
• Reads the traceparent header (if present) into ctx.TraceID.
• Sets ctx.Model = meta for Order.
• Sets ctx.Operation = OpCreate.
• Leaves ctx.ResourceID empty — create has no path id.
• Calls Pipeline.execute(ctx).

If Config.QueryTimeout is non-zero, ctx.Ctx is wrapped in a context.WithTimeout here, so every downstream DB call inherits the deadline.

2. The Auth step runs

Pipeline.Auth.build("Order", OpCreate) returns a chain consisting of matching middleware in registration order, then the default Auth handler at the end (which is a passthrough).

For our setup the chain is just [auth.JWTAuth, defaultAuth]. JWTAuth:

• Reads the Authorization header.
• Verifies the signature with the configured secret.
• Parses the claims and populates ctx.Auth = &AuthInfo{UserID: …, Roles: …, TenantID: …}.
• Calls next() to continue.

A missing or invalid token would have produced ctx.Abort(401, "UNAUTHORIZED", …) and returned without next(), ending the request right here.

3. The Deserialize step runs

The default handler parses two things:

• Query parameters → ctx.Query (a *QueryParams). For a create, this is mostly empty — there are no filter or sort to read.
• Body. The Content-Type is application/json, so it reads up to 4 MB from ctx.Request.Body, sets ctx.RawBody to the raw bytes, and parses the JSON into the read-only ctx.ParsedBody (a *RequestBody):

// ctx.ParsedBody now holds { "total": 42.5, "status": "pending" }
total, _ := ctx.Field("total")   // 42.5
status, _ := ctx.Field("status") // "pending"

The same values are bound to the typed record ctx.Record; middleware mutate either through ctx.SetField / ctx.DeleteField. The two are not the same gesture: SetField(name, nil) writes the column as NULL, which is how you discard a value the client sent, while DeleteField(name) leaves the column out of the write entirely.

If the Content-Type had been multipart/form-data, the default handler would route through parseMultipart instead, populating ctx.ParsedBody with form fields and ctx.Files with the file parts.

After-position middleware on Deserialize (e.g. idempotency.Middleware, which sees ctx.RawBody) runs next. With idempotency configured, the middleware would compute a body hash and either replay a cached response or fall through to step 4.

4. The Validate step runs

The default handler iterates ctx.Model.Fields and applies the mfx: tag rules to ctx.ParsedBody:

• id is stripped — the adapter assigns it.
• readonly fields (created_at, updated_at) are stripped.
• immutable fields are stripped if OpUpdate — not on create.
• required fields must be present. total and status are required; the request supplies both, so no error.
• enum membership is checked on status — "pending" is in the allowed set, so no error.
• min / max are checked on numeric fields when present.

If any rule had failed, the step would have called ctx.Abort(422, "VALIDATION_ERROR", …) with details: [...] listing the bad fields.

Custom Validate middleware (none in this example) would run alongside the default — Before middleware first, then the default, then After.

5. The Service step runs

Two middleware are scoped to this request:

maniflex.WithTransaction(nil) runs first:

• Sees ctx.Tx == nil.
• Calls ctx.BeginTx(ctx.Ctx, nil), which delegates to the adapter.
• Assigns the resulting Tx to ctx.Tx and re-wraps ctx.Ctx with the tx stored under txContextKey{}.
• Defers tx.Rollback() — a no-op after Commit.
• Calls next() to run the rest of the pipeline inside the transaction.

service.SetField("customer_id", ...) runs second:

• Resolves the callback against ctx.Auth.UserID.
• Calls ctx.SetField("customer_id", "user-alice"), writing through to both ctx.ParsedBody and the typed ctx.Record.
• Calls next().

6. The DB step runs

The default DB step calls defaultSteps.db:

• Sees ctx.Tx != nil and constructs a dbExec{adapter, tx: ctx.Tx}.
• Builds the DB-column write set from the typed ctx.Record (falling back to toDBMap(ctx.ParsedBody) for bodies the record can’t represent); here the column names match the JSON keys.
• If the model had mfx:"encrypted" fields, calls encryptFields to replace plaintexts with enc:<base64> envelopes and write {field}_hmac companions for unique ones.
• Dispatches by ctx.Operation:

result, err := exec.Create(ctx.Ctx, model, dbData)

exec.Create on a transactional dbExec calls tx.Create(...), which runs INSERT INTO orders (...) RETURNING * (Postgres) or INSERT ... ; SELECT ... (SQLite).

The adapter returns the inserted row as a map[string]any. The DB step assigns it to ctx.DBResult.

If the adapter returned maniflex.ErrNotFound, the step would abort with 404 NOT_FOUND. *maniflex.ErrConstraint becomes 409 CONFLICT. A context-cancelled error becomes 504 TIMEOUT when a server-side deadline expired, or 499 when the client simply hung up. Any other adapter error becomes 500 DB_ERROR.

6a. Audit-log Before middleware

We registered db.AuditLog at the default Before position (because WithChanges() needs to read the pre-image). On OpCreate there is no pre-image, so the middleware merely sets up to collect the post-image. It calls next(), which runs the rest of the chain — the default DB handler above.

After next() returns and ctx.Response is still nil (the create succeeded), the middleware:

• Reads ctx.DBResult for the inserted row.
• Builds an AuditRecord with model, operation, actor (ctx.Auth.UserID), tenant, request id, trace id, and a diff of every changed field.
• Spawns a goroutine that calls sink.Write(bgCtx, record). Audit writes are fire-and-forget — a sink error never fails the request.

7. WithTransaction commits

Control returns to WithTransaction (because we are inside its next() call). It checks:

• next() returned nil → no pipeline error.
• ctx.Response == nil or < 400 → no aborted step.
• Calls tx.Commit(). The deferred Rollback is now a no-op.
• Runs any callbacks registered with ctx.AfterCommit — the write is durable, so the side effects that were waiting on it may fire.
• Clears ctx.Tx so any post-commit code uses the bare adapter.

If next() had returned an error, or if any step had set ctx.Response to a status >= 400, Commit would have been skipped and the deferred Rollback would have fired — and the AfterCommit callbacks would have been dropped rather than run, since the write they announce did not happen.

8. The Response step runs

The default Response handler:

• Sees ctx.Response == nil.
• Sees ctx.Operation == OpCreate.
• Builds:

ctx.Response = &APIResponse{
    StatusCode: http.StatusCreated,
    Data:       toJSONMap(ctx.DBResult.(map[string]any), model),
}

toJSONMap converts DB column names back to JSON field names and applies hidden and writeonly filtering — any column tagged those is dropped from the response shape.

After-position middleware on Response runs next. CORS is deliberately absent from this step: response.CORSHeaders wraps the HTTP router, adding the appropriate Access-Control-* headers before routing and Auth. A valid browser preflight already returned 204 No Content before this pipeline began.

9. The envelope is written to the wire

APIResponse.Write(ctx.Writer):

• Sets Content-Type: application/json.
• Writes the status code header (201 Created).
• Encodes {"data": {...}} to the response body.
• Returns.

chi’s RequestID middleware (registered at the router root, outside the maniflex pipeline) wraps the whole exchange — it has already set X-Request-Id on the response by the time we get here. Maniflex’s trusted-proxy resolver is registered alongside it only when Config.TrustProxyHeaders is set, so RemoteAddr reflects the forwarded client IP just for servers that opted into trusting proxy headers.

The dispatch cleanup

After the response is written, the handler runs its cleanup phase:

• Closes any open multipart file readers in ctx.Files.
• Removes the multipart temporary directory.
• Lets the *ServerContext go out of scope; it is garbage-collected with the request.

The framework does not pool or reuse ServerContext values. The per-request allocation is small; the simplicity is worth more than the saved allocations.

What changes for other operations

Different operations exercise slightly different paths:

• OpRead / OpList — Validate runs but is a no-op (it only fires for create/update). The DB step calls FindByID or FindMany. Response for List wraps with meta: {total, page, limit, pages}.
• OpUpdate — Like create, but ctx.ResourceID is set, immutable fields are stripped in Validate, and the DB step calls Update. The audit middleware fetches the pre-image before next() so the Changes diff has both sides.
• OpDelete — No body to deserialize, no Validate work. The DB step calls Delete (which becomes a soft-delete UPDATE for models with WithDeletedAt). The default Response is 204 No Content.
• OpAction — The trimmed pipeline runs Auth → action middleware → handler → Response. The handler is responsible for its own body parsing, validation, and database calls.
• /openapi.json — A separate three-step pipeline (OpenAPI.Auth → Generate → Response) builds the spec from the registry every time, then writes the JSON document.

What happens on errors

Three error paths at every step:

A transaction in flight is rolled back by WithTransaction’s deferred Rollback in all three cases — the same code path that handles success.

What this tour did not show

• Multi-tenant scoping with db.Tenancy — would have appended to ctx.Query.Filters in step 5/6.
• mfx:"file" uploads — would have parsed multipart in step 3 and written bytes to FileStorage between steps 5 and 6.
• mfx:"scheduled" — fires outside the request, in a separate Scheduled Runner goroutine.
• mfx:"versioned" — would have written a sibling history row in step 6’s After phase, in the same transaction.
• The OpenAPI pipeline — same shape, three steps, separate registrations.

Each of those is covered in its own page; the lifecycle in step-by-step form is the same.

Models & BaseModel

A model is a Go struct registered with the server. From it, maniflex derives a database table, the JSON request and response shapes, the set of REST routes, and the validation applied to every write. This page covers what a struct must contain to be a valid model, how it maps to a table, and the options available at registration. Field-level tags are documented in Field Tags Reference; relationships in Relations.

Definition

A model is an ordinary struct that embeds maniflex.BaseModel:

type Article struct {
    maniflex.BaseModel
    Title string `json:"title" mfx:"required,filterable,sortable"`
    Body  string `json:"body"  mfx:"required"`
}

Registration validates the struct and adds it to the registry:

server.MustRegister(Article{})

Register returns an error; MustRegister panics on failure and is intended for use in main or package initialisation. A struct is rejected at registration if it is not a struct type or does not embed BaseModel.

Register every model before the first call to Handler or Start. That call atomically seals the server’s routes, specifications, and middleware pipeline. A later Register returns maniflex.ErrRegistrationClosed without changing the registry; MustRegister panics on the same error. Actions, rollups, computed fields, realtime documentation, global search, storage, and pipeline middleware share the same setup window.

Two embedding rules are enforced there as well:

• Embed by value, never by pointer. *maniflex.BaseModel — or any other pointer embed — is left nil by the record scanner, so every field access through it panics on the first request. It is refused at registration instead.
• Two fields cannot map to the same column. A field shadowing one of BaseModel’s columns produced two entries with the same DB name, and the framework then disagreed with itself about which was meant: lookups took the first, writes took the last. Rename one, or give it an explicit db:"...".

BaseModel

Every model must embed maniflex.BaseModel. It contributes three columns common to all tables:

type BaseModel struct {
    ID        string    `json:"id"         db:"id"         mfx:"readonly"`
    CreatedAt time.Time `json:"created_at" db:"created_at" mfx:"readonly"`
    UpdatedAt time.Time `json:"updated_at" db:"updated_at" mfx:"readonly"`
}

• ID — the primary key, a UUIDv4 string assigned by the framework on create. What that guarantees, and what it rules out, is the Record Identity contract.
• CreatedAt — set once, when the row is created.
• UpdatedAt — refreshed on every update.

All three are managed by the framework and all three are readonly: values supplied for them in a request body are ignored rather than stored — including id, so a client cannot choose the primary key. Because they are part of BaseModel, they are never declared on individual models.

A struct that does not embed BaseModel — or otherwise lacks an id column — fails registration.

Querying the BaseModel columns

readonly is the only default. None of the three columns is filterable or sortable unless the model says so — filterable and sortable widen a model’s public query surface, and that is a decision each model makes rather than inherits.

BaseModel lives in the framework, so its struct tags are the one place you cannot edit. ModelConfig.BaseModelTags is the knob instead:

server.MustRegister(Post{}, maniflex.ModelConfig{
    BaseModelTags: map[string]string{
        "id":         "filterable,sortable",
        "created_at": "filterable,sortable,index",
    },
})

Keys are DB column names; values use the same comma-separated syntax as an mfx struct tag. Each column accepts only the options meaningful for it:

Anything else is a registration error. index is not offered on id because id is the primary key and already indexed, so the option would only add a redundant duplicate.

Options are unioned onto readonly, never replacing it. There is no way to make created_at client-writable through this — a form that let readonly fall off by omission would turn a typo into a silently writable timestamp.

Without the opt-in, ?sort=created_at:desc and ?filter=created_at:gte:... return 400, and the error names BaseModelTags as the fix.

Keyset pagination. cursor_field:created_at requires created_at to be sortable, and does not grant it implicitly — so a model using it needs the matching BaseModelTags entry too. Registration fails with an explanatory error if you write one half without the other.

Field mapping

Each exported field of a model maps to a database column. Three struct tags control the mapping:

A minimal field needs only a json tag; db is derived and mfx is optional. The mfx tag is the largest of the three and has its own reference in Field Tags Reference. Fields that name a related model — for example a UserID foreign key — are interpreted as relations; see Relations.

Nullability is the Go type

A pointer field gets a NULL column; everything else gets NOT NULL. No tag controls this — the type is the whole declaration:

type Note struct {
    maniflex.BaseModel
    Title string  `json:"title"`  // NOT NULL — cannot be null
    Body  *string `json:"body"`   // NULL     — may be null
}

That decides what a request may send. {"body": null} stores SQL NULL; {"title": null} is refused with 422 naming the field, because the column has no null to store:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [{
      "field": "title",
      "message": "field \"title\" cannot be null; its type has no null value — send a value, omit the field, or make it a pointer to allow null"
    }]
  }
}

Three things are distinct and stay distinct: null (refused unless the field is a pointer), "" (a value, stored as written), and omitting the key (leaves the stored value alone on a PATCH).

If you need to tell “empty” from “not set”, make the field a pointer. A non-pointer field genuinely cannot represent the difference — it reads back as the zero value either way.

Note the corollary for anything reading the database directly: because every non-pointer field is NOT NULL, NOT NULL says nothing about whether a value is required, and the zero value rather than NULL is what “absent” means. If you are writing a migration script, a reporting query, or another service against a maniflex schema, read Field Schema & Nullability first — that distinction has cost real data.

Table names

By default the table name is the struct name converted to snake_case and pluralised:

A short list of Latin and Greek stems inflect classically — analysis, basis, axis, diagnosis, thesis (and hypothesis), datum, medium, matrix, vertex, criterion, phenomenon — including inside a compound name, so BloodAnalysis becomes blood_analyses. Everything else takes the English ending: album → albums, complex → complexes, and index → indexes, since that is the plural the database world uses.

To use a different name, pass a ModelConfig with TableName set when registering:

server.MustRegister(
    Article{}, maniflex.ModelConfig{TableName: "articles"},
)

TableName is also how you pin an existing table whose generated name has changed — see the v0.3.0 note in the changelog if you have a model named after one of the stems above.

Registration options

ModelConfig carries per-model options. All fields are optional; an omitted ModelConfig applies the defaults described above.

Optimistic locking (OptimisticLock)

When OptimisticLock: true, every PATCH and DELETE request that includes an If-Match header is checked against the current record’s ETag before the write executes. A mismatch returns 412 Precondition Failed (PRECONDITION_FAILED). Requests without If-Match are unaffected — the flag opts in to enforcement, not mandatory locking.

The ETag format is identical to the one emitted by response.Cache (MD5 of the JSON response body), so clients can use the header from a preceding GET directly:

server.MustRegister(Invoice{}, maniflex.ModelConfig{OptimisticLock: true})

server.Pipeline.Response.Register(
    response.Cache(response.CacheConfig{MaxAge: 300}),
    maniflex.ForModel("Invoice"),
    maniflex.ForOperation(maniflex.OpRead),
    maniflex.AtPosition(maniflex.After),
)

GET  /invoices/42          → 200  ETag: "d41d8cd9..."
PATCH /invoices/42         If-Match: "d41d8cd9..."  → 200
PATCH /invoices/42         If-Match: "stale"        → 412
PATCH /invoices/42         If-Match: *              → 200
PATCH /invoices/99         If-Match: *              → 404  (no such record)

If-Match: * is the RFC 9110 wildcard: it holds for any existing record, so it means “overwrite whatever is there, but do not create it” rather than pinning a particular version. It still takes the row lock, so it is safe to use on a contended record — it just does not care which version it lands on.

The check and the write it guards run as a single transaction, with the record held under a row lock (SELECT … FOR UPDATE on Postgres) from the ETag comparison until the write commits. Two clients holding the same ETag therefore cannot both succeed: the loser waits on the lock, then re-reads a record whose ETag has moved on and gets its 412. When the request already runs inside a transaction (maniflex.WithTransaction) the guard joins it and the lock is held until that transaction commits; otherwise the DB step opens and commits one of its own.

Singleton models (Singleton)

Some resources are inherently single-row: an application config record, a set of feature flags, the banner an admin edits and every client reads at launch. With Singleton: true the model drops its collection and item routes and exposes just two endpoints on the bare table path — no id in the URL:

GET   /:model   → read the one row
PATCH /:model   → update the one row

There is no POST, DELETE, or list endpoint; requesting them returns 405 Method Not Allowed, and there is no /:model/:id subtree.

The single backing row is provisioned lazily under the well-known maniflex.SingletonID on first access, from each column’s default. So the first GET returns defaults before anything has been written, and PATCH always targets an existing row — it behaves like an upsert:

type AppConfig struct {
    maniflex.BaseModel
    MaintenanceMode bool   `json:"maintenance_mode" mfx:"default:false"`
    MinAppVersion   string `json:"min_app_version"  mfx:"default:1.0.0"`
    Banner          string `json:"banner"`
}

server.MustRegister(
    AppConfig{}, maniflex.ModelConfig{Singleton: true, TableName: "config"},
)

GET   /config                                  → 200  {"data":{"id":"singleton","maintenance_mode":false,"min_app_version":"1.0.0","banner":""}}
PATCH /config   {"maintenance_mode": true}     → 200  {"data":{"id":"singleton","maintenance_mode":true, ...}}
GET   /config                                  → 200  (reflects the update)
POST  /config                                  → 405

Because the row is auto-provisioned from column defaults, a singleton model may not declare mfx:"required" fields — there would be no value to satisfy them on first access. Such a model is rejected at registration. Give fields sensible mfx:"default:…" values (or make them pointers) instead.

One row per tenant

The example above is one row for the whole application. The other common shape is one row per tenant — a storefront, a profile, a per-org settings record — which is near-universal in B2B SaaS.

You get it by scoping the model the same way you scope any other: register a db.Tenancy or db.ForceFilter for it on the DB step. The singleton then resolves and provisions the caller’s row rather than a global one.

type StoreSite struct {
    maniflex.BaseModel
    OwnerID string `json:"owner_id" db:"owner_id" mfx:"filterable,unique,default:"`
    Banner  string `json:"banner"                 mfx:"default:untitled"`
}

server.MustRegister(StoreSite{}, maniflex.ModelConfig{Singleton: true})

server.Pipeline.DB.Register(
    db.Tenancy("owner_id", func(ctx *maniflex.ServerContext) string {
        return ctx.Auth.Claims["owner_id"].(string)
    }),
    maniflex.ForModel("StoreSite"),
)

GET   /store_sites   (as owner A)   → 200  A's storefront, created on first access
GET   /store_sites   (as owner B)   → 200  B's storefront — a different row
PATCH /store_sites   (as owner A)   → 200  updates A's, never B's

There is no separate SingletonScope setting, because a bare column name cannot say where the value comes from — whether it is ctx.Auth.UserID, a tenant claim, or something else. The scoping middleware already answers that, so the singleton reads its scope from the request’s forced filters and there is exactly one place to configure it.

The route shape is unchanged: still the bare table path, still no id, still no POST/DELETE. Only which row it addresses changes.

A few consequences worth knowing:

• A scoped row keeps an ordinary generated primary key. maniflex.SingletonID names the global row only; one fixed id could not name one row per scope.
• Give the scope column a unique index (mfx:"unique", above). Two concurrent first accesses would otherwise both provision a row; with the index, the loser collides and re-reads the winner’s.
• A request with no scope gets the global row. If your resolver returns nil for an unauthenticated caller, that caller reads the SingletonID row. Scope-or-refuse is what db.Tenancy does (it answers 403 when it cannot determine the tenant); db.ForceFilter applies no filter instead.
• The scope has to be one the framework can write, not merely read. It is stamped onto the provisioned row, so it must be a plain equality — which is what db.Tenancy and db.ForceFilter build. A scope that names no single value (an in filter, or a db.ForceFilterVia whose value lives on another table) cannot provision a row and is refused rather than creating one its own author could not then read.

This replaces the previous workaround — Headless plus a hand-written action — which cost 40–60 lines and, because actions skip the Validate step, silently gave up every mfx tag rule (required, enum, min/max, immutable) and the generated OpenAPI schema along with them.

Upgrading: a singleton that already has a global row and then gains a scope does not migrate that row — it has no scope column value, so it matches nobody and each tenant is provisioned a fresh one. Backfill or drop it deliberately.

ModelConfig registration order

A ModelConfig is positioned immediately after the model it configures:

server.MustRegister(
    User{},
    Article{}, maniflex.ModelConfig{Versioned: true},
    Comment{},
)

Here User and Comment use defaults; only Article is versioned.

Two argument shapes are registration errors, because there is no valid reading of either and both used to silently discard the config you wrote:

• A ModelConfig at position 0 (no preceding model to attach to).
• Two ModelConfigs in a row (the second has no fresh model to bind to).

See Strict mode for the full set of configuration problems caught at startup.

Optional embeds

Beyond BaseModel, the framework provides embeds that add columns and switch on behaviour when present:

Embedding one of these is equivalent to setting SoftDelete in ModelConfig. The two approaches and their query semantics are covered in Soft Delete.

type Article struct {
    maniflex.BaseModel
    maniflex.WithDeletedAt          // DELETE marks deleted_at instead of removing the row
    Title string `json:"title" mfx:"required"`
}

Registration order

Models must be registered before the database adapter is opened. The adapter is constructed from the registry — it reads the registered models to run migrations and resolve relations — so the registry must be complete first:

server.MustRegister(User{}, Article{}, Comment{})   // 1. populate the registry
db, err := sqlite.Open("./app.db", server.Registry()) // 2. build the adapter from it
server.SetDB(db)                                      // 3. inject the adapter

Registering a model after SetDB has no effect on an already-open adapter.

Next

• Field Tags Reference — every mfx: tag and its meaning.
• Relations — foreign keys and slice fields.
• Soft Delete — WithDeletedAt, WithIsDeleted, and query behaviour.

Record Identity

Every record in a Maniflex application is identified by one column, id, holding a string. This page states what that means as a v1 contract: what the framework guarantees, what it assumes, and what it does not support.

The behaviour described here is pinned by tests/e2e/identity_test.go.

The contract

Identity is a single string column named id. It is contributed by the embedded maniflex.BaseModel; a model that lacks it fails registration. There is no composite primary key and no alternative identity column.

The framework generates the value. On insert, when id is empty, the adapter assigns a UUIDv4 in canonical lowercase form — 9f8e7d6c-…, 36 characters, random. Nothing about the value is meaningful: it is not sequential, not time-ordered, and carries no tenant, type, or shard information.

Clients never choose it. id is mfx:"readonly", and the Validate step strips the column from every write body unconditionally — including a value a middleware stamped with ctx.SetField, which is a deliberate exception to the rule that server-set values survive. An "id" in a POST or PATCH body is ignored, not rejected: the request succeeds and the framework’s value is used.

The value never changes. No generated route reassigns an id. Updates, restores, and version history all keep the row’s original identity.

On the wire it is an opaque string. Generated OpenAPI declares both the id property and the {id} path parameter as {"type":"string","format":"uuid"}, and the property as readOnly. Nothing parses or validates the id in the request path: an id of any shape that does not match a row produces 404, never 400. Treat ids as opaque on the client side — compare them for equality, do not order or parse them.

In the database it is TEXT PRIMARY KEY on every supported driver, PostgreSQL included. The framework does not use a native uuid column type, a sequence, or an identity column.

Relations carry the same string. A foreign key column stores the target row’s id verbatim, and ?include= resolves relations by string equality. Foreign key columns are therefore string (or *string when the relation is optional).

Pagination assumes ids are unordered but unique. Keyset pagination orders by (cursor field, id), using the id only to break ties so a page boundary is total. Because v4 ids are random, that tiebreak order is arbitrary — stable across a walk, but not meaningful. Do not sort by id expecting insertion order; sort by created_at (opting in through BaseModelTags).

Adapter interfaces are string-typed. FindByID, Update, Delete, and their transactional counterparts all take id string. A custom adapter implements that signature; a multi-column key cannot be expressed through it.

Assigning your own id

Below the request pipeline, the adapter generates an id only when none was supplied. Code writing through the model accessor may therefore choose its own:

row, err := ctx.GetModel("Invoice").Create(map[string]any{
    "id":     "INV-2026-0001",
    "amount": 5000,
})

The framework itself relies on this: maniflex.SingletonID is the fixed id of a singleton model’s single row.

This is supported, with the responsibilities that come with it:

• Uniqueness is yours. A collision surfaces as a primary-key constraint error from the database, not as a framework-level validation message.
• URL safety is yours. The id appears in /{model}/{id} paths. Keep it to characters that survive a path segment unescaped.
• The OpenAPI document still says format: uuid. Consumers generating clients from the spec may validate against it.
• It does not reach the HTTP surface. There is no way for a client, or for a middleware on the request path, to supply an id — only server-side code writing through the accessor or an adapter directly.

Use it for rows your application names rather than discovers: a singleton, a fixed configuration row, a record keyed by an external system’s identifier.

Not supported in v1

These are absent by decision, not by oversight. Support for them would be additive, so applications that need them are not blocked from adopting v1 — but nothing in v1 should be read as promising them.

Why this shape

A single opaque string is the narrowest assumption that every other generated feature can be written against: one route shape, one foreign-key type, one cursor tiebreaker, one adapter signature. Random v4 ids are also safe to expose — they leak neither row counts nor creation order, which sequential ids do.

The cost is real and worth stating: random ids cluster poorly in a B-tree index, so very large tables pay more on insert than they would with a time-ordered id. If that matters for a specific table, keep the generated id as the primary key and add your own time-ordered column with an index for the access pattern that needs it.

Field Schema & Nullability

This page is the frozen contract for the DDL maniflex emits: what a Go field becomes as a column, and what that column’s nullability does and does not tell you. It exists for the people reading the database from outside the application — a migration script, a reporting replica, BI, another service — because the encoding is not the one most of them assume.

The short version, and the one thing to take away:

NOT NULL does not mean “required”, and NULL is not how maniflex says “no value”. A non-pointer field is always NOT NULL, and its zero value — '', 0, false — is what “absent” means.

What a field becomes

For a model whose fields cover every case:

type SchemaSpec struct {
    maniflex.BaseModel

    ReqText string  `db:"req_text" mfx:"required"`
    ReqNum  int     `db:"req_num"  mfx:"required"`

    OptText string  `db:"opt_text"`
    OptNum  int     `db:"opt_num"`
    OptRate float64 `db:"opt_rate"`
    OptFlag bool    `db:"opt_flag"`

    NullText *string `db:"null_text"`
    NullNum  *int    `db:"null_num"`

    Tagged string `db:"tagged" mfx:"default:pending"`
}

AutoMigrate emits exactly this:

CREATE TABLE "schema_specs" (
  "id"         TEXT PRIMARY KEY,
  "created_at" TEXT NOT NULL DEFAULT '0001-01-01T00:00:00Z',
  "updated_at" TEXT NOT NULL DEFAULT '0001-01-01T00:00:00Z',
  "req_text"   TEXT    NOT NULL,
  "req_num"    INTEGER NOT NULL,
  "opt_text"   TEXT    NOT NULL DEFAULT '',
  "opt_num"    INTEGER NOT NULL DEFAULT 0,
  "opt_rate"   REAL    NOT NULL DEFAULT 0,
  "opt_flag"   INTEGER NOT NULL DEFAULT 0,
  "null_text"  TEXT    NULL,
  "null_num"   INTEGER NULL,
  "tagged"     TEXT    NOT NULL DEFAULT 'pending'
)

tests/e2e/schema_contract_test.go pins every row of that table against the DDL actually emitted, so this page cannot drift from the code.

Reading required-ness from the schema

Both a required and an optional non-pointer column are NOT NULL. The only schema-level difference is that a required column carries no DEFAULT:

"req_text" TEXT NOT NULL              -- required
"opt_text" TEXT NOT NULL DEFAULT ''   -- optional

So an external consumer that needs the distinction must test NOT NULL and no default. Testing NOT NULL alone reads every optional column as required.

This is worth stating plainly because getting it wrong is expensive and silent. A migration tool that read NOT NULL as “this reference must exist”, and dropped rows whose parent was missing, discarded every storefront order in a production database — the order_id column it was checking is legitimately empty until an order is confirmed.

If you can read the API instead of the schema, prefer it: openapi.json lists required fields explicitly in each model’s create schema, and it says what it means rather than implying it.

Getting a genuinely nullable column

Declare the field a pointer. That is the supported way to say “this may have no value” to the database:

OrderID *string `db:"order_id" mfx:"relation"`

A pointer field is emitted NULL, gets no synthesised zero default, reads back as null in JSON, and — since the include fix in this release — populates correctly through ?include= when it is a BelongsTo foreign key. Rows whose pointer key is genuinely NULL come back without the relation key at all.

Use a pointer when the difference between “not set” and “set to the zero value” matters — an unset price versus a price of zero, an unconfirmed order versus one attached to order "". Use a plain value when it does not.

Why the columns are not simply nullable

The obvious alternative — emit NULL for every non-required scalar — is not something this version can do safely. AutoMigrate never rewrites an existing column; it creates tables and adds columns, and warns about drift rather than altering. Changing the emitted nullability would therefore apply only to newly created tables, leaving the same model with two different schemas depending on when its table was first created, and no mechanism to reconcile them. That needs a migration story before it needs a DDL change.

The zero-value default is not decorative either: it is what lets ALTER TABLE ADD COLUMN succeed against a table that already has rows, on both SQLite and Postgres. A model can grow a field without manual DDL because of it.

Referential integrity is an application invariant

One more thing the schema will not tell you: a REFERENCES constraint is emitted only for a BelongsTo relation carrying an on_delete action the database can enforce. Specifically, a column gets no constraint when it is:

• a plain indexed id column with no mfx:"relation" — the usual shape for an owner_id;
• a relation left at the default on_delete (a bare mfx:"relation"), since there is no action to enforce. The exception is a JunctionModel, whose keys cascade unless the model says otherwise;
• an edge whose deletion maniflex handles itself, which is where soft delete lands — those are enforced in the delete path instead, so the set of constraints emitted and the set of edges the cascade skips are drawn by the same line.

The database will therefore accept an orphan. Referential integrity in a maniflex application is maintained by the application, not the storage layer, so a PRAGMA foreign_key_check or a Postgres constraint scan proves less about a maniflex database than it looks like it does.

Out of contract for v1

• Altering an existing column’s type or nullability during migration.
• Expressing required-ness in the schema in any way other than the absent DEFAULT described above.
• CHECK constraints derived from mfx validation tags (min:, max:, enum:); those are enforced in the Validate step, not the database.

Field Tags Reference

A model’s behaviour is declared with three struct tags on each field. This page documents all three, and every directive accepted by the mfx tag.

The three tags

Title string `json:"title" db:"title" mfx:"required,filterable,sortable"`

The mfx tag holds a comma-separated list of directives. Whitespace around each directive is trimmed. Directives are either flags (a bare word) or key-value directives (key:value).

An unrecognised directive is a registration error, and the message names the directive it thinks you meant:

maniflex: model "User" field "Role" has unknown mfx option
"read_only" (did you mean "readonly"?) — an unrecognised option is
not applied, so a protective directive that is misspelt leaves the
field unprotected

Directives used to be matched exactly and anything else discarded in silence. For a descriptive directive that was merely puzzling — a misspelt sortable just meant no sorting — but for a protective one it was a hole: mfx:"read_only" left Readonly false, so the field stayed writable by any client, with nothing in the logs or the OpenAPI spec to show it. Directives are case-sensitive and lowercase; mfx:"Readonly" is rejected rather than quietly accepted.

Excluding a field

A field is dropped from the model entirely — no column, not in any payload — if any of its three tags is set to -:

Internal string `mfx:"-"`     // excluded
Cache    string `json:"-"`    // excluded
Scratch  string `db:"-"`      // excluded

Validation directives

These constrain the values a field accepts on write.

Status   string `json:"status"   mfx:"required,enum:draft|published|archived"`
Priority int    `json:"priority" mfx:"min:1,max:5,default:3"`
Password string `json:"password" mfx:"required,writeonly,minlen:8"`
Message  string `json:"message"  mfx:"maxlen:5000"`

Magnitude vs. length

min:/max: bound a number’s value. minlen:/maxlen: bound a length — of a string, or of a list. Putting one where the other belongs is a registration error naming the tag you wanted:

maniflex: model "User" field "Password" has mfx:"min:"/"max:" but its Go type
is string — those bound a number's magnitude — for a length bound use
mfx:"minlen:"/"maxlen:"

The error exists because the mistake used to be invisible. mfx:"max:5000" on a string reads exactly like “at most 5000 characters”, and instead rejected every non-empty value at runtime with field "message" must be a number — nothing at startup, and an error message that named neither the tag nor the type. This framework’s own tutorial shipped Password string mfx:"min:8" and rejected every password.

The range a bound may span

A min:/max: value is parsed as a float64, which represents every integer up to 2^53 (9007199254740992) exactly and only some beyond it. On an integer-typed field a bound at or past that point is a registration error rather than a bound enforced as some nearby number:

maniflex: model "Ledger" field "Balance" has an mfx:"max:" bound that float64
rounded to 9223372036854776000, at or beyond 2^53 (9007199254740992) — a bound
is parsed as a float64, which cannot represent every integer past that point, so
the bound enforced would not be the one written.

The rounding is not conservative in either direction: max:9007199254740995 becomes ...996, a ceiling one looser than written, and max:9223372036854775807 — “cap at MaxInt64” — becomes a number above MaxInt64, so the guard can never fire and the column is silently unbounded.

Float-typed fields are unaffected: a bound there is inexact by the nature of the column, and max:1e20 asks for a magnitude rather than an exact value. For an integer range wider than 2^53, check it in a Validate middleware instead.

String length is counted in characters, not bytes. A cap sized against English would otherwise reject the same message written in Arabic or carrying emoji — a limit that behaves differently depending on the writer’s language, and never for the author.

For a maniflex.FileKeys field use max_count: rather than maxlen:; it is the file-specific bound and has a default. Declaring maxlen: there is a registration error pointing at it.

Malformed values are refused at registration

A value these directives cannot use is a startup error, not a silent no-op:

The first two used to be dropped on the floor, so a tag that reads as a constraint enforced nothing. readonly,required is the same unsatisfiable shape as hidden,required: readonly strips the field from the request before the required check runs, so the check never sees it and the field was quietly optional. (hidden implies readonly, so that combination reports its own more specific message.)

Separately, a value that a min/max bound cannot be measured against — a string sent to a numeric field — now fails validation with “must be a number” rather than skipping the check.

How default: is applied

default:V becomes a SQL DEFAULT clause on the column. Nothing applies it in Go — it fires because the INSERT omits the column, so it takes effect whenever a write does not name the field. That holds for both doors into a model:

The Go zero is the only signal a struct can give, so a defaulted column cannot be given an explicit zero through Create[T] — Priority: 0 against default:3 stores 3. Make the field a pointer when that distinction matters:

Priority *int `json:"priority" mfx:"default:3"` // nil → 3, new(int) → 0

Only defaulted columns behave this way. A zero on a field with no default: tag is written as that zero, on both paths.

Before v0.2.5, Create[T] wrote every column at its Go value and a default: never fired — the same model created over HTTP and in Go disagreed. In the same release, default: on a pointer field started reaching the schema at all; it was previously emitted only for NOT NULL columns and silently dropped.

Write-access directives

These govern whether a field can be set by a client, and when.

BaseModel’s id, created_at and updated_at are all readonly, and that is their only default — none of them is filterable or sortable until the model opts in with ModelConfig.BaseModelTags. Use immutable for values that are set once and must not change afterwards, such as an owner ID.

Both mean “not from a client”. A value the server stamps via ctx.SetField — db.Tenancy writing a tenant column, an auth middleware writing an owner — is kept, even on a readonly or immutable field. Only values parsed from the request body are stripped.

They cover a multipart upload too. A mfx:"file" field carrying readonly, hidden, or immutable on update refuses an uploaded part with 422 VALIDATION_ERROR, and is left out of the multipart/form-data schema. For a file the client should upload but never see the storage key of, use writeonly — see Who may write a file field.

Email   string `json:"email"    mfx:"required,immutable"`
ApiKey  string `json:"api_key"  mfx:"readonly"`

Response-visibility directives

Both directives drop the field from API responses. They differ in whether the client may write the field.

• writeonly is for values the client must supply but should never see again — typically passwords, and the storage key of a private file field. The field is included in the create and update request schemas; only the response is scrubbed.
• hidden is for values clients have no business touching at all — server-managed internals, audit fields, derived data. The field is dropped from create and update schemas as well, so it cannot be set from the API. It is still stored, and code running inside the pipeline (a middleware on the Service step, for example) can populate it.

// Client sets it on create, never sees it back.
Password string `json:"password" mfx:"required,writeonly"`

// Server-managed; client can neither read nor write it.
InternalScore float64 `json:"internal_score" mfx:"hidden"`

hidden therefore implies readonly — writing it out as mfx:"hidden,readonly" is allowed but redundant. If you want a field the client writes but never reads, that is writeonly, and spelling both (mfx:"hidden,writeonly") leaves it writable: the explicit directive wins over the implication.

mfx:"hidden,required" is rejected at registration. The two contradict — hidden stops the client sending the field, required insists it does — so no request could satisfy it. A value the client must supply but never reads back is mfx:"writeonly,required".

A field that is both readonly and not hidden is the opposite case: visible in responses, never accepted from the client.

json:"-" is treated as hidden and read-only: the field stays a real, persisted column that the server owns, but it never appears in API responses and is never accepted from the client. This matches the Go convention that json:"-" affects serialization, not schema. To exclude a field from the database entirely (no column), use db:"-" or mfx:"-" instead.

Record-locking directives

These freeze a whole record — not just a field — once its state matches a condition. Useful for terminal states in business workflows (posted invoices, closed pay periods, confirmed POs).

Multiple lock_when directives accumulate; any matching condition locks the record. The directive can be written on any field — the referenced field is what matters.

Both halves of the directive are checked at registration, so you never ship a rule that silently never matches: the JSON name has to resolve to a real field, and the value has to be one that field could hold. lock_when:count=five on an integer column is a startup error rather than a lock that never fires, as is lock_when against a time.Time or a struct — the directive tests equality and covers string, bool and numeric columns.

The comparison is made on the field’s own type rather than on the two sides’ printed forms, so it does not depend on which shape a driver returns: SQLite reports a bool column as an integer, Postgres as a bool, and a NUMERIC arrives through lib/pq as text. 1 is accepted where the field is a bool.

type Invoice struct {
    maniflex.BaseModel
    Number string
    Status string `mfx:"enum:draft|posted|void,lock_when:status=posted,lock_when:status=void"`
    Amount int
}

The transition into a locked state is itself allowed — when the request arrives, the loaded record is still in its previous state. After that update commits, the record becomes frozen.

lock_when is checked before the write reaches the adapter. On update it runs in the Validate step, ahead of that step’s other rules — but only when the request’s scope is already in place. A forced filter registered on the DB step (db.Tenancy, db.ForceFilter) has not been applied at that point, and a guard reading the row by id alone would answer 422 RECORD_LOCKED for a record the caller’s own reads 404 on, disclosing both that it exists and that it has reached the locked state. So the check moves to the DB step in that case, after the scope is enforced: the same refusal, one step later. Declaring maniflex.ProvidesScope() hoists the scope ahead of Validate and keeps the early abort.

On delete it always runs in the DB step, likewise after the scope. Creates are exempt: there is no prior state to check.

The guard fails closed. It reads the record through the request’s transaction when one is active — so it sees state the same request has written but not yet committed — and if that read fails for any reason other than “no such record”, the request is rejected (500 DB_ERROR) rather than allowed through unchecked.

Pessimistic lock directive

Eliminates manual ctx.LockForUpdate calls in the most common case: a create that must read-then-write a shared resource without a concurrent write sneaking in between.

type Dispense struct {
    maniflex.BaseModel
    StockID  string `json:"stock_id"  db:"stock_id"  mfx:"required,lock_scope:StockBalance"`
    Quantity int    `json:"quantity"  db:"quantity"  mfx:"required,min:1"`
}

Requirements:

• The model must run inside a transaction. Register maniflex.WithTransaction(nil) on the Service step; otherwise the DB step aborts with 500 LOCK_SCOPE_NO_TX.
• The referenced model name must be registered. A typo is caught at startup (in Handler()), so it never reaches production silently.
• If the referenced row does not exist, the create returns 404 NOT_FOUND.
• The referenced row must be in the request’s scope. When a forced filter names a column the referenced model also carries, the row is looked up through that filter first, so a create naming another tenant’s row gets the same 404 as one naming a row that is not there — without it, the id was a probe and the lock landed on a row the caller cannot see. A referenced model that carries no such column cannot be scoped this way and is still located by id alone.

server.Pipeline.Service.Register(
    maniflex.WithTransaction(nil),
    maniflex.ForModel("Dispense"),
    maniflex.ForOperation(maniflex.OpCreate),
)

Comparison with ctx.LockForUpdate:

See Transactions for the underlying ctx.LockForUpdate and BeginTx APIs.

Query directives

These opt a field into the query string. A field is not filterable or sortable unless explicitly tagged.

See Querying for the filter, sort, and cursor-pagination grammar.

Schema directives

Slug  string `json:"slug"  mfx:"required,unique"`
Email string `json:"email" mfx:"index"`

index creates an index named idx_<table>_<column>. It is skipped when the column is already covered by another index — a unique constraint on the same field (databases index unique columns implicitly), a ModelConfig.Indices entry, or a scheduled-column auto-index — so adding it is always safe. Indexing a foreign-key column (e.g. mfx:"index" on UserID) is a common, valid use.

unique is enforced on both the create-table and the add-column (ALTER TABLE) paths — AutoMigrate creates a UNIQUE INDEX named uidx_<table>_<column> in both cases. Adding a unique column to a table that already holds rows with duplicate values in that column fails migration (the index build errors, naming the table and column) rather than silently dropping the constraint; resolve the duplicates before deploying.

JSON and other custom columns

A bare map[string]any, map[string]string, or []string field has no SQL column mapping and fails AutoMigrate with a clear error. Wrap it in a named type that implements maniflex.SQLTyper (plus driver.Valuer + sql.Scanner) so it controls its own column type — e.g. a JSONMap that maps to JSONB on Postgres and TEXT on SQLite. maniflex.LocaleString is a built-in example. To keep such a field out of the database entirely, tag it mfx:"-".

A NOT NULL column of such a type is given a zero-value DEFAULT so that adding it to a table which already has rows succeeds. For a type whose SQLType is one the migrator has no literal rule for — BLOB, BYTEA, UUID, NUMERIC(12,2) — that default is a CAST to the column’s own type, and the value cast is the type’s zero driver.Valuer output where it has one, else '', {} or [] by kind. Give the type a Value() a zero receiver can answer if the generic choice is wrong for it.

To filter inside such a column, see json_array / json_object above.

Relation directives

A field may declare a relationship to another model. Relations are opt-in — an <Name>ID field is a plain column unless you tag it.

onDelete sub-options are joined to the relation: directive with a semicolon, not a comma. Relationships are covered in full in Relations.

A field whose name ends in ID (e.g. UserID) is a plain scalar column unless tagged mfx:"relation". So a value column that merely ends in ID — an external reference, an opaque token — needs no special tag:

ExternalID string `json:"external_id"` // just a string, not a relation
UserID     string `json:"user_id" mfx:"relation"` // → User (opt in)

File upload directives

file marks a field as a file-upload field. The column stores the storage key; multipart form-data is then accepted for create and update on the model.

The field’s Go type must be string (one key) or maniflex.FileKeys (many). Any other type is a registration error — every rule below is keyed on the column being a storage key, so on another type they would all be silently skipped.

Avatar string            `json:"avatar" mfx:"file,max_size:2MB,accept:image/*"`
Logo   string            `json:"logo"   mfx:"file,file_acl:public,accept:image/*"`
Images maniflex.FileKeys `json:"images" mfx:"file,accept:image/*,max_count:10"`

See File Fields & Uploads for the upload workflow, and Many files per field for FileKeys.

Encryption directives

Encrypted fields cannot be filtered or sorted, because the stored value is ciphertext. If unique is also set, a companion {field}_hmac column enforces uniqueness without exposing the plaintext.

SSN string `json:"ssn" mfx:"encrypted,key:patient-pii"`

Scheduled directives

The scheduled directive declares a time-driven transition on a timestamp field — for example, soft-deleting a row once a timestamp passes. The directive only marks the field; the transitions are applied by a background runner documented in Events & Background Jobs.

It is an advanced feature with several sub-options joined by semicolons:

ExpiresAt time.Time `json:"expires_at" mfx:"scheduled;soft-delete"`
PublishAt time.Time `json:"publish_at" mfx:"scheduled;field=status;from=draft;to=published"`

Locale directives

These apply to fields declared as maniflex.LocaleString — a multilingual string stored as a JSON object keyed by locale code (e.g. {"en":"Finance","ar":"مالية"}).

Mark a field as locale-aware with mfx:"locale". All other locale directives require locale to be present.

type Department struct {
    maniflex.BaseModel
    Name maniflex.LocaleString `json:"name" mfx:"locale,filterable,sortable"`
    Bio  maniflex.LocaleString `json:"bio"  mfx:"locale,resolve,default_locale:ar"`
}

The resolved locale for a request follows a precedence chain: ?locale= param → Accept-Language header → default_locale tag → model DefaultLocale → app LocaleOptions.Default → "en".

See Localization for the full LocaleResolver setup and filtering/sorting behaviour.

Quick reference

Relations

A relation connects two models through a foreign-key column or a junction table. Relations are declared on the struct — by a field name, a tag, or a slice — and are populated on demand via the ?include= query parameter.

maniflex recognises three kinds:

BelongsTo

Relations are opt-in: tag the foreign-key field mfx:"relation". The target model is inferred from the field name with the trailing ID stripped (UserID → User).

type Post struct {
    maniflex.BaseModel
    Title  string `json:"title" mfx:"required"`
    UserID string `json:"user_id" mfx:"required,filterable,relation"` // → User
}

UserID is a foreign key to User, keyed user (snake-case of the trimmed field name) — the value used in ?include=, in nested filters (?filter=user.role:eq:admin), and in nested sorts (?sort=user.name:asc).

The FK field is also a regular column. Tag it filterable if clients need to query by it, exactly like any scalar.

Note: an <Name>ID field is a plain scalar column unless you tag it mfx:"relation". A value column that merely ends in ID — ExternalID, CloudEventID, a third-party token — stays a plain column with no relation and no ?include= key. (The legacy mfx:"norelation" opt-out is now a deprecated no-op, kept only so existing models compile.)

When the field name doesn’t match the target model, name it explicitly with mfx:"relation:Target". A bare mfx:"relation" on a field that doesn’t end in ID fails at startup: there’s no suffix to strip, so the target would be inferred from the whole field name — a guess that is almost never a real model.

A relation whose target model is simply never registered is allowed by default (it may be a plain foreign id that wants no relation tag) and rejected under strict mode.

Including the related row

curl 'localhost:8080/api/posts?include=user'

Each post in the response gains a user object populated from the related table. Multiple includes are comma-separated:

curl 'localhost:8080/api/posts/<id>?include=user,comments'

BelongsTo (explicit)

When the FK field name does not match the target model — for example, a ManagerID pointing to User — declare the relation with mfx:"relation:Name" and add a companion field of the target type:

type Team struct {
    maniflex.BaseModel
    Name      string `json:"name"  mfx:"required"`
    ManagerID string `json:"manager_id" mfx:"required,filterable,relation:Manager"`
    Manager   User   `json:"manager,omitempty"`
}

• ManagerID is the column that stores the FK.
• Manager is the companion field: it carries the target type (User) so the framework can resolve the relation. It is not a column itself — its only role is type information for relation scanning.

The relation key here is manager (snake-case of Manager), so the include becomes ?include=manager.

A relation:Name directive without a matching companion field fails registration.

HasMany

The inverse side: a slice of the related struct, declared on the model that does not hold the FK.

type User struct {
    maniflex.BaseModel
    Name  string `json:"name"`
    Posts []Post `json:"posts,omitempty"` // populated when ?include=posts
}

There is no column on users for this — Posts is purely a relation declaration. The FK is expected on the related table, named after the parent model: Post is expected to carry user_id. (That column comes from UserID on Post, as in the BelongsTo example above.)

The relation key for a slice is the snake-case of the field’s JSON name, here posts.

curl 'localhost:8080/api/users/<id>?include=posts'

ManyToMany

A many-to-many relation uses a third junction model that carries the two FKs. Both sides declare a slice with mfx:"through:JunctionModel":

type Product struct {
    maniflex.BaseModel
    Name string `json:"name"`
    Tags []Tag `json:"tags,omitempty" mfx:"through:ProductTag"`
}

type Tag struct {
    maniflex.BaseModel
    Label    string    `json:"label"`
    Products []Product `json:"products,omitempty" mfx:"through:ProductTag"`
}

// The junction model — register it just like any other.
type ProductTag struct {
    maniflex.BaseModel
    ProductID string `json:"product_id" mfx:"required,filterable,relation"`
    TagID     string `json:"tag_id"     mfx:"required,filterable,relation"`
}

All three models must be registered. The junction’s FK columns are declared as BelongsTo relations (mfx:"relation" on ProductID and TagID), so the framework can resolve which side of the join goes where.

?include=tags on a product follows the junction and returns the related tags directly.

Junction payload (_through)

A junction often carries data of its own — a role, a position, a date the link was made. When it does, each included row gains a _through object holding those columns:

{
  "id": "tag-1",
  "label": "blue",
  "_through": { "position": 2, "linked_at": "2026-07-19T09:00:00Z" }
}

The two foreign keys and the junction’s id are excluded — they say nothing the response does not already carry.

The junction is a model like any other, and _through honours its tags. A column marked mfx:"hidden" or mfx:"writeonly" is absent, exactly as it would be in a response from the junction’s own endpoint:

type ProductTag struct {
    maniflex.BaseModel
    ProductID string `json:"product_id" mfx:"required,filterable,relation"`
    TagID     string `json:"tag_id"     mfx:"required,filterable,relation"`
    Position  int    `json:"position"`                      // in _through
    InvitedBy string `json:"invited_by" mfx:"hidden"`       // not in _through
}

Two further exclusions are worth knowing:

• mfx:"encrypted" columns are omitted, along with their _hmac companions. The junction payload has no decryption pass, so the alternative would be emitting ciphertext — no use to a client, and it discloses the encryption envelope. Put a value you need to read on the related model, not on the junction.
• Columns the junction model does not declare are omitted. A column present in the table but absent from the model is schema drift, and dumping it is what used to make this a leak.

Before v0.2.5 _through was copied verbatim from the junction row, so hidden and write-only columns surfaced on every include.

Which models are join tables

A junction can be declared three ways. In order of precedence:

Auto-detection accepts only the unambiguous shape — two foreign keys, an id, timestamps, and nothing else:

type ProductTag struct {           // auto-detected
    maniflex.BaseModel
    ProductID string `json:"product_id" mfx:"relation"`
    TagID     string `json:"tag_id"     mfx:"relation"`
}

Add a column of its own and detection stops, because that shape is equally what an ordinary entity looks like:

type Order struct {                // NOT a junction — nothing is inferred
    maniflex.BaseModel
    CustomerID string `json:"customer_id" mfx:"relation"`
    AddressID  string `json:"address_id"  mfx:"relation"`
    Total      int    `json:"total"`
}

Before v0.2.6 Order was treated as a join table, so Customer and Address silently gained a many-to-many through it. If you relied on detection for a junction that carries payload, embed JunctionModel — see below.

A junction that carries payload says so:

type Enrollment struct {
    maniflex.BaseModel
    maniflex.JunctionModel
    StudentID string `json:"student_id" mfx:"relation"`
    CourseID  string `json:"course_id"  mfx:"relation"`
    Term      string `json:"term"`      // in _through
}

JunctionModel is embedded alongside BaseModel, not instead of it — a junction is an ordinary model with an id. The model must have exactly two BelongsTo relations to distinct models; anything else is a registration error.

ModelConfig.DisableAutoJunction opts a model out of detection entirely, for a link-shaped model that should not gain the relation.

Unique links

Junction pairs are not unique by default. Declare it when they should be:

type ProductTag struct {
    maniflex.BaseModel
    maniflex.JunctionModel `mfx:"unique"`
    ProductID string `json:"product_id" mfx:"relation"`
    TagID     string `json:"tag_id"     mfx:"relation"`
}

This emits a UNIQUE index over the two key columns, so a repeated link is refused with 409. It also lets an include collapse duplicate pairs: with the declaration a repeat is corruption, without it a repeat is data.

Off by default because a junction carrying its own attributes may legitimately repeat a pair — Enrollment{student_id, course_id, term} holds one row per term, and each carries its own _through payload. A pure link table almost always wants the tag.

Adding it to a table that already holds duplicates fails the migration until they are cleaned up. That is why it is separate from the marker: embedding JunctionModel changes nothing about the schema, so declaring what a model is never risks a migration.

Junction deletes

A junction’s foreign keys default to ON DELETE CASCADE, so deleting either endpoint takes its link rows with it — a link to a row that no longer exists says nothing. An explicit mfx:"on_delete:..." on the column wins, and edges where either side soft-deletes are handled in maniflex’s own delete path rather than by a database constraint (see below).

Cascading deletes

A BelongsTo relation may declare what happens to this row when the parent it points at is deleted, using the onDelete sub-option:

AuthorID string `json:"author_id" mfx:"relation:Author;onDelete:cascade"`

The action is validated at startup: it must target a registered model, and setNull needs a nullable FK. cascade recurses — deleting a row deletes its children, then their children — and reference cycles are handled.

How it is enforced (and soft delete)

The action is enforced one of two ways, chosen automatically per relation. The rule is that maniflex enforces the edge itself whenever it has something to do beyond deleting the row:

• Nothing to do beyond the row → a real database FOREIGN KEY … ON DELETE … constraint carries it, and the database enforces it natively (and enforces referential integrity on insert: a row naming a non-existent parent is refused with 409).
• Either side soft-deletes → the database cannot help (a soft delete is an UPDATE, so ON DELETE never fires, and a DB cascade can only hard-delete), so maniflex enforces it in the delete request’s own transaction instead. A soft-delete child of a cascaded parent is soft-deleted identically — its deleted_at is set, the row is not removed.
• The child is Versioned or is a rollup child → maniflex enforces it, and no ON DELETE clause is emitted for that edge. A database ON DELETE removes the rows and tells nobody: the history would lose its delete entries and the rollup would keep counting children that are gone. On the maniflex path the child keeps both — a cascaded row records the same history a direct delete would, and every rollup it fed is recomputed once at the end of the sweep. The FK constraint is what is dropped, not the integrity: the children are deleted before the parent, in the same transaction.

Either way the whole deletion is atomic: a restrict that fires rolls back any cascade that ran alongside it.

Large fan-outs

On the maniflex-enforced path the children of a deleted parent are walked in pages of 500, ordered by id and bounded by the last id seen, and each page is applied before the next is read. Only the id column is selected, so the memory a delete needs is set by the page size rather than by how many children the row has. restrict does not read the children at all — it asks how many there are.

The work is still proportional to the fan-out, and it all happens inside the delete request’s transaction: deleting a row with a million descendants is a long transaction holding locks the whole time. Prefer soft-deleting the parent and reaping in a job when the fan-out is that large.

A child that is Versioned or is a rollup child costs one extra read per row — the walk selects only id, and the history row’s diff and the rollup’s foreign key both need the rest of it. That is the price of the bookkeeping; a child with neither pays none of it.

Existing SQLite tables. New FK constraints are declared when a table is created. SQLite cannot add a foreign key to a table that already exists, so adding onDelete to a model with a pre-existing SQLite table does not retroactively add the constraint — recreate the table, or rely on the soft-delete path, which is enforced in the application layer regardless. Postgres adds the constraint on the next migration.

Soft delete and relations

When the related model uses soft delete, rows whose deleted marker is set are omitted from ?include= results — the same filter the framework applies to list endpoints. See Soft Delete.

Scoping and ?include=

A request’s forced filters — the scope imposed by db.Tenancy or db.ForceFilter — are applied to included rows as well as to the primary read, for every relation kind, wherever the related model carries the filtered column. For a many-to-many they apply to the junction rows too, on the same terms: a link row is read only if it is in scope, whenever the junction carries the column.

This matters because the foreign key is the client’s to set. Without it, a caller who can write an FK (or a many-to-many junction row) puts their own row inside another tenant’s ?include=, and an attach pulls another tenant’s record into their own response.

A scoped write now refuses such a key up front — every BelongsTo key a create or update sets is read through the request’s scope, and one naming a parent the caller cannot see is refused with that parent’s 404, junction rows included. The include scoping here is the second line: it holds for a row that reached the table by some other road — an unscoped back-office write, an import, a row predating that check.

// Tenancy on both models; the include is scoped by the same filter.
server.Pipeline.DB.Register(
    db.Tenancy("org_id", orgOf),
    maniflex.ForModel("Order", "OrderLine"),
)

What is not covered. Be precise about this, because the gap is narrow but real:

• A related model with no such column is not scoped. That is the right answer for the case that produces it — a shared lookup table (currencies, categories, statuses) is not tenant-partitioned and has nothing to scope by — but if a model is partitioned by something the filter cannot name, its includes are unscoped — and so is the key check on the write, which uses the same “does the parent carry this column” rule. Validating that FK is yours.
• Relation-path filters (db.ForceFilterVia) are skipped: they are written against the primary model’s relations and mean nothing on the related table.
• A link between two of your own rows written by another tenant is caught only if the junction carries the scope column. Scoping the related rows alone cannot catch it: both endpoints are yours, so both pass. Put the tenant column on a partitioned junction and register the scope on it, and the write is refused outright; without that column the junction is shared, and the link is neither refused nor hidden.

Before this release the junction was read unscoped and without its soft-delete condition, so a link another tenant wrote between two of your records surfaced in your include with that tenant’s _through payload, and a soft-deleted link kept materialising its related row.

Quick reference

Soft Delete

A soft-deleted row is left in the database but marked as deleted. DELETE requests flip the marker; list, read, and include queries hide rows whose marker is set. This page covers how a model opts in, the two storage styles, and the query semantics that follow.

Opting in

There are two ways to enable soft delete on a model. Both produce the same behaviour; pick whichever fits the declaration style of the rest of the model.

By embed

Embed one of the framework’s marker types:

type Article struct {
    maniflex.BaseModel
    maniflex.WithDeletedAt              // timestamp-based soft delete
    Title string `json:"title"`
}

Both columns are tagged readonly and filterable. They are not part of any write request — the framework manages them.

By configuration

The same setup, expressed at registration:

server.MustRegister(
    Article{}, maniflex.ModelConfig{
        SoftDelete: maniflex.SoftDeleteConfig{
            Enabled:   true,
            Field:     "deleted_at",
            FieldType: maniflex.SoftDeleteTimestamp, // or maniflex.SoftDeleteBool
        },
    },
)

If both an embed and a ModelConfig.SoftDelete are present, the explicit config wins.

Choosing between timestamp and boolean

Both styles work; they differ in what you can tell from the column afterwards.

• WithDeletedAt records when the row was deleted, which makes audit trails, “deleted in the last 30 days” queries, and undelete-with-context possible. It is the default choice.
• WithIsDeleted stores only the fact of deletion. Use it when the surrounding system already records deletion timestamps elsewhere, or when a boolean fits an existing schema better.

Delete semantics

For a soft-deletable model, DELETE /api/<table>/{id} updates the marker instead of removing the row:

The endpoint, the response, and the status code are the same as for a hard-delete model; only the underlying SQL differs.

Query semantics

Once enabled, soft-deleted rows are filtered out everywhere the framework reads the table:

• List (GET /<table>) — only un-deleted rows are returned.
• Read (GET /<table>/{id}) — a soft-deleted row returns 404.
• Includes — relations populated via ?include= skip soft-deleted children, and a many-to-many skips links whose junction row is soft-deleted.
• Update — PATCH on a soft-deleted row returns 404; the row is treated as absent.
• Delete — a second DELETE on the same row returns 404 and leaves the marker as it was, so the original deletion time survives. This holds inside a transaction too.

To surface the marker for clients that need it (e.g. an admin tool), filter on it explicitly:

# Only soft-deleted rows
curl 'localhost:8080/api/articles?filter=deleted_at:ne:null'

deleted_at and is_deleted are filterable, so the standard filter grammar applies — see Querying.

Restoring a row

Opt a model in with ModelConfig.RestoreEnabled to mount a restore endpoint:

server.Register(Article{}, maniflex.ModelConfig{RestoreEnabled: true})

curl -X POST 'localhost:8080/api/articles/<id>/restore'

The request carries no body — it names the row in the URL and says only “undo the delete”. A successful restore returns 200 with the restored record, so the client need not re-read it.

It is off by default, and deliberately so: un-deleting is a privileged operation, and an endpoint that appeared merely because a version was upgraded would not be covered by the authorisation an app had already written. The route is only mounted for models that actually soft-delete — on a hard-delete model there is nothing to restore.

It dispatches as an update

A restore runs as OpUpdate, not as an operation of its own. That is the point: every middleware an app already registered for “who may modify this row” — auth, tenancy, force filters, audit — governs un-deleting it, with nothing to rewrite and no new operation constant to discover.

// This already covers restore. Nothing further to do.
server.Pipeline.Auth.Register(auth.RequireRole("editor"),
    maniflex.ForOperation(maniflex.OpUpdate))

Where the two must be told apart — an audit sink recording “restored” rather than “updated”, or a validation rule that only makes sense against a body — read ctx.IsRestore(). Note a restore’s ctx.ParsedBody is empty, so body-driven validation middleware sees nothing to check.

Scoping is enforced too. Because a soft-deleted row is invisible to every read path, the restore cannot read its target back to check scope the way an update does; instead the request’s forced filters are applied to the restore statement itself. A caller cannot un-delete a row outside their tenancy by knowing its id.

What it writes

Only the delete marker is cleared. updated_at is left untouched, so a restore does not read as an edit to caches, sync clients, or anything else watching that column — the audit or event record is where a restore is recorded.

Cascade is not undone. A restore brings back the row it names and nothing else: nothing records which children an onDelete:cascade removed, so restore each explicitly, or model the relationship so the children survive the parent’s deletion. See Relations.

Custom adapters

The endpoint needs a database adapter implementing maniflex.Restorer. The bundled SQLite and Postgres adapters do; a third-party adapter that does not is unaffected and answers 501. It is a separate interface, not a DBAdapter method, so adding it broke nothing:

type Restorer interface {
    Restore(ctx context.Context, model *ModelMeta, id string, q *QueryParams) (any, error)
}

Apply q’s filters (the request’s forced scope, possibly nil) to the statement, and return ErrNotFound when no row matches — including a row that exists but is not deleted.

Interaction with hard delete

A model is either soft- or hard-delete; the choice is a property of the model, not the request. If you need a true hard delete on a soft-deletable model — for example, to honour an erasure request — perform it through a raw query or a custom action that bypasses the standard handler.

Quick reference

File Fields & Uploads

A field tagged mfx:"file" accepts an uploaded file alongside the model’s JSON. The column stores an opaque storage key; the bytes live in a configured FileStorage backend. Standalone upload, download, and delete endpoints can also be mounted (see Standalone file endpoints).

Config changed. File settings now live under a single Config.FilesConfig struct (maniflex.FilesConfig). The old flat Config.FileStorage, Config.FileSignedURLTTL, and Config.FileMiddleware fields have been removed. The mapping is:

Old (Config.…)	New (Config.FilesConfig.…)
FileStorage	Storage
FileSignedURLTTL	SignedURLTTL
FileMiddleware	BeforeMiddlewares
(implied by FileStorage != nil)	MountEndpoints — now explicit, see the footgun

New: KeyGen (custom storage-key layout) and AfterMiddlewares (post-handler observation).

Declaring a file field

Add the file directive to a string field:

type Article struct {
    maniflex.BaseModel
    Title string `json:"title" mfx:"required"`
    Cover string `json:"cover" mfx:"file,max_size:2MB,accept:image/*"`
}

The column’s Go and DB types are string — what is stored is the storage key returned after the upload. The on-disk bytes are managed by the storage backend; the database row holds only the reference.

A file field’s Go type must be string (one key) or maniflex.FileKeys (many). Anything else is a registration error: every file rule is keyed on the column being a storage key, so on another type they would all be skipped.

Tag sub-options:

Those three are the whole set — anything else is a registration error naming the field. A typo used to be read as private, which looks like the safe direction and is not the safe outcome: the field was asked to serve signed or public URLs and served raw storage keys instead, with nothing to say why.

Who may write a file field

file_acl decides how the value is presented. The access tags decide who may set it, and they mean the same thing for a file field as anywhere else — a multipart upload is a client write like any other:

mfx:"file,writeonly" is the combination to reach for when the storage key should not appear in responses but the file must stay uploadable and downloadable. The client posts the file, every response omits the key, and GET /{model}/{id}/{field} still streams the bytes. The OpenAPI read schema marks the field writeOnly: true, so a generated client models it correctly rather than expecting a key that never arrives.

type Document struct {
    maniflex.BaseModel
    // Uploadable, never echoed, still downloadable through the attachment route.
    Scan string `json:"scan" db:"scan" mfx:"file,writeonly,max_size:10MB"`
    // Server-managed: only the application sets this.
    Report string `json:"report" db:"report" mfx:"file,readonly"`
}

A client upload to a readonly, hidden, or already-set immutable field is refused with 422 VALIDATION_ERROR, and those fields are left out of the multipart/form-data schema so a generated client never offers the part.

Before this was enforced, readonly and hidden were applied by stripping the field from the parsed JSON body — which a multipart part never passes through. A mfx:"file,readonly" field therefore refused a key reference but accepted an upload, so a client could set a server-managed document on create and replace its bytes on update. If you were relying on that to get “uploadable but not echoed”, writeonly is the tag that means it.

accept matches the content type the client declared on the multipart part; when the part declares nothing (or the generic application/octet-stream), the type is sniffed from the first 512 bytes. A declared type is a client-supplied claim, so treat accept as an input filter, not a security boundary — downloads are what enforce safety, via X-Content-Type-Options: nosniff and forced attachment for anything outside the inline allowlist (see Standalone file endpoints).

Tag detail is in Field Tags Reference.

Many files per field (FileKeys)

A gallery, or any attachment set, is a maniflex.FileKeys column:

type Post struct {
    maniflex.BaseModel
    Title  string            `json:"title"  mfx:"required"`
    Images maniflex.FileKeys `json:"images" mfx:"file,accept:image/*,max_size:5MB,max_count:10,file_acl:signed"`
}

It stores as a JSON array (JSONB on Postgres, TEXT on SQLite), so ordering is preserved exactly as written — a gallery keeps its sequence. Every rule a single-key field enforces applies per key: existence, max_size (per file, not per array), accept, file_acl signing on read, auto_delete, and cleanup on hard delete.

Write by key reference, not multipart. Upload each file first — via POST /files or a presigned upload — then send the keys:

PATCH /posts/1
{"images": ["uploads/a1/one.jpg", "uploads/b2/two.jpg"]}

A multipart upload to a FileKeys field is refused (422). Multipart carries one file per field, so it could only ever store one key and would silently drop the rest; and routing many large files through the app process is what presigned uploads exist to avoid.

A PATCH replaces the whole array, as it does any column. With auto_delete (the default), keys present before the write and absent after it are deleted from storage once the write commits. The diff is a set difference, so reordering deletes nothing, and a key you keep is never touched:

PATCH /posts/1  {"images": ["uploads/a1/one.jpg", "uploads/c3/three.jpg"]}
// one.jpg   kept    — still referenced
// two.jpg   deleted — dropped by this write
// three.jpg kept    — newly referenced

max_count bounds the array (default DefaultMaxFileCount, 100). Every key is Stat’d against storage to enforce the field’s rules, so an uncapped array would be one request buying N storage round-trips. Over the cap is 422 TOO_MANY_FILES.

No attachment route is mounted for a FileKeys field — that route streams one object’s bytes and a list names no single one. Use file_acl:signed to have each key rewritten to a URL in the response.

file_acl modes

type Attachment struct {
    maniflex.BaseModel
    Logo   string `mfx:"file,file_acl:public,max_size:1MB,accept:image/*"`
    Resume string `mfx:"file,file_acl:signed,max_size:5MB,accept:application/pdf"`
    Notes  string `mfx:"file"`  // implicit private — raw key in the response
}

The rewrite happens in the Response step on create, read, list, and update. A null/empty value passes through unchanged — no fabricated URLs to nothing.

Configure the signed-URL lifetime once on Config:

maniflex.New(maniflex.Config{
    FilesConfig: maniflex.FilesConfig{
        SignedURLTTL: 15 * time.Minute, // default: 1h
    },
})

S3Storage.URL uses awss3.NewPresignClient; ttl=0 (public mode) maps to the AWS 7-day maximum.

LocalStorage cannot sign. URL returns the server-relative /files/<key> for both signed and public modes, ignoring the TTL entirely — so file_acl:signed against it yields a permanent path where a time-limited one was asked for, and how exposed that path is depends on whatever guards GET /files/*. That is a weaker guarantee than the tag requests, so the framework no longer lets it pass unremarked: it warns at boot, naming the model and fields, and Config.Strict makes it a startup error.

Use a signing backend, or mark the field file_acl:private — its downloads go through the per-model attachment route, which enforces the same auth as reading the parent record. Bring an HMAC layer only if you need signed URLs and local disk.

A backend declares this by implementing maniflex.SignedURLCapable. Not implementing it means “I can sign”, so S3Storage and any third-party signer need do nothing.

Configuring storage

Uploads require a FileStorage implementation, set on Config.FilesConfig.Storage. The framework ships one backend; bring your own for cloud storage.

import "github.com/xaleel/maniflex/storage"

fs, err := storage.NewLocalStorage("./uploads")
if err != nil {
    log.Fatal(err)
}
defer fs.Close()

server := maniflex.New(maniflex.Config{
    Port: 8080,
    FilesConfig: maniflex.FilesConfig{
        Storage:        fs,
        MountEndpoints: true, // mount POST/GET/DELETE /files — see the footgun below
    },
})

LocalStorage pins the directory with Go’s directory-scoped os.Root; file and metadata operations may follow symlinks only while they remain inside that root. Links which escape it are rejected. Close the backend when the process no longer uses it to release the root directory handle.

FileStorage is a small interface — Store, Retrieve, Delete, Exists, URL — making S3, R2, GCS, or any other key-value store straightforward to adapt.

When Storage is nil, model endpoints still accept JSON, but multipart uploads and the standalone /files routes respond with 501 Not Implemented.

MountEndpoints is explicit

MountEndpoints gates only the standalone /files routes and defaults to false. Setting Storage alone is not enough to mount them:

Migration footgun. Before this release a non-nil FileStorage auto-mounted /files. That is no longer implied — if you relied on the standalone endpoints, add MountEndpoints: true. Model file fields and per-model attachment routes remain gated on Storage alone and are unaffected.

Upload size limits

A multipart request is capped at 32 MB in total by default, across every part. Anything larger is rejected with 413 BODY_TOO_LARGE while it streams — before a byte is written to a temp file, let alone to storage. Raise or lower the ceiling per app:

FilesConfig: maniflex.FilesConfig{
    Storage:         fs,
    MaxUploadBytes:  100 << 20, // total request size (default 32 MB)
    MaxUploadMemory:   8 << 20, // buffered in RAM before spooling (default 32 MB)
}

MaxUploadBytes bounds the request; the per-field max_size tag bounds an individual attachment within it. Both apply, and the request ceiling is checked first — so max_size:2MB on a field does not stop a client from sending a 50 GB body, but MaxUploadBytes does.

For a tighter limit on one model, register body.MaxBodySize on the Deserialize step; it overrides MaxUploadBytes for the models it is scoped to.

Custom storage keys with KeyGen

By default a POST /files upload is stored under uploads/<uuid>/<sanitised-filename>. Override KeyGen to control the layout — for example, to shard by tenant read from the request context:

FilesConfig: maniflex.FilesConfig{
    Storage:        fs,
    MountEndpoints: true,
    KeyGen: func(ctx *maniflex.ServerContext, h *multipart.FileHeader) string {
        tenant := ctx.Auth.Claims["tenant"] // populated by a BeforeMiddleware
        return fmt.Sprintf("%s/%s", tenant, h.Filename)
    },
},

The returned string is used verbatim as the storage key — sanitise any user-supplied component yourself (the default uses sanitizeFilename). KeyGen applies only to the standalone POST /files route; per-model attachment keys are framework-generated.

KeyGen controls the layout of a key; it does not bind the key to a caller. The framework adds a scope prefix on top of whatever KeyGen returns — see Key ownership and FilesConfig.KeyScope.

S3, R2, MinIO, DigitalOcean Spaces

The satellite module maniflex/storage/s3 ships a FileStorage implementation backed by the AWS SDK v2. It works against any S3-compatible service.

import "github.com/xaleel/maniflex/storage/s3"

store, err := s3.New(ctx, s3.Config{
    Bucket: "my-app-uploads",
    Region: "us-east-1",
    // Endpoint, UsePathStyle, KeyPrefix, ACL are all optional.
})
if err != nil { log.Fatal(err) }
server.SetStorage(store)

Credentials follow the standard AWS resolution chain (env vars, shared config, IAM instance role, IRSA, ECS task role). Override with Config.AWSConfig when you need a custom credential provider, HTTP client, or retry policy.

Per-service tips:

Use KeyPrefix to share one bucket across environments (KeyPrefix: "staging/") — callers pass logical keys and never see the prefix. File metadata (filename, size, content type) is stored as native S3 object metadata so objects remain browsable via the AWS console and aws s3 cp without the maniflex layer.

How uploads work

A model containing one or more file fields accepts multipart/form-data on create and update, in addition to JSON:

• Form fields named the same as JSON fields populate the row’s scalar values.
• Form file parts named after a file field are streamed to storage; the resulting key is written to the column.

A form carries only strings, so a value bound for a column that is not one is converted before it is written, and a string that will not convert is 422 rather than stored:

An empty value for a non-string column is read as no value at all, because a browser posts every input in the form including the ones nobody filled in. A nullable column (*int) stores NULL; one whose type has no null is refused by name, the same answer the same body gets as JSON.

Conceptually:

POST /api/articles
Content-Type: multipart/form-data; boundary=...

--...
Content-Disposition: form-data; name="title"

The First Post
--...
Content-Disposition: form-data; name="cover"; filename="hero.png"
Content-Type: image/png

<bytes>
--...

The response is the usual JSON envelope; the cover field carries the storage key the client uses to fetch the file later.

The framework rejects an upload before it reaches storage if it violates the field’s max_size or accept constraints.

Sending a pre-uploaded key

A file field also accepts a plain string in JSON — the storage key of a file already uploaded via the standalone endpoint. This is useful when the upload is decoupled from the record creation (large files uploaded ahead of time, re-using an existing file, and so on).

The key is checked against storage before the write: setting a file field to a string key that does not exist in the configured FileStorage is rejected with 422 FILE_NOT_FOUND, so a record can never reference a dangling key. (Pass JSON null to clear the field.) In production the key exists because the client uploaded it first — via the multipart part, a prior POST /files, or a presigned upload. In tests, seed the key into the shared storage before referencing it.

The field’s max_size and accept rules apply here too, checked against the object actually in storage — the same bytes get the same answer whichever way they arrived. This is new in v0.2.3: before it, this path checked only that the key existed, so uploading out of band and referencing the key was a way past both rules. See the changelog if you relied on that.

Key ownership

A storage key is bound to the principal that mints it, so a key one caller learns cannot be pinned onto another caller’s record. Keys are not secrets — they travel in signed URLs and file_acl:private responses — and without this a caller who obtained another record’s (or another tenant’s) key could reference it on their own record, and an auto_delete field could then delete a blob it never owned.

Every minting path — POST /files, a presigned upload, and a multipart upload through a model — prefixes the key with a hash of the caller’s scope, and a reference by a different scope is refused with 403 FILE_FORBIDDEN. The scope defaults to ctx.Auth.TenantID (so a tenant’s members share one), else ctx.Auth.UserID. Override it when your principal lives elsewhere:

FilesConfig: maniflex.FilesConfig{
    Storage: store,
    // Bind each key to the user rather than the tenant. Guard the nil case:
    // an anonymous request has no principal, and returns an unscoped key.
    KeyScope: func(ctx *maniflex.ServerContext) string {
        if ctx.Auth == nil {
            return ""
        }
        return ctx.Auth.UserID
    },
}

The scope must resolve consistently across the mint request and the later reference — if your POST /files auth and your model auth populate ctx.Auth differently, read whatever both share.

A key minted while no principal was present is unscoped and referenceable by anyone; returning "" from KeyScope opts a request out. Keys minted before v0.2.3 carry no scope marker and are likewise left to the existence check, so upgrading breaks no reference to an already-stored key — the guarantee holds for every key minted under a principal from v0.2.3 on.

Direct-to-storage uploads (upload:presigned)

By default an upload travels client → app → storage, and the app holds the whole body while it does: the multipart form is drained before the handler runs, and the in-memory buffer defaults to the same 32 MB as the body cap, so nothing spools to disk either. A 60 MB video therefore costs 60 MB of server memory and two hops of bandwidth to store one object.

Add upload:presigned and the bytes go straight to the bucket:

type Post struct {
    maniflex.BaseModel
    Title string `json:"title"`
    Video string `json:"video" mfx:"file,upload:presigned,accept:video/mp4,max_size:60MB"`
}

That mounts one extra route:

POST /posts/video/upload-url

There is no record id in that path, deliberately: a create-time file field has no record yet, so a record-scoped route could not serve one. The same route works for create and update.

The flow is two phases, and the second one is just an ordinary write:

① POST /posts/video/upload-url
   {"filename": "clip.mp4", "content_type": "video/mp4", "size": 41231234}

   → 200 {
       "url":        "https://bucket.s3.amazonaws.com/",
       "method":     "POST",
       "fields":     { "key": "...", "policy": "...", "x-amz-signature": "..." },
       "key":        "uploads/<uuid>/clip.mp4",
       "max_size":   62914560,
       "expires_at": "2026-07-17T13:05:00Z"
     }

② the client POSTs the file straight to `url` as multipart/form-data,
   sending every entry of `fields` first and the file last

③ POST /posts   {"title": "...", "video": "uploads/<uuid>/clip.mp4"}
   → the ordinary create, which verifies the object and stores the key

Phase ③ is the completion step, and there is nothing else to call: the record either names the key or it does not. That is why no pending-upload state exists to reconcile — if a client uploads and never completes, no record references the object and nothing is corrupt (the object itself is an orphan; see auto_delete).

The field’s rules bind at both ends. At ① the declared content_type and size are checked against accept and max_size, so a URL is never minted for a file the field would refuse. The limits are then pinned into the signature — S3’s POST policy carries a content-length-range, so S3 itself rejects an oversize body — and at ③ the stored object’s real size and type are checked again. That last check is the one that matters: a signature can only bound what the backend enforces, and the record is what makes an object real.

The client never chooses the key. It is minted server-side through FilesConfig.KeyGen (so a per-tenant prefix scheme covers presigned uploads too) and returned in the response. A client that could name the key could aim its upload at another record’s object.

The authorisation covers one key, not one write. It is short-lived, not one-shot. Neither an S3 POST policy nor a presigned PUT can be spent — the storage backend verifies a signature, and a signature that verifies once verifies every time until it expires. So whoever holds the response from ① may repeat ② as often as they like inside the window — including after ③ has stored the key, overwriting the bytes a record already points at. No backend can close this; it is a property of signed URLs rather than of this framework.

Three things bound it. The key is minted server-side, so a replay can only rewrite that object and cannot reach another. The mint route is authenticated, so the window opens only for callers you already trust with the write. And expires_at in the response is the hard edge — set by FilesConfig.SignedURLTTL, default 1 hour.

An hour is generous for a capability that stays live after the upload finishes. Shorten it if your clients upload promptly — but note the same knob bounds signed downloads, so the two cannot be tuned apart; pick the shorter requirement. If the bytes must be immutable once written, verify them at ③ and copy the object to a key the client was never authorised for.

Auth applies. The mint route runs Auth → handler → Response, so whatever gates the model gates the minting — granting the right to write an object is not something to leave unauthenticated. Note the operation is maniflex.OpPresignUpload, not OpCreate: the mint is not the create and can precede one by minutes, so scope middleware with ForOperation(OpPresignUpload) if you need it there.

Backend support. Presigning requires a backend that can mint one. storage/s3 can (AWS S3, R2, MinIO, Spaces, …). LocalStorage cannot, and says so: the route answers 501 PRESIGN_UNSUPPORTED rather than handing back an unsigned URL, which would be an open write endpoint rather than a degraded presigned one. Use the ordinary multipart upload with LocalStorage.

Streaming uploads (upload:stream)

upload:presigned takes the bytes off the app entirely, which is ideal when the client can do the two-phase dance and the backend can presign. When it cannot — LocalStorage, or a client that only knows how to POST one multipart form — the bytes still have to pass through the app, and by default the whole request is buffered first (in memory up to MaxUploadMemory, the rest to temp files) before a single byte reaches storage. upload:stream removes that landing: the field’s part is piped straight into FileStorage.Store as it arrives off the socket.

type Post struct {
    maniflex.BaseModel
    Title string `json:"title"`
    Video string `json:"video" mfx:"file,upload:stream,accept:video/mp4,max_size:60MB"`
}

Nothing about the request shape changes — it is the same multipart POST /posts as an unflagged file field. Only where the bytes go changes: to the backend directly, not to the app’s disk first.

Two rules bind differently when the length is not known until the stream ends:

• accept is checked first, from the part’s declared type (or a sniff of the first 512 bytes when it declares none), so a disallowed type is refused with 415 before anything is stored.
• max_size is enforced mid-stream: the upload is cut off and answered 413 the moment it runs past the limit. By then a partial object exists in storage — the request ends non-2xx, so the same orphan cleanup that protects every failed upload deletes it (see Automatic cleanup). A backend that can reject early (S3 rejects an oversize multipart part) still saves the bandwidth; the framework catches the rest.

Because the length is unknown while streaming, FileStorage.Store receives a FileMeta.Size of 0 and must store an unsized reader — read it to EOF rather than trusting Size. storage/s3 does this transparently (the AWS SDK uploader switches to a multipart upload); LocalStorage copies the reader as-is. A custom backend that assumed a known length needs to handle the unsized case before enabling upload:stream against it.

Which one? upload:presigned when the bytes should never touch the app and the backend can presign — the best choice for the very largest files. upload:stream when they must pass through (to scan, transform, or because the backend cannot presign) but should not land on disk on the way. Plain file (buffered) for everything else — it is the default for a reason, and streaming trades a pre-storage validation gate for a stored-then-cleaned one. The two upload: strategies are mutually exclusive on one field; setting both is a registration error.

Standalone file endpoints

When MountEndpoints is true, three routes are mounted under PathPrefix:

POST /files returns 201 with {"data": {"key": "...", "content_type": "...", "size": ..., "filename": "..."}}. The returned key is the value to store in a file-tagged column. It streams the file part straight to storage as it arrives (see Streaming uploads), so a large standalone upload never lands on the app server’s disk; size in the response is the length measured while streaming. A custom FilesConfig.KeyGen here sees a *multipart.FileHeader whose Size is 0, since the length is not yet known — key off Filename/Header instead.

GET /files/{key...} streams the body with Content-Type and Content-Length from the stored metadata. For safety it always sends X-Content-Type-Options: nosniff and serves only an allowlist of content types (common images, PDF, plain text) inline; everything else — including text/html and image/svg+xml — is sent as a Content-Disposition: attachment download so a stored file cannot execute script on the API origin. The original filename is serialized as a standards-compliant media-type parameter rather than copied verbatim from storage metadata; quotes and controls cannot create extra header parameters, and names requiring UTF-8 use filename*. Missing keys return 404.

These endpoints are storage-key-addressed and have no built-in auth when BeforeMiddlewares is empty. Set it to wrap the routes with the same pipeline middleware (e.g. JWT, role checks) that protects your model endpoints:

maniflex.New(maniflex.Config{
    FilesConfig: maniflex.FilesConfig{
        Storage:        fs,
        MountEndpoints: true,
        BeforeMiddlewares: []maniflex.MiddlewareFunc{
            auth.JWTAuth(secret, auth.JWTOptions{}),
            auth.RequireRole("admin"),
        },
    },
})

Each middleware sees a synthesised ServerContext (Request, Writer, Ctx, RequestID, logger — no Model/Operation, since these routes are outside the model pipeline). Aborting the context short-circuits the request before the file handler runs. Leaving BeforeMiddlewares empty keeps the pre-fix behaviour for backward compatibility, but production deployments should populate it — anyone who guesses a key could otherwise delete arbitrary files. The server logs a warning at startup when /files is mounted without BeforeMiddlewares. For a deliberately public file service, set FilesConfig.AllowPublic; this suppresses strict/production validation errors but installs no middleware and changes no runtime behavior.

Before vs. after middleware

BeforeMiddlewares run before the handler and own request control: they can authenticate, populate ctx.Auth, or short-circuit (abort / set ctx.Response) to replace the response entirely.

AfterMiddlewares run after the handler has served the request. Because the handler streams its response (status, headers, body) straight to the client, the response is already committed by the time an after-middleware runs — so they are for observation and side effects only (audit logging, metrics, cleanup), never for altering the response. Read the outcome with:

AfterMiddlewares: []maniflex.MiddlewareFunc{
    func(ctx *maniflex.ServerContext, next func() error) error {
        status := ctx.Writer.(interface{ Status() int }).Status()
        log.Printf("file request completed: %d", status)
        return next()
    },
},

Setting ctx.Response from an after-middleware is ignored (and logged) rather than corrupting the already-sent body. To alter, replace, or block the response, use BeforeMiddlewares.

Per-model attachment routes

For each mfx:"file" field on each model, the framework mounts a record- scoped download path:

GET /:model/:id/:file_field

E.g. GET /api/patients/123/discharge_summary streams the file referenced by Patient.DischargeSummary for record 123.

Unlike GET /files/{key...}, this route runs through the read pipeline for the parent record — the same Auth, soft-delete, and tenancy middleware that protect GET /api/patients/123 also protect the download. Use this for any attachment whose access depends on the parent row.

Response codes:

The route is only mounted when Config.FilesConfig.Storage is configured; with no storage backend, the route is absent and requests return 404 from the router. (Unlike the standalone /files endpoints, per-model attachment routes do not require MountEndpoints.)

Internally this is dispatched as its own operation, maniflex.OpReadAttachment. Middleware filtered by ForOperation(OpRead) does apply to attachment requests: an attachment is a read of one record, so whatever decides who may read that record decides who may download its file. The implication runs one way only — ForOperation(OpReadAttachment) means attachment requests alone.

Before v0.2.5 an OpRead-scoped middleware did not run for attachments, so tenancy written that way left the attachment route unscoped.

Resumable downloads (HTTP Range)

Both download routes — GET /files/{key...} and the per-model attachment route — honour the Range request header, so a client can resume an interrupted download or seek into a large media file instead of refetching it from the start.

# the last 500 bytes
curl -H 'Range: bytes=-500' localhost:8080/api/files/uploads/<uuid>/clip.mp4

# resume from where a failed download stopped
curl -H 'Range: bytes=1048576-' localhost:8080/api/patients/123/scan

A satisfiable range answers 206 Partial Content:

The security headers a full download sends — X-Content-Type-Options: nosniff and the Content-Disposition inline/attachment decision — are identical on a 206.

Response codes:

Ranges the server declines. A malformed header, an unrecognised unit, and a multi-range request (bytes=0-99,200-299) are all answered with the whole object and 200 rather than an error — the spec permits ignoring any Range, and serving several windows would require a multipart/byteranges body. A client that asks for several windows gets the object and slices it itself.

Backend support

How much a range actually saves depends on the storage backend:

To support ranges in your own backend, implement the optional maniflex.RangeRetriever alongside FileStorage:

func (s *MyStorage) RetrieveRange(
    ctx context.Context, key string, offset, length int64,
) (io.ReadCloser, maniflex.FileMeta, error) {
    // Return exactly the bytes [offset, offset+length).
}

The framework resolves the Range header against the size your Stat reports before calling, so offset and length are always absolute and in bounds — you never have to parse a header or clamp a window. Adding the method is all that is needed; there is nothing to register.

Automatic cleanup

By default, a file field’s stored bytes are removed when:

• the record is hard-deleted, or
• the field is overwritten by an update.

Setting auto_delete:false opts out, leaving the file in storage for out-of-band lifecycle management. Soft-deleted rows never trigger cleanup — the file is preserved until the row is hard-deleted.

Bring-your-own storage

Implement maniflex.FileStorage:

type FileStorage interface {
    Store(ctx context.Context, key string, r io.Reader, meta FileMeta) error
    Retrieve(ctx context.Context, key string) (io.ReadCloser, FileMeta, error)
    Delete(ctx context.Context, key string) error
    Exists(ctx context.Context, key string) (bool, error)
    Stat(ctx context.Context, key string) (FileMeta, error)
    PresignUpload(ctx context.Context, key string, opts PresignUploadOptions) (*PresignedUpload, error)
    URL(ctx context.Context, key string, opts PresignURLOptions) (string, error)
}

Stat and PresignUpload are new in v0.2.3 and break every third-party backend until it implements them.

Stat returns an object’s metadata without fetching its body. Return maniflex.ErrFileNotFound for a missing key. Its Size and ContentType are what a file field’s max_size and accept are checked against when a record references a key, so they must describe what is really stored — a client that uploaded 5 GB to a 60 MB field is caught here or nowhere. If your backend has no cheap metadata call, Retrieve and measure; it is correct, merely slower.

PresignUpload mints a direct-to-storage authorisation. If your backend cannot, return maniflex.ErrPresignUnsupported — the framework turns that into a clean 501. Do not return an unsigned URL instead: that is not a degraded presigned upload, it is an unauthenticated write endpoint. Pin opts.MaxSize into the signature if you can (S3’s POST policy does, via content-length-range; a presigned PUT cannot), since the framework’s own check can only run once the bytes are already stored and paid for.

URL’s signature changed in v0.4.2 and breaks every third-party backend until updated. The ttl time.Duration parameter became a PresignURLOptions struct so callers can pin the response headers a URL serves with, not only how long it lives.

The mechanical migration is ttl → maniflex.PresignURLOptions{TTL: ttl}; opts.TTL keeps every meaning ttl had, zero still being the permanent / public mode. A backend that cannot honour the response overrides needs nothing further — ignoring them is supported, and LocalStorage does exactly that.

Retrieve returns maniflex.ErrFileNotFound when the key does not exist. Delete should also return maniflex.ErrFileNotFound for missing keys so the standalone DELETE /files/* handler can surface a 404 without an extra Exists round-trip; backends that cannot detect the case atomically (e.g. S3 DeleteObject succeeds for missing keys) may return nil instead — both are treated as “delete succeeded”. Store is given a framework-generated key of the form uploads/<uuid>/<sanitised-filename>; create any intermediate directories or object prefixes as needed.

Signed URL options

URL takes a PresignURLOptions. Beyond TTL, every field asks the backend to pin a response header into the URL, so one signed link can serve an object differently from how it is stored:

url, err := store.URL(ctx, key, maniflex.PresignURLOptions{
    TTL:      15 * time.Minute,
    Download: true,
    Filename: "invoice-2026.pdf",
})

Download and Filename are the common case, and are encoded for you — non-ASCII names come out in the RFC 5987 filename* form rather than as a raw UTF-8 filename= that standards-compliant browsers discard. Backends must call opts.ContentDisposition() rather than reading the fields directly, so every backend encodes a name the same way. Set ResponseContentDisposition yourself only for a form those two cannot express; it always wins over them.

The remaining fields — ResponseCacheControl, ResponseContentEncoding, ResponseContentLanguage, ResponseContentType, ResponseExpires — map to S3’s response-* query parameters, and VersionID selects one version of an object in a versioned bucket.

They are best-effort: a backend honours what it can and ignores the rest. LocalStorage ignores all of them and returns /files/<key> as before. That is deliberate rather than unfinished — it serves from your application’s own origin, where the parameters would be unsigned, so honouring a caller-chosen ResponseContentType over stored bytes would be a stored-XSS vector. S3’s are safe because they sit inside the signature.

Options set on a signed URL are not reachable from mfx:"file_acl:signed", which still mints a URL with the configured TTL and nothing else. Call FileStorage.URL yourself where you need the overrides.

Optional: RangeRetriever

Beyond FileStorage, a backend may implement maniflex.RangeRetriever to serve byte windows for resumable downloads:

type RangeRetriever interface {
    RetrieveRange(ctx context.Context, key string, offset, length int64) (io.ReadCloser, FileMeta, error)
}

It is optional and additive — a backend that omits it keeps working, serving the whole object with 200 for a Range request. Implement it if your backend can fetch a window natively (S3’s GetObject Range, a file Seek), since that is where the saving is; the bounds are pre-resolved against your Stat size, so they are always absolute and in range.

Storage backends are also expected to:

• honour ctx cancellation in Store — long uploads must abort when the request deadline elapses or the server is shutting down,

• refuse keys that name the backend’s own bookkeeping, if it keeps that bookkeeping in the same key namespace as the objects — sibling .meta.json files, as LocalStorage does. Two rules make the difference between a guard and the appearance of one:

  Put the check in whatever function turns a key into a path, not in each method. LocalStorage had it in Store and Retrieve and was missing it in Stat, Exists and Delete, so a client could delete the sidecar of any file it could name; the file kept serving, permanently stripped of its content type and download filename.

  Compare the way the storage layer compares. Windows and macOS match filenames case-insensitively, and Windows ignores trailing dots and spaces, so x.META.JSON, x.meta.json. and x.meta.json all open x.meta.json there. An exact suffix match reads as airtight and holds only on Linux.

Filenames flowing through the framework-generated key are sanitised to the charset [A-Za-z0-9._-] (other runes become _), leading dots are stripped, and the result is truncated to 120 characters. CR / LF / NUL bytes never survive into the storage key.

File fields vs. static files

File fields handle user-supplied content. They are unrelated to Static Files, which serves a fixed directory of assets you ship with the app.

Static Files

Alongside the generated model API, maniflex can serve a directory of plain static files — HTML, CSS, JavaScript, images, downloads — straight off disk. This is useful for a small admin page, a landing page, or assets referenced by an OpenAPI viewer, without standing up a separate web server.

How it works

Static serving is opt-in: set StaticDir to the directory you want served, and every file inside it is served under the /static URL path.

server := maniflex.New(maniflex.Config{
    StaticDir: "static", // serve ./static — nothing is served unless you name a dir
})

myapp/
├── main.go
└── static/
    ├── index.html        →  GET /static/index.html
    ├── css/app.css       →  GET /static/css/app.css
    └── logo.png          →  GET /static/logo.png

Files are served verbatim, so a single-page app is served in full — its index.html at the directory root and every nested asset at its own path:

static/
├── report.json                     →  GET /static/report.json
└── admin/                          →  GET /static/admin/  (serves index.html)
    ├── index.html
    └── scripts/app.js               →  GET /static/admin/scripts/app.js

If StaticDir is left empty, no static route is mounted and maniflex serves only the API. If it is set but the directory does not exist, the server logs a warning and skips the mount; the rest of the API is unaffected.

Changed in v0.2.1. Static serving used to default to <cwd>/static — any static/ directory in the working directory was published at /static/ automatically. It is now opt-in: set StaticDir explicitly. If you relied on the old default, add StaticDir: "static".

Customising the directory and prefix

Three maniflex.Config fields control static serving:

server := maniflex.New(maniflex.Config{
    StaticDir:    "public",   // serve ./public
    StaticPrefix: "/assets",  // under /assets instead of /static
})

StaticDisabled exists so an app that sets StaticDir unconditionally can still flip serving off from an env var or flag without clearing the field.

The /static route

A few details follow from how the route is mounted (the buildRouter block in router.go):

• Resolved from the working directory. A relative StaticDir resolves against <cwd>, wherever the process was started — not the location of the binary. Run the server from the project root, or cd there first, so a relative path like "static" is found.
• Mounted outside PathPrefix. Static files live at /static/... (or your StaticPrefix), not /api/static/.... The PathPrefix from maniflex.Config scopes only the model API and /openapi.json; the static mount sits at the router root.
• Trailing-slash redirect. A request to /static (no trailing slash) is 301-redirected to /static/. Requests below it are served directly.
• Directory listing. A directory request serves its index.html. Without one it answers 404, unless StaticDirectoryListing is set — a listing names every file in the directory, including ones nothing links to, so it is opt-in.

Behind maniflex.Mount

maniflex.Mount forwards PathPrefix and nothing else, so the second bullet above has a consequence: a mounted server answers 404 for every asset it serves standalone. Mount warns about it at startup, naming the prefix that went dark, whenever StaticDir is set and StaticDisabled is not.

Forward the prefix yourself to fix it, reusing the server’s own handler rather than an http.FileServer — which has none of the limits below:

r := chi.NewRouter()
maniflex.Mount(r, server)

// Static lives outside PathPrefix, so Mount does not carry it across.
inner := server.Handler()
r.Handle("/static/*", http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
    req = req.WithContext(context.WithValue(req.Context(), chi.RouteCtxKey, chi.NewRouteContext()))
    inner.ServeHTTP(w, req)
}))

The fresh chi.RouteContext is the working part: it lets the inner router re-route from the URL. r.Mount("/static", server.Handler()) reads as the obvious equivalent and answers 404, because chi hands a mounted handler an already-stripped route path.

Set StaticDisabled when something else serves the assets — a CDN, or the outer router’s own file handler — and the warning goes with it.

What is reachable

The mount is deliberately narrower than a plain file server, so pointing StaticDir at a directory that is also a working tree does not publish it:

Relative symlinks within the tree are followed normally. A symlink with an absolute target is refused even when it happens to point back inside, because os.Root cannot confirm that without resolving the path outside its own walk — which is the race it exists to remove. Use a relative link.

None of this makes an unsafe directory safe. It is still your call which directory is published; these limits only stop the most common ways one leaks more than intended.

Static files vs. file uploads

Static serving is for assets you ship with the app. It is unrelated to the file-upload feature, which stores user-submitted files and is wired up separately through Config.FilesConfig.Storage and the /files endpoints. For user uploads see File Fields & Uploads.

Localization

maniflex has first-class support for multilingual string fields. A single maniflex.LocaleString field stores all translations in one JSON column and the framework resolves the right one for each request automatically.

The LocaleString type

maniflex.LocaleString is a map[string]string where each key is a locale code and each value is the translation for that locale:

{ "en": "Finance", "ar": "مالية", "fr": "Finance" }

On SQLite it is stored as TEXT (JSON-encoded). On Postgres it is stored as JSONB, which allows GIN-indexed key lookups.

Declare a field as locale-aware with the locale directive:

type Department struct {
    maniflex.BaseModel
    Name maniflex.LocaleString `json:"name" mfx:"locale,filterable,sortable"`
    Code string                `json:"code" mfx:"required,unique"`
}

On create and update the client sends the full map:

{ "name": { "en": "Finance", "ar": "مالية" }, "code": "FIN" }

On read the framework emits a locale-resolved view (see Response modes).

Response modes

Every LocaleString field has a response mode that controls the shape of the field in API responses. The mode is resolved in this order:

1. The field’s own mfx tag (split, resolve, or dynamic)
2. The model’s ModelConfig.DefaultLocaleMode
3. The app’s LocaleOptions.DefaultLocaleMode
4. The framework default: split

split (default)

Two keys are emitted in the response:

• name — the resolved string for the effective locale
• name_i18n — the full map[string]string (always present)

{
	"name": "Finance",
	"name_i18n": { "en": "Finance", "ar": "مالية" }
}

The resolved string gives display code a stable string type; the companion _i18n map gives the editor everything it needs to build a translation form.

The companion suffix defaults to "_i18n" and is configurable via LocaleOptions.SplitSuffix.

Writing a split-mode field back

Both keys are understood on write, so a client can PATCH the object it just GETed without special-casing localized fields:

The companion takes precedence because it is the complete value, while name is one locale’s rendering of it. That is what makes an echoed response lossless: the translations the response did not show still come back in _i18n.

A bare string replaces the column rather than merging into the stored map — the same as a map write, which has never been a per-key patch. So sending only "name": "Finance" with ?locale=en leaves the field as {"en": "Finance"} and drops any other translations. Send the _i18n map when you mean to keep them.

Before v0.2.5 the _i18n key was ignored on write and a bare string was stored as a JSON scalar, which the next read could not parse — a GET→PATCH round-trip through a generic edit form left the record unreadable, returning 500 for that record and for the whole collection, since one bad row fails the list scan. A column still holding a scalar from that era now resolves to its value and logs a warning instead of erroring, so the row can be repaired with an ordinary PATCH.

That fix reached only one of the two write paths at first: the companion was consumed just when the body also carried a bare string in name. Sent on its own it answered 200 and wrote nothing — an empty column on create — and sent beside a name map it was dropped. The table above holds on every path as of this release.

resolve

The field is always a plain string — the resolved value for the effective locale. No companion field is emitted.

{ "name": "Finance" }

Use resolve when clients only ever need one language and the extra _i18n key adds no value.

dynamic

Replicates legacy behaviour:

• When ?locale= is present: emits a string (resolved for that locale)
• When ?locale= is absent: emits the full map

The field type is non-deterministic. Not recommended for new models.

Setting up the LocaleResolver

Install the LocaleResolver middleware on the Deserialize step before registration, so it runs before the framework’s built-in Deserialize:

server.Pipeline.Deserialize.Register(maniflex.LocaleResolver(maniflex.LocaleOptions{
    Supported:  []string{"en", "ar", "fr"},
    Default:    "en",
    FromHeader: true,
    RTL:        []string{"ar", "he", "fa", "ur"},
}))

LocaleOptions fields:

Locale resolution chain

When resolving which string to return, the framework walks this chain (most to least specific) and returns the first non-empty match:

1. Explicit ?locale= query parameter
2. Accept-Language header (first match in Supported), when FromHeader: true
3. Field’s default_locale:code tag
4. Model’s ModelConfig.DefaultLocale
5. App’s LocaleOptions.Default (default "en")
6. Any non-empty value in the map (last resort)

// Field-level default: Arabic is preferred for this field even when the
// request does not specify a locale.
Bio maniflex.LocaleString `json:"bio" mfx:"locale,default_locale:ar"`

// Model-level default: all locale fields on this model use French by default,
// unless overridden by a field's `default_locale` tag.
server.MustRegister(Article{}, maniflex.ModelConfig{DefaultLocale: "fr"})

Requiring a locale key

Use validate.RequireLocale to enforce that specific locale keys are present and non-empty on create (or update) requests:

server.Pipeline.Validate.Register(
    validate.RequireLocale("name", "en"),
    maniflex.ForModel("Department"),
    maniflex.ForOperation(maniflex.OpCreate),
)

A request that omits the "en" key, or supplies an empty string for it, is rejected with HTTP 422 MISSING_LOCALE. Pass multiple keys to require several locales at once:

validate.RequireLocale("name", "en", "ar")

Filtering and sorting locale fields

LocaleString fields tagged filterable and sortable work with the standard query string grammar. In split and resolve mode the framework automatically targets the effective locale’s JSON key in the database query.

GET /departments?filter=name:ilike:%25fin%25&sort=name:asc

In the example above, when the effective locale is "en", the adapter runs:

• SQLite: json_extract("departments"."name", '$.en') LIKE '%fin%'
• Postgres: "departments"."name"->>'en' ILIKE '%fin%'

You can also filter a specific locale key explicitly:

GET /departments?filter=name.ar:contains:مال

In dynamic mode without an explicit ?locale= the filter hits the raw JSON column, which typically returns no results for plain-string comparisons — this is intentional: in dynamic mode the field’s meaning depends on request context.

Searching localized content

The mfx:"searchable" full-text directive (the ?q= endpoint) indexes plain string columns only — tagging a LocaleString field searchable fails at model registration, because full-text search has no single text column to index:

maniflex: model "Department" field "Name" is mfx:"searchable" but its type is
maniflex.LocaleString; full-text search only indexes text (string) columns

Two ways to make localized content searchable:

• Substring filter (simplest). Tag the LocaleString field filterable and use ?filter=name:ilike:%25term%25. Because the value is stored as one JSON object, an ilike against the raw column matches across every locale’s text at once — no extra schema.
• Denormalized plaintext column. Add a plain string column (e.g. SearchText) tagged searchable, and populate it on create/update from a Service-step middleware that flattens the localized strings. Use this when you need true ?q= full-text ranking rather than substring matching.

RTL meta

When the resolved locale is in LocaleOptions.RTL, every response envelope gains a meta object with "_dir": "rtl" — for both list responses (which already carry pagination in meta) and single-record responses (read / create / update):

{
	"data": {
		"name": "مالية",
		"name_i18n": { "en": "Finance", "ar": "مالية" }
	},
	"meta": { "_dir": "rtl" }
}

List responses include pagination alongside the direction flag:

{ "data": [...],
  "meta": { "total": 5, "page": 1, "limit": 20, "pages": 1, "_dir": "rtl" } }

Clients can use meta._dir to switch text direction without needing to know which locale is active.

Model-level mode override

Set a uniform mode for all LocaleString fields on a model without tagging each one individually:

server.MustRegister(LegacyArticle{}, maniflex.ModelConfig{
    DefaultLocaleMode: maniflex.LocaleModeDynamic,
})

Field-level tags take precedence over the model setting, which in turn takes precedence over the app-level LocaleOptions.DefaultLocaleMode.

Full example

type Product struct {
    maniflex.BaseModel
    Name        maniflex.LocaleString `json:"name"        mfx:"locale,filterable,sortable"`
    Description maniflex.LocaleString `json:"description" mfx:"locale,resolve"`
    SKU         string                `json:"sku"         mfx:"required,unique"`
}

func main() {
    server := maniflex.New(maniflex.Config{
        // application settings
    })

    server.Pipeline.Deserialize.Register(maniflex.LocaleResolver(maniflex.LocaleOptions{
        Supported:  []string{"en", "ar"},
        Default:    "en",
        FromHeader: true,
        RTL:        []string{"ar"},
    }))

    server.MustRegister(Product{})

    db, _ := sqlite.Open("store.db", server.Registry())
    server.SetDB(db)
    server.Start()
}

With this setup:

• GET /products returns name as the resolved English string plus name_i18n with all translations; description is always a resolved English string.
• GET /products?locale=ar resolves both fields to Arabic.
• POST /products with {"name":{"en":"Laptop"},"sku":"LAP-01"} succeeds.

Pipeline Overview

Every HTTP request handled by a generated model route flows through the same six-step pipeline. Each step has a default behaviour supplied by the framework and a registry of user middleware that can run before, after, or in place of it. This page describes what each step is responsible for; later pages cover how to register middleware on them and how state flows between them.

The six steps

Auth → Deserialize → Validate → Service → DB → Response

The OpenAPI endpoint (GET /openapi.json) has its own three-step pipeline — Auth → Generate → Response — accessible via server.Pipeline.OpenAPI. The model-route pipeline described here is the one used for everything else.

Operations

The CRUD operation a request performs is identified by an Operation value that is stable across all six steps:

A HEAD request has no operation of its own: it is GET with the body suppressed, so it runs as OpList (collection) or OpRead (item) — same middleware, same status code, no body. The OpHead constant still exists but is never set on a request; scope HEAD-aware middleware with OpRead / OpList.

ctx.Operation is the value middleware uses to branch behaviour. OpAction requests follow a trimmed pipeline (Auth → action handler → Response); the Deserialize, Validate, Service, and DB steps are skipped for them.

Per-step responsibilities

Auth

The Auth step is the place to verify a token, look up a user, and set ctx.Auth. The default handler does nothing; an unauthenticated request reaches the DB layer with ctx.Auth == nil. Add a middleware here to reject anonymous callers, populate identity, or check scopes.

Deserialize

The Deserialize step assembles request input from three sources:

• The URL query string becomes a *QueryParams on ctx.Query. Filter and sort references are validated against the model’s tag-derived field lists.
• A JSON body becomes ctx.ParsedBody (a read-only *RequestBody, JSON-keyed) and is bound to the typed record ctx.Record. Bodies over 4 MB are rejected as 413 BODY_TOO_LARGE; a genuine I/O failure reading the body is 400 BODY_READ_ERROR.
• A multipart body populates both ctx.ParsedBody (the form fields) and ctx.Files (the file parts). The form-field-to-file-field mapping is by name. A form carries only strings, so a value bound for a number, boolean or timestamp column is converted here — see How uploads work.

Reads carry no body, so only ctx.Query is populated for OpList / OpRead.

Validate

The Validate step runs only on OpCreate and OpUpdate. It applies the rules declared by mfx: tags to ctx.ParsedBody:

• readonly fields and the id column are silently stripped.
• immutable fields are stripped on update.
• required fields must be present on create.
• enum, min, max are checked when the value is present.
• Each value must be one the field’s Go type can hold: {"age": "abc"} for an int column is 422, as are 1.5 for an int, a number for a string, and a timestamp that is not RFC 3339.

The type check applies to the columns whose type accepts one shape. A type that brings its own — a LocaleString, or a SQLTyper such as money.Amount, which takes both {"amount", "currency"} and a bare 12.34 — is asked whether it can read the value rather than measured against a rule this step invented.

Validation failures abort the pipeline with 422 Unprocessable Entity and a details payload listing every offending field.

Service

The Service step has no default behaviour — it exists for application logic. Hashing a password before persistence, charging a payment, recomputing a derived total, calling an external API: all of these belong here. A Service middleware that needs to short-circuit the request calls ctx.Abort(...) and returns without invoking next().

DB

The DB step is the only step with side effects on the database. It selects the operation matching ctx.Operation, builds the column-keyed write set from ctx.Record (falling back to ctx.ParsedBody), calls the adapter, and writes the result into ctx.DBResult — a *ListResult for lists, otherwise the record (a typed *T on reads). When ctx.Tx is set, the call is routed through the transaction; otherwise the bare adapter is used.

Two error classes are normalised at this step:

• maniflex.ErrNotFound becomes 404 NOT_FOUND.
• *maniflex.ErrConstraint is split by kind: a unique or foreign-key violation becomes 409 CONFLICT, while a NOT NULL violation becomes 422 VALIDATION_ERROR (a missing-required-value problem, not a conflict).

A cancelled context becomes 504 TIMEOUT — unless the cancellation came from the client hanging up, which is 499 with no body (see Error Handling). All other adapter errors surface as 500 DB_ERROR.

Response

The Response step serialises ctx.DBResult into an APIResponse and writes it to the wire. List responses include a meta block with total, page, limit, and pages; single-record responses do not. The standard envelope is {"data": ...} for success and {"error": {...}} for failure.

Short-circuiting

Any middleware can stop the pipeline by setting ctx.Response (typically via ctx.Abort(status, code, message)) and returning without calling next(). Subsequent steps are skipped and the Response step writes the prepared error envelope. This is the standard mechanism for unauthorised requests, validation failures inside Service middleware, and any other refusal that should not reach the database.

Per-step middleware

Each step exposes a *StepRegistry on server.Pipeline:

server.Pipeline.Auth.Register(jwtAuth)
server.Pipeline.Service.Register(hashPassword,
    maniflex.ForModel("User"), maniflex.ForOperation(maniflex.OpCreate))

Registered middleware can run Before the default (the default position), After it, or Replace it entirely. Scoping by model and operation is covered in Writing Middleware.

Next

• ServerContext — the object threaded through every step.
• Writing Middleware — Register, options, positions.
• Transactions — wrapping the DB step in a transaction.
• Error Handling — the error envelope and sentinel errors.

ServerContext

*maniflex.ServerContext is the object threaded through every pipeline step for one HTTP request. Steps read from it, write to it, and call next() to proceed. Middleware does the same. This page documents the fields and methods middleware will commonly touch.

Lifecycle

A new ServerContext is constructed by the handler for every request, populated incrementally by the pipeline, and discarded once the response is written. It is not safe to share across requests or goroutines.

The fields populated by each step are:

Routing context

Set by the handler before Auth runs; safe to read in any step.

A Singleton has no {id} to read, so ResourceID is pinned to the SingletonID placeholder. For an unscoped singleton that placeholder is the row’s real id. For a scoped one it is not — there is one row per scope, and the DB step swaps in the caller’s real id once the forced filters are known.

Middleware running before that swap — anything at the DB pipeline’s Before position — therefore sees a value that addresses no row. Call ctx.ResolveResourceID() instead of reading the field directly when you need an id you can query with:

id := ctx.ResolveResourceID() // "" if the scoped row is not provisioned yet

It returns ctx.ResourceID unchanged for every non-singleton request, and never provisions a row.

For it to resolve anything, the scope must already be established — register the scope middleware with maniflex.ProvidesScope():

server.Pipeline.DB.Register(
    db.Tenancy("org_id", tenantFromAuth),
    maniflex.ProvidesScope(),
)

That hoists it to run right after Deserialize instead of at the DB step, so Validate, Service and the DB step all see the same scope. Without it the scope still applies to the query, but nothing before the DB step can ask what it is.

Step outputs

Populated in order by the pipeline.

Setting Response from any step causes the remaining steps to skip and the prepared envelope to be written. See Abort below.

Auth

Auth *AuthInfo is populated by Auth middleware. When nil, the request is anonymous.

type AuthInfo struct {
    UserID       string
    Roles        []string
    Claims       map[string]any
    TenantID     string
    IdentityType AuthIdentityType  // human, service_account, anonymous
    Scopes       []string
    SessionID    string
    AuthMethod   string             // "jwt", "api_key", "session", …
}

ctx.HasRole(role string) bool is a convenience wrapper that returns false when Auth is nil.

Transactions

Tx Tx carries the active transaction, if any. When set, the default DB step routes through it. ctx.BeginTx(ctx.Ctx, opts) returns a Tx and is the standard way for middleware to start one. See Transactions for the full pattern.

Aborting the pipeline

ctx.Abort(status int, code, message string) populates ctx.Response with an error envelope. The current middleware must then return nil without calling next(). Subsequent steps are skipped; the Response step writes the prepared error. For 5xx statuses, the supplied message is logged with the request ID but replaced by generic status text on the wire; 4xx messages are preserved.

if header == "" {
    ctx.Abort(http.StatusUnauthorized, "UNAUTHORIZED", "missing token")
    return nil
}

Calling next() after Abort

Abort does not stop the pipeline — it only populates ctx.Response. If the middleware calls next() afterwards, the chain continues exactly as if the abort had not happened:

• The remaining steps still execute, with all their side effects. The DB step will still issue its query and possibly modify the database; a Service middleware will still call out to external services.
• Any of those steps may overwrite ctx.Response — for example, the DB step replaces it with a 404 NOT_FOUND if the record is missing, or the default Response step builds a 200 OK envelope from ctx.DBResult. Whichever step writes last wins.
• If nothing downstream touches ctx.Response, the original abort envelope is preserved and sent to the client — but the side effects have already happened.

The result is almost always a bug: either the client sees a misleading status (a write succeeded but the response claims it was rejected), or the database is mutated by a request that was meant to be refused. Always return without next() after Abort.

Reading input

Three helpers wrap common request reads:

BindJSON calls Abort internally on error and returns a non-nil error so the caller can return nil immediately.

The request body

ctx.ParsedBody holds the deserialized JSON (or multipart form) body as a *RequestBody. It is read-only: there is no exported way to index or assign it, so a stray ctx.ParsedBody["x"] = y is a compile error. This is deliberate. The body is mirrored onto a typed record (ctx.Record), and the only mutators — ctx.SetField / ctx.DeleteField — keep both in sync; writing the map directly would update one and not the other, and the change could be silently dropped at the DB step.

Reading

All are nil-safe: ctx.ParsedBody is nil for body-less requests (GET, DELETE) and the readers return zero values rather than panicking.

Numbers read from the body are float64

The body is JSON decoded into a map, so every number in it is a float64 — including one written as an integer. A float64 represents every integer only up to 2^53 (9007199254740992), so a larger one read back through ctx.Field, ParsedBody.Map(), a validation callback or an ABAC policy has been rounded, and can differ from what the client sent in either direction.

The stored value has not been. Writes source their columns from the typed record (ctx.Record), where an int64 field decodes from the JSON number exactly, so a large id or amount reaches the database intact — the body map is the fallback and a typed write does not use it. That is the trap worth knowing: above 2^53 the value a policy inspects and the value the row receives can disagree.

If a middleware needs an integer larger than 2^53 exactly, read it from the typed record (maniflex.For[T](ctx)) rather than from the body map.

For typed access, read the whole body as the concrete model struct:

u, ok := maniflex.For[User](ctx)   // (*User, bool) — false if no User body is bound
u, err := maniflex.Bind[User](ctx) // (*User, error) — errors when absent

// or adapt a typed handler straight into middleware:
server.Pipeline.Service.Register(
    maniflex.Handle(func(ctx *maniflex.ServerContext, u *User) error {
        if u.Age < 18 {
            ctx.Abort(http.StatusUnprocessableEntity, "TOO_YOUNG", "must be 18+")
        }
        return nil
    }),
    maniflex.ForModel("User"), maniflex.ForOperation(maniflex.OpCreate),
)

Writing

Middleware that injects or rewrites a field must go through these setters so the value reaches both the body and the typed record (and so the DB step persists it):

server.Pipeline.Service.Register(func(ctx *maniflex.ServerContext, next func() error) error {
    ctx.SetField("owner_id", ctx.Auth.UserID) // force the owner server-side
    return next()
}, maniflex.ForOperation(maniflex.OpCreate))

Cross-step storage

For state that one middleware needs to pass to another:

ctx.Set("invoiceID", inv.ID)
// later, in another middleware:
id, ok := ctx.Get("invoiceID")

The store is per-request and discarded with the context.

Direct database access

Middleware that needs to reach beyond ctx.Model — to read another model, run a raw query, or take a row lock — has four entry points, all routed through ctx.Tx when one is active:

GetModel returns an accessor whose methods route through ctx.Tx when set, so middleware in a transaction does not have to thread the Tx manually.

Typed cross-model helpers

GetModel(name) is dynamic — string-named, exchanging map[string]any. For compile-time types use the generic free functions, which resolve the model from the type parameter and route through ctx.Tx the same way (so they also participate in maniflex.Batch):

u, err   := maniflex.Read[User](ctx, id)        // *User
all, err := maniflex.List[User](ctx, nil)        // []*User
created, err := maniflex.Create(ctx, &User{Name: "Jane"})
maniflex.Update(ctx, id, &User{ /* full record */ })
maniflex.Delete[User](ctx, id)

Results that are not a registered model — raw SQL, aggregates, recursive queries — use maniflex.Row (an alias for map[string]any); RawQuery, Aggregate, and RecursiveQuery return []maniflex.Row.

Placeholders in raw SQL are rebound to the adapter’s dialect, so ? works on both SQLite and Postgres ($N). Always pass values as args — never interpolate them into the query string.

Logging

ctx.Logger() *slog.Logger returns a slog logger pre-seeded with request_id, trace_id, and service attributes, so log lines emitted from middleware are correlated automatically.

ctx.Logger().Info("payment captured",
    slog.String("invoice_id", inv.ID),
    slog.Float64("amount", inv.Total),
)

Service name

ctx.ServiceName() returns the Config.ServiceName configured on the server. Middleware uses this to enrich audit records or outgoing requests without holding a reference to the framework Config.

Next

• Writing Middleware — composing middleware on these fields.
• Transactions — ctx.Tx, BeginTx, LockForUpdate.
• Error Handling — Abort and the response envelope.

Writing Middleware

A middleware is a function that runs as part of one of the six pipeline steps. It can inspect and modify the request context, call into the database, decide whether to proceed, and inject behaviour before or after the step’s default handler.

Signature

type MiddlewareFunc func(ctx *maniflex.ServerContext, next func() error) error

A middleware does one of two things:

• Continue the pipeline — perform its work, then call next() and return the result. The chain executes the remaining middleware in the step and then the steps after it.
• Short-circuit — set ctx.Response (typically via ctx.Abort(...)) and return nil without calling next(). The remaining steps are skipped and the prepared response is written to the wire.

func bearerToken(ctx *maniflex.ServerContext, next func() error) error {
    header := ctx.Request.Header.Get("Authorization")
    if !strings.HasPrefix(header, "Bearer ") {
        ctx.Abort(http.StatusUnauthorized, "UNAUTHORIZED", "missing bearer token")
        return nil
    }
    ctx.Auth = &maniflex.AuthInfo{UserID: parseSubject(header)}
    return next()
}

Typed middleware

For middleware that works with the request body, maniflex.Handle[T] adapts a typed handler into a MiddlewareFunc. It hands you the bound record as a concrete *T (the same value ctx.Record holds) instead of a map, runs only when a *T body is bound, and is skipped on body-less operations:

server.Pipeline.Service.Register(
    maniflex.Handle(func(ctx *maniflex.ServerContext, u *User) error {
        if u.Age < 18 {
            ctx.Abort(http.StatusUnprocessableEntity, "TOO_YOUNG", "must be 18+")
        }
        return nil
    }),
    maniflex.ForModel("User"), maniflex.ForOperation(maniflex.OpCreate),
)

To change a field, call ctx.SetField(name, value) rather than mutating the struct, so the write reaches both the body and the record (see ServerContext › The request body). For an ad-hoc typed read inside a plain middleware, use maniflex.For[T](ctx) / maniflex.Bind[T](ctx).

Where the record is bound matters. Deserialize decodes the client’s body into *T before Validate runs, so a middleware registered on Deserialize sees the raw request: readonly, hidden and immutable fields still hold whatever the client sent, because nothing has refused them yet. From Validate onwards — which is where the example above sits — those fields have been reset, so u.Role is the empty string rather than the "admin" a client tried to send. Register body-inspecting middleware on Validate or later unless you specifically want to see what was attempted.

Registration

Each pipeline step exposes a *StepRegistry on server.Pipeline. Register a middleware on the step where its work belongs:

server.Pipeline.Auth.Register(bearerToken)

Without options, the middleware applies to every model and every operation.

Register must be called before Start() or Handler(). Building the router closes the registration window: each step’s chain is composed once per (model, operation) and cached from then on, rather than rebuilt on every request, so the middleware set has to stop changing. A Register after that point panics — it could otherwise only apply to some requests and not others, and it would be mutating a slice live requests are reading.

server.Pipeline.Auth.Register(bearerToken)   // fine
server.Start()                               // window closes
server.Pipeline.DB.Register(audit)           // panics

Scoping

Two functional options narrow the scope. They are independent and may be combined.

ForModel(names ...string)

Restrict to one or more models, by struct name:

server.Pipeline.Service.Register(hashPassword, maniflex.ForModel("User"))

ForOperation(ops ...Operation)

Restrict to specific operations:

server.Pipeline.Auth.Register(requireToken,
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
)

Operation values: OpList, OpRead, OpCreate, OpUpdate, OpDelete, OpOptions, OpAction. Registering on Validate/Service/DB with OpAction has no effect — those steps are skipped for action endpoints. A HEAD request runs as the GET it mirrors (OpRead / OpList), so scope it with those.

Combining

server.Pipeline.Service.Register(chargePayment,
    maniflex.ForModel("Order"),
    maniflex.ForOperation(maniflex.OpCreate),
)

Position

By default, a middleware runs before the step’s default handler. Use AtPosition to change that.

// Run after the DB step succeeds — useful for audit logs.
server.Pipeline.DB.Register(auditLog,
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
    maniflex.AtPosition(maniflex.After),
)

// Replace the default DB step for one model entirely.
server.Pipeline.DB.Register(customDispatch,
    maniflex.ForModel("LegacyOrder"),
    maniflex.AtPosition(maniflex.Replace),
)

Within a step, all matching Before middlewares run in registration order, then the core handler (default or Replace), then all matching After middlewares in registration order. If multiple Replace middlewares match, the last one registered wins.

A Replace on the DB step takes over feeding the Response step, so it must leave ctx.DBResult in the shape that step expects: a *maniflex.ListResult for a list, and a record for a read, create, or update. A record is a map[string]any or a pointer to this model’s struct, and the same goes for each of a ListResult’s Items. Anything else is rejected with 500 INVALID_DB_RESULT naming the type it got — including a pointer to another model’s struct, or to a type defined from this one, since the response is built by walking this model’s fields through whatever it is handed. A read, create or update that leaves ctx.DBResult unset is rejected the same way; a list that does is answered with an empty page. On a ListResult you need only set Items and Total — a missing or partial Query is filled in with the default page and limit.

Naming for traces

maniflex.WithName("name") attaches a human label to a middleware for use in pipeline trace logs (enabled via Config.Trace). It does not change runtime behaviour:

server.Pipeline.Auth.Register(rateLimit, maniflex.WithName("rate-limiter"))

Step-specific guidance

After-middleware error handling

An After middleware sees ctx.Response when the default step has populated it. Inspect it to decide whether to act:

func auditLog(ctx *maniflex.ServerContext, next func() error) error {
    if err := next(); err != nil {
        return err
    }
    // don't audit failed writes
    if ctx.Response != nil && ctx.Response.StatusCode < 400 {
        record(ctx)
    }
    return nil
}

Per-model middleware at registration

For middleware that belongs to exactly one model, ModelConfig.Middleware attaches hooks scoped to that model at registration time, avoiding the separate Register call:

server.MustRegister(
    Order{}, maniflex.ModelConfig{
        Middleware: &maniflex.ModelMiddleware{
            Validate: []maniflex.MiddlewareFunc{checkStock},
            Service:  []maniflex.MiddlewareFunc{chargePayment},
        },
    },
)

Both forms are equivalent; choose whichever keeps the declaration close to the code that depends on it.

Built-in middleware

Several middleware functions ship with the framework or its satellite modules — JWT auth, password hashing, audit logging, CORS, and more. They are documented in Middleware Catalogue.

Next

• ServerContext — the fields a middleware reads and writes.
• Transactions — maniflex.WithTransaction as a Service-step middleware.
• Error Handling — what Abort produces and how it propagates.

Transactions

A transaction wraps one or more database operations so they either all commit or all roll back. In maniflex the unit of transactional work is normally a single request: every database call performed by its pipeline runs in the same transaction, and the transaction commits if and only if the request produces a successful response.

Enabling transactions

The shipped middleware maniflex.WithTransaction wraps the DB step in a transaction. Register it on the Service step, scoped to the operations that should be transactional:

server.Pipeline.Service.Register(
    maniflex.WithTransaction(nil), // nil = default isolation level
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
)

Once registered, every matching request executes the DB step (and any subsequent After-DB middleware) inside a transaction. The middleware:

1. Begins a transaction before calling next().
2. Stores it on ctx.Tx and the underlying ctx.Ctx, so all downstream code can join it.
3. Commits if next() returns nil and ctx.Response is a 2xx.
4. Rolls back if next() returns an error, if ctx.Response.StatusCode >= 400, or if anything panics.

The same middleware can be registered on the DB step at Replace position if you want to substitute the default DB step entirely.

Customising isolation

maniflex.TxOptions is an alias for sql.TxOptions:

server.Pipeline.Service.Register(
    maniflex.WithTransaction(&maniflex.TxOptions{
        Isolation: sql.LevelSerializable,
        ReadOnly:  false,
    }),
    maniflex.ForModel("Invoice"),
)

SQLite ignores most isolation levels. Write-locking does not depend on them: sqlite.Open gives its write connections _txlock=immediate, so every transaction takes the write lock at BEGIN rather than on its first write.

Joining the transaction from middleware

When ctx.Tx is set, every CRUD call made through ctx.GetModel(...), ctx.RawQuery, ctx.RawExec, and the default DB step routes through it automatically:

server.Pipeline.Service.Register(func(ctx *maniflex.ServerContext, next func() error) error {
    // This Update participates in the same transaction as the DB step that follows.
    if _, err := ctx.GetModel("Inventory").Update(itemID, map[string]any{
        "reserved": true,
    }); err != nil {
        return err  // triggers rollback
    }
    return next()
}, maniflex.ForModel("Order"), maniflex.ForOperation(maniflex.OpCreate))

There is no separate “transactional” API — calling ctx.GetModel is enough.

Starting a transaction manually

When WithTransaction does not fit — for example, when only part of a request should be transactional, or when the transaction must span an action endpoint — begin one yourself:

tx, err := ctx.BeginTx(ctx.Ctx, nil)
if err != nil {
    return err
}
ctx.Tx = tx
defer tx.Rollback()  // no-op after Commit

// ... transactional work via ctx.GetModel / ctx.RawExec ...

if err := tx.Commit(); err != nil {
    return err
}
ctx.Tx = nil  // clear so post-commit code uses the bare adapter

tx.Rollback() after a successful commit is safe — it returns sql.ErrTxDone, which the framework swallows. Always defer it.

Pessimistic locking

Inside a transaction, ctx.LockForUpdate(modelName, id) acquires a row-level write lock and returns the current row:

row, err := ctx.LockForUpdate("StockBalance", stockID)
if err != nil {
    return err
}
if row["quantity"].(int64) < 1 {
    ctx.Abort(http.StatusConflict, "OUT_OF_STOCK", "no inventory remaining")
    return nil
}

On Postgres this appends FOR UPDATE to the SELECT. On SQLite the lock is at the transaction level — the row is protected because the transaction itself is write-locked.

LockForUpdate returns an error if ctx.Tx is nil; the lock is meaningless outside a transaction.

Joining from outside a ServerContext

Code without access to *ServerContext — for example, a job-queue helper, or an outbox writer — can retrieve the active transaction from ctx.Ctx using maniflex.TxFromContext:

func enqueue(ctx context.Context, job Job) error {
    if tx := maniflex.TxFromContext(ctx); tx != nil {
        return enqueueInTx(tx, job)
    }
    return enqueueDirect(job)
}

WithTransaction stores the active transaction on the context.Context for exactly this purpose.

The transaction is reachable only while it is open. Once WithTransaction commits or rolls back, both ctx.Tx and TxFromContext go back to nil, so a middleware that resumes after its next() — an audit hook, an outbox enqueue — takes the tx == nil branch and writes through the bare adapter, rather than into a finished transaction.

Adapter scope

A transaction lives on a single DBAdapter. ctx.BeginTx opens the transaction on the request’s model adapter (its ModelConfig.Adapter if set, otherwise Config.DB). All operations on that ctx.Tx must target models routed to the same adapter.

maniflex.Batch enforces this at runtime: calling b.Create("X", ...) for a model that routes to a different adapter than the batch transaction returns an error suggesting pkg/saga for cross-adapter coordination. See Per-model adapter routing.

Nesting

WithTransaction is idempotent: if ctx.Tx is already set when it runs, it simply calls next() without starting a new transaction. The outer transaction remains the unit of commit.

SQLite does not support nested transactions; calling ctx.BeginTx while one is already active returns an error.

Failure semantics

A transaction is rolled back when:

• the chain returns a non-nil error from any step;
• ctx.Response is set to a status >= 400 (e.g. via ctx.Abort);
• a panic occurs (the framework’s panic recoverer ensures rollback).

WithTransaction is committed when:

• the chain completes without error and ctx.Response is a 2xx (or unset).

A commit failure is reported as 500 TX_COMMIT_ERROR; a begin failure as 500 TX_BEGIN_ERROR.

Next

• Writing Middleware — how to register WithTransaction or write your own transactional middleware.
• Error Handling — how a rollback surfaces to the client.

Error Handling

Every error returned by the pipeline is delivered to the client as the same JSON envelope. This page describes that envelope, the sentinel errors the framework recognises, and how to produce errors from middleware.

The error envelope

A failing request writes:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "field \"email\" is required",
    "details": { /* optional, per-error */ }
  }
}

with the HTTP status code from the underlying failure. The code is a short machine-readable identifier; message is a human-readable summary; details is optional and may carry per-field errors or other structured context.

A successful request uses the {"data": ...} envelope instead; the two are mutually exclusive.

Built-in error responses

The default pipeline produces the following errors without any user code:

A panic anywhere in the pipeline is caught and reported as 500 PANIC by the framework’s recoverer — with one deliberate exception. A handler that panics with http.ErrAbortHandler is abandoning its response on purpose (this is what httputil.ReverseProxy does when an upstream dies mid-stream), so the recoverer passes it on and net/http closes the connection silently. It is not logged as a panic, and no error envelope is appended to whatever was already written.

499 is nginx’s non-standard “Client Closed Request” (maniflex.StatusClientClosedRequest). Nothing is written to the client — the connection is already gone — but the status is what your access log, metrics, and any After middleware reading the response status will see, so a caller who hangs up is not counted as a server timeout. Only a genuine server-side deadline produces 504 TIMEOUT. The disconnect itself is logged at DEBUG, not as an error.

Aborting from middleware

The standard way to produce an error from middleware is ctx.Abort:

ctx.Abort(statusCode, code, message)

It populates ctx.Response with an error envelope. The caller must then return nil (or an error) without calling next():

if header == "" {
    ctx.Abort(http.StatusUnauthorized, "UNAUTHORIZED", "missing token")
    return nil
}

Subsequent steps are skipped; the Response step writes the prepared envelope. Calling next() after Abort allows downstream steps to overwrite the response — usually not what you want.

For a 5xx status, message is a private diagnostic: Maniflex logs it once through Config.Logger, correlated by request_id, but sends only generic status text such as internal server error or bad gateway. The HTTP status and stable error code remain public. Any details on a directly assigned 5xx APIResponse are also removed at the wire boundary. Validated 4xx messages and details are unchanged. Every routed response echoes the correlation value in X-Request-Id.

Returning structured details

For per-field errors and similar payloads, set ctx.Response directly:

ctx.Response = &maniflex.APIResponse{
    StatusCode: http.StatusUnprocessableEntity,
    Error: &maniflex.APIError{
        Code:    "VALIDATION_ERROR",
        Message: "one or more fields failed validation",
        Details: []map[string]string{
            {"field": "email",    "message": "must be a valid email"},
            {"field": "password", "message": "must be at least 8 characters"},
        },
    },
}
return nil

This is the shape used by the default Validate step.

Sentinel errors from the adapter

Adapter methods return errors that the DB step maps to HTTP responses. The two that user code most often interacts with are exported as sentinels.

maniflex.ErrNotFound

var ErrNotFound = errors.New("record not found")

Returned by FindByID, Update, and Delete when the row does not exist (or is soft-deleted). Detect it with errors.Is:

row, err := ctx.GetModel("Invoice").Read(id)
if errors.Is(err, maniflex.ErrNotFound) {
    ctx.Abort(http.StatusNotFound, "INVOICE_NOT_FOUND",
        fmt.Sprintf("invoice %s does not exist", id))
    return nil
}

The default DB step does this conversion automatically; you only need it when you are calling the adapter yourself from a Service middleware.

*maniflex.ErrConstraint

type ErrConstraint struct {
    Kind    ConstraintKind  // unique, foreign_key, or not_null
    Table   string
    Column  string  // may be empty when the driver does not expose it
    Detail  string  // raw driver message
}

Returned by Create and Update on unique or check constraint violations. Both SQLite and Postgres errors are normalised into this type, so middleware need not inspect driver-specific codes.

row, err := ctx.GetModel("User").Create(data)
var ec *maniflex.ErrConstraint
if errors.As(err, &ec) {
    ctx.Abort(http.StatusConflict, "DUPLICATE",
        fmt.Sprintf("%s already exists", ec.Column))
    return nil
}

Every exported sentinel

ErrNotFound and ErrConstraint above are the two you match in a handler. The rest are listed here because they are part of the compatibility contract: a sentinel keeps its identity for all of v1, so errors.Is against any of them goes on working. Match on these values, never on message text — the text is explicitly not covered (see Stability & Compatibility).

Core module, github.com/xaleel/maniflex:

Subpackages:

TestErrorsDocListsEveryExportedSentinel fails when an exported Err* identifier is missing from this page, so a new one cannot ship undocumented.

Errors and transactions

When a request runs inside a transaction (see Transactions) and any step returns an error or sets ctx.Response to status >= 400, the transaction is rolled back before the response is written. The client sees the error envelope; the database sees no change.

Logging errors

ctx.Logger() returns a *slog.Logger pre-seeded with request_id and trace_id, so a single log line correlates with the request that produced it:

ctx.Logger().Error("payment provider rejected charge",
    slog.String("provider", "stripe"),
    slog.String("error_code", resp.Code),
)
ctx.Abort(http.StatusBadGateway, "PAYMENT_PROVIDER_ERROR", resp.Message)
return nil

Abort logs the supplied 5xx message automatically. The explicit log is still useful when you have structured provider fields that should not be flattened into the diagnostic string. Neither resp.Message nor those fields reach the client.

Next

• ServerContext — the full set of fields available to error-producing middleware.
• Transactions — rollback semantics.
• Writing Middleware — where to attach error-producing logic.

Example 2: B2B SaaS API

This example builds a small multi-tenant SaaS backend. Compared to Example 1, it exercises every concept introduced in the “Defining Your API” and “The Request Pipeline” sections:

• Multiple related models with BelongsTo and HasMany relations.
• Soft delete on the records that matter for an audit trail.
• A bearer-token Auth middleware that populates ctx.Auth.
• A Service-step middleware that scopes every query to the caller’s tenant.
• A Service-step middleware that runs inside a transaction.
• Custom error envelopes with ctx.Abort.

The goal is to show how the pieces compose; the auth and tenancy code is deliberately minimal so the example fits on one page.

Domain

A SaaS platform with three resources:

• Organization — the tenant. Every other record belongs to one.
• Member — a user belonging to an organization, with a role.
• Project — a unit of work owned by a member.

type Organization struct {
    maniflex.BaseModel
    maniflex.WithDeletedAt
    Name string `json:"name" mfx:"required,filterable,sortable"`
    Plan string `json:"plan" mfx:"required,enum:free|pro|enterprise,default:free"`

    Members  []Member  `json:"members,omitempty"`
    Projects []Project `json:"projects,omitempty"`
}

type Member struct {
    maniflex.BaseModel
    maniflex.WithDeletedAt
    OrganizationID string `json:"organization_id" mfx:"required,filterable,immutable"`
    Email          string `json:"email"           mfx:"required,filterable,unique"`
    Role           string `json:"role"            mfx:"required,enum:owner|admin|editor|viewer,default:viewer,filterable"`

    Projects []Project `json:"projects,omitempty"`
}

type Project struct {
    maniflex.BaseModel
    maniflex.WithDeletedAt
    OrganizationID string `json:"organization_id" mfx:"required,filterable,immutable"`
    OwnerID        string `json:"owner_id"        mfx:"required,filterable,relation:Owner"`
    Owner          Member `json:"owner,omitempty"`

    Name   string `json:"name"   mfx:"required,filterable,sortable"`
    Status string `json:"status" mfx:"required,enum:active|paused|archived,default:active,filterable,sortable"`
}

Owner is a companion field; the explicit relation:Owner tag is required because the FK name (OwnerID) does not match the model name (Member). OrganizationID follows the convention, so no companion is needed there.

Wiring

A single main.go registers the models, installs three middlewares, and starts the server.

func main() {
    server := maniflex.New(maniflex.Config{
        Port:        8080,
        PathPrefix:  "/api",
    })

    server.MustRegister(Organization{}, Member{}, Project{})

    db, err := sqlite.Open("./saas.db", server.Registry())
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()
    server.SetDB(db)

    registerMiddleware(server)

    if err := server.Start(); err != nil {
        log.Fatal(err)
    }
}

Auth — populating ctx.Auth

A real deployment would verify a JWT; this example resolves a bearer token against an in-memory map to keep the focus on ctx.Auth:

var tokens = map[string]maniflex.AuthInfo{
    "alice-token": {UserID: "user-alice", TenantID: "org-acme",  Roles: []string{"owner"}},
    "bob-token":   {UserID: "user-bob",   TenantID: "org-acme",  Roles: []string{"editor"}},
    "carol-token": {UserID: "user-carol", TenantID: "org-globex", Roles: []string{"admin"}},
}

func bearerAuth(ctx *maniflex.ServerContext, next func() error) error {
    header := ctx.Request.Header.Get("Authorization")
    token := strings.TrimPrefix(header, "Bearer ")
    info, ok := tokens[token]
    if !ok {
        ctx.Abort(http.StatusUnauthorized, "UNAUTHORIZED", "invalid or missing token")
        return nil
    }
    ctx.Auth = &info
    return next()
}

Tenant scoping — filtering by ctx.Auth.TenantID

A B2B API must never leak data across tenants. A Service-step middleware inspects every list and read, and rejects writes that would assign records to a foreign organization:

func enforceTenant(ctx *maniflex.ServerContext, next func() error) error {
    tenant := ctx.Auth.TenantID

    switch ctx.Operation {
    case maniflex.OpList:
        // Inject a filter so users only see their organization's rows.
        ctx.Query.Filters = append(ctx.Query.Filters, maniflex.Filter{
            Field: "organization_id", Op: "eq", Value: tenant,
        })

    case maniflex.OpCreate, maniflex.OpUpdate:
        if v, ok := ctx.Field("organization_id"); ok && v != tenant {
            ctx.Abort(http.StatusForbidden, "TENANT_MISMATCH",
                "organization_id does not match the authenticated tenant")
            return nil
        }
        ctx.SetField("organization_id", tenant)
    }
    return next()
}

The middleware applies to the two tenanted models — Member and Project — and to every operation. Organization itself is not scoped, because the auth middleware already binds each token to exactly one organization.

Transactions — creating a project atomically

A new project should fail entirely if the member quota check fails. A Service middleware wraps the operation in a transaction and uses ctx.LockForUpdate to read the organization with a write lock:

func enforceProjectQuota(ctx *maniflex.ServerContext, next func() error) error {
    org, err := ctx.LockForUpdate("Organization", ctx.Auth.TenantID)
    if err != nil {
        return err
    }

    rows, err := ctx.RawQuery(
        `SELECT COUNT(*) AS n FROM projects WHERE organization_id = ? AND deleted_at IS NULL`,
        ctx.Auth.TenantID,
    )
    if err != nil {
        return err
    }
    count := rows[0]["n"].(int64)

    limit := planLimit(org["plan"].(string))
    if count >= limit {
        ctx.Abort(http.StatusPaymentRequired, "PROJECT_LIMIT",
            fmt.Sprintf("plan %q allows %d projects; upgrade to add more", org["plan"], limit))
        return nil
    }
    return next()
}

func planLimit(plan string) int64 {
    switch plan {
    case "enterprise":
        return 1000
    case "pro":
        return 25
    default:
        return 3
    }
}

Registering the middleware

All three middlewares are registered in one place:

func registerMiddleware(s *maniflex.Server) {
    // Auth on every write — reads are public within the tenant once they
    // pass enforceTenant below; tighten or relax to taste.
    s.Pipeline.Auth.Register(bearerAuth,
        maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete, maniflex.OpList, maniflex.OpRead),
    )

    // Tenant scoping for the two tenanted models.
    s.Pipeline.Service.Register(enforceTenant,
        maniflex.ForModel("Member", "Project"),
    )

    // The DB step is wrapped in a transaction for project creation, and the
    // quota check runs inside it before next() reaches DB.
    s.Pipeline.Service.Register(maniflex.WithTransaction(nil),
        maniflex.ForModel("Project"), maniflex.ForOperation(maniflex.OpCreate),
    )
    s.Pipeline.Service.Register(enforceProjectQuota,
        maniflex.ForModel("Project"), maniflex.ForOperation(maniflex.OpCreate),
    )
}

Order matters: WithTransaction is registered before enforceProjectQuota, so the transaction is open by the time the quota check calls ctx.LockForUpdate.

A request, end to end

# Alice (org-acme, owner) creates a project.
curl -X POST localhost:8080/api/projects \
  -H 'Authorization: Bearer alice-token' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Atlas","owner_id":"user-alice"}'

What happens:

1. Auth — bearerAuth resolves alice-token and sets ctx.Auth.
2. Deserialize — JSON body parsed into ctx.ParsedBody.
3. Validate — mfx: tag rules pass; organization_id is missing but the next step injects it.
4. Service:
   1. enforceTenant writes organization_id = "org-acme" into the body.
   2. WithTransaction begins a transaction.
   3. enforceProjectQuota locks the organization row, counts existing projects, and either aborts with 402 PROJECT_LIMIT or proceeds.
5. DB — Create runs through the transaction; ctx.DBResult holds the inserted row.
6. Response — the envelope is written; the transaction commits.

Carol’s carol-token belongs to org-globex, so the same payload from her is rejected before it reaches the DB step:

curl 'localhost:8080/api/projects?filter=organization_id:eq:org-acme' \
  -H 'Authorization: Bearer carol-token'
# → list filtered to org-globex only; the requested filter is ignored

What this example showed

• Relations declared with both the convention (OrganizationID) and the explicit relation:Owner form.
• WithDeletedAt on every audited model.
• ctx.Auth populated by an Auth middleware, then read by Service middleware to scope queries.
• ctx.Query.Filters modified to enforce a tenant invariant.
• maniflex.WithTransaction plus ctx.LockForUpdate for a check-and-act write.
• Custom error codes (TENANT_MISMATCH, PROJECT_LIMIT) emitted with ctx.Abort.

Where to go next

The next section covers the ready-made middleware that ships with maniflex — the production-quality versions of the auth and validation helpers sketched here.

• Middleware Catalogue — JWT auth, password hashing, unique validation, audit logging, and more.
• Querying — the full filter, sort, and include grammar used in this example.

Middleware Catalogue

The catalogue is a set of ready-made middleware packages that cover the common needs of every production API — authentication, validation, password hashing, audit logging, caching, CORS, and so on. Most return an ordinary maniflex.MiddlewareFunc you register on the appropriate pipeline step, with the same scoping options as any other middleware. CORS returns maniflex.HTTPMiddleware because browser preflight must run before Auth.

The packages live under maniflex/middleware/. Most are part of the root module, so they need no extra require to use. Only the two with heavy third-party dependencies are broken out into their own Go modules — middleware/db/redis (the Redis rate-limit/cache backend) and middleware/service/bcrypt (password hashing) — so a project pulls those dependencies in only when it uses them:

How to use the catalogue

Import the package you need and register the returned middleware on the matching pipeline step:

import (
    "github.com/xaleel/maniflex/middleware/auth"
    "github.com/xaleel/maniflex/middleware/service"
)

server.Pipeline.Auth.Register(
    auth.JWTAuth("my-signing-secret", auth.JWTOptions{Issuer: "my-app"}),
)

server.Pipeline.Service.Register(
    service.HashField("password", svcbcrypt.Hasher()), // svcbcrypt = middleware/service/bcrypt
    maniflex.ForModel("User"),
)

Each middleware factory returns a maniflex.MiddlewareFunc, so the standard options — ForModel, ForOperation, AtPosition, WithName — apply verbatim.

Composition

Catalogue middleware is designed to be composable. The expected stack for a typical REST API is roughly:

1. Auth — JWTAuth or APIKeyAuth populates ctx.Auth; RequireRole gates sensitive operations.
2. Body — MaxBodySize and StripUnknownFields shape input early.
3. Validate — built-in tag rules plus UniqueField and friends.
4. Service — HashField, SetField, SlugifyField, then any custom business logic, then the maniflex/events helpers (events.Emit / events.Webhook / events.SendEmail) on the After side.
5. DB — Tenancy or ForceFilter enforces row-level scoping; AuditLog and Invalidate run After.
6. Response — Cache, RedactField, then Logging / Metrics on the After side.

Install CORSHeaders separately in Config.HTTPMiddlewares; it must wrap the router rather than wait for the Response step.

Mix and match freely; nothing in the catalogue is required.

Writing your own

The catalogue is just an applied form of Writing Middleware. If a built-in does not match your needs, write your own — the contract is the same func(ctx *maniflex.ServerContext, next func() error) error signature.

Auth Middleware

The maniflex/middleware/auth package supplies authentication and authorisation middleware. Each function returns a maniflex.MiddlewareFunc that either populates ctx.Auth on success or aborts with 401/403 on failure. Most register on the Auth step; the exceptions are called out where they occur — Enforce (attribute policies) runs on the DB step so the record is available, and ReadAudit runs on the Response step after a 2xx.

JWTAuth

Verifies a bearer JWT and populates ctx.Auth from its claims.

import "github.com/xaleel/maniflex/middleware/auth"

server.Pipeline.Auth.Register(
    auth.JWTAuth("my-signing-secret", auth.JWTOptions{
        Issuer:       "my-app",
        Audience:     "api",
        TenantClaim:  "org_id",   // copied into AuthInfo.TenantID
        ScopesClaim:  "scope",    // copied into AuthInfo.Scopes
    }),
)

Supports HMAC (HS256/384/512) when the secret is a string and asymmetric algorithms (RS256/384/512) when JWTOptions.PublicKey is set — useful with external identity providers (Auth0, Okta, Cognito, etc.). AuthMethod on ctx.Auth is set to "jwt".

Where the token is read from

By default the token comes from Authorization, which must carry the Bearer scheme — a bare token there is malformed, not merely unadorned. Point JWTOptions.Header at another header to read it from there instead:

auth.JWTAuth(secret, auth.JWTOptions{Header: "X-Auth-Token"})

A custom header accepts the token with or without the Bearer prefix, so a client that sends it out of habit is not punished for it. The scheme name is matched case-insensitively on both, per RFC 7235 — bearer <token> is valid.

Tokens must carry an exp claim: one with no expiry is rejected (401 TOKEN_MISSING_EXPIRY), since it would otherwise be valid forever. Set JWTOptions.AllowNoExpiry to accept non-expiring tokens from issuers that deliberately mint them. On the HMAC path the signing secret must be non-empty (an empty secret panics at startup) and should be at least 32 bytes — a shorter secret is allowed but logs a warning.

JWKSAuth

Verifies asymmetric JWTs against a rotating JWK Set published by an identity provider (e.g. an issuer’s /.well-known/jwks.json), instead of pinning a single static key. Signing keys are fetched, cached, and selected by the token header’s kid; an unknown kid triggers a rate-limited refetch, so a rotated key is picked up without a redeploy. RSA (RS256/384/512) and EC (ES256/384/512) are supported.

server.Pipeline.Auth.Register(auth.JWKSAuth(
    "https://issuer.example.com/.well-known/jwks.json",
    auth.JWTOptions{Issuer: "https://issuer.example.com", Audience: "api"},
))

All JWTOptions (Issuer, Audience, claim mappings, ClockSkew) apply exactly as with JWTAuth — reach for the static-key JWTAuth only when the key is fixed or for offline tests. See Auth & Security Hardening for the production checklist.

The JWKS URL must be https://

The JWK Set is the entire root of trust here. There is no shared secret: a token is accepted if its signature verifies against a key from that URL, and Issuer and Audience are claims inside the token, checked only once the signature already has. Anyone who can control the bytes that URL returns can therefore serve their own public key and mint tokens for any identity they like.

A plaintext URL logs a warning at construction. Two things make a moment of interception last much longer than the moment:

• a fetch replaces the whole key map and caches it for an hour, so one intercepted response buys an hour with nobody on the wire;
• when a later refresh fails, a cached key of any age is still used — so breaking the endpoint afterwards keeps an injected key alive indefinitely.

http://localhost and other loopback addresses are exempt and log nothing: a local Keycloak or dex is an ordinary development setup and there is no wire to intercept. A private LAN address such as 192.168.1.10 is not exempt — it is still another host, reached over a network someone may be sitting on.

Redirects are policed as well as the configured URL. Go’s default HTTP client follows https:// → http:// without complaint, so an issuer that redirects could move key material onto plaintext while your configured https:// URL looks untouched. Such a redirect is refused and the fetch fails.

APIKeyAuth

Validates a static API key from a request header. Each entry maps one key to the AuthInfo it grants.

server.Pipeline.Auth.Register(auth.APIKeyAuth("X-API-Key",
    auth.APIKeyEntry{Key: "svc-abc", Auth: maniflex.AuthInfo{
        UserID: "svc-1", Roles: []string{"admin"},
    }},
    auth.APIKeyEntry{Key: "svc-xyz", Auth: maniflex.AuthInfo{
        UserID: "svc-2", Roles: []string{"reader"},
    }},
))

AuthMethod on ctx.Auth is set to "api_key". Combine with JWTAuth on the same step to accept either credential — the first match wins.

Keys are indexed by their SHA-256 digest rather than by the key itself, so lookup timing is a function of the digest and not of the secret, and the raw keys are not retained in the index. Lookup stays O(1) — comparing every entry with subtle.ConstantTimeCompare would close the same gap but scan every configured key on every authenticated request.

These are static keys held in memory: they are as good as the deployment’s secret handling, they cannot be revoked without a restart, and they do not expire. For rotation, revocation, or per-user credentials, use JWTAuth with an auth.Revoker.

RequireRole

Rejects the request unless ctx.Auth.Roles contains the named role. Typically registered with ForModel / ForOperation to scope where the check applies.

server.Pipeline.Auth.Register(
    auth.RequireRole("admin"),
    maniflex.ForModel("User"), maniflex.ForOperation(maniflex.OpDelete),
)

Both failure cases return 403 FORBIDDEN: an anonymous request (ctx.Auth == nil) and an authenticated request lacking the role are treated alike. This differs from RequireOwner, which answers 401 to an anonymous caller.

RequireScope and RequireAnyScope

Reject the request unless ctx.Auth.Scopes carries the OAuth2 grants the route needs. JWTAuth fills that slice from JWTOptions.ScopesClaim (default "scope"), accepting both the JSON array form and RFC 6749’s space-delimited string.

RequireScope requires every listed scope:

server.Pipeline.Auth.Register(
    auth.RequireScope("posts:read", "posts:write"),
    maniflex.ForModel("Post"), maniflex.ForOperation(maniflex.OpUpdate),
)

That is the opposite of RequireRole, deliberately. A role names who the caller is, so holding one of several is the usual question; a scope names a grant that was issued, so an endpoint that both reads and writes needs both grants — not either. Where several grants really are each sufficient, ask for that explicitly:

server.Pipeline.Auth.Register(auth.RequireAnyScope("posts:write", "admin"))

The refusal names only the scopes the caller is missing, so a client granted three of four is told which one to go and ask for.

Scopes match exactly. A read:* grant does not satisfy read:posts — the framework cannot know whether :, /, or nothing at all delimits your issuer’s hierarchy. Express one with Enforce and a Policy.

Both constructors panic when given no scopes. Under all-of semantics an empty requirement is vacuously satisfied, so such a guard would admit every request while reading as though it protected the route.

Like RequireRole, both answer 403 FORBIDDEN to an anonymous caller and to an authenticated one lacking the grant.

RequireOwner

Enforces that the authenticated user owns the record being read or written. On create it stamps ownerField = ctx.Auth.UserID automatically; on read, update, and delete it fetches the target and compares its ownerField to the caller — answering 404 (not 403, so the endpoint never reveals that a record it doesn’t own exists). ownerField may be given as the JSON or the DB column name. Callers holding any role in adminRoles bypass the check.

server.Pipeline.Auth.Register(auth.RequireOwner("user_id", "admin"))

RequireOwner scopes single-resource operations only — a collection GET still returns every row. Constrain list reads with db.ForceFilter or db.Tenancy on the DB step.

Enforce — attribute-based policies

RequireRole and RequireOwner answer who is calling; Enforce answers may this principal touch this record, evaluating a Policy against the affected row’s fields. A Policy is a plain function:

type Policy func(ctx *maniflex.ServerContext, resource map[string]any) (allow bool, err error)

Return (false, nil) for a 403 FORBIDDEN; a non-nil error becomes a 500. Register on the DB step (not Auth), so the row is available:

sameTenant := func(ctx *maniflex.ServerContext, r map[string]any) (bool, error) {
    return r["tenant_id"] == ctx.Auth.TenantID, nil
}
server.Pipeline.DB.Register(auth.Enforce(sameTenant), maniflex.ForModel("Patient"))

Which record the policy sees depends on the operation:

Compose policies with AllOf, AnyOf, and Not:

auth.Enforce(auth.AllOf(sameTenant, auth.AnyOf(isOwner, auth.Not(isArchived))))

For lists the policy runs per row after the query, so pagination totals reflect the pre-filter count. When the rule can be expressed as a WHERE clause, prefer db.ForceFilter — it scopes in SQL, keeps totals accurate, and never fetches rows the caller can’t see.

AllowAnonymous

Marks the routes it is registered for as tolerating a request that carries no credential at all. Register it before the authenticator and scope it with the usual filters; JWTAuth and JWKSAuth honour it.

server.Pipeline.Auth.Register(auth.AllowAnonymous(),
    maniflex.ForModel("Post"),
    maniflex.ForOperation(maniflex.OpList, maniflex.OpRead),
)
server.Pipeline.Auth.Register(auth.JWTAuth(secret))   // everything else, unchanged

Exactly one thing changes: a request with no token is served with ctx.Auth left nil instead of answering 401. A credential that was presented and failed — expired, wrongly signed, revoked, malformed, or missing its Bearer scheme — is still 401 here, as it is everywhere else. Degrading a bad token to anonymous would turn an expired session into a silent change of permissions.

Two consequences worth planning around:

• The exemption is what you enumerate, not the coverage. The authenticator stays registered globally, so a model added next month is protected by default. Forgetting an entry in the exemption list produces a 401 on the first request rather than an endpoint that quietly opens.
• A token that is presented still authenticates. This is what scoping JWTAuth away from a route cannot do — there the middleware never runs, so even a valid token leaves ctx.Auth nil. Use AllowAnonymous when a route shows more to a signed-in visitor than to a stranger (published posts to everyone, drafts to their author).

ctx.Auth stays nil for the anonymous caller rather than being filled with a blank principal, so every ctx.Auth == nil test keeps meaning what it means. Ordering is by registration within a step: an AllowAnonymous registered after the authenticator sets its marker too late to be read, which fails closed.

AllowPublicRead

A passthrough on OpRead and OpList; on every other operation it requires ctx.Auth to be populated.

It does not, on its own, make reads reachable. An authenticator that aborts on a missing credential has already answered 401 and returned without calling next(), so an AllowPublicRead registered after it never runs — and registered before it, the passthrough calls next() straight into the authenticator, which aborts anyway. Pair it with AllowAnonymous:

server.Pipeline.Auth.Register(auth.AllowAnonymous(),
    maniflex.ForOperation(maniflex.OpList, maniflex.OpRead),
)
server.Pipeline.Auth.Register(auth.JWTAuth("..."))
server.Pipeline.Auth.Register(auth.AllowPublicRead())

Here it is the belt to AllowAnonymous’s braces: one registration, covering every model, re-asserting that nothing without a principal may write — a check no per-route exemption list can drift away from.

BlockOperation

Refuses the listed operations outright, regardless of identity. Useful for making a model effectively read-only at the HTTP layer.

server.Pipeline.Auth.Register(
    auth.BlockOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
    maniflex.ForModel("AuditLog"),
)

The model’s routes remain mounted but always return 405 METHOD_NOT_ALLOWED.

Token revocation and logout

A JWT is valid until its exp and nothing the server does can take it back. That is fine until a user logs out, changes their password, or has their account compromised — at which point “valid until it expires” is exactly wrong. Set JWTOptions.Revoker to give the server its say back, at the cost of a lookup per request.

rev := auth.NewMemoryRevoker()

server.Pipeline.Auth.Register(auth.JWTAuth(secret, auth.JWTOptions{Revoker: rev}))
server.Action(auth.Logout(rev, ""))                    // POST /logout
server.Action(auth.LogoutAll(rev, "", 24*time.Hour))   // POST /logout-all

Logout revokes the token the caller authenticated with — logout on this device. LogoutAll revokes every token belonging to the caller, including sessions whose jti the server has never seen; it is the one to call after a password change. Both respond 204, and both must be mounted behind the same auth middleware as everything else (they read ctx.Auth).

The two granularities

The per-user cutoff is what makes “log out everywhere” possible: the outstanding jti values are unknown and usually unknowable, so a per-token blocklist alone cannot express it. Logging in again works immediately — the cutoff kills tokens issued before it, not the account.

What changes when it is on

• A jti becomes mandatory. A token without one cannot be revoked, so it is refused with 401 TOKEN_NOT_REVOCABLE rather than handed a permanent exemption from the blocklist. Mint a unique jti per token.
• An iat becomes required for users who have a cutoff. A token that cannot be placed relative to the cutoff is refused. Tokens without iat keep working for every user who has never called LogoutAll.
• A store outage refuses requests — see below.

Error codes:

Failing closed

Every Revoker method returns an error, and the middleware refuses the request when a lookup fails rather than reading “I could not check” as “not revoked”. A blocklist that fails open silently un-revokes every logged-out token for the duration of an outage — precisely when it matters most. This is why Revoker is its own interface rather than a reuse of maniflex.CacheStore, whose Get reports a miss and an outage identically.

The refusal is 503, not 401: the credential is fine, the server is not, and answering 401 would push every healthy client into a re-login storm during an incident.

Backends

NewMemoryRevoker() keeps the blocklist in-process. Its limitation is structural: a second replica does not see a logout performed by the first, and a restart loses every entry — which un-revokes every still-unexpired token. It suits single-replica deployments, development, and tests.

Behind more than one replica, use a shared store. Two ship.

Redis — server-side key expiry, so nothing ever has to be swept:

import authredis "github.com/xaleel/maniflex/middleware/auth/redis"

rev := authredis.NewRevoker(redisClient, "myapp:revoked")

SQL — the database you already run, with no second piece of infrastructure and no extra dependency (the package imports nothing but database/sql):

import authsql "github.com/xaleel/maniflex/middleware/auth/sql"

if err := authsql.Migrate(ctx, db, "postgres"); err != nil {   // or "sqlite"
    log.Fatal(err)
}
rev := authsql.NewRevoker(db)

Migrate creates revoked_token and revoked_user and is safe to run on every boot and from every replica — every statement is IF NOT EXISTS, and none rewrites an existing column. Use WithTablePrefix("auth_") if those names are taken; pass the same option to both calls.

SQL has no TTL, so expired rows are swept rather than expiring themselves. This never affects correctness — both reads filter on the deadline, so a row the sweep has not reached yet stops being honoured at exactly the right moment — it only bounds the table. The Revoker sweeps every 128 writes on its own; call Prune(ctx) to do it on a schedule and see the error, or WithPruneEvery(0) to turn the automatic sweep off and take over entirely:

tokens, users, err := rev.Prune(ctx)

One behavioural note when comparing the two: RevokeUser moves a cutoff forward in the INSERT … ON CONFLICT itself, so concurrent revocations cannot resurrect tokens by landing out of order. The Redis backend reads then writes and documents that race as benign.

Or implement auth.Revoker yourself over any store — four methods, and the interface is in terms of context.Context and time.Time only.

VerifyToken hook

JWTOptions.VerifyToken is the final say on a token that has passed every other check — signature, registered claims, and revocation. Return an error to refuse the request with 401 INVALID_TOKEN carrying that message.

auth.JWTAuth(secret, auth.JWTOptions{
    VerifyToken: func(ctx *maniflex.ServerContext, claims map[string]any, info *maniflex.AuthInfo) error {
        if claims["tier"] != "paid" {
            return errors.New("subscription required")
        }
        info.Roles = append(info.Roles, "subscriber") // may enrich the principal
        return nil
    },
})

Use it for issuer-specific rules the framework does not model: a required custom claim, a tenant allowlist, a per-user check against your own store. For revocation specifically, prefer Revoker — it is the same hook point with the blocklist and its failure semantics already written.

CSRF

Protects unsafe HTTP methods (POST/PUT/PATCH/DELETE) against cross-site request forgery. Two strategies, selected by CSRFOptions.Mode:

• CSRFDoubleSubmit (default) — issues a random token in a non-HttpOnly cookie on safe requests and requires the client to echo it in a header on unsafe ones.
• CSRFSignedToken — derives the expected token as HMAC(SessionID, Secret); stateless, no cookie issued. Register it after the JWT step so ctx.Auth.SessionID is populated (e.g. from the token’s jti claim).

server.Pipeline.Auth.Register(auth.CSRF(auth.CSRFOptions{
    AllowedOrigins: []string{"https://admin.example.com", "*.example.com"},
    Secure:         true,
}))

Bearer-authenticated requests are exempt by default — a bearer token read from JS is not an ambient credential, so it isn’t CSRF-vulnerable. Set EnforceBearer: true only if your bearer flow also rides browser-managed cookies. The optional AllowedOrigins allowlist (exact origins or *.host wildcards) is checked first on unsafe methods. Failures abort with a 403 carrying one of CSRF_ORIGIN_REJECTED, CSRF_TOKEN_MISSING, CSRF_COOKIE_MISSING, CSRF_NO_SESSION, or CSRF_TOKEN_MISMATCH.

From a login Action, hand the token to the SPA with auth.IssueCSRFCookie(w, opts) (double-submit) or auth.SignedCSRFToken(sessionID, secret) (signed mode).

The admin panel does not use this middleware. It ships its own always-on double-submit check over its own forms — see Admin Panel → CSRF protection. Registering auth.CSRF neither configures nor disables it, and leaving auth.CSRF off does not leave the panel unprotected.

ReadAudit

Writes a structured audit record after every successful read or list — the read-side counterpart to db.AuditLog, for data where who looked is itself the compliance control (clinical, financial). Implement a ReadAuditSink and register ReadAudit at the After position on the Response step, so it fires only on a 2xx:

server.Pipeline.Response.Register(
    auth.ReadAudit(mySink),
    maniflex.ForModel("Patient", "LabResult"),
    maniflex.ForOperation(maniflex.OpRead, maniflex.OpList),
    maniflex.AtPosition(maniflex.After),
)

Each ReadAuditRecord carries the actor, roles, tenant, session, request/trace IDs, client IP, and either the accessed RecordID (read) or the RecordCount (list). Writes are fire-and-forget — a goroutine with a 5 s timeout, so a slow sink never delays the response — and sink errors are discarded, so back a lossless requirement with a durable queue.

Scoping patterns

The middleware in this package combines with ForModel / ForOperation to build per-route policy without writing custom Auth code:

// Public reads, JWT writes, admin-only deletes
server.Pipeline.Auth.Register(auth.AllowAnonymous(),
    maniflex.ForOperation(maniflex.OpList, maniflex.OpRead))
server.Pipeline.Auth.Register(auth.JWTAuth("..."))
server.Pipeline.Auth.Register(auth.RequireRole("admin"),
    maniflex.ForOperation(maniflex.OpDelete))

Note which registration carries the filter. Scoping the authenticator to the write operations would work today and fail later: ForModel/ForOperation are inclusion-only, so anything they do not name is covered by no auth registration at all. Scoping the exemption instead leaves the authenticator global, so the default for a route nobody listed is refusal.

Body Middleware

The maniflex/middleware/body package shapes the request body during the Deserialize and Validate steps — before the framework’s tag rules run.

MaxBodySize

Overrides the default 4 MB body limit for the current request. Register on the Deserialize step, scoped to the model that needs the larger limit:

import "github.com/xaleel/maniflex/middleware/body"

server.Pipeline.Deserialize.Register(
    body.MaxBodySize(16 << 20),  // 16 MB
    maniflex.ForModel("Article"),
)

Requests over the limit are aborted with 413 BODY_TOO_LARGE before the JSON parser runs — as is any request over the 4 MB default when this middleware is not registered. An oversized body is never truncated to fit.

StripUnknownFields

Removes keys from ctx.ParsedBody that do not correspond to a model field. Register on the Validate step (or Deserialize After-position) so the cleanup happens before tag validation and the DB step:

server.Pipeline.Validate.Register(body.StripUnknownFields())

The default behaviour is to accept and silently ignore unknown fields. Use this middleware to enforce a stricter contract when desired.

CoerceTypes

Coerces string values in ctx.ParsedBody into the Go type declared on the model — "42" → 42 (int), "3.14" → 3.14 (float64), "true" → true (bool). Helps when the client sends form-encoded or query-string-shaped payloads. Only string→int/float64/bool is performed; other types are left as-is.

server.Pipeline.Validate.Register(body.CoerceTypes())

Coercion happens before the framework’s min / max / enum checks, so numeric ranges and enums work against the coerced values.

Validate Middleware

The maniflex/middleware/validate package supplies validators that go beyond what mfx: tags can express. Each one runs on the Validate step alongside the built-in tag enforcement, and most abort with 422 VALIDATION_ERROR on rejection. The exceptions:

• RestrictField/FieldRole answer 403 FIELD_FORBIDDEN, because they gate on who is asking, not on whether the value is valid.
• RequireLocale answers 422 MISSING_LOCALE — still a 422, but with its own code so a missing translation is distinguishable from a plain validation miss.
• UniqueField answers 409 CONFLICT, not a 422 — a duplicate is a conflict with existing state rather than malformed input, and this is the same answer the database’s own constraint gives for the identical error. If the underlying count query itself fails it answers 500 UNIQUE_CHECK_FAILED rather than letting a duplicate slip through.

UniqueField

Rejects a create or update whose value collides with an existing row.

import "github.com/xaleel/maniflex/middleware/validate"

server.Pipeline.Validate.Register(
    validate.UniqueField(sqlDB, maniflex.Postgres, "email"),
    maniflex.ForModel("User"),
)

The middleware runs a count query against the underlying database before the DB step. It answers the same 409 CONFLICT the mfx:"unique" constraint produces — identical status, code, message and details — so a client handles one response whichever mechanism caught the duplicate. What it buys is when: the collision is reported before the write is attempted, and named by JSON field.

It is not a substitute for mfx:"unique". Count-then-write is not atomic, so two concurrent requests can both pass the count; the database constraint remains the actual guarantee.

The driver argument selects the placeholder dialect (maniflex.Postgres → $N, maniflex.SQLite → ?) and must match the driver used to open the adapter. The third argument is the JSON field name; it is resolved to the underlying DB column via ctx.Model.FieldByJSONName.

RegexField

Validates that a string field matches a regular expression:

server.Pipeline.Validate.Register(
    validate.RegexField("phone", `^\+?[0-9]{7,15}$`),
    maniflex.ForModel("Contact"),
)

A non-matching value aborts with 422 and the field name in details.

ForbiddenValues

Rejects writes that contain any of the listed values for a field. Use it for defence-in-depth on enum-like fields where the mfx enum tag would still allow a privileged value:

server.Pipeline.Validate.Register(
    validate.ForbiddenValues("role", "superadmin", "root"),
    maniflex.ForModel("User"),
)

RequireAtLeastOne

Ensures at least one of the named fields is present in the request body. Most useful on OpUpdate, where every field is otherwise optional:

server.Pipeline.Validate.Register(
    validate.RequireAtLeastOne("name", "email"),
    maniflex.ForOperation(maniflex.OpUpdate),
)

RequireLocale

Ensures a localised (LocaleString) field carries a non-empty value for each of the required locale keys. Use it for translatable fields where certain languages are mandatory:

server.Pipeline.Validate.Register(
    validate.RequireLocale("name", "en", "ar"),
    maniflex.ForModel("Department"),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate),
)

The field value may arrive as a JSON object (map[string]any) or a Go-native map[string]string. A locale key that is absent, null, or empty fails the check. When any required locale is missing the request is aborted with 422 MISSING_LOCALE, and details lists every offending locale keyed by field. If the field is absent from the body, null, or not a locale map at all, the rule passes silently — pair it with required when presence itself is mandatory.

NumericPrecision

Enforces decimal precision and scale on a numeric field. The check is a string-parse, so it works regardless of how the column is stored (INTEGER, NUMERIC(p,s), TEXT, custom SQLTyper):

server.Pipeline.Validate.Register(
    validate.NumericPrecision("amount", 19, 4), // up to 19 total digits, max 4 after the point
    maniflex.ForModel("Invoice"),
)

• precision — maximum total significant digits (integer + fractional). Pass 0 to disable.
• scale — maximum digits after the decimal point. Pass 0 to disable.

Sign (+/-), leading zeros, and trailing fractional zeros do not count toward either limit. Scientific notation (1e3) is rejected because its implied precision is ambiguous — supply financial values in plain form. Absent and null values are skipped; pair with required when presence matters.

CrossFieldValidate

A general-purpose escape hatch for rules that span multiple fields:

server.Pipeline.Validate.Register(
    validate.CrossFieldValidate(func(body map[string]any) error {
        if body["status"] == "scheduled" && body["scheduled_at"] == nil {
            return fmt.Errorf("scheduled_at is required when status is scheduled")
        }
        return nil
    }),
    maniflex.ForModel("Post"),
)

The returned error becomes the message of a 422 VALIDATION_ERROR response.

DateRange

Ensures an end field is not before a start field. Accepts RFC3339 timestamps ("2026-05-01T08:00:00Z") and YYYY-MM-DD date strings. If either field is absent, null, or unparseable, the rule passes silently — pair with required or another rule when presence matters.

server.Pipeline.Validate.Register(
    validate.DateRange("start_date", "end_date"),
    maniflex.ForModel("Booking"),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate),
)

Equal dates are accepted (start == end). A 422 VALIDATION_ERROR is returned with the end field named in details when the end precedes the start.

RequireWhen

Makes a field required only when other fields satisfy all listed conditions. Each condition is a "field:op:value" string; op is one of eq, ne, gt, gte, lt, lte. Multiple conditions are ANDed. Invalid syntax panics at startup so misconfiguration is caught before the first request.

// Require rejection_reason whenever status is "rejected"
server.Pipeline.Validate.Register(
    validate.RequireWhen("rejection_reason", "status:eq:rejected"),
    maniflex.ForModel("Claim"),
)

// Require shipping_address only for physical orders with priority >= 3
server.Pipeline.Validate.Register(
    validate.RequireWhen("shipping_address", "order_type:eq:physical", "priority:gte:3"),
    maniflex.ForModel("Order"),
)

When the conditions are met but the target field is absent, null, or empty string, the request is rejected with 422 VALIDATION_ERROR. When the conditions are not all met, the rule passes regardless of the target field’s value — it does not prevent the field from being supplied.

Numeric comparisons (gt, gte, lt, lte) coerce both the body value and the condition value to float64. Non-numeric body values cause the condition to evaluate as false (the target field stays optional).

FieldRole / RestrictField

Gate a field on who is writing it. These are the write-side twin of response.RedactField — the same predicate shape, on the opposite step.

// Only a superuser may write status; everyone else may write the rest of the row
server.Pipeline.Validate.Register(
    validate.FieldRole("subscription_expires_at", "superuser"),
    maniflex.ForModel("User"),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate),
)

RestrictField takes a predicate instead of a role list, for gates roles cannot express (ownership, tenant, plan tier):

server.Pipeline.Validate.Register(
    validate.RestrictField("document_quota_bytes",
        func(ctx *maniflex.ServerContext) bool {
            return ctx.HasRole("superuser") || isBillingAdmin(ctx)
        }),
    maniflex.ForModel("User"),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate),
)

FieldRole(field, roles...) is exactly RestrictField with a ctx.HasRole predicate (OR-semantics). With no roles passed it rejects every write of the field, so an accidentally empty list fails closed — matching auth.RequireRole.

Declare the field so a typo can’t fail open

Misspell the field name and the gate is inert: it watches for a body key nothing sends, the real field keeps its name, and nothing gates it. Add maniflex.RequiresField and that becomes a startup failure:

server.Pipeline.Validate.Register(
    validate.FieldRole("subscription_expires_at", "superuser"),
    maniflex.ForModel("User"),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate),
    maniflex.RequiresField("subscription_expires_at"), // ← checked at startup
)

The declared name is checked against the model, so writing it twice catches a misspelling rather than duplicating one. Do this on every gate that protects a field you care about.

Without it, a mismatch is only a warning on the first request that reaches the model — no help for an endpoint nobody exercises, and indistinguishable from a gate deliberately registered across models where only some carry the field. See Startup Validation.

Why this isn’t readonly

The mfx: write controls are static: readonly, immutable, hidden apply to every caller identically. They cover “no client ever writes this”. They cannot express “only a superuser may set subscription_expires_at, while the owner writes the rest of their own row” — which, without this, costs a separate endpoint per privileged field.

Refused, not stripped

A caller without permission gets 403 FIELD_FORBIDDEN naming the field. This deliberately differs from readonly, which silently drops the field:

Answering 200 to a write that did not happen, echoing the old value back, is indistinguishable from success. The write is refused whole — a mixed PATCH {"title": …, "status": …} from a non-holder changes neither field.

Details

• Only a field present in the body is gated. A PATCH that does not mention it passes untouched. An explicit null is a write, and is gated.
• Create and update both, when you scope it with ForOperation.
• field is the JSON name.
• Scope it with maniflex.ForModel. Registered without one it applies to every model, and a gate naming a field the model does not have can never fire. It warns once per model in that case, since a typo would otherwise leave the real field ungated in silence.

Workflow Middleware

maniflex/middleware/workflow enforces a state-machine on a model’s status field. Declare the permitted transitions once; the middleware rejects writes that would move a record between states the workflow does not allow, or that fail a guard (e.g. role check).

import "github.com/xaleel/maniflex/middleware/workflow"

sm := workflow.New("status",
    workflow.Allow("draft",     "submitted"),
    workflow.Allow("submitted", "approved", workflow.RequireRole("manager")),
    workflow.Allow("submitted", "rejected", workflow.RequireRole("manager")),
    workflow.Allow("approved",  "paid",     workflow.RequireRole("finance")),
    workflow.AllowAny(workflow.RequireRole("admin")),    // admin escape hatch
    workflow.AllowInitial("draft", "submitted"),         // legal seed states on Create
)

server.Pipeline.Validate.Register(
    sm.Middleware(),
    maniflex.ForModel("Invoice"),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate),
)

How it runs

The middleware lives on the Validate step. (A machine that declares OnTransition hooks registers on the DB step instead — see Transition hooks.)

• On OpCreate — if AllowInitial is declared, the value of the chosen field must be in the set; otherwise any initial value passes. No guards apply on Create (the Create itself is its own authorisation surface).
• On OpUpdate — if the body does not include the status field, the middleware is a no-op. Otherwise it reads the current record via ctx.GetModel(modelName).Read(id) (so reads participate in ctx.Tx when active), extracts from, compares to the body’s to, and:
  • same-state writes (from == to) pass silently;
  • the first matching rule wins; its guards run in order;
  • the first guard error rejects the transition with 422 INVALID_TRANSITION.

A PATCH that triggers the read also costs one round-trip. Stash the loaded record on ctx.Set if you need it again later in the request.

Rules

Rule matching is a linear scan in declaration order — write narrow rules before broad ones if you want them to take precedence.

A machine with no Allow rules permits nothing — every transition is rejected. If you want hooks without restricting transitions, say so explicitly with AllowAny().

Guards

type Guard interface {
    Check(ctx *maniflex.ServerContext, from, to string) error
}

• RequireRole(roles ...string) — pass if the caller holds any one of the listed roles. OR-semantics; passing zero roles always rejects (a defensive choice against accidentally unguarded “require” rules).
• GuardFunc — adapt any func(ctx, from, to) error to the interface.

A non-nil guard error becomes the response message:

{
  "error": {
    "code": "INVALID_TRANSITION",
    "message": "role [manager] required for transition \"submitted\" → \"approved\"",
    "details": [{"field": "status", "from": "submitted", "to": "approved"}]
  },
  "status": 422
}

Transition hooks (OnTransition)

OnTransition(from, to, fn) attaches a side effect to a transition. The hook runs inside the write’s transaction, so it commits with the transition or not at all:

sm := workflow.New("status",
    workflow.Allow("pending",   "confirmed", workflow.RequireRole("store_owner")),
    workflow.Allow("confirmed", "pending",   workflow.RequireRole("store_owner")),
    workflow.AllowAny(workflow.RequireRole("admin")),

    workflow.OnTransition("pending",   "confirmed", applyStoreCredit),
    workflow.OnTransition("confirmed", "pending",   reverseStoreCredit),
    workflow.OnTransition("*",         "delivered", emitReviewRequested),
)

server.Pipeline.Service.Register(
    maniflex.WithTransaction(nil),
    maniflex.ForModel("Order"),
    maniflex.ForOperation(maniflex.OpUpdate),
)
server.Pipeline.DB.Register(
    sm.Hooks(),
    maniflex.ForModel("Order"),
    maniflex.ForOperation(maniflex.OpUpdate),
)

type Hook func(ctx *maniflex.ServerContext, from, to string) error

Hooks() replaces Middleware() — it does not supplement it

A machine with hooks registers sm.Hooks() on the DB step, and that is the only registration it needs: Hooks() enforces the same rules and guards Middleware() does, and more strictly. Declaring a hook makes Middleware() panic rather than let it be registered on Validate where the hooks could never fire.

The split exists because the two cannot run at the same point. A guard must run before anything is written; a hook must run inside the write’s transaction — and that transaction does not exist until WithTransaction opens it on the Service step, after Validate.

That is also why Hooks() re-reads from rather than trusting the Validate step’s verdict. The Validate-step read takes no lock, so two concurrent PATCHes can both observe from="pending", both pass, and both apply the store credit. Hooks() re-reads from through ctx.LockForUpdate inside the transaction: the loser waits, then sees confirmed and is either a no-op (same-state) or re-checked as the transition it has really become. Because the re-read can name a different rule than the one that passed on the stale value, the matching rule’s guards re-run too.

With no active transaction, Hooks() refuses the request with 500 WORKFLOW_NO_TX rather than take no lock and silently reintroduce the race — the same fail-loudly stance as mfx:"lock_scope".

Semantics

• Fire-all-matching, in declaration order — unlike Allow, which is first-match-wins. OnTransition("pending", "confirmed", …) and OnTransition("*", "delivered", …) are independent side effects, and a rule ordering that silenced one of them would be a bug rather than a policy.
• OpUpdate only. A Create seeds an initial state (AllowInitial governs it); it is not a transition. Use a Service-step middleware for create-time side effects.
• Same-state writes fire nothing — a no-op is not a transition.
• A returned error rolls the whole request back, transition included, and answers 500 WORKFLOW_HOOK_ERROR. To choose your own status, call ctx.Abort(…) and return nil; the write still rolls back and your response is what the client sees.
• The hook runs after the write lands, so a read through ctx.Tx sees the new state.

Status field type

Values are compared as strings via fmt.Sprintf("%v", v), matching validate.ForbiddenValues. This covers string, int, and custom enum types.

Service Middleware

The maniflex/middleware/service package supplies business-logic helpers for the Service step — field transforms, derived values, and owner-scoping. Side-effect helpers (events, webhooks, email) live in the separate maniflex/events package, not here — see Side effects below.

Field transforms

HashField

Replaces a plaintext field with its hash before the DB step, using a Hasher you supply. The bcrypt hasher lives in the satellite package maniflex/middleware/service/bcrypt (kept separate so the core has no bcrypt dependency):

import (
    "github.com/xaleel/maniflex/middleware/service"
    svcbcrypt "github.com/xaleel/maniflex/middleware/service/bcrypt"
)

server.Pipeline.Service.Register(
    service.HashField("password", svcbcrypt.Hasher()),
    maniflex.ForModel("User"),
)

svcbcrypt.Hasher() takes an optional cost (svcbcrypt.Hasher(12)); the default is suitable for production. A Hasher is just func(plaintext string) (string, error), so you can supply argon2 or any other implementation.

SlugifyField

Derives a slug field from a source field on create:

server.Pipeline.Service.Register(
    service.SlugifyField("title", "slug"),
    maniflex.ForModel("Post"), maniflex.ForOperation(maniflex.OpCreate),
)

Punctuation is stripped, spaces become hyphens, and the result is lowercased.

SetField

Sets a field on every create or update based on context — typically pulling identity from ctx.Auth:

server.Pipeline.Service.Register(
    service.SetField("user_id", func(ctx *maniflex.ServerContext) any {
        return ctx.Auth.UserID
    }),
    maniflex.ForOperation(maniflex.OpCreate),
)

StripField

Removes a field from the request body (and the typed record) before the DB step. Useful for input-only confirmation fields that should never reach the database:

server.Pipeline.Service.Register(service.StripField("password_confirm"))

TimestampWhen

Sets a timestamp column when another field transitions to a specific value — for example, recording published_at the moment status becomes "published":

server.Pipeline.Service.Register(
    service.TimestampWhen("published_at", "status", "published"),
    maniflex.ForModel("Post"),
)

Timestamp

Unconditionally sets a timestamp column to the current time on every write it runs for — use ForOperation to scope it (e.g. a last_seen_at touched on update):

server.Pipeline.Service.Register(
    service.Timestamp("last_seen_at"),
    maniflex.ForModel("User"), maniflex.ForOperation(maniflex.OpUpdate),
)

CopyField

Copies one field’s value into another before the DB step — for denormalising a value the client shouldn’t set directly:

server.Pipeline.Service.Register(
    service.CopyField("email", "billing_email"),
    maniflex.ForModel("Account"), maniflex.ForOperation(maniflex.OpCreate),
)

Authorisation

OwnerScope

Forces a user-id field to the authenticated caller on create. It is exactly SetField("user_id", ctx.Auth.UserID) — an unconditional overwrite, so any value the client sent for that field is replaced (not rejected):

server.Pipeline.Service.Register(
    service.OwnerScope("user_id"),
    maniflex.ForOperation(maniflex.OpCreate),
)

Side effects

Side effects — events, webhooks, email — are not in this package. They live in maniflex/events, and only events.Emit is pipeline middleware; events.Webhook and events.SendEmail are event-bus subscribers, not middleware, so they are wired with bus.Subscribe, not Pipeline.Register.

events.Emit publishes a domain event on the DB step at maniflex.After, after the write succeeds:

import "github.com/xaleel/maniflex/events"

server.Pipeline.DB.Register(
    events.Emit(bus),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
    maniflex.AtPosition(maniflex.After),
)

Webhooks and email then react to those events as subscribers:

bus.Subscribe(ctx, events.Subscription{
    Patterns: []string{"order.*"},
    Handler:  events.Webhook(events.WebhookConfig{URL: "https://hooks.example.com/orders", Secret: "whsec_…"}),
})

bus is any events.Bus — events/inproc for a single binary, or the Kafka, NATS, RabbitMQ, and Redis adapters. See Events & Background Jobs for the full API, including the transactional outbox that makes events.Emit commit atomically with the write (without it, a rolled-back transaction leaves an already-sent side effect — outbound emails do not unsend themselves).

DB Middleware

The maniflex/middleware/db package wraps the DB step with row-level scoping, request budgeting, post-write hooks, and result caching.

Row-level scoping

ForceFilter

Injects a filter on every list, read, update, and delete, regardless of what the client requested. Used to enforce invariants the client cannot override:

import "github.com/xaleel/maniflex/middleware/db"

server.Pipeline.DB.Register(
    db.ForceFilter("org_id", func(ctx *maniflex.ServerContext) any {
        return ctx.Auth.Claims["org_id"]
    }),
    maniflex.ProvidesScope(),
)

On a list or a read the filter goes into the query. On an update or a delete there is nowhere to put it — the adapter’s Update and Delete are keyed by id alone — so the DB step reads the record back through the filter first and answers 404 if it does not match, indistinguishably from a record that is genuinely absent. The check and the write share one transaction, so the row cannot leave scope in between.

On a create or an update the scope value is also stamped onto the row. An equality on a plain column says two things at once — “only rows where field = value” and “a row you create has field = value” — and both are honoured. Without the stamp a create stored whatever the client sent in the scope column, so the row landed outside its own author’s scope: invisible to them on their next read, and, since that column is the client’s to send, plantable straight into someone else’s scope. The stamp is skipped on update when the column is immutable, which cannot change anyway.

A foreign key the write names is checked too. The stamp makes the row look correctly owned whatever its foreign keys say, so POST {"order_id": "<another tenant's>"} used to land a child under their parent. The child is hidden from that tenant on every read — see the include rule below — but the framework itself still writes to the parent: a rollup recomputes the parent’s denormalised column over every child naming it, so a planted row moved a total in a row its author could neither read nor reach. So every BelongsTo key a create or update sets is read through the scope first, and a miss is the same 404 a scoped read of that parent gives.

Three shapes are deliberately left alone. A key the write doesn’t set can’t move the row anywhere, and the row itself was already read back through the scope. A key written empty is legal — the child carries the scope column itself, so a child with no parent is perfectly describable (unlike ForceFilterVia below, where the parent is the scope and a null key is a 422). And a parent carrying no column the scope names is shared rather than partitioned — a currency table, a plan catalogue — so every tenant may still reference it, the same rule the includes below apply. A key naming a model you never registered — the microservice case of storing a foreign id by design — has no parent table to read, so nothing is checked.

That read is the only cost, and only a request carrying a forced filter pays it: a write with nothing scoped goes straight to the adapter as before. A client’s own ?filter= never constrains a write — only filters the server imposed do.

The field takes either spelling — the DB column name or the json name — and resolves to the same column on every path the scope reaches: the query, the write-back read, the value stamped onto the row, and the relation includes. Pick one and stay with it; a scope that resolved on some paths and not others would be a scope with a hole in it, which is what audit O2 found when the include gate accepted only the DB spelling.

If you build a maniflex.FilterExpr by hand and it expresses who may touch the row rather than which rows were asked for, set Forced: true on it; that is what carries it onto updates and deletes. ForceFilter and Tenancy set it for you.

Forced filters also travel into ?include=: a related model carrying the scope column is fetched through it, so a child that reached another tenant’s parent by some other road — an unscoped back-office write, an import, a row predating the key check above — does not surface in that tenant’s include. A many-to-many junction carrying the column is read through it too, so a link another tenant wrote between two of this tenant’s rows stays out as well. A related model with no such column — a shared lookup table like currencies or categories — is deliberately left unscoped, since it is not partitioned and has nothing to scope by.

Forced: true also lets a scope be imposed before the DB step. The Deserialize step rebuilds ctx.Query from the request, which discards a plain filter an earlier step appended — but a Forced filter survives that rebuild. So an Auth-step middleware may append a Forced filter to ctx.Query.Filters and have it reach the query; a non-forced one set that early is dropped. The DB step remains the idiomatic home for scoping (ForceFilter, Tenancy), and is required when the scope must also cover writes end-to-end within one transaction.

ProvidesScope — running the scope before Validate

Registering a scoper on the DB step puts it after Validate. The scope reaches the query, but nothing earlier in the chain can ask what it is. Declare maniflex.ProvidesScope() to hoist it to run right after Deserialize instead:

server.Pipeline.DB.Register(
    db.Tenancy("org_id", tenantFromAuth),
    maniflex.ProvidesScope(),          // ← hoists it ahead of Validate
)

Add it to every ForceFilter, ForceFilterVia and Tenancy registration unless you have a reason not to. It changes when the middleware runs, never what it does: the same filter is appended, the same rows are scoped, and an operation that skips the DB step still skips it. Hoisted middleware runs exactly once — it is removed from its own step, not duplicated.

It is opt-in, and forgetting it fails quietly. The framework cannot tell a scope provider from any other middleware, so it will not infer this, and there is no startup error for a registration that omits it. What you get instead is a scope that works for the query and is invisible to everything before the write. The sharpest symptom is on a scoped Singleton, whose row id is not known until its scope is: validate.UniqueField then excludes the record under edit by a placeholder that matches nothing, the row collides with itself, and every PATCH is refused with 422 "<field> is already taken" (audit 13.12).

lock_when is the other case, and it degrades rather than breaking: without the hoist the guard cannot read the row through your scope, so it moves to the DB step and refuses the update there instead — correctly, one step later. Hoisting restores the early abort, before the Service step’s transaction and business logic run.

Anything that needs the record a request addresses should ask ctx.ResolveResourceID() rather than reading ctx.ResourceID directly — see the context reference.

Use the maniflex.Op* constants for Operator. It’s a bare string type, and a hand-built filter is never parsed — only filters arriving over HTTP are — so Operator: "equals" compiles and boots, and until v0.2.3 it produced a scope that silently matched every row. An operator no adapter implements is now refused with an error naming it, and the adapters render it as a false predicate rather than a true one, so a filter reaching one by some other path matches nothing instead of everything. maniflex.FilterOperator.Valid() reports whether an operator is one the query builder implements.

ForceFilterVia

ForceFilter maps a field to a value, which needs the model to carry that field. A child table often doesn’t: a DamagedItem has an item_id and nothing else, and whether it’s yours is a fact about its Item. ForceFilterVia scopes such a model through the column its parent carries: