types

type AggregateFn string

type AggregateOrder struct {
	Term      AggregateTerm
	Direction OrderDirection
}

type AggregateTerm struct {
	// Fn is the aggregate function, or AggregateNone for a group key.
	Fn AggregateFn
	// Column is the snake case column name. It is empty only for COUNT(*).
	Column string
	// Bucket truncates a time group key. It is only meaningful when Fn is
	// AggregateNone and the column is a time column.
	Bucket TimeBucket
	// Conditions restrict a measure to the rows matching them, rendering as a
	// CASE expression inside the aggregate call. They reuse the query filter
	// tree, so conditional aggregation needs no predicate language of its own.
	Conditions []Filter
	// Alias names the term in the SELECT list and binds it to a field of the
	// result row. An empty alias defaults to the column name.
	Alias string
}

type Aggregator[M Model, R any] interface {
	// Select declares the projection. A term without an aggregate function is
	// a group key, and GROUP BY is derived from those keys, so the SELECT and
	// GROUP BY lists cannot disagree. At least one aggregate term is required.
	Select(terms ...AggregateTerm) Aggregator[M, R]
	// Where restricts the rows entering the aggregation, using the same filter
	// tree as WithQuery.
	Where(filters ...Filter) Aggregator[M, R]
	// Having restricts the produced groups by their measures.
	Having(conditions ...Having) Aggregator[M, R]
	// OrderBy sorts the result rows by a projection term.
	OrderBy(orders ...AggregateOrder) Aggregator[M, R]
	// Limit caps the number of result rows.
	Limit(n int) Aggregator[M, R]
	// Offset skips result rows, for paginating a grouped report.
	Offset(n int) Aggregator[M, R]

	// Scan runs the query and fills dest with one element per group.
	Scan(dest *[]R) error
	// ScanOne runs an ungrouped aggregation and fills dest with its single
	// row. It fails when the projection declares group keys.
	ScanOne(dest *R) error
	// CountGroups reports how many groups the query produces, which is the
	// total a paginated grouped report needs. OrderBy, Limit and Offset set on
	// the builder do not apply to it.
	CountGroups(count *int) error

	// WithDryRun builds the SQL without database I/O. An optional collector
	// receives the generated Query, Args, and RenderedSQL of the next
	// terminal operation instead of executing it.
	WithDryRun(collector ...*[]SQLStatement) Aggregator[M, R]
}

type AnyColumnRef interface {
	// Name returns the database column name resolved by gorm.
	Name() string
	// contains filtered or unexported methods
}

type Assignment struct {
	Column string
	Value  any
}

type Cache[T any] interface {
	// Get retrieves a value from the cache by key.
	// Returns ErrEntryNotFound if the key does not exist.
	Get(ctx context.Context, key string) (T, error)

	// Set stores a value in the cache with the specified TTL.
	Set(ctx context.Context, key string, value T, ttl time.Duration) error

	// Delete removes a key from the cache.
	// Deleting a key that does not exist is not an error.
	Delete(ctx context.Context, key string) error

	// Exists checks if a key exists in the cache.
	// Returns true if the key exists, false otherwise.
	Exists(ctx context.Context, key string) bool
}

type Coder interface {
	Code() int
	Status() int
	Msg() string
}

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

type ColumnRef[T any] interface {
	AnyColumnRef
	// contains filtered or unexported methods
}

type ControllerConfig[M Model] struct {
	// ParamName names the route parameter that carries the resource ID.
	ParamName string
	// Route is the raw route string the handler is registered under. Controller
	// factories derive the service registry key from it, so it must match the
	// route passed to the corresponding service.Register call. router.Register
	// fills it in automatically; an empty route resolves no service and the
	// handler falls back to the no-op default service.
	Route string
}

