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=created_at:desc, ?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 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 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.
    server.MustRegister(Post{})

    // 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.
    log.Fatal(server.Start())
}

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. 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 entry at /api/openapi.json.

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)
    }

    log.Fatal(server.Start())
}

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

    log.Fatal(server.Start())
}

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",
    })

    // 2. Register both models — populates the registry.
    server.MustRegister(Post{}, 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.
    log.Fatal(server.Start())
}

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

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),
)
server.Pipeline.Response.Register(response.CORSHeaders("https://app.example.com"))

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.

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. response.CORSHeaders adds the appropriate Access-Control-* headers via ctx.Writer.Header().

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. chi’s RealIP 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.

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"`
    CreatedAt time.Time `json:"created_at" db:"created_at" mfx:"readonly,sortable"`
    UpdatedAt time.Time `json:"updated_at" db:"updated_at" mfx:"readonly,sortable"`
}

• ID — the primary key, a UUID assigned by the framework on create.
• CreatedAt — set once, when the row is created.
• UpdatedAt — refreshed on every update.

All three are managed by the framework. CreatedAt and UpdatedAt are readonly: values supplied for them in a request body are ignored rather than stored. 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.

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.

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(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.

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"`

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 created_at and updated_at are readonly. 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.

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. 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. A typo in the referenced JSON name is caught at registration so you never ship a rule that silently never matches.

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 default Validate step’s other rules on update, and before the adapter’s Delete call on delete. 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.

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:"-".

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:

• Neither side soft-deletes → 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.

Either way the whole deletion is atomic: a restrict that fires rolls back any cascade that ran alongside 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.

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. The framework does not validate junction writes, so the include is where the scope has to hold.

// 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 the FK write is yours to validate.
• Relation-path filters (db.ForceFilterVia) are skipped: they are written against the primary model’s relations and mean nothing on the related table.
• The scope applies to the rows returned, not to the junction. A row that should never have been attached is now invisible rather than absent; clean it up at the write.

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.
• 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.

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
    },
})

LocalStorage.URL returns the server-relative /files/<key> for both signed and public modes (no real signing — bring an HMAC layer if you need it). S3Storage.URL uses awss3.NewPresignClient; ttl=0 (public mode) maps to the AWS 7-day maximum.

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)
}

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

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.

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.

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. 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.

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, ttl time.Duration) (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.

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.

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,
• reject keys ending in .meta.json in both Store and Retrieve if the backend uses sibling JSON files as a metadata layout (LocalStorage’s case), so the framework’s internal layout is never reachable through the file handler.

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. Because it is backed by Go’s http.FileServer, a request for a directory with no index.html returns a file listing. Add an index.html to each directory you do not want browsable — and only point StaticDir at a directory whose whole contents are safe to publish.

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.

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{...})

    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.

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.

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.

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.

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).

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 (map[string]any or a *T) for a read, create, or update. Anything else is rejected with 500 INVALID_DB_RESULT naming the type it got. 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:

func ctx.Abort(statusCode int, code, message string)

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.

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
}

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_DECLINED", resp.Message)
return nil

Log first, then abort — the log line is what you’ll need when debugging.

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)

    log.Fatal(server.Start())
}

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. Each one is an ordinary maniflex.MiddlewareFunc you register on the appropriate pipeline step, with the same scoping options as any other middleware.

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 — CORSHeaders, Cache, RedactField, then Logging / Metrics on the After side.

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.

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.

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.

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.

AllowPublicRead

A passthrough that exempts read operations from upstream auth requirements. Register it before JWTAuth / APIKeyAuth to let unauthenticated callers hit GET routes while keeping writes locked down.

server.Pipeline.Auth.Register(auth.AllowPublicRead())
server.Pipeline.Auth.Register(auth.JWTAuth("..."),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
)

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 the Redis backend:

import authredis "github.com/xaleel/maniflex/middleware/auth/redis"

rev := authredis.NewRevoker(redisClient, "myapp:revoked")

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).

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.AllowPublicRead())
server.Pipeline.Auth.Register(auth.JWTAuth("..."),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete))
server.Pipeline.Auth.Register(auth.RequireRole("admin"),
    maniflex.ForOperation(maniflex.OpDelete))

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.

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.

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: 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).

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:

// A DamagedItem is the caller's if its Item is
server.Pipeline.DB.Register(
    db.ForceFilterVia("item", "owner_id", func(ctx *maniflex.ServerContext) any {
        return ctx.Auth.Claims["owner_id"]
    }),
    maniflex.ForModel("DamagedItem"),
    maniflex.ProvidesScope(),
)

The first argument names the relation, in the same vocabulary a nested ?filter= uses (?filter=author.status:neq:banned → author); the second names a column on the parent, by JSON or DB name. The relation must be a BelongsTo — the join needs a foreign key on this row pointing at the one row that owns it, which is what a HasMany doesn’t have.

The alternative is to denormalise owner_id onto every child — a schema change plus a standing obligation to keep it in step, on exactly the tables whose scoping is easiest to get wrong — or to hand-write the predicate, which is what declarative scoping exists to replace.

Reads join the parent and apply the predicate. Updates and deletes read the row back through it and answer 404 on a miss, exactly as they do for ForceFilter.

