crud

type Authorize ¶

type Authorize func(ctx context.Context) error

Authorize is a hook the shim passes in to perform the per-RPC authorization check. The library runs it before the repository call and wraps its error as connect.CodePermissionDenied.

Returning nil allows the call. Returning a non-nil error fails the call. The hook may be nil — in which case authorization is skipped (mirroring methods declared without auth_required: true in proto).

type CreateOp ¶

type CreateOp[Req, Resp, Ent any] struct {
	EntityLower string
	Auth        Authorize
	Tenant      RequireTenant
	Entity      func(req *Req) Ent
	Persist     func(ctx context.Context, tenantID string, entity Ent) error
	Pack        func(entity Ent) *Resp
}

CreateOp wires the per-RPC concerns of a Create handler.

Create returns the constructed entity in the response. The shim supplies:

• Entity — proto request -> internal entity constructor.
• Persist — repository call. tenantID is empty when Tenant is nil.
• Pack — internal entity -> connect.Response.
• EntityLower — lowercase entity name used in the error envelope.
• Auth/Tenant — optional hooks.

type DeleteOp ¶

type DeleteOp[Req, Resp any] struct {
	EntityLower string
	Auth        Authorize
	Tenant      RequireTenant
	ID          func(req *Req) string
	Persist     func(ctx context.Context, tenantID string, id string) error
	// Pack is optional. When nil, HandleDelete returns the proto's
	// zero-value response (matching the legacy DeleteResponse{} shape).
	Pack func() *Resp
}

DeleteOp wires the per-RPC concerns of a Delete handler.

type GetOp ¶

type GetOp[Req, Resp, Ent any] struct {
	EntityLower string
	Auth        Authorize
	Tenant      RequireTenant
	ID          func(req *Req) string
	Fetch       func(ctx context.Context, tenantID string, id string) (Ent, error)
	Pack        func(entity Ent) *Resp
}

GetOp wires the per-RPC concerns of a Get handler.

type ListOp ¶

type ListOp[Req, Resp, Ent any] struct {
	EntityLower  string
	Auth         Authorize
	Tenant       RequireTenant
	PkColumnName string // empty disables PK-cursor pagination

	// Columns is the entity's declared column allowlist (the generated
	// db.<Entity>Columns var). User-supplied order_by columns are
	// validated against it — identifier-shape validation alone lets an
	// undeclared column reach the database, where some engines silently
	// treat it as a constant (an ordering no-op).
	Columns []string

	// Pagination knobs. The library applies the same defaults the legacy
	// template did when these are zero.
	HasPagination   bool
	DefaultPageSize int // 0 -> 50
	MaxPageSize     int // 0 -> 100

	// HasOrderBy enables req.Msg.OrderBy / req.Msg.Descending handling
	// via the OrderBy/Descending closures.
	HasOrderBy bool
	OrderBy    func(req *Req) (clause string, descending bool)

	// Filters returns extra orm.QueryOption values built from per-field
	// filter logic. The shim implements this as a static sequence of
	// "if req.Msg.X != nil { opts = append(opts, orm.WhereILike(...)) }"
	// statements — same as the legacy template, just lifted into a
	// closure.
	Filters func(req *Req) []orm.QueryOption

	// PageToken / PageSize accessors. PageSize is clamped by the
	// library; PageToken is decoded by the library.
	PageToken func(req *Req) string
	PageSize  func(req *Req) int

	// Query runs the repository call. tenantID is "" when Tenant is nil.
	// Returns slice + error; the library handles the +1 fetch and
	// trim-to-pageSize.
	Query func(ctx context.Context, tenantID string, opts []orm.QueryOption) ([]Ent, error)

	// EntityID extracts the cursor key from the last-of-page entity.
	// Required when HasPagination is true.
	EntityID func(entity Ent) string

	// Pack receives the trimmed item slice and the next page token (empty
	// when no further page). Shim assembles the response with the right
	// repeated-field name.
	Pack func(items []Ent, nextPageToken string) *Resp
}