type Cursor struct {
	// Order is the feed's stable ordering. An empty column falls back to the
	// primary key in the database layer.
	Order Order
	// Value is the boundary row's column value. An empty value disables
	// cursor pagination, which makes a zero Cursor a no-op.
	Value string
	// Backward travels against Order instead of along it, which is what a
	// request for the previous page means.
	Backward bool
}

type Database[M Model] interface {
	// Create inserts one or more records (pure INSERT), setting framework IDs
	// and forcing created_at/updated_at to now. A primary or unique key
	// collision fails with database.ErrDuplicatedKey instead of updating the
	// existing row.
	Create(objs ...M) error
	// Delete removes one or more records using WithPurge, the model Purge setting, or soft delete by default.
	Delete(objs ...M) error
	// Update saves one or more full model values by primary key (pure UPDATE,
	// zero values included). Objects without an ID fail with
	// database.ErrIDRequired; records without a live row fail with
	// database.ErrRecordNotFound. created_at/created_by/deleted_at are never
	// written; updated_at is always refreshed by the framework.
	Update(objs ...M) error
	// Upsert inserts records or, on any unique-key collision, overwrites the
	// conflicting row (INSERT ... ON DUPLICATE KEY UPDATE). It runs no model
	// hooks and re-syncs caller objects with the persisted rows; reserve it
	// for deliberate merge writes such as imports and sync jobs.
	Upsert(objs ...M) error
	// UpdateByID updates database columns of a record by its ID in one
	// UPDATE statement, without running model hooks. Assignments come from
	// the generated column references (SampleCols.Status.Set(v)) or the
	// Assign constructor for dynamic columns; at least one is required, and
	// empty columns, nil values and a column assigned twice are rejected.
	UpdateByID(id string, assignments ...Assignment) error
	// List retrieves multiple records matching the query conditions.
	// dest must be a non-nil pointer to a slice; the slice value itself may be
	// nil or preallocated with make. List fully replaces the slice contents with
	// the query result: any pre-existing elements are discarded, never merged or
	// appended to. After a successful call len(*dest) equals the number of rows
	// returned, so a "dirty" dest does not leak stale rows into the result.
	List(dest *[]M) error
	// Get retrieves a single record by its ID.
	// The destination must be a non-nil pointer matching M. When M is *T,
	// both &value and new(T) are valid destinations; a nil *T returns ErrNilDest.
	// Get returns database.ErrRecordNotFound when no matching record exists.
	Get(dest M, id string) error
	// First retrieves the first record matching the current query conditions.
	// First returns database.ErrRecordNotFound when no matching record exists.
	First(dest M) error
	// Last retrieves the last record matching the current query conditions.
	// Last returns database.ErrRecordNotFound when no matching record exists.
	Last(dest M) error
	// Take retrieves the first record in no specified order.
	// Take returns database.ErrRecordNotFound when no matching record exists.
	Take(dest M) error
	// Count returns the total number of records matching the query conditions.
	Count(*int) error

	DatabaseOption[M]
}