Creates are scoped too, and they have to be. The foreign key is what the whole scope hangs from, and it’s the one part of it the client supplies. On a create there’s no row to read back, so without a check nothing looks at item_id at all and POST {"item_id": "<another tenant's>"} lands a row under their parent — where they can see it and you can’t. On an update the row read back is the one the old item_id points at, so a PATCH that rewrites the key passes a check of where the row used to be and then moves it somewhere else. So the parent a write names is read through the scope’s own predicate first, and a miss is the same 404 a scoped read of that parent gives. A create that names no parent at all is refused with 422: the join would find nothing, so the row would be invisible to whoever created it.

That parent read is the only added cost, and only a scope that runs through a parent pays it.

There’s no TenancyVia, because Tenancy is ForceFilter plus stamping the tenant column onto writes — and the whole premise here is a model with no such column to stamp. Checking the parent is what takes its place.

Actions: ForceFilterVia registers on the DB step, so like every other DB-step middleware it doesn’t run for a custom Action — see Scoping Actions. There’s no ForceFilterViaAction: an ActionScope’s filters apply to whatever model the handler touches, while a Via scope is resolved against one specific model’s relations, and an action runs on a synthetic model with none. For a single-model action, build the nested FilterExpr by hand (IsNested, RelationKey, RelationTable, RelationFK, NestedField, Forced) and pass it to ctx.SetActionScope. ctx.ViaFilter — the resolver ForceFilterVia is built on — reports this rather than guessing if you call it from an action.

Tenancy

A specialised ForceFilter for the common multi-tenant case. Reads the tenant id from ctx.Auth and pins every query to it:

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

Tenancy also rewrites the org_id field on creates and updates so a tenant cannot place rows into another tenant’s bucket. That rewrite is why the scoping on updates matters twice over: it stamps the caller’s tenant onto whatever row the update reaches, so an update that reached the wrong row would not merely overwrite it — it would move it into the caller’s tenant and leave the owner unable to see it at all.

That stamp is written with ctx.SetField, which marks the field as set by the server. A tenant column is normally readonly — a client must not choose its own tenant — and readonly means not from a client, so the Validate step keeps a value the server stamped and strips only one that arrived in the request body. Without that distinction a hoisted Tenancy would have its stamp discarded and write the row with an empty tenant: invisible to the tenant that created it, and visible to every caller whose scope is also empty.

Scoping Actions: TenancyAction / ForceFilterAction

Tenancy and ForceFilter register on the DB step, and a custom Action does not run it — its pipeline is Auth → middleware → handler → Response. Their only output is a filter on ctx.Query, which nothing in that chain reads, so registering them on the DB step does nothing at all for an Action, silently.

Use the Action variants instead, in the action’s own Middleware list, where they run after Auth and can read ctx.Auth:

server.Action(maniflex.ActionConfig{
    Method: "POST", Path: "/orders/{id}/refund",
    Middleware: []maniflex.MiddlewareFunc{
        auth.JWTAuth(secret),
        db.TenancyAction("org_id", func(ctx *maniflex.ServerContext) string {
            return ctx.Auth.Claims["org_id"].(string)
        }),
    },
    Handler: refund,
})

Inside that handler every DB path either applies the scope or refuses to run:

Reads see only matching rows. A create is stamped with the scope’s values, overwriting whatever the caller supplied — a row created outside the scope would be invisible to the caller that created it. An update or delete of a record outside the scope returns ErrNotFound, the same answer the scoped read gives.

Transactions work normally. Tx mirrors DBAdapter — its FindByID/FindMany take a *QueryParams, its Update/Delete are keyed by id — so the Tx that ctx.BeginTx returns is scoped the same way the accessor is, and that matters because ctx.Tx is a public field: anything downstream that picks the transaction up is scoped too. maniflex.WithTransaction and maniflex.Batch both call ctx.BeginTx, so both work on a scoped action:

tx, err := ctx.BeginTx(ctx.Ctx, nil)  // scoped
defer tx.Rollback()
// tx.FindByID / tx.Update / tx.Delete all honour the scope
return tx.Commit()

The refusals are the point. Raw SQL is opaque to the framework: a SELECT string cannot be scoped without rewriting it. Scoping the convenient paths and letting those leak in silence would put the guarantee in this page and not in the code — worse than no guarantee, because it would be trusted. Refusing means an action either honours the scope or fails at the first request that exercises it.

When a path genuinely must step outside the scope — an audit query across tenants, a migration — say so:

rows, err := ctx.Unscoped().RawQuery("SELECT ... FROM orders")

ctx.Unscoped() exposes RawQuery, RawExec, BeginTx, GetModel and Search with no scope applied. It is a distinct call rather than a flag so the bypass shows up at the call site, in the diff, and in a grep — which only works while it stays rare, so it is deliberately not needed for ordinary work.

The scope applies only to Actions. A generated CRUD route gets its scoping from the DB step, where ctx.RawQuery from an After-DB middleware is a normal thing to do and is not refused.

Action variants: RateLimitAction / AuditLogAction

RateLimit and AuditLog register on the DB step, which a custom Action never runs, so they never fire for one. Their action-list counterparts run in the action’s own Middleware list — after the global Auth step, so ctx.Auth is available:

server.Action(maniflex.ActionConfig{
    Method: "POST", Path: "/reports/{id}/evidence",
    Middleware: []maniflex.MiddlewareFunc{
        auth.JWTAuth(secret),
        db.RateLimitAction(db.RateLimitConfig{RequestsPerMinute: 10}),
        db.AuditLogAction(mySink),
    },
    Handler: uploadEvidence,
})

RateLimitAction takes the same RateLimitConfig as RateLimit but keys on the caller (its KeyFunc, else the authenticated user id, else the remote IP) plus the request method and path, since an action has no model/operation to key on. It rejects over-limit requests with 429 RATE_LIMITED and a Retry-After header.

AuditLogAction writes one audit record after a successful action (a >= 400 response is skipped), sourcing the actor and tenant from ctx.Auth, the resource id from the {id} URL param, the result from ctx.Response.Data, and Operation = OpAction. Writes are fire-and-forget, so a sink error never fails the request; change diffing (WithChanges) does not apply to actions.

Request budgeting

Paginate

Caps the maximum ?limit= accepted on list responses. Per-model overrides are common for tables whose rows are expensive to render:

server.Pipeline.DB.Register(db.Paginate(50), maniflex.ForModel("AuditLog"))

RateLimit

A token-bucket rate limiter scoped by IP or by authenticated user:

server.Pipeline.DB.Register(
    db.RateLimit(db.RateLimitConfig{
        RequestsPerMinute: 10,
        KeyFunc: func(ctx *maniflex.ServerContext) string {
            if ctx.Auth != nil {
                return ctx.Auth.UserID
            }
            return ctx.Request.RemoteAddr
        },
    }),
    maniflex.ForModel("PasswordReset"),
)

Rejected requests receive 429 RATE_LIMITED. The counter is in-process by default; for a limit shared across replicas set RateLimitConfig.Backend (see middleware/db/redis for the Redis implementation).

When the key falls back to the client IP (ctx.Request.RemoteAddr), that address is the direct TCP peer unless Config.TrustProxyHeaders is enabled — set it (only behind a trusted proxy) so per-IP limits see the real client instead of the load balancer. See Security.

RateLimitField

Rate-limits by the value of a request-body field rather than by caller identity — cap password-reset or OTP requests per email address, for instance, so one address cannot be flooded regardless of which client sends the requests:

server.Pipeline.DB.Register(
    db.RateLimitField("email", 3, time.Hour),
    maniflex.ForModel("PasswordReset"),
    maniflex.ForOperation(maniflex.OpCreate),
)

The arguments are the field name (its parsed-body value becomes the bucket key), the request cap, and the window. If the field is absent from the parsed body the limit is not applied, so a legitimate request is never blocked by a missing field. Rejected requests receive 429 RATE_LIMITED. Pass db.WithRateLimitBackend to share the window across replicas, or db.WithRateLimitErrorMessage to override the 429 message.

Post-write hooks

These run at maniflex.After position so they only fire when the database write succeeded.

AuditLog

Writes one audit record per mutating operation to a configured sink:

server.Pipeline.DB.Register(
    db.AuditLog(mySink),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
    maniflex.AtPosition(maniflex.After),
)

mySink is anything implementing the audit interface — a logger, a database table, an external SIEM. The record carries the operation, model name, actor (from ctx.Auth), and a JSON diff of the affected row.

Invalidate

Invalidates cache keys when a row changes. The key list is computed per request:

server.Pipeline.DB.Register(
    db.Invalidate(redisCache, func(ctx *maniflex.ServerContext) []string {
        return []string{
            "posts:list",
            fmt.Sprintf("post:%s", ctx.ResourceID),
        }
    }),
    maniflex.ForModel("Post"),
    maniflex.AtPosition(maniflex.After),
)

CacheQuery

Memoises read results (OpRead, OpList) in a CacheStore — the read-side complement to Invalidate. On a cache hit it sets ctx.DBResult and the adapter read is skipped; the Response step renders the cached result. On a miss it runs the read and stores the result for TTL. Pair it with Invalidate on writes to evict stale entries.

cache := maniflex.NewMemoryCache() // or a Redis-backed CacheStore

server.Pipeline.DB.Register(
    db.CacheQuery(cache, db.CacheConfig{
        TTL:     5 * time.Minute,
        KeyFunc: func(ctx *maniflex.ServerContext) string {
            // Only cache the common, high-traffic query shapes. Requests that
            // filter on `name` or carry a ?q= search are typically long-tail,
            // ad-hoc lookups — caching them floods the store with low-value
            // entries that are rarely read back, so skip them by returning "".
            if q := ctx.Query; q != nil {
                if q.Search != "" {
                    return ""
                }
                for _, f := range q.Filters {
                    if f.Field == "name" {
                        return ""
                    }
                }
            }
            return "products:list:" + ctx.Request.URL.RawQuery
        },
    }),
    maniflex.ForModel("Product"),
    maniflex.ForOperation(maniflex.OpList, maniflex.OpRead),
)
server.Pipeline.DB.Register(
    db.Invalidate(cache, func(*maniflex.ServerContext) []string {
        return []string{"products:list:..."}
    }),
    maniflex.ForModel("Product"),
    maniflex.ForOperation(maniflex.OpCreate, maniflex.OpUpdate, maniflex.OpDelete),
    maniflex.AtPosition(maniflex.After),
)

