migration

type Group[R any] struct {
	// ID field within the Group specifically denotes the intended domain or area, such as "foo-queue",
	// ensuring that migration steps within this group are uniquely identified and do not overlap
	// or interfere with migrations from other namespaces.
	ID string
	// Steps field is an ordered list of individual migration actions,
	// each capable of migrating up or down (applying or rolling back changes).
	// The generic type parameter `R` allows the migration steps to work with a shared resource,
	// which could be something like a live database connection or a transaction object.
	// This design provides flexibility and consistency,
	// ensuring that all steps in a given migration group have access to necessary shared resources.
	Steps []Step[R]
}

type Migratable interface {
	Migrate(context.Context) error
}

type Migrator[R resourceConnection] struct {
	// Resource is the ResourceConnection where the migration steps needs to operate.
	Resource R
	// Namespace field denotes the intended domain or area, such as "foo-repository",
	// ensuring that migration steps are uniquely identified
	// and do not interfere with migrations from other namespaces.
	Namespace string
	// Steps field is an ordered list of individual migration actions,
	// each capable of migrating up or down (applying or rolling back changes).
	// The generic type parameter `R` allows the migration steps to work with a shared resource,
	// which could be something like a live database connection or a transaction object.
	// This design provides flexibility and consistency,
	// ensuring that all steps in a given migration group have access to necessary shared resources.
	Steps Steps[R]
	// StateRepository is the crud resource that contains the state of the migration steps.
	// The state repository doesn't have to be the same as the actual resource which is being managed.
	StateRepository StateRepository
	// EnsureStateRepository is an optional field that is guaranteed to be called before each migration.
	// If your StateRepository is not needing this, because it creates itself upon interaction,
	// then just leave this unset.
	//
	// EnsureStateRepository should be an idempotent function,
	// calling it multiple times should result at the same final state.
	EnsureStateRepository func(context.Context) error
}

type State struct {
	ID StateID `ext:"id"`
	// Dirty will tells if the given migration step's state
	Dirty bool
}

type StateID struct {
	Namespace string
	Version   Version
}

type StateRepository interface {
	comproto.OnePhaseCommitProtocol
	crud.Creator[State]
	crud.ByIDFinder[State, StateID]
	crud.ByIDDeleter[StateID]
}

type Step[R any] interface {
	// MigrateUp applies the specific migration action associated with this step.
	// It is assumed that this step has not been executed prior to this invocation.
	//
	// Upon failure, it is up to the Migrator to undo the resources changes
	MigrateUp(R, context.Context) error
	// MigrateDown reverses the changes made by the corresponding MigrateUp action.
	// It is assumed that MigrateUp was successfully executed before calling this method.
	MigrateDown(R, context.Context) error
}

type Steps[R any] map[Version]Step[R]

type Version string