type DatabaseOption[M Model] interface {
	// WithQuery adds query conditions from model fields or raw SQL configuration.
	WithQuery(query M, opts ...QueryOptions) Database[M]
	// WithCursor enables cursor-based pagination for List operations.
	WithCursor(cursor Cursor) Database[M]
	// WithSelect specifies columns for SELECT and Update column selection
	// where supported, through the generated column references.
	WithSelect(columns ...AnyColumnRef) Database[M]
	// WithLock adds row-level locking to SELECT queries (must be used within a transaction).
	WithLock(mode ...consts.LockMode) Database[M]
	// WithBatchSize sets the batch size for Create, Update, and Delete.
	WithBatchSize(size int) Database[M]
	// WithPagination applies pagination parameters (page, size) to the query.
	WithPagination(page, size int) Database[M]
	// WithLimit restricts the number of returned records for read operations.
	WithLimit(limit int) Database[M]
	// WithOffset skips records before returning read operation results.
	WithOffset(offset int) Database[M]
	// WithOrder adds ORDER BY terms to sort query results.
	WithOrder(orders ...Order) Database[M]
	// WithExpand enables eager loading of specified associations.
	WithExpand(expand []string, orders ...Order) Database[M]
	// WithPurge controls whether Delete permanently removes records instead of soft deleting them.
	WithPurge(...bool) Database[M]
	// WithDeleted includes soft-deleted records in read operations (List, Get,
	// First, Last, Take, Count). Only the soft-delete condition is lifted;
	// combining it with a write operation or Cleanup fails the chain.
	WithDeleted() Database[M]
	// WithReplica routes this read to a configured read replica —
	// WithReplica(false) forces the primary instead, overriding a model's
	// PreferReplica default. Reads only; a write operation fails the chain.
	WithReplica(prefer ...bool) Database[M]
	// WithDryRun builds SQL without database I/O, framework hooks, cache
	// mutation, or object field filling. An optional collector receives the
	// generated Query, Args, and RenderedSQL of the next terminal operation.
	WithDryRun(collector ...*[]SQLStatement) Database[M]
	// WithoutHook disables model hooks for the operation.
	WithoutHook() Database[M]
}

type Decision struct {
	Allowed     bool
	Source      consts.GrantSource
	Reason      consts.DenyReason
	MatchedRule []string
}

type ESDocumenter interface {
	// Document returns a map representing an Elasticsearch document.
	// The returned map should contain all fields to be indexed, where:
	//   - keys are field names (string type)
	//   - values are field values (any type)
	//
	// Implementation notes:
	//   1. The returned map should only contain JSON-serializable values.
	//   2. Field names should match those defined in the Elasticsearch mapping.
	//   3. Complex types (like nested objects or arrays) should be correctly
	//      represented in the returned map.
	//
	// Example:
	//   return map[string]any{
	//       "id":    "1234",
	//       "title": "Sample Document",
	//       "tags":  []string{"tag1", "tag2"},
	//   }
	Document() map[string]any

	// GetID returns a string that uniquely identifies the document.
	// This ID is typically used as the Elasticsearch document ID.
	//
	// Implementation notes:
	//   1. The ID should be unique within the index.
	//   2. If no custom ID is needed, consider returning an empty string
	//      to let Elasticsearch auto-generate an ID.
	//   3. The ID should be a string, even if it's originally a numeric value.
	//
	// Example:
	//   return "user_12345"
	GetID() string
}

type Filter struct {
	Column string
	Op     FilterOp
	Value  any
}

type FilterOp string

type Having struct {
	Term  AggregateTerm
	Op    HavingOp
	Value any
}

type HavingOp string

type Logger interface {
	With(fields ...string) Logger

	WithContext(context.Context, consts.Phase) Logger

	StandardLogger
	StructuredLogger
	ZapLogger
}

type Model interface {
	TableName() string  // TableName returns the explicit table name; gorm's Tabler reads the same method.
	GetID() string      // GetID returns the string form of the id, or "" when the id is unset.
	SetID(id ...string) // SetID sets the id when unset; Base generates a UUID without an argument while AutoBase leaves generation to the database.
	ClearID()           // ClearID always set the id to empty.
	GetCreatedBy() string
	GetUpdatedBy() string
	GetCreatedAt() time.Time
	GetUpdatedAt() time.Time
	SetCreatedBy(string)
	SetUpdatedBy(string)
	SetCreatedAt(time.Time)
	SetUpdatedAt(time.Time)
	Expands() []string // Expands returns association paths that should be preloaded by default.
	Purge() bool       // Purge indicates whether to permanently delete records (hard delete). Default is false (soft delete).

	CreateBefore(context.Context) error
	CreateAfter(context.Context) error
	DeleteBefore(context.Context) error
	DeleteAfter(context.Context) error
	UpdateBefore(context.Context) error
	UpdateAfter(context.Context) error
	ListBefore(context.Context) error
	ListAfter(context.Context) error
	GetBefore(context.Context) error
	GetAfter(context.Context) error
}