KeyFunc must capture every input that changes the result (model, tenant, filters, sort, pagination, includes); returning "" skips the cache for that request. The value stored is ctx.DBResult, so a distributed CacheStore must round-trip a *maniflex.ListResult for lists — a store that decodes list entries into a bare map is treated as a miss rather than panicking. Avoid caching mfx:"encrypted" models, since the decrypted result would live in the cache.

Ordering

Row-level scopers (ForceFilter, ForceFilterVia, Tenancy) must run Before the default DB step — the default position — so the filter is in place when the SELECT or UPDATE runs. Post-write hooks must run After, so they observe the result. The package’s defaults follow this; only change them if you know why.

Before is the latest a scoper can run, not the earliest it should. Pair it with maniflex.ProvidesScope() to hoist the scoper ahead of the Validate step, so the steps between Deserialize and the write see the same scope the query does.

Response Middleware

The maniflex/middleware/response package shapes the outgoing response — headers, body transforms, redactions, and observability hooks — on the Response step.

Cross-cutting headers

CORSHeaders

Adds CORS headers to every response. At least one origin is required — pass explicit origins (recommended) or "*" to allow any origin. Calling it with no origins panics at startup, so a permissive wildcard is never applied by accident.

import "github.com/xaleel/maniflex/middleware/response"

// Explicit origins (recommended)
server.Pipeline.Response.Register(response.CORSHeaders("https://app.example.com"))

// Public API: opt in to any origin explicitly
server.Pipeline.Response.Register(response.CORSHeaders("*"))

For credentials or custom allowed headers/methods/max-age, use CORSHeadersWithConfig. AllowCredentials cannot be combined with a "*" origin (browsers reject that combination) and panics if you try:

server.Pipeline.Response.Register(response.CORSHeadersWithConfig(response.CORSConfig{
    AllowOrigins:     []string{"https://app.example.com"},
    AllowCredentials: true,
}))

AddHeader

Sets one static header on every response:

server.Pipeline.Response.Register(
    response.AddHeader("Strict-Transport-Security", "max-age=63072000"),
)

Caching

Cache

Sets Cache-Control: public, max-age=N on successful reads. Register at maniflex.After so the framework’s own headers do not override yours:

server.Pipeline.Response.Register(
    response.Cache(300),  // 5 minutes
    maniflex.ForOperation(maniflex.OpRead, maniflex.OpList),
    maniflex.AtPosition(maniflex.After),
)

Body transforms

TransformField

Rewrites a single field value before serialisation. Common use: rebasing a stored relative path onto a CDN host.

server.Pipeline.Response.Register(
    response.TransformField("avatar_url", func(v any) any {
        return cdnBase + v.(string)
    }),
)

RedactField

Hides a field from the response conditionally. The predicate decides per request, often based on ctx.Auth:

server.Pipeline.Response.Register(
    response.RedactField("phone", func(ctx *maniflex.ServerContext) bool {
        return !ctx.HasRole("support")
    }),
)

RedactField is the right tool for view-time access control on individual columns. For all-or-nothing exclusion across an entire model, the hidden or writeonly field tag is simpler.

For the write side — “only a superuser may set this field” — use validate.FieldRole / validate.RestrictField, which takes the same predicate on the Validate step. Note the two differ on purpose when the predicate fails: a redacted read returns the record without the field, while a refused write returns 403 rather than quietly dropping it.

It covers exports too: GET /:model/export masks the same field for the same callers, and drops it from the CSV/XLSX header rather than emitting an empty column.

Writing your own masking middleware

A Response-step middleware normally masks by editing ctx.Response after next() returns. That is not enough on its own, because an export has no ctx.Response — it streams its bytes during next() — so a middleware that only edits one masks the JSON and leaves the export in full.

Declare the field instead, before calling next():

func maskSalary(ctx *maniflex.ServerContext, next func() error) error {
    if !ctx.HasRole("admin") {
        ctx.RedactResponseField("salary") // before next(), so the export sees it
    }
    return next()
}

The declaration is honoured by every read path — list, single read, create and update echoes, and both export formats. response.RedactField does this for you.

Before v0.2.5 a masking middleware applied to JSON responses only. An app that hid a column from non-admins served it in full at /:model/export.

Envelope

Replaces the default {"data": ...} envelope with one of your own:

server.Pipeline.Response.Register(
    response.Envelope(func(ctx *maniflex.ServerContext, data any, meta *maniflex.ResponseMeta) any {
        return map[string]any{
            "result":   data,
            "paging":   meta,
            "trace_id": ctx.TraceID,
        }
    }),
)

Useful when integrating with a frontend or API gateway that expects a different shape. Error responses are unaffected; only success responses are re-enveloped.

Observability

Logging

Writes a structured access log line per request at maniflex.After:

server.Pipeline.Response.Register(
    response.Logging(slog.Default()),
    maniflex.AtPosition(maniflex.After),
)

The line carries request ID, trace ID, method, path, status, duration, and the authenticated user when set.

Metrics

Records per-request metrics — count, latency, status class — into a configured collector:

server.Pipeline.Response.Register(
    response.Metrics(myCollector),
    maniflex.AtPosition(maniflex.After),
)

A reference Prometheus collector is provided; any sink with the same interface works.

OpenAPI Middleware

