dbhook

type ChildDelete[In any, Out any] struct {
	// Child names the table the hooks came from, so a refusal can say which
	// relation blocked the delete rather than naming none.
	Child string

	// Deleting runs inside the transaction, before the parent row is touched.
	// Returning an error refuses the delete and unwinds every child that ran
	// before it.
	Deleting func(ctx context.Context, claims tenancy.Claims, parent *Out, in In) error

	// Deleted runs once the outermost transaction has committed, in the same
	// order Deleting ran. It returns nothing: there is no longer anything to
	// fail.
	Deleted func(ctx context.Context, claims tenancy.Claims, parent *Out, in In)
}

type Create[In any, Out any] struct {
	Input In
	Hooks CreateHooks[In, Out]
}

type CreateHooks[In any, Out any] struct {
	// Validator holds the rules the schema cannot express. The generated
	// checks run first and separately, so a rule here is about the business
	// rather than about NOT NULL.
	Validator CreateValidator[In]

	// Before runs after validation and before the INSERT. Changes it makes to
	// the input are written.
	Before func(ctx context.Context, claims tenancy.Claims, in *In) error

	// After runs after the INSERT with the row as it was stored, including
	// everything the database filled in.
	After func(ctx context.Context, claims tenancy.Claims, created *Out) error

	// AfterCommit runs once the work has actually landed. It returns nothing:
	// there is no longer anything to fail, and a panic is contained rather than
	// allowed to unwind a request that succeeded.
	AfterCommit func(ctx context.Context, claims tenancy.Claims, created *Out)
}

type CreateValidator[In any] interface {
	RunCreate(ctx context.Context, claims tenancy.Claims, in *In) error
}

type Delete[In any, Out any] struct {
	Input In
	Hooks DeleteHooks[In, Out]
}

type DeleteHooks[In any, Out any] struct {
	// Before runs after the row is read and before it is retired or removed.
	Before func(ctx context.Context, claims tenancy.Claims, in *In, prev *Out) error

	// Children are the tables that point at this one, each with whatever it
	// wants to happen when one of its parents goes away.
	//
	// They run after Before and before the row is touched, in the order rig
	// derived — see the resource's own writer, which assembles this list. The
	// parent's own veto comes first on purpose: "this team may not be deleted
	// while the season is open" is the cheapest and most specific rule in the
	// building, and it should not require running every child's cleanup before
	// it gets to say so.
	//
	// A generated writer fills this in. Setting it by hand is possible and is
	// not the intended path: what belongs to the application is the function on
	// the child, not the wiring that finds it.
	Children []ChildDelete[In, Out]

	// After runs after the delete, with the row as it was.
	After func(ctx context.Context, claims tenancy.Claims, prev *Out) error

	// AfterCommit runs once the deletion has landed.
	AfterCommit func(ctx context.Context, claims tenancy.Claims, prev *Out)
}

type ReadHooks[Filter any, Out any] struct {
	// Narrow returns conditions every filtered read is limited to, or nil for
	// none.
	//
	// It returns a filter rather than editing the caller's, and the difference
	// matters: the two are combined with AND, so a caller whose own filter is
	// an OR cannot widen its way out of this one. Editing theirs in place could
	// not promise that.
	//
	// Get is not filtered — it fetches by primary key — so this does not apply
	// to it. Nor does it apply to the read a write makes to find its row: a
	// rule about which rows exist for a caller at all is what the tenant column
	// is for, and this is a view on top of that.
	Narrow func(ctx context.Context, claims *tenancy.Claims) (*Filter, error)

	// Rows runs on what a read is about to answer with, whether that is a page
	// of them or the single row a Get found.
	//
	// One call per read rather than one per row, so a hook that has to look
	// something up can do it once. Returning an error fails the read.
	Rows func(ctx context.Context, claims *tenancy.Claims, rows []*Out) error
}

type Restore[In any, Out any] struct {
	Input In
	Hooks RestoreHooks[In, Out]
}

type RestoreHooks[In any, Out any] struct {
	// Validator holds the rules the row has to satisfy to be live again. It
	// runs on whatever Before settled on.
	Validator RestoreValidator[In, Out]

	// Before is where a restore's values come from.
	//
	// It is handed the row as it was retired and an empty input. Setting a
	// field on that input writes it as the row comes back, which is how a value
	// the world has taken since gets changed on the way in:
	//
	//	if taken { in.Title = patch.NewOptional(prev.Title + " (restored)") }
	//
	// Returning an error refuses the restore instead. Which of the two to do is
	// the application's call, which is why this is a hook and not a rule.
	Before func(ctx context.Context, claims tenancy.Claims, in *In, prev *Out) error

	// After runs after the restore, with the live row and the state it was
	// restored from.
	After func(ctx context.Context, claims tenancy.Claims, restored, prev *Out) error

	// AfterCommit runs once the restore has landed.
	AfterCommit func(ctx context.Context, claims tenancy.Claims, restored, prev *Out)
}

type RestoreValidator[In any, Out any] interface {
	RunRestore(ctx context.Context, claims tenancy.Claims, in *In, prev *Out) error
}

type Update[In any, Out any] struct {
	Input In
	Hooks UpdateHooks[In, Out]
}

type UpdateHooks[In any, Out any] struct {
	// Validator holds the rules the schema cannot express. It is a different
	// type from the one a create takes: whether a row may exist is not whether
	// it may change, and an update cannot touch an immutable column at all.
	//
	// It runs after Before, so what it judges is the row as it will be written
	// rather than as it arrived.
	Validator UpdateValidator[In, Out]

	// Before runs first, before validation and before the UPDATE. Changes it
	// makes to the input are written — including to fields the request did not
	// mention, since setting a patch is what makes a column part of the
	// statement — and are then judged by the rules like anything else.
	Before func(ctx context.Context, claims tenancy.Claims, in *In, prev *Out) error

	// After runs after the UPDATE, with the new row and the old one.
	After func(ctx context.Context, claims tenancy.Claims, updated, prev *Out) error

	// AfterCommit runs once the change has landed.
	AfterCommit func(ctx context.Context, claims tenancy.Claims, updated, prev *Out)
}

type UpdateValidator[In any, Out any] interface {
	RunUpdate(ctx context.Context, claims tenancy.Claims, in *In, prev *Out) error
}