type Module[M Model, REQ Request, RSP Response] interface {
	// Service returns the service instance that handles business logic for this module.
	Service() Service[M, REQ, RSP]

	// Route returns the base API path for this module's endpoints.
	Route() string

	// Pub determines whether the API endpoints are public or require authentication.
	Pub() bool

	// Param returns the URL parameter name used for resource identification.
	Param() string
}

type NumericColumn[T any] struct {
	Column[T]
}

type Order struct {
	Column    string
	Direction OrderDirection
}

type OrderDirection string

type Permission struct {
	// Object is the protected resource, usually a route path template such as
	// /api/things/{id}.
	Object string

	// Action is the operation on that object, usually an HTTP method.
	Action string
}

type QueryOptions struct {
	// AllowEmpty allows a query without any condition to match all records.
	// By default a nil model, a zero-value model, or all-empty field values
	// add the "1 = 0" safety condition instead, so a forgotten filter cannot
	// return or delete the whole table. RawQuery and Filters count as
	// real conditions and disable the safety check on their own.
	AllowEmpty bool

	// RawQuery is a raw parameterized SQL fragment added as an extra WHERE
	// condition. It works with a nil model and combines with model-field
	// conditions otherwise.
	RawQuery string

	// RawQueryArgs are the values bound to the RawQuery placeholders.
	RawQueryArgs []any

	// PresentFields marks columns whose filter values were explicitly provided
	// by the caller, keyed by snake case column name. Query construction treats
	// zero values (false, 0) of these columns as real conditions instead of
	// dropping them as unset, so a filter like "enabled=false" works. Columns
	// not listed here keep the default zero-value skip.
	PresentFields map[string]struct{}

	// Filters are field-level operator filters ("field[op]=value"). They
	// apply in every WithQuery path, including nil/empty model queries, so
	// List and Count stay consistent. A condition with an unknown operator
	// or empty column fails closed: query construction adds "1 = 0" instead
	// of dropping it.
	Filters []Filter
}