The maniflex/middleware/openapi package customises the auto-generated OpenAPI 3.1 specification served at GET /openapi.json. Every middleware here is registered on the Pipeline.OpenAPI.Generate step at maniflex.After position, so it sees the framework’s generated spec and can mutate it before the Response step serialises it.

SetTitle, SetDescription

Override the default title and description, which are derived from Config.ServiceName:

import "github.com/xaleel/maniflex/middleware/openapi"

server.Pipeline.OpenAPI.Generate.Register(
    openapi.SetTitle("Orders API"),
    maniflex.After,
)
server.Pipeline.OpenAPI.Generate.Register(
    openapi.SetDescription("# Orders API\nProduction endpoints for the orders service."),
    maniflex.After,
)

SetVersion

Overrides the spec’s info.version, which is otherwise the framework default. Use it to surface your service’s own release version in the published spec:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.SetVersion("2.1.0"),
    maniflex.After,
)

AddServer

Declares a server URL in servers[]. Repeat for multiple environments:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddServer("https://api.example.com",     "Production"), maniflex.After)
server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddServer("https://staging.example.com", "Staging"),    maniflex.After)

Without AddServer the spec carries no servers array, leaving clients to resolve URLs against the host that served the spec.

AddSecurityScheme

Adds a security scheme to components.securitySchemes and applies it to every operation generated by the framework:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddSecurityScheme("bearerAuth", maniflex.OASSecurityScheme{
        Type:         "http",
        Scheme:       "bearer",
        BearerFormat: "JWT",
    }),
    maniflex.After,
)

Pair with auth.JWTAuth on the runtime side. For API keys, use Type: "apiKey" and set In and Name.

AddTag

Appends a Tag Object to the spec. Tags render as collapsible groups in Swagger UI; maniflex already emits one tag per model, so use AddTag for cross-cutting or documentation-only groupings. A tag whose name already exists is not duplicated.

server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddTag("Authentication", "Endpoints related to user authentication"),
    maniflex.After,
)

InjectRequestExample

Attaches an example request body to a specific operation so Swagger UI’s “Try it out” pre-populates with realistic values. The operation is named by path and lower-case method:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.InjectRequestExample(
        openapi.OperationTarget{Path: "/posts", Method: "post"},
        "Example post", map[string]any{
            "title":  "Hello World",
            "body":   "My first post.",
            "status": "draft",
        }),
    maniflex.After,
)

The example is only applied when the target operation and its request body exist in the generated spec; an unmatched target is a no-op.

AddExtension

A general-purpose escape hatch — receives the full *maniflex.OpenAPISpec and lets you mutate any part of it:

server.Pipeline.OpenAPI.Generate.Register(
    openapi.AddExtension(func(spec *maniflex.OpenAPISpec) {
        spec.Info.Description += "\n\nContact the API team at [email protected]."
    }),
    maniflex.After,
)

Use sparingly — anything you can express through the typed helpers is easier to read.

Securing the spec itself

To gate access to /openapi.json, register an Auth middleware on Pipeline.OpenAPI.Auth — it has the same shape as the model-route Auth step:

server.Pipeline.OpenAPI.Auth.Register(auth.RequireRole("internal"))

This is the standard pattern for keeping internal APIs out of the public view while leaving the public surface documented.

Querying

Every generated list and read endpoint accepts the same query parameters — page, limit, filter, sort, include, and select. This page documents their grammar and the fields that opt in to each.

page and limit

Standard offset pagination.

?page=2&limit=20

Values above the maximum are clamped silently. Negative or non-numeric values are rejected with 400 INVALID_QUERY.

The response carries meta.total, meta.page, meta.limit, and meta.pages — see Response Envelope.

cursor (keyset pagination)

Offset pagination skips or duplicates rows when the dataset changes between page fetches — delete a row on page 1 and page 2 silently jumps a record. Keyset (cursor) pagination walks the data by a stable ordering key instead, so the window never shifts. Opt a model in by naming a sortable, effectively monotonic cursor column:

type Event struct {
    maniflex.BaseModel `mfx:"cursor_field:created_at"` // created_at is sortable on BaseModel
    Name string        `json:"name" db:"name"`
}

Equivalently, set ModelConfig.CursorField: "created_at" at registration, or put mfx:"...,cursor_field:<name>" on any of the model’s own fields.

The cursor column must be mfx:"sortable" and not nullable — a pointer field (*time.Time) is rejected at registration. Keyset pagination needs a total order, and NULL has no place in one: the boundary comparison is never true for it, and Postgres and SQLite don’t even agree where NULLs sort. A nullable cursor column would drop or repeat rows across pages, so the model fails to register rather than paginating wrongly.

The presence of ?cursor= switches the request into keyset mode (it supersedes ?page). Send an empty value for the first page, then the meta.next_cursor from each response to fetch the next:

GET /events?cursor=&limit=20          → first page
GET /events?cursor=<next_cursor>&limit=20  → following page

The walk is ordered by (cursor_field, id) — id is the implicit tiebreaker so the order is total even when the cursor column ties. The default direction is ascending; sort on the cursor field to reverse it:

GET /events?cursor=&sort=created_at:desc

Any ?sort= on a different field is rejected with 400 in cursor mode, since the keyset order is fixed to the cursor column.

Cursor responses carry a different meta shape — no total/page/pages (the count is skipped, which is the point on large tables):

