(*---------------------------------------------------------------------------
   Copyright (c) 2025 Thomas Gazagnaire. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** Forwarding engine for DTN bundles.

    The engine coordinates bundle processing: receiving bundles, evaluating
    policies, storing bundles, and triggering forwarding when contacts become
    available. *)

(** {1 Engine Configuration} *)

type config = {
  local_node : Cgr.Node.t;
  local_eid : Bundle.eid;
  admin_eid : Bundle.eid;  (** Typically ipn:NODE.0 *)
}
(** Engine configuration. *)

val make_config : node_id:int64 -> config
(** [make_config ~node_id] creates a config for node [ipn:node_id.*]. *)

(** {1 Engine State} *)

type t
(** The forwarding engine. *)

val create :
  config:config -> policy:Policy.t -> contact_plan:Cgr.Contact_plan.t -> t
(** [create ~config ~policy ~contact_plan] creates a new engine. *)

val config : t -> config
(** [config t] returns the engine's configuration. *)

val store : t -> Store.t
(** [store t] returns the bundle store. *)

val contact_plan : t -> Cgr.Contact_plan.t
(** [contact_plan t] returns the current contact plan. *)

val set_contact_plan : t -> Cgr.Contact_plan.t -> unit
(** [set_contact_plan t plan] updates the contact plan. *)

val policy : t -> Policy.t
(** [policy t] returns the current policy. *)

val set_policy : t -> Policy.t -> unit
(** [set_policy t policy] updates the routing policy. *)

(** {1 Bundle Processing} *)

type forward_request = {
  bundle : Bundle.t;
  next_hop : Bundle.eid;
  via : Action.cla option;
}
(** A request to forward a bundle. *)

type process_result =
  | Forward of forward_request list
  | Stored
  | Delivered
  | Dropped of string
  | Admin_handled  (** Result of processing a bundle. *)

val process : t -> Bundle.t -> tenant:Delegation.Name.t option -> process_result
(** [process t bundle ~tenant] processes an incoming bundle according to policy.
*)

val process_admin : t -> Admin.t -> Admin.t option
(** [process_admin t record] handles an admin record, returning a response if
    needed. *)

(** {1 Contact Events} *)

val on_contact_start : t -> Cgr.Contact.t -> forward_request list
(** [on_contact_start t contact] is called when a contact becomes active.
    Returns bundles ready to forward on this contact. *)

val on_contact_end : t -> Cgr.Contact.t -> unit
(** [on_contact_end t contact] is called when a contact ends. *)

(** {1 Periodic Tasks} *)

val cleanup_expired : t -> current_time:float -> int
(** [cleanup_expired t ~current_time] removes expired bundles. Returns count
    removed. *)

val check_routes : t -> forward_request list
(** [check_routes t] checks for bundles that now have routes available. *)

(** {1 Statistics} *)

type stats = {
  bundles_received : int;
  bundles_forwarded : int;
  bundles_delivered : int;
  bundles_dropped : int;
  admin_handled : int;
}
(** Engine statistics. *)

val stats : t -> stats
(** [stats t] returns engine statistics. *)

val pp_stats : stats Fmt.t
(** Pretty-printer for stats. *)