type RBAC interface {
	// Authorize reports whether subject may perform action on object inside
	// tenant, and what allowed it.
	//
	// Implementations should treat tenant as the authorization domain, subject as
	// the authenticated identity, object as the protected route or resource, and
	// action as the operation being checked, such as an HTTP method.
	//
	// The reason is answered alongside the decision rather than by a second
	// method. Deriving it costs a handful of allocations against the thousands
	// the decision itself takes, so a decision-only entry point would be a
	// second way to ask one question, distinguished by a saving too small to
	// measure.
	Authorize(ctx context.Context, tenant string, subject string, object string, action string) (Decision, error)

	// RemoveRole removes role from tenant, including its permission policies and
	// subject assignments. Callers should use this when deleting a role record so
	// authorization state does not retain stale grants.
	RemoveRole(ctx context.Context, tenant string, role string) error

	// SetRolePermissions replaces the entire permission set held by role inside
	// tenant with permissions, leaving the role's subject assignments untouched.
	//
	// It replaces rather than adds on purpose: the argument is the whole truth,
	// so an entry the caller drops stops allowing requests, and passing an empty
	// set revokes everything. A grant-only API would leave a removed entry
	// allowing requests forever, with nothing left in the source to show it.
	//
	// Implementations must apply the whole set as one step. Revoking and then
	// granting back one permission at a time exposes the role's members to an
	// empty or partial set while the replacement is in flight, which denies
	// requests the role is entitled to.
	//
	// It is the only way to write a role's permissions, which is why it takes
	// the whole set: an interface offering a single grant beside it would let a
	// caller build one up a row at a time and never learn that the entry it
	// dropped is still allowing requests.
	SetRolePermissions(ctx context.Context, tenant string, role string, permissions []Permission) error

	// SetPermissionsForAuthenticated replaces the entire set of permissions every
	// authenticated subject holds. The grant is bound to neither a tenant nor a
	// role, so it reaches subjects that hold no role at all, in every tenant.
	//
	// It is SetRolePermissions for the implicit role every authenticated subject
	// carries, and shares its contract: the argument is the whole truth, an empty
	// set revokes everything, and the whole set is applied as one step.
	//
	// Reserve it for objects that answer only about the caller and already narrow
	// their result to what the caller may see; anything else granted this way
	// becomes reachable by every subject that can log in. Unauthenticated requests
	// are unaffected, because authorization runs only after authentication.
	SetPermissionsForAuthenticated(ctx context.Context, permissions []Permission) error

	// AssignRole assigns subject to role inside tenant.
	// This creates tenant membership for subject and makes the role's
	// tenant-scoped permissions available to that subject.
	AssignRole(ctx context.Context, tenant string, subject string, role string) error

	// UnassignRole removes subject's assignment to role inside tenant.
	// Other roles held by the same subject in the same tenant are left unchanged.
	UnassignRole(ctx context.Context, tenant string, subject string, role string) error

	// RolesForSubject returns the roles subject holds inside tenant.
	//
	// It answers both questions the pair it replaced answered separately:
	// membership is a non-empty result, and holding one particular role is that
	// role being among them. Neither deserved an entry point of its own, and
	// keeping the general one leaves this and SubjectsInTenant as the two
	// directions of a single relation.
	RolesForSubject(ctx context.Context, tenant string, subject string) ([]string, error)

	// SubjectsInTenant returns subjects with at least one role assignment in
	// tenant. It checks membership, not whether any specific route is authorized.
	SubjectsInTenant(ctx context.Context, tenant string) ([]string, error)

	// AssignSystemRole assigns subject to a system-level role outside any tenant.
	// System roles are intended for cross-tenant framework privileges and should
	// not be used for ordinary tenant-local authorization.
	AssignSystemRole(ctx context.Context, subject string, role string) error

	// UnassignSystemRole removes subject's assignment to a system-level role.
	UnassignSystemRole(ctx context.Context, subject string, role string) error

	// HasSystemRole reports whether subject holds a system-level role.
	// This check is separate from Authorize because system roles are not scoped to
	// tenant route policies.
	HasSystemRole(ctx context.Context, subject string, role string) (bool, error)

	// RemoveSubject removes every role assignment held by subject, both
	// tenant-scoped and system-level, across all tenants. Use this when a
	// subject is deleted or deactivated so no orphaned role bindings remain.
	RemoveSubject(ctx context.Context, subject string) error

	// ReloadPolicies discards the authorization state the process holds in
	// memory and rebuilds it from storage.
	//
	// Implementations answer from memory and keep it in step as they write, so
	// the two agree as long as this process is the only writer. They stop
	// agreeing when the stored rules change behind its back: another replica
	// writing them, an operator repairing them by hand, a restore. Nothing
	// detects that on its own, so this is the lever that puts a process back
	// onto the stored state without restarting it.
	//
	// It reads every rule and is not part of the write path, which maintains
	// memory itself. Reserve it for recovery and for the moment a change is
	// known to have happened elsewhere.
	ReloadPolicies(ctx context.Context) error
}

type Request any

type Response any

type SQLStatement struct {
	// Query is the parameterized SQL with placeholders.
	Query string
	// Args contains the values bound to Query.
	Args []any
	// RenderedSQL is dialect-rendered SQL for logging, inspection, and manual debugging.
	RenderedSQL string
}

