interfaces

type ActionAfterValidationFn = corecrud.AfterValidationSuccessFn[*DynamicEntity]

type ActionBeforeValidationFn = corecrud.BeforeValidationFn[*DynamicEntity]

type ActionResult = dyn.OpResult[any]

type ActionType string

type ActionValidateExtraFn = corecrud.UpdateValidateExtraFn[*DynamicEntity]

type ComputeFnRequest struct {
	// SchemaName and FieldName identify what is being computed, so one function can serve several
	// fields or several schemas.
	SchemaName string
	FieldName  string

	// Models are the rows to compute over: a page of rows on a read, exactly one on a
	// meta/compute call, where it is the unsaved model the client posted.
	Models []dmodel.DynamicFields

	// Args carries the caller-supplied extras of a meta/compute call. Nil on a read.
	Args map[string]any
}

type ComputedFieldFn func(ctx corectx.Context, req ComputeFnRequest) ([]any, error)

type CrudAction string

type DynamicActionDefinition struct {
	// ActionName is mandatory and unique within the engine.
	ActionName string

	// ActionType decides the HTTP method the REST engine registers this action under.
	// Mandatory as soon as RestPath is set, and ignored when the action is not exposed.
	ActionType ActionType

	// RestPath is the route path relative to the engine's RoutePath(), and may carry Echo
	// path params (":id"). An empty string means the resource base path itself.
	// Segments are [a-zA-Z0-9_]: the word separator is "_", hyphens are rejected.
	// Leave both this and ActionType unset to keep the action off the REST surface.
	RestPath string

	// RestHandler optionally replaces the generic handler. When set, it owns request
	// binding and response shaping, and the engine only registers the route for it.
	RestHandler echo.HandlerFunc

	// ParamSchema is optional. When provided, the pipeline validates params against it
	// before MainProcess runs. It does not gate the validator hooks below, which the crud
	// helper runs against the resource's own schema.
	ParamSchema func() *dmodel.ModelSchema

	// ValidateAsEdit runs the schema validation in "for edit" mode, which skips absent
	// fields and no-update fields. Set it for partial-update actions.
	ValidateAsEdit bool

	// KeysToFetch is optional. When provided, the engine fetches the identified record
	// and hands it to ValidateExtra as foundModel.
	KeysToFetch KeysToFetchFn

	// Permission is the action code to assert, e.g. "read", "create".
	// An empty string skips the permission check.
	Permission string

	// PermissionScope overrides the engine's default scope for this action only.
	PermissionScope *requestguard.ResourceScope

	// IsOrgScoped confines the action to one organization: the REST caller must supply
	// "?org_id=", the value must name an org the caller belongs to, and the action only ever
	// sees records of that org.
	//
	// A nil value means true. Org scoping is the default because the unsafe direction is the
	// silent one: an action that forgot to declare it would otherwise expose every org's rows
	// to anyone holding a grant. Opt out with util.ToPtr(false), and only for a resource that
	// genuinely has no owning org — schema metadata, or a resource with no org column at all.
	//
	// It has no effect on a resource whose schema declares no org_id field; such a resource
	// cannot be org-filtered and is left alone.
	IsOrgScoped *bool

	// PrimarySchema names the parent resource this action hangs off, and nests its REST route
	// under it:
	//
	//	/{PrimarySchema}/:{PrimaryRestIdParam}/{engine.RoutePath()}/{RestPath}
	//
	// so that the full path of a nested get-by-id reads
	// "/{primary-schema}/{primary-id}/{current-schema}/{current-id}".
	// Leave it nil for a top-level resource, which is the common case.
	PrimarySchema *string

	// PrimaryRestIdParam names the path parameter carrying the parent id, and is mandatory
	// whenever PrimarySchema is set. The value lands in the action params under this name.
	// Segments follow RestPathRegex: [a-zA-Z0-9_], the word separator is "_".
	PrimaryRestIdParam *string

	// The validator hooks. The definition is the single place they live: the service reads
	// them from here and passes them to the crud helper unchanged. There is no per-call way
	// to supply one, so what runs on a create is answerable by reading this definition alone.
	//
	// ModifyAction replaces these fields rather than chaining them, so a module attaching a
	// guard to an action that may already have one reads the existing hook first and calls it
	// from its own — see rejectArchivedOnCreate in inventory/dynamicengines.
	BeforeValidation       ActionBeforeValidationFn
	AfterValidationSuccess ActionAfterValidationFn
	ValidateExtra          ActionValidateExtraFn

	// MainProcess is mandatory.
	MainProcess DynamicActionProcessFn
}

