gazagnaire.org
DTN controller and policy language for satellite networks
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Thomas Gazagnaire. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Forwarding engine for DTN bundles.
7
8 The engine coordinates bundle processing: receiving bundles, evaluating
9 policies, storing bundles, and triggering forwarding when contacts become
10 available. *)
11
12(** {1 Engine Configuration} *)
13
14type config = {
15 local_node : Cgr.Node.t;
16 local_eid : Bundle.eid;
17 admin_eid : Bundle.eid; (** Typically ipn:NODE.0 *)
18}
19(** Engine configuration. *)
20
21val make_config : node_id:int64 -> config
22(** [make_config ~node_id] creates a config for node [ipn:node_id.*]. *)
23
24(** {1 Engine State} *)
25
26type t
27(** The forwarding engine. *)
28
29val create :
30 config:config -> policy:Policy.t -> contact_plan:Cgr.Contact_plan.t -> t
31(** [create ~config ~policy ~contact_plan] creates a new engine. *)
32
33val config : t -> config
34(** [config t] returns the engine's configuration. *)
35
36val store : t -> Store.t
37(** [store t] returns the bundle store. *)
38
39val contact_plan : t -> Cgr.Contact_plan.t
40(** [contact_plan t] returns the current contact plan. *)
41
42val set_contact_plan : t -> Cgr.Contact_plan.t -> unit
43(** [set_contact_plan t plan] updates the contact plan. *)
44
45val policy : t -> Policy.t
46(** [policy t] returns the current policy. *)
47
48val set_policy : t -> Policy.t -> unit
49(** [set_policy t policy] updates the routing policy. *)
50
51(** {1 Bundle Processing} *)
52
53type forward_request = {
54 bundle : Bundle.t;
55 next_hop : Bundle.eid;
56 via : Action.cla option;
57}
58(** A request to forward a bundle. *)
59
60type process_result =
61 | Forward of forward_request list
62 | Stored
63 | Delivered
64 | Dropped of string
65 | Admin_handled (** Result of processing a bundle. *)
66
67val process : t -> Bundle.t -> tenant:Delegation.Name.t option -> process_result
68(** [process t bundle ~tenant] processes an incoming bundle according to policy.
69*)
70
71val process_admin : t -> Admin.t -> Admin.t option
72(** [process_admin t record] handles an admin record, returning a response if
73 needed. *)
74
75(** {1 Contact Events} *)
76
77val on_contact_start : t -> Cgr.Contact.t -> forward_request list
78(** [on_contact_start t contact] is called when a contact becomes active.
79 Returns bundles ready to forward on this contact. *)
80
81val on_contact_end : t -> Cgr.Contact.t -> unit
82(** [on_contact_end t contact] is called when a contact ends. *)
83
84(** {1 Periodic Tasks} *)
85
86val cleanup_expired : t -> current_time:float -> int
87(** [cleanup_expired t ~current_time] removes expired bundles. Returns count
88 removed. *)
89
90val check_routes : t -> forward_request list
91(** [check_routes t] checks for bundles that now have routes available. *)
92
93(** {1 Statistics} *)
94
95type stats = {
96 bundles_received : int;
97 bundles_forwarded : int;
98 bundles_delivered : int;
99 bundles_dropped : int;
100 admin_handled : int;
101}
102(** Engine statistics. *)
103
104val stats : t -> stats
105(** [stats t] returns engine statistics. *)
106
107val pp_stats : stats Fmt.t
108(** Pretty-printer for stats. *)