type Service[M Model, REQ Request, RSP Response] interface {
	Create(*ServiceContext, REQ) (RSP, error)
	Delete(*ServiceContext, REQ) (RSP, error)
	Update(*ServiceContext, REQ) (RSP, error)
	Patch(*ServiceContext, REQ) (RSP, error)
	List(*ServiceContext, REQ) (RSP, error)
	Get(*ServiceContext, REQ) (RSP, error)

	CreateMany(*ServiceContext, REQ) (RSP, error)
	DeleteMany(*ServiceContext, REQ) (RSP, error)
	UpdateMany(*ServiceContext, REQ) (RSP, error)
	PatchMany(*ServiceContext, REQ) (RSP, error)

	CreateBefore(*ServiceContext, M) error
	CreateAfter(*ServiceContext, M) error
	DeleteBefore(*ServiceContext, M) error
	DeleteAfter(*ServiceContext, M) error
	UpdateBefore(*ServiceContext, M) error
	UpdateAfter(*ServiceContext, M) error
	PatchBefore(*ServiceContext, M) error
	PatchAfter(*ServiceContext, M) error
	ListBefore(*ServiceContext, *[]M) error
	ListAfter(*ServiceContext, *[]M) error
	GetBefore(*ServiceContext, M) error
	GetAfter(*ServiceContext, M) error

	CreateManyBefore(*ServiceContext, ...M) error
	CreateManyAfter(*ServiceContext, ...M) error
	DeleteManyBefore(*ServiceContext, ...M) error
	DeleteManyAfter(*ServiceContext, ...M) error
	UpdateManyBefore(*ServiceContext, ...M) error
	UpdateManyAfter(*ServiceContext, ...M) error
	PatchManyBefore(*ServiceContext, ...M) error
	PatchManyAfter(*ServiceContext, ...M) error

	Import(*ServiceContext, io.Reader) ([]M, error)
	Export(*ServiceContext, ...M) ([]byte, error)

	// SSE streams Server-Sent Events for the route: the implementation opens
	// the stream via ServiceContext.SSE and blocks until it is over. Query
	// parameters are read from ServiceContext.Query(). The action never binds
	// Payload or Result types, so the method carries no REQ or RSP.
	SSE(*ServiceContext) error

	// Filter lets a service rewrite the query condition before the
	// controller-side listing runs (List and Export). The model carries the
	// URL-decoded equality condition and the options carry the parsed operator
	// filters; the typical use is row-level data scoping: append typed filters
	// (e.g. Cols.GroupID.In(...)) to options.Filters or narrow the model
	// condition, then return both. Returning an error aborts the request — the
	// correct behavior when loading the caller's data scope fails. The
	// controller calls Filter once and shares the result between List and
	// Count, so both always see the same condition set.
	Filter(*ServiceContext, M, QueryOptions) (M, QueryOptions, error)

	Logger
}

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

type StandardLogger interface {
	Debug(args ...any)
	Info(args ...any)
	Warn(args ...any)
	Error(args ...any)
	Fatal(args ...any)

	Debugf(format string, args ...any)
	Infof(format string, args ...any)
	Warnf(format string, args ...any)
	Errorf(format string, args ...any)
	Fatalf(format string, args ...any)
}

type StructuredLogger interface {
	Debugw(msg string, keysAndValues ...any)
	Infow(msg string, keysAndValues ...any)
	Warnw(msg string, keysAndValues ...any)
	Errorw(msg string, keysAndValues ...any)
	Fatalw(msg string, keysAndValues ...any)
}

type Subquery struct {
	// Model is an allocated instance of the related model. It carries the
	// child table name and its soft-delete scope, so a subquery hides the same
	// rows a List on that model hides.
	Model Model
	// Filters narrow the related rows. They must include a FilterCorrelate,
	// directly or inside a group: without one the subquery would be a cross
	// join, so it fails closed instead.
	Filters []Filter
	// Negate turns the condition into NOT EXISTS.
	Negate bool
}

type TimeBucket string

type TimeColumn struct {
	Column[time.Time]
}

type ZapLogger interface {
	Debugz(msg string, fields ...zap.Field)
	Infoz(msg string, fields ...zap.Field)
	Warnz(msg string, fields ...zap.Field)
	Errorz(msg string, fields ...zap.Field)
	Fatalz(msg string, fields ...zap.Field)
}