type DynamicActionDelta struct {
	// ActionName is mandatory and must name an existing action.
	ActionName string

	// ActionType, RestPath and RestHandler are plain values: a zero value keeps the existing
	// one. Withdrawing an action from the REST surface is therefore not expressible through
	// a delta — routes are registered once at startup, so there is nothing to withdraw from.
	ActionType  ActionType
	RestPath    string
	RestHandler echo.HandlerFunc

	ParamSchema func() *dmodel.ModelSchema

	// ValidateAsEdit is a pointer so that overriding it back to false is expressible.
	ValidateAsEdit *bool

	KeysToFetch KeysToFetchFn

	// Permission is a pointer so that overriding it to "" (skip the check) is expressible.
	Permission *string

	PermissionScope *requestguard.ResourceScope

	// IsOrgScoped is a pointer for the same reason it is one on the definition: nil means
	// "keep what the action already declared", and util.ToPtr(false) withdraws org scoping.
	IsOrgScoped *bool

	PrimarySchema      *string
	PrimaryRestIdParam *string

	BeforeValidation       ActionBeforeValidationFn
	AfterValidationSuccess ActionAfterValidationFn
	ValidateExtra          ActionValidateExtraFn
	MainProcess            DynamicActionProcessFn
}

type DynamicActionProcessFn func(ctx corectx.Context, input ProcessInput) (*ActionResult, error)

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

type DynamicResourceEngine interface {
	// ResourceName is the dynamic-model schema name this engine serves, e.g. "iam_user".
	// It doubles as the permission resource code and as the REST route path segment.
	ResourceName() string

	Schema() *dmodel.ModelSchema

	// RoutePath is the REST path segment, defaulting to ResourceName().
	RoutePath() string
	SetRoutePath(path string)

	// DefaultPermissionScope applies to actions that declare no PermissionScope.
	DefaultPermissionScope() requestguard.ResourceScope
	SetDefaultPermissionScope(scope requestguard.ResourceScope)

	RestApi() DynamicRestApi
	ResourceService() DynamicResourceService
	ResourceRepository() DynamicResourceRepository

	SetRestApi(restApi DynamicRestApi)
	SetResourceService(service DynamicResourceService)
	SetResourceRepository(repository DynamicResourceRepository)

	// DefineAction registers a new action. It fails when the action name is already taken,
	// or when a mandatory field of the definition is missing.
	DefineAction(definition DynamicActionDefinition) error

	// DefineComputedFieldFunction registers the Go implementation of a "function"-kind computed
	// field. The name must match the schema's computed declaration; a schema naming a function no
	// engine defines fails AssertComputedFunctionsDefined at boot rather than at first read.
	//
	// It fails when the name is empty or already registered on this engine.
	DefineComputedFieldFunction(name string, fn ComputedFieldFn) error

	// ComputedFieldFunction returns the registered implementation, if any.
	ComputedFieldFunction(name string) (ComputedFieldFn, bool)

	// AssertComputedFunctionsDefined reports every "function"-kind computed field of this
	// engine's schema whose function was never registered. Called once at startup, after modules
	// have had their chance to register — an engine is built before its module's Init body runs,
	// so this cannot be a construction-time check.
	AssertComputedFunctionsDefined() error

	// ModifyAction overrides fields of an already defined action.
	// It fails when the named action does not exist.
	ModifyAction(delta DynamicActionDelta) error

	// Action returns a copy of the named action definition.
	Action(actionName string) (DynamicActionDefinition, bool)

	// ActionNames lists every defined action name.
	ActionNames() []string

	// ExecuteAction runs the full pipeline of the named action: org scoping, permission
	// check, ParamSchema validation, key fetching, main process.
	//
	// The validator hooks are not part of it. They run inside the crud helper the resource
	// service delegates to, so they fire on a direct service call too.
	ExecuteAction(ctx corectx.Context, actionName string, params dmodel.DynamicFields) (*ActionResult, error)
}

type DynamicResourceEngineRegistry interface {
	// NewEngine creates and registers an engine for the given dynamic-model schema name.
	// It fails when the schema is unknown or an engine for it already exists.
	// Only the first NewEngineOptions is used, the rest are ignored.
	NewEngine(schemaName string, options ...NewEngineOptions) (DynamicResourceEngine, error)

	// GetEngine returns the engine registered for the given schema name.
	GetEngine(schemaName string) (DynamicResourceEngine, bool)

	// MustGetEngine is GetEngine that panics when the engine is missing.
	MustGetEngine(schemaName string) DynamicResourceEngine

	// AllEngines returns every registered engine.
	AllEngines() []DynamicResourceEngine
}

