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(** DTN-native administrative records for borealis control.
7
8 Instead of gRPC, borealis uses Bundle Protocol administrative records for
9 control plane messages. This provides:
10 - Single protocol for control and data
11 - Store-and-forward tolerance
12 - BPSec authentication
13 - Compact CBOR encoding
14
15 Admin bundles are sent to the node's admin endpoint ([ipn:NODE.0]). *)
16
17(** {1 Admin Record Types} *)
18
19type status = {
20 node_id : Bundle.eid;
21 uptime_secs : float;
22 bundles_stored : int;
23 bundles_forwarded : int;
24 bundles_delivered : int;
25 bundles_dropped : int;
26 active_contacts : int;
27}
28(** Node status information. *)
29
30type contact = {
31 from_node : string;
32 to_node : string;
33 start_time : float;
34 stop_time : float;
35 rate_bps : float;
36 owlt_secs : float;
37}
38(** A scheduled contact. *)
39
40type contact_plan = { contacts : contact list }
41(** A contact plan update. *)
42
43type config_delta = {
44 key : string;
45 value : string option; (** None means delete *)
46}
47(** Configuration change. *)
48
49type query =
50 | Query_status
51 | Query_contacts
52 | Query_policy
53 | Query_bundles of { filter : string option } (** Query types. *)
54
55type response =
56 | Response_status of status
57 | Response_contacts of contact_plan
58 | Response_policy of { source : string }
59 | Response_bundles of { count : int; bundle_ids : string list }
60 | Response_error of { code : int; message : string } (** Query responses. *)
61
62type t =
63 | Status_report of status
64 | Policy_update of { compiled : string; source : string }
65 | Contact_update of contact_plan
66 | Config_update of config_delta list
67 | Query of query
68 | Response of response (** Administrative record types. *)
69
70(** {1 CBOR Schema} *)
71
72val codec : t Cbort.t
73(** CBOR codec for admin records. *)
74
75(** {1 Encoding/Decoding} *)
76
77val encode : t -> string
78(** [encode record] encodes to CBOR bytes. *)
79
80val decode : string -> (t, string) result
81(** [decode bytes] decodes from CBOR bytes. *)
82
83(** {1 Bundle Creation} *)
84
85val make_bundle :
86 source:Bundle.eid ->
87 destination:Bundle.eid ->
88 timestamp:Bundle.timestamp ->
89 t ->
90 Bundle.t
91(** [make_bundle ~source ~destination ~timestamp record] creates an admin bundle
92 containing [record]. *)
93
94val extract : Bundle.t -> (t, string) result
95(** [extract bundle] extracts the admin record from an admin bundle. *)
96
97val is_admin_bundle : Bundle.t -> bool
98(** [is_admin_bundle bundle] returns true if this is an admin bundle. *)
99
100(** {1 Utilities} *)
101
102val pp : t Fmt.t
103(** Pretty-printer. *)
104
105val pp_status : status Fmt.t
106val pp_contact : contact Fmt.t
107val pp_query : query Fmt.t
108val pp_response : response Fmt.t