{ "data": [ ... ], "meta": { "limit": 20, "next_cursor": "eyJ2Ijoi...", "has_more": true } }

has_more is false and next_cursor is omitted on the last page. The token is opaque — treat it as a string and pass it back verbatim.

filter

Each filter is a colon-separated triple — field, operator, value:

?filter=status:eq:published
?filter=views:gt:100
?filter=created_at:gte:2025-01-01

Multiple filters combine with AND:

?filter=status:eq:published&filter=views:gt:100

Filters reference a field by its json name. Only fields tagged mfx:"filterable" may be used; unknown or non-filterable references abort the request with 400 INVALID_QUERY.

Operators

?filter=tag:in:go,rust,zig
?filter=amount:between:100,500
?filter=created_at:between:2025-01-01,2025-03-31
?filter=archived_at:is_null
?filter=title:ilike:%intro%
?filter=title:contains:intro

Patterns vs. literals

like and ilike take a pattern: % matches any run of characters and _ matches exactly one. That is what makes ?filter=title:ilike:%intro% work — but it also means a value the user typed is interpreted rather than matched. ?filter=label:like:50% finds 500 units and 50 off as readily as the 50% you were looking for, and there is no portable way to escape a % in a pattern (SQLite has no escape character by default; Postgres has a backslash).

contains, starts_with, and ends_with take a literal: % and _ in the value are escaped for you and match themselves, so ?filter=label:contains:50% finds exactly the labels containing 50%. They are case-insensitive on both backends. Use them for anything a user typed — a search box, a filename, an SKU — and reach for like/ilike only when the caller genuinely is writing a pattern.

Note that % must still be percent-encoded in a URL (%25), as in any query string:

?filter=label:contains:50%25       → matches the literal "50%"
?filter=label:like:50%25           → matches "50%", "500 units", "50 off", …

Filtering on related fields

When a relation is declared on the model, you can filter by a field on the related table using dot notation:

?filter=user.role:eq:admin
?filter=posts.status:eq:published

The related field must itself be filterable. The framework joins the related table for the query; no separate ?include= is required to filter on it (but you still need ?include= to return the related row).

q (full-text search)

?q= runs a native full-text search over every field tagged mfx:"searchable" and orders the results by match relevance:

?q=hello world
?q=postgres&filter=tag:eq:db

This is distinct from filter: full-text search uses the database’s own ranking, stemming, and tokenisation rather than literal comparison, so ?q=run also matches running, and the densest match ranks first. The backend’s native machinery does the work — a tsvector column and GIN index on PostgreSQL, an FTS5 index on SQLite — both provisioned automatically during migration.

• Only models with at least one mfx:"searchable" field accept ?q=; on any other model it aborts with 400 INVALID_QUERY. Searchable fields must be text columns.
• ?q= combines with ?filter= (ANDed) and the usual ?page=/?limit= offset pagination. It cannot be combined with ?cursor=, since keyset order and relevance order are mutually exclusive.
• An empty value (?q=) is ignored — the list is returned unfiltered.
• On PostgreSQL the text-search configuration defaults to english; override it per model with ModelConfig.SearchLanguage.

type Article struct {
    maniflex.BaseModel
    Title string `json:"title" db:"title" mfx:"required,searchable"`
    Body  string `json:"body"  db:"body"  mfx:"searchable"`
}
// GET /articles?q=keyset+pagination → relevance-ranked matches

sort

Each sort is field:direction:

?sort=created_at:desc
?sort=title:asc

Multiple sorts compose left-to-right (primary, secondary, …):

?sort=status:asc&sort=created_at:desc

Only fields tagged mfx:"sortable" may be used. BaseModel’s created_at and updated_at are sortable by default.

Sorting on a relation field

Use relation.field to sort by a column on a BelongsTo parent. The server adds the LEFT JOIN automatically — no filter or include on that relation is required:

?sort=user.name:asc
?sort=vendor.name:desc&filter=status:eq:open

The related field must be tagged mfx:"sortable" on the parent model. Only BelongsTo relations are supported; relation.field on a HasMany or ManyToMany returns 400, as does an unknown relation or a non-sortable related field.

include

Loads related records inline. The value is a comma-separated list of relation keys:

?include=user
?include=user,comments

Each key becomes a nested object (for BelongsTo) or array (for HasMany and ManyToMany) on the returned row. See Relations for how relation keys are derived.

Includes are populated by separate queries after the main query — they do not multiply rows or affect pagination.

One level of nesting

A key may carry a single dot to load a relation of the related model:

?include=author.company
?include=author.company,comments

?include=author.company implies author — the parent is what the child hangs off — so you do not need to name both.

Two segments is the limit. ?include=a.b.c is refused with 400 INVALID_QUERY. Each level is one more batched query, and the tree comes from the client, so leaving it uncapped would let a caller choose how much work a request costs.

Every segment must name a real relation; a typo is a 400, not a silently missing key. Nested rows are scoped, decrypted and field-filtered exactly as the first level is — a forced filter (db.Tenancy, db.ForceFilter) applies at every level, and hidden / writeonly fields on the nested model stay out.

Go callers: nesting applies to the JSON response. The typed relation structs (post.Author) are still populated one level deep, so post.Author.Company is not filled in by a typed read. Use the JSON path, or a second maniflex.Read.

select

