package reconciler

// Reconcilable objects carry status
type Reconcilable[Obj comparable] interface {
  comparable
  GetStatus() Status
  WithStatus(Status) Obj
}

// Reconciliation target defines the operations for reconciling a single
// object.
type Target[Obj Reconcilable[Obj]] interface {
  Init(context.Context) error
  Update(context.Context, Obj) error
  Delete(context.Context, Obj) error
  Sync(context.Context, statedb.Iterator[Obj]) (outOfSync bool, err error)
}

type params[Obj Reconcilable[Obj]] struct {
  cell.In

  // ... other dependencies ...

  // Dependencies that parametrize the reconciler for the concrete
  // use case:
  Config
  Target Target[Obj]
  StatusIndex statedb.Index[Obj, StatusKind]
}

// Register creates a reconciler and adds it to the application lifecycle.
// "cell.Invoke(reconciler.Register[MyObject])".
func Register[Obj Reconcilable[Obj]](p params[Obj]) { ... }
  

package example

// Define the object that presents the desired state.
type MyObject struct { ... }
func (m *MyObject) GetStatus() reconciler.Status { ... }
func (m *MyObject) WithStatus(s reconciler.Status) *MyObject { /* copy and set status */ }
var statusIndex = reconciler.NewStatusIndex[*MyObject]()
var idIndex = statedb.Index[*MyObject, UUID]{...}

// Define a safe API for managing the desired state. Alternatively if it's obvious
// the RWTable[*MyObject] could be directly exposed.
// (TODO: Not sure at all if we want to call these sort of things managers)
type MyObjectManager struct {...}
func (m *MyObjectManager) Set(...) error {}
func (m *MyObjectManager) Get(...) error {}
func (m *MyObjectManager) Wait(context.Context) error { 
  // see example/sysctl.go for how we can wait for reconciliation.
}
func newMyObjectManager(db *statedb.DB, table statedb.RWTable[*MyObject) *MyObjectManager { ... }

var Cell = cell.Module(
  "my-module", 
  "There are many like it, but this one is mine",

  // Create the table for the desired state. Keep write access protected to this module.
  statedb.NewProtectedTableCell[*MyObject]("my-objects", idIndex, statusIndex),

  // Provide a public API for managing the desired state to the rest of the application.
  cell.Provide(newMyObjectManager),

  // Provide the reconciler dependencies, but scoped to just this module.
  cell.ProvidePrivate(
    func() reconciler.Target[*MyObject] { return &myObjectTarget{} },
    func() reconciler.Config { ...},
    func() statedb.Index[*MyObject, reconciler.StatusKind] { return statusIndex },
  ),

  // Create and register the reconciler to the application lifecycle. 
  cell.Invoke(reconciler.Register[*MyObject]),
)

type myObjectTarget struct { ... }
func (r *myObjectTarget) Init(context.Context) error { ... }
func (r *myObjectTarget) Update(context.Context, Obj) error { ... }
func (r *myObjectTarget) Delete(context.Context, Obj) error { ... }
func (r *myObjectTarget) Sync(context.Context, statedb.Iterator[Obj]) (outOfSync bool, err error) { .. }

Status{ModuleID: iptables, Level: Degraded, Since: 3.000499163s ago, Message: Incremental reconciliation failure, Err: oops iptables error}

# HELP cilium_reconciler_full_duration_seconds Histogram over full reconciliation duration
# TYPE cilium_reconciler_full_duration_seconds histogram
cilium_reconciler_full_duration_seconds_bucket{module_id="sysctl",le="0.005"} 1
# ...
cilium_reconciler_full_duration_seconds_sum{module_id="sysctl"} 6.0364e-05
cilium_reconciler_full_duration_seconds_count{module_id="sysctl"} 1
# HELP cilium_reconciler_full_total Number of full reconciliations performed
# TYPE cilium_reconciler_full_total counter
cilium_reconciler_full_total{module_id="sysctl"} 1
# HELP cilium_reconciler_incremental_duration_seconds Histogram of per-operation duration during incremental reconciliation
# TYPE cilium_reconciler_incremental_duration_seconds histogram
cilium_reconciler_incremental_duration_seconds_bucket{module_id="iptables",le="0.005"} 4
# ...
cilium_reconciler_incremental_duration_seconds_sum{module_id="iptables"} 9.6464e-05
cilium_reconciler_incremental_duration_seconds_count{module_id="iptables"} 4
cilium_reconciler_incremental_duration_seconds_bucket{module_id="sysctl",le="0.005"} 14
# ...
cilium_reconciler_incremental_duration_seconds_sum{module_id="sysctl"} 0.0009456850000000001
cilium_reconciler_incremental_duration_seconds_count{module_id="sysctl"} 14
# HELP cilium_reconciler_incremental_errors_current The number of objects currently failing to be reconciled
# TYPE cilium_reconciler_incremental_errors_current gauge
cilium_reconciler_incremental_errors_current{module_id="iptables"} 1
cilium_reconciler_incremental_errors_current{module_id="sysctl"} 0
# HELP cilium_reconciler_incremental_errors_total Total number of errors encountered during incremental reconciliation
# TYPE cilium_reconciler_incremental_errors_total counter
cilium_reconciler_incremental_errors_total{module_id="iptables"} 4
cilium_reconciler_incremental_errors_total{module_id="sysctl"} 4
# HELP cilium_reconciler_incremental_total Number of incremental reconciliations performed
# TYPE cilium_reconciler_incremental_total counter
cilium_reconciler_incremental_total{module_id="iptables"} 4
cilium_reconciler_incremental_total{module_id="sysctl"} 15