ListOp wires the per-RPC concerns of a List handler. Pagination, filter, and order-by bookkeeping live in the library; the per-RPC shim still provides the per-field filter -> orm.QueryOption mapping (this is data, not lifecycle, and reflection-free Go can't generalize it without a code-gen table).

type Repo ¶

type Repo[M any] struct {
	// contains filtered or unexported fields
}

Repo is the generic data-access layer over a Bun-tagged model M. One Repo per entity replaces the ~250 LOC of per-entity Create/Get/List/ Count/ListAll/Update/UpdateMasked/Delete the generator used to emit; the generated code now supplies only the Bun-tagged struct, the ToProto/ FromProto pair, and a single crud.NewRepo[Model](Spec{...}) line.

All lifecycle semantics the pre-generic code carried are preserved exactly: tenant scoping, Bun-native + legacy-TEXT soft delete, the deleted_at IS NULL update-guard (Bun auto-scopes SELECT/DELETE to live rows but NOT UPDATE), AIP-134 masked updates with an updatable allowlist → orm.UnknownFieldError, managed-timestamp stamping, server-allocated / ULID PKs, and array nil→{} normalization. The QueryOption escape hatch (orm.QueryOption func(*bun.SelectQuery)) is threaded straight through to List/Count, and bun.IDB (db.Bun()) remains the raw-SQL escape hatch.

func NewRepo[M any](spec Spec) *Repo[M]

func (r *Repo[M]) Columns(db orm.Context) []string

func (r *Repo[M]) Count(ctx context.Context, db orm.Context, tenantID string, opts ...orm.QueryOption) (int64, error)

func (r *Repo[M]) Create(ctx context.Context, db orm.Context, entity *M, tenantID string) error

func (r *Repo[M]) Delete(ctx context.Context, db orm.Context, id any, tenantID string) error

func (r *Repo[M]) Get(ctx context.Context, db orm.Context, id any, tenantID string) (*M, error)

func (r *Repo[M]) List(ctx context.Context, db orm.Context, tenantID string, opts ...orm.QueryOption) ([]*M, error)

func (r *Repo[M]) ListAll(ctx context.Context, db orm.Context, tenantID string, opts ...orm.QueryOption) ([]*M, error)

func (r *Repo[M]) PkColumn(db orm.Context) string

func (r *Repo[M]) Update(ctx context.Context, db orm.Context, entity *M, tenantID string) error

func (r *Repo[M]) UpdateMasked(ctx context.Context, db orm.Context, entity *M, fields []string, tenantID string) error

type RequireTenant ¶

type RequireTenant func(ctx context.Context) (string, error)

RequireTenant is a hook the shim passes in for tenant-scoped operations. The library invokes it after the auth check, expects a tenant ID string back, and forwards it into the repository call. The returned error is wrapped as connect.CodeUnauthenticated.

Methods on tenant-aware entities pass a real closure that delegates to the project's middleware.RequireTenantID. Methods on global entities pass nil and the library treats the call as un-tenanted.

type Spec ¶

type Spec struct {
	TenantColumn        string
	Timestamps          bool
	LegacyTextDeletedAt bool
}

Spec is the IRREDUCIBLE per-entity descriptor the generator emits for a Repo. Everything Bun's own table schema can answer — table name, primary key column + Go field, autoincrement/server-allocated PK, the native (,soft_delete) deleted-at field, the full column set, array columns — is derived by reflection from the Bun-tagged model at first use (once per entity, never in the hot path). Spec carries ONLY the forge conventions Bun cannot infer from struct tags:

• TenantColumn — the multi-tenancy scoping column ("" = global entity, no tenant scoping). Bun has no concept of a tenant key.
• Timestamps — forge's managed created_at/updated_at stamping (set on Create, re-stamped on every Update/UpdateMasked). Distinct from a DB DEFAULT: forge stamps in Go so the value is identical across the row and visible to the caller without a re-read.
• LegacyTextDeletedAt — soft delete whose deleted_at column is a legacy TEXT column (Go type string) that Bun's time.Time-based ,soft_delete cannot round-trip. When true the repo hand-rolls the deleted_at IS NULL filter and the CURRENT_TIMESTAMP stamp (kalshi fr-3fba9166ba). Bun-native soft delete (proper time deleted_at) is detected from the schema and needs no flag.

type UpdateOp ¶

type UpdateOp[Req, Resp, Ent any] struct {
	EntityLower    string
	EntityFieldLow string // lowercase form of the proto field that holds the entity, e.g. "user"
	Auth           Authorize
	Tenant         RequireTenant
	Entity         func(req *Req) (entity Ent, ok bool)
	Persist        func(ctx context.Context, tenantID string, entity Ent) error
	Pack           func(entity Ent) *Resp

	// Mask extracts the AIP-134 update_mask paths from the request
	// (req.GetUpdateMask().GetPaths()). nil when the proto's update
	// request has no update_mask field — HandleUpdate then behaves
	// exactly as before this field existed (full replace via Persist).
	Mask func(req *Req) []string

	// PersistMasked writes ONLY the named fields (proto field names ==
	// column names, snake_case). The generator wires it whenever it
	// wires Mask. If Mask is set but PersistMasked is nil and a request
	// arrives with concrete paths, HandleUpdate fails CodeInternal —
	// silently widening a masked write to a full replace is the
	// data-loss bug this hook exists to prevent.
	PersistMasked func(ctx context.Context, tenantID string, entity Ent, fields []string) error
}

UpdateOp wires the per-RPC concerns of an Update handler. The shim supplies an EntityFromReq closure that returns (entity, ok). The library treats ok == false as "request missing entity" and returns CodeInvalidArgument with the same wording the legacy generator used.