Request a subset of fields instead of the full row. Useful for wide tables (payroll, product catalogues with 40+ attributes) where most columns are irrelevant to the caller.

?select=id,name,department
?select=id,amount,status

The value is a comma-separated list of JSON field names. Unknown names abort the request with 400 INVALID_QUERY. Fields tagged mfx:"hidden" or mfx:"writeonly" are still stripped from the response even if explicitly selected — the projection happens at the database layer, not as an ACL bypass.

?select= applies to both list (GET /:model) and read (GET /:model/:id) endpoints. It can be combined freely with filter, sort, and include.

Putting it together

A complete request that exercises all parameters:

GET /api/posts
    ?filter=status:eq:published
    &filter=views:gte:100
    &sort=created_at:desc
    &include=user,comments
    &select=id,title,views,status
    &page=1
    &limit=20

The framework parses the query string once in the Deserialize step into ctx.Query (a *QueryParams), which middleware can read and modify before the DB step. Tenant-scoping middleware, for example, appends a filter to ctx.Query.Filters to enforce row-level access — see Example 2.

Searching

maniflex has two layers of full-text search:

• Per-model search — the ?q= parameter on a model’s list endpoint, over its mfx:"searchable" fields. Covered in Querying.
• Cross-model search — search several models at once and merge the hits into one relevance-ranked list. That is what this page documents: the ctx.Search primitive and the built-in GET /search endpoint.

Both use the database’s native full-text engine (PostgreSQL tsvector / ts_rank, SQLite FTS5 / bm25), provisioned automatically for every model that declares mfx:"searchable" fields. Free-form input is sanitised, so a query can never be a syntax error.

The ctx.Search primitive

ctx.Search runs a cross-model search and returns the merged, relevance-ranked hits. Use it from a custom Action to build search endpoints scoped to exactly the models you choose, with your own authorisation:

server.Action(maniflex.ActionConfig{
    Method: "GET", Path: "/search-community",
    Middleware: []maniflex.MiddlewareFunc{communityAuth},
    Handler: func(ctx *maniflex.ServerContext) error {
        hits, err := ctx.Search(maniflex.SearchOptions{
            Query:  ctx.QueryParam("q"),
            Models: []string{"Post", "Comment"}, // explicit, app-authorised set
            Limit:  20,
        })
        if err != nil {
            ctx.Abort(400, "SEARCH_ERROR", err.Error())
            return nil
        }
        ctx.Response = &maniflex.APIResponse{StatusCode: 200, Data: hits}
        return nil
    },
})

type SearchOptions struct {
    Query         string   // the search text; blank → no-op (no results)
    Models        []string // models to search; empty → all GlobalSearchable models
    Limit         int      // max merged results; <= 0 → 20
    PerModelLimit int      // fairness cap (see Merge order); <= 0 → pure relevance
}

type SearchResult struct {
    Model   string  `json:"model"`   // the model the hit came from
    ID      string  `json:"id"`      // primary key of the matched row
    Snippet string  `json:"snippet"` // excerpt of the matched text
    Score   float64 `json:"score"`   // relevance, higher = more relevant
}

func (c *ServerContext) Search(opts SearchOptions) ([]SearchResult, error)

With an explicit Models list each named model only needs mfx:"searchable" fields — it does not need GlobalSearchable. That flag governs only the built-in endpoint below; the Action path is yours to authorise. ctx.Search participates in ctx.Tx when one is active and excludes soft-deleted rows.

The built-in GET /search endpoint

Enable it explicitly, then opt models in with ModelConfig.GlobalSearchable:

server.EnableGlobalSearch() // mounts GET {PathPrefix}/search

server.MustRegister(
    Post{},    maniflex.ModelConfig{GlobalSearchable: true},
    Comment{}, maniflex.ModelConfig{GlobalSearchable: true},
    Product{}, maniflex.ModelConfig{GlobalSearchable: true},
)

GlobalSearchable requires the model to declare at least one mfx:"searchable" field; registration fails otherwise.

GET /api/search?q=wireless+headphones
GET /api/search?q=invoice&limit=10&models=Product

The response is the standard envelope with a flat array of hits, ordered by score descending:

{
  "data": [
    {"model": "Product", "id": "9f8…", "snippet": "wireless …", "score": 0.61},
    {"model": "Post",    "id": "1a2…", "snippet": "… wireless", "score": 0.18}
  ]
}

Configure the route and limits via EnableGlobalSearch:

server.EnableGlobalSearch(maniflex.GlobalSearchConfig{
    Path:         "/search",
    DefaultLimit: 20,
    MaxLimit:     100,
})

Authorization

The endpoint runs only the global Auth pipeline step — it does not apply per-model auth or tenancy middleware. Gate it with Pipeline.Auth middleware, either globally or scoped to the search operation:

server.Pipeline.Auth.Register(requireLogin, maniflex.ForOperation(maniflex.OpSearch))

Because per-model row-level rules are not applied, only set GlobalSearchable on models that are safe to expose this way. When you need per-model authorisation, build a scoped Action with ctx.Search instead (see above) and attach your own middleware. Middleware registered for OpSearch on the Deserialize, Validate, Service, or DB steps never runs (the endpoint skips them) and is reported with a startup warning.

Merge order

A deployment uses one database driver, so every model shares one ranking function and the scores are directly comparable; results merge by score descending.