type DynamicResourceRepository interface {
	// Embedding this interface lets the repository be passed directly to the generic
	// helpers of modules/core/dynamicmodel/crud, which expect a dyn.DynamicModelRepository.
	dyn.DynamicModelRepository

	BeginTransaction(ctx corectx.Context) (database.DbTransaction, error)

	Insert(ctx corectx.Context, data dmodel.DynamicFields) (*dyn.OpResult[int], error)
	Update(ctx corectx.Context, data dmodel.DynamicFields) (*dyn.OpResult[dyn.MutateResultData], error)
	DeleteOne(ctx corectx.Context, keys dmodel.DynamicFields) (*dyn.OpResult[dyn.MutateResultData], error)

	// FindByKeys fetches the single record identified by the given primary or unique keys.
	FindByKeys(ctx corectx.Context, keys dmodel.DynamicFields) (*dyn.OpResult[dmodel.DynamicFields], error)

	GetOne(ctx corectx.Context, param dyn.RepoGetOneParam) (*dyn.OpResult[dmodel.DynamicFields], error)
	Search(ctx corectx.Context, param dyn.RepoSearchParam) (*dyn.OpResult[dyn.PagedResultData[dmodel.DynamicFields]], error)
	Exists(ctx corectx.Context, keys []dmodel.DynamicFields) (*dyn.OpResult[dyn.RepoExistsResult], error)
}

type DynamicResourceService interface {
	Create(ctx corectx.Context, params dmodel.DynamicFields) (*dyn.OpResult[dmodel.DynamicFields], error)
	Update(ctx corectx.Context, params dmodel.DynamicFields) (*dyn.OpResult[dyn.MutateResultData], error)
	Delete(ctx corectx.Context, params dmodel.DynamicFields) (*dyn.OpResult[dyn.MutateResultData], error)
	SetArchived(ctx corectx.Context, params dmodel.DynamicFields) (*dyn.OpResult[dyn.MutateResultData], error)

	// GetById fetches one record by primary key. Params carry "id" and optional "fields".
	GetById(ctx corectx.Context, params dmodel.DynamicFields) (*dyn.OpResult[dyn.SingleResultData[dmodel.DynamicFields]], error)

	// GetOne fetches one record by any unique key carried in params.
	GetOne(ctx corectx.Context, params dmodel.DynamicFields) (*dyn.OpResult[dyn.SingleResultData[dmodel.DynamicFields]], error)

	Search(ctx corectx.Context, params dmodel.DynamicFields) (*dyn.OpResult[dyn.PagedResultData[dmodel.DynamicFields]], error)
	Exists(ctx corectx.Context, params dmodel.DynamicFields) (*dyn.OpResult[dyn.ExistsResultData], error)

	// Schema is the dynamic-model schema this service operates on.
	Schema() *dmodel.ModelSchema
}

type DynamicRestApi interface {
	// RegisterRoutes adds every endpoint of the resource to the given route group.
	RegisterRoutes(route *echo.Group, middlewares ...echo.MiddlewareFunc)
}

type KeysToFetchFn func(params dmodel.DynamicFields) dmodel.DynamicFields

type NewEngineOptions struct {
	// CrudActions selects which built-in CRUD actions this engine defines.
	// Nil or empty means all of them, so the zero value keeps the default behavior.
	//
	// An action left out is not registered as a REST route, and the resource service
	// refuses it when invoked directly.
	CrudActions []CrudAction

	// DefaultSearchFields is the field list a search returns when it specifies neither
	// fields nor a resolvable view. When empty, every column of the schema is returned.
	//
	// Primary key fields are always included by the query builder, so listing them here
	// is redundant.
	DefaultSearchFields []string
}

type ProcessInput struct {
	Params dmodel.DynamicFields

	// FoundModel is the record the action's KeysToFetch identified, already fetched by the
	// pipeline. It is nil when the action declares no KeysToFetch, and when the record does
	// not exist.
	//
	// It exists so that a MainProcess needing the record does not re-read a row the pipeline
	// has already read on its behalf.
	FoundModel *dmodel.DynamicFields

	// ResourceService is the engine's service subengine. A module that installed its own
	// extended service via Engine.SetResourceService type-asserts this to its own interface.
	ResourceService DynamicResourceService

	// ResourceRepository is the engine's repository subengine, for actions that need
	// direct database access without going through the service.
	ResourceRepository DynamicResourceRepository
}