By default the merge is pure relevance — if one model’s hits dominate, the result can be entirely from that model. Set PerModelLimit to give each model a fair share: the merge first takes up to PerModelLimit of each model’s top-scoring hits, then backfills any remaining slots up to Limit from the leftovers (best score first, regardless of model). It is a fair-chance floor, not a hard ceiling — the result still fills to Limit when some models have fewer hits.

Cross-model scores are a heuristic: bm25 and ts_rank depend on each table’s own corpus statistics, so a common term can score higher in a table where it is rarer. Use PerModelLimit when you want guaranteed representation across models rather than a pure score ranking.

Response Envelope

Every response from a generated route follows one of two shapes — the data envelope or the error envelope. This page documents both, along with the status codes the framework emits.

Success envelope

A successful single-row response — OpRead, OpCreate, OpUpdate:

{
  "data": {
    "id": "8c1a…",
    "title": "First post",
    "created_at": "2026-05-19T12:34:56Z",
    "updated_at": "2026-05-19T12:34:56Z"
  }
}

A successful list response carries the same data key plus a meta block:

{
  "data": [
    { "id": "8c1a…", "title": "First post", ... },
    { "id": "9d2b…", "title": "Second post", ... }
  ],
  "meta": {
    "total": 137,
    "page": 1,
    "limit": 20,
    "pages": 7
  }
}

When a request uses cursor (keyset) pagination (?cursor=), the meta block takes a different shape — no total/page/pages (the count is skipped):

{ "data": [ ... ], "meta": { "limit": 20, "next_cursor": "eyJ2Ijoi...", "has_more": true } }

DELETE returns 204 No Content with no body.

Error envelope

Every error response uses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "one or more fields failed validation",
    "details": [
      { "field": "email",    "message": "field \"email\" is required" },
      { "field": "password", "message": "must be at least 8 characters" }
    ]
  }
}

details is an array wherever it is present, including on a 409 CONFLICT from a unique violation. That one was a bare object until v0.3.0, so a duplicate value answered in two shapes depending on whether the database or validate.UniqueField caught it; a client that ranged over details had to type-switch first.

A composite unique constraint contributes one entry per column, so a form can highlight every input involved:

{"error": {"code": "CONFLICT", "message": "unique constraint violation",
  "details": [
    {"field": "phone_number", "message": "the combination of phone_number, owner_id is already taken"},
    {"field": "owner_id",     "message": "the combination of phone_number, owner_id is already taken"}
  ]}}

The message names the combination rather than a column because neither column is in violation on its own — that phone number is fine, the pair is not.

The catalogue of built-in codes is in Error Handling.

Status codes

HEAD mirrors the GET for the same URL with the body suppressed: same status (including 404 for a record that does not exist), same headers, same middleware — just no body.

OPTIONS returns 204 No Content with an Allow header listing the methods the route accepts.

Headers

Every response carries:

Custom middleware can add more — see Response Middleware for AddHeader, CORSHeaders, Cache, and friends.

Computed (virtual) fields

Server.AddComputedField registers a derived field that appears in every read response (create echo, single read, update echo, list rows) without being stored:

server.MustAddComputedField("Product", "stock_level",
    func(ctx *maniflex.ServerContext, row map[string]any) (any, error) {
        return stockService.CurrentLevel(ctx.Ctx, row["id"].(string))
    })

The function runs in the Response step after the DB row has been converted to JSON keys, so row’s keys are JSON field names. It receives the *ServerContext, so it can reach ctx.Tx, ctx.GetModel and ctx.Auth.

Computed fields:

• Cannot be filtered or sorted — they’re materialised on output only.
• Are name-collision-checked at registration: a name that matches a real model field, or that’s already registered as computed, is rejected.
• Tolerate errors per-row — a non-nil error from the function is logged and the field is omitted from that row; the rest of the response is unaffected.
• Tolerate a panic the same way — a panicking callback is logged (with its stack, at ERROR) and its field omitted, exactly as a returned error is. It costs that one field on that one row: the record is still returned and the model’s other computed fields still resolve. This holds for batch callbacks too, so converting a per-row field to a batch one does not change what a bad row costs.
• Run on every read path that goes through the default Response step, including the create and update echoes.
• Must be goroutine-safe. On a multi-row page the per-row callbacks run concurrently (bounded to 8 at a time), so a callback that writes to a captured variable, a shared map, or any other state must synchronise it. Batch callbacks are called once for the whole page and are not affected.

Do not use ctx.Tx from a per-row callback. A *sql.Tx is not safe for concurrent use, and the callbacks for one page share the same ServerContext. Reads through ctx.GetModel or maniflex.Read enlist ctx.Tx when one is open, so a computed field that reads while the request is in a transaction is exactly this case. Resolve such a field with AddBatchComputedField, which runs once and sequentially.

• Appear in the OpenAPI spec as read-only properties of the model’s response schema (never in a create or update body).

Use them for derived values that change too often to denormalise (stock level, leave balance, account balance) or that depend on external systems.

Batch resolution (AddBatchComputedField)

AddComputedField runs once per row, so a resolver that queries is an N+1: a 50-row page costs 50 round-trips. AddBatchComputedField resolves the whole page in one call instead — this is what lets a generated GET /store-sites return an item_count without a hand-written action: