Skip to content

Commit 7d83eb0

Browse files
committed
core: register a dApp with the RAN again when it lost the RAN
A libe3 dApp that was released by the RAN, or lost its connection to it, reported the disconnect and then stayed down until the program called stop() and start(). Aerial's manager runs setup again every second until it works (#121). A RAN that releases a quiet dApp (#93) would otherwise leave every such dApp down. A dApp started with start() now has a thread that, after E3Config::reconnect_interval_ms (default 1000, 0 is off), stops and starts the interface again, and again every interval until the RAN answers. The cases are: * the RAN released the dApp, or the connection was lost: the disconnect handler runs first, as before; * setup did not finish or the RAN refused it, including a dApp that was started before any RAN was up; * a restart that fails because the RAN cannot be reached asks again; * a dApp whose inbound or outbound connection cannot be made because the RAN left first: those threads ended with a log line and the dApp never noticed that the RAN was gone, so nothing would have brought it back. It reports CONNECTION_LOST now. The same gap made test_dapp_ran_loss fail now and then on the POSIX link, whenever the RAN stopped before the dApp had connected. The new session has a new dApp id and none of the old subscriptions. The application subscribes again; it learns the dApp is back from the setup response handler, which runs on every setup. A dApp that called release(), and one that called stop(), are not restarted, and stop() does not wait for a RAN. start() and stop() keep their meaning: they are now the locked halves start_locked() and stop_locked() behind one lock, which the reconnect thread takes to restart, so a restart cannot overlap a call of the application. stop() joins the reconnect thread before it takes that lock. test_dapp_ran_loss and test_dapp_idle_e2e set the interval to 0: the first restarts the dApp by hand, the second counts dApps on the RAN. Specification and guide: 03 and 05 say a dApp may run Setup again after a release or a lost link, with a new identifier and no subscriptions; the integrator guide gets the row and its pointers; the Word edition is rebuilt. README and swig/README.md name reconnect_interval_ms and set_disconnect_handler, and the handler's comment and the example say the library registers again. The interop page replaces "the dApp does not reconnect", says what a dApp sees against OCUDU's 30 s idle close, and gets a ledger row. Tests: a dApp registers with a new RAN on ZeroMQ and POSIX without stop() and start(), hears of it, and can subscribe; one released for being idle is told RELEASED_BY_RAN and comes back; one started before any RAN registers when one comes up; one that released itself stays released; stop() ends the retrying quickly; 0 keeps the dApp down. Assisted-by: Claude:claude-sonnet-5-5 Signed-off-by: Thecave3 <thecave003@gmail.com>
1 parent a7f00b8 commit 7d83eb0

17 files changed

Lines changed: 539 additions & 38 deletions

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -382,6 +382,7 @@ The single entry-point class for both roles. Configure `E3Config.role = E3Role::
382382
| `set_setup_response_handler(handler)` | (dApp) Callback for incoming `SetupResponse` |
383383
| `set_xapp_control_handler(handler)` | (dApp) Callback for incoming `XAppControlAction` |
384384
| `set_message_ack_handler(handler)` | (dApp) Callback for incoming `MessageAck` |
385+
| `set_disconnect_handler(handler)` | (dApp) Callback when the RAN released the dApp or the connection to it was lost. The dApp then registers again by itself unless `reconnect_interval_ms` is 0 |
385386
| `wait_for_setup(timeout)` | (dApp) Block until setup handshake completes |
386387
| `subscribe(ran_function_id, telemetry, control, ...)` | (dApp) Subscribe to a RAN function |
387388
| `unsubscribe(ran_function_id)` | (dApp) Tear down a subscription |
@@ -417,6 +418,7 @@ for local development (IPC) or production deployments.
417418
| `recv_timeout_ms` | uint32_t | Receive timeout (ms) |
418419
| `send_timeout_ms` | uint32_t | Send timeout (ms) |
419420
| `dapp_idle_timeout_s` | uint32_t | RAN: seconds without a message from a dApp before it is released and removed (default 1800, 0 never). Only what the dApp sends counts. In the C API, `e3_config_t` has `dapp_idle_timeout_s` and the flag `set_dapp_idle_timeout`, since 0 is a legitimate value |
421+
| `reconnect_interval_ms` | uint32_t | dApp: milliseconds between attempts to register again after a release, a lost link or a failed setup (default 1000, 0 never). The new session has a new dApp id and no subscriptions |
420422
| `receive_buffer_size` | size_t | Receive buffer size (bytes) |
421423
| `send_buffer_size` | size_t | Send buffer size (bytes) |
422424
| `io_threads` | size_t | Number of I/O threads |

‎docs/e3ap/03-procedure-flow.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -327,7 +327,8 @@ the link.
327327

328328
### Abnormal conditions
329329

330-
* The link is lost with no RELEASE message. The dApp reports the reason "connection lost". The dApp does not reconnect by itself. The application stops the session and starts it again.
330+
* The link is lost with no RELEASE message. The dApp reports the reason "connection lost".
331+
* After a RELEASE message from the E3 Agent or a lost link, a dApp may run the Setup procedure again by itself. It gets a new dApp identifier and none of its earlier subscriptions. The application subscribes again. A dApp that sent its own RELEASE message does not.
331332
* An E3 Agent that does not detect the end of a dApp keeps its dApp identifier, its subscriptions and its running service models. An E3 Agent detects it from a closed connection, or from a dApp that has sent nothing for a long time. Only what the dApp sends shows that the dApp is there: a message the E3 Agent sends to a dApp is broadcast and proves nothing.
332333
* A RELEASE message from a dApp that names another dApp identifier is not authenticated by the protocol. An E3 Agent that can tell its connections apart should bind each dApp identifier to the connection that first sent a message naming it, and ignore a message that names the identifier on another connection. An E3 Agent that does not bind removes the named dApp.
333334

‎docs/e3ap/05-semantics-and-constraints.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,8 +130,8 @@ side.
130130

131131
### Lost links
132132

133-
A dApp that loses its link reports the reason "connection lost". It does not
134-
reconnect by itself. An E3 Agent that loses a dApp, or that has heard nothing from it for a long
133+
A dApp that loses its link reports the reason "connection lost". It may run the Setup
134+
procedure again by itself, and then has a new dApp identifier and no subscriptions. An E3 Agent that loses a dApp, or that has heard nothing from it for a long
135135
time, should send a RELEASE message where the link is still there, and should remove the
136136
registration and the subscriptions of that dApp. Some implementations do not detect this, so the
137137
registration stays.
71 Bytes
Binary file not shown.

‎docs/e3ap/integrator-guide.md‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ in the connectors.
5050
| Claim | Code pointer |
5151
|---|---|
5252
| Version string `1.0.0` | `include/libe3/types.hpp:475` |
53-
| The RAN does not check the dApp's version | `e3_interface.cpp:937` (`handle_setup_request` only logs it) |
53+
| The RAN does not check the dApp's version | `e3_interface.cpp:970` (`handle_setup_request` only logs it) |
5454
| E3 Agent binds the three ZeroMQ sockets | `src/connector/zmq_connector.cpp:130-141`, `201-218`, `265-272` |
5555
| dApp connects: REQ, SUB, PUB | `zmq_connector.cpp:356-367`, `449-470`, `484-492` |
5656
| dApp waits 200 ms after connecting the PUB socket (slow joiner) | `zmq_connector.cpp:505` |
@@ -66,32 +66,32 @@ in the connectors.
6666

6767
| Claim | Code pointer |
6868
|---|---|
69-
| Setup on the E3 Agent: decode, register, build the list, answer | `src/core/e3_interface.cpp:528-576`, `931-1043` |
70-
| Negative reply for garbage or a wrong PDU type, with the cause protocolError | `e3_interface.cpp:1045-1079` |
71-
| RAN function list limits: data 1 to 32768 octets, 256 identifiers, 64 functions | `e3_interface.cpp:960-1001`, `src/core/sm_registry.cpp:35-57` |
72-
| Encode failure of the SETUP RESPONSE ends the process | `e3_interface.cpp:1026-1032` |
73-
| Setup on the dApp: 5 attempts, 4 receives of 500 ms each | `e3_interface.cpp:1374-1452` |
74-
| A negative response still gives "success" to the dApp | `e3_interface.cpp:1446`, `1610-1613` |
75-
| Subscription: the registration, the RAN function, the lists and every identifier are checked, and a refusal carries a cause | `e3_interface.cpp:892-925`, `1081-1154` |
69+
| Setup on the E3 Agent: decode, register, build the list, answer | `src/core/e3_interface.cpp:561-609`, `964-1076` |
70+
| Negative reply for garbage or a wrong PDU type, with the cause protocolError | `e3_interface.cpp:1078-1112` |
71+
| RAN function list limits: data 1 to 32768 octets, 256 identifiers, 64 functions | `e3_interface.cpp:993-1034`, `src/core/sm_registry.cpp:35-57` |
72+
| Encode failure of the SETUP RESPONSE ends the process | `e3_interface.cpp:1059-1065` |
73+
| Setup on the dApp: 5 attempts, 4 receives of 500 ms each | `e3_interface.cpp:1458-1541` |
74+
| A negative response still gives "success" to the dApp | `e3_interface.cpp:1530`, `1703-1706` |
75+
| Subscription: the registration, the RAN function, the lists and every identifier are checked, and a refusal carries a cause | `e3_interface.cpp:925-958`, `1114-1187` |
7676
| Repeat returns the existing identifier. Renewal after expiry keeps the identifier | `subscription_manager.cpp:187-205` |
77-
| The response echoes the request lists and interval | `e3_interface.cpp:1138-1149` |
78-
| Subscription expiry sweep every 250 ms | `e3_interface.cpp:40`, `789-813` |
79-
| Subscription delete | `e3_interface.cpp:1156-1197` |
80-
| The dApp keeps its own deadline from the response | `e3_interface.cpp:1651-1661` |
81-
| Service model starts with the first subscriber and stops with the last | `subscription_manager.cpp:238-241`, `376-378`, `535-554`; `e3_interface.cpp:1914-1928` |
82-
| dApp control: the registration, the RAN function, the control identifier and a running service model are checked. Otherwise a negative MESSAGE ACK with a cause | `e3_interface.cpp:1199-1262` |
83-
| The core sends a MESSAGE ACK only to refuse a control. The service model answers for the controls it takes | `e3_interface.cpp:1209-1222`, `examples/sm_simple/simple_service_model.hpp:167` |
84-
| The dApp handles every MESSAGE ACK, with no dApp filter | `e3_interface.cpp:1719-1733` |
85-
| dApp report goes through a queue of 1024 and a worker | `e3_interface.cpp:654-684`, `767-788`, `1264-1272` |
86-
| A report with `sequence_id` 0 is refused with `INVALID_PARAM` | `e3_interface.cpp:1864` |
77+
| The response echoes the request lists and interval | `e3_interface.cpp:1171-1182` |
78+
| Subscription expiry sweep every 250 ms | `e3_interface.cpp:40`, `822-846` |
79+
| Subscription delete | `e3_interface.cpp:1189-1230` |
80+
| The dApp keeps its own deadline from the response | `e3_interface.cpp:1744-1754` |
81+
| Service model starts with the first subscriber and stops with the last | `subscription_manager.cpp:238-241`, `376-378`, `535-554`; `e3_interface.cpp:2007-2021` |
82+
| dApp control: the registration, the RAN function, the control identifier and a running service model are checked. Otherwise a negative MESSAGE ACK with a cause | `e3_interface.cpp:1232-1295` |
83+
| The core sends a MESSAGE ACK only to refuse a control. The service model answers for the controls it takes | `e3_interface.cpp:1242-1255`, `examples/sm_simple/simple_service_model.hpp:167` |
84+
| The dApp handles every MESSAGE ACK, with no dApp filter | `e3_interface.cpp:1812-1826` |
85+
| dApp report goes through a queue of 1024 and a worker | `e3_interface.cpp:687-717`, `800-821`, `1297-1305` |
86+
| A report with `sequence_id` 0 is refused with `INVALID_PARAM` | `e3_interface.cpp:1957` |
8787
| xApp control from the E3 Agent has no check of `sequence_id` | `src/core/e3_agent.cpp:230-251` |
88-
| Release from the dApp: unregister, free identifiers, stop service models | `e3_interface.cpp:1274-1297`; `subscription_manager.cpp:84-138` |
89-
| RELEASE from the E3 Agent to a dApp that sent nothing for `dapp_idle_timeout_s` (default 1800 s, 0 is off): queued first, then the removal a release from the dApp gets. Only what the dApp sends resets the time | `e3_interface.cpp:1344-1364`; `subscription_manager.cpp:403-410`, `422-434` |
90-
| RELEASE from the E3 Agent: the dApp clears its session | `e3_interface.cpp:1573-1605` |
88+
| Release from the dApp: unregister, free identifiers, stop service models | `e3_interface.cpp:1307-1330`; `subscription_manager.cpp:84-138` |
89+
| RELEASE from the E3 Agent to a dApp that sent nothing for `dapp_idle_timeout_s` (default 1800 s, 0 is off): queued first, then the removal a release from the dApp gets. Only what the dApp sends resets the time | `e3_interface.cpp:1428-1448`; `subscription_manager.cpp:403-410`, `422-434` |
90+
| RELEASE from the E3 Agent: the dApp clears its session | `e3_interface.cpp:1665-1698` |
9191
| Message identifiers: one counter, 1 to 4294967295 | `e3_interface.cpp:167-174` |
9292
| A request identifier of 0 is replaced | `e3_interface.cpp:189-196` |
9393
| The timestamp is set in the `Pdu` constructor | `types.hpp:426-437` |
94-
| Outbound queue of 128 places, 10 ms pop | `e3_interface.cpp:265`, `705-765`; `include/libe3/lockfree_queue.hpp:55` |
94+
| Outbound queue of 128 places, 10 ms pop | `e3_interface.cpp:265`, `738-798`; `include/libe3/lockfree_queue.hpp:55` |
9595

9696
### Encoding and framing (chapter 04)
9797

@@ -102,8 +102,9 @@ in the connectors.
102102
| The dApp sends unframed | `posix_connector.cpp:681`, `798` |
103103
| The E3 Agent reads one raw `recv()` of up to 60000 octets | `posix_connector.cpp:355`, `537` |
104104
| Per-peer send timeout 500 ms | `posix_connector.cpp:41`, `181` |
105-
| A POSIX E3 Agent removes a dApp whose connection closed, if the dApp had sent a message that names it on that connection. ZeroMQ cannot tell its peers apart, so there the idle time removes the dApp | `posix_connector.cpp:515`, `556`, `565-574`, `584-592`; `e3_interface.cpp:1323-1342` |
106-
| A POSIX E3 Agent binds a dApp identifier to the connection that first named it, and drops a later message that names it on another connection. A dApp that has not spoken yet is not bound: the first message wins | `e3_interface.cpp:619`, `1299-1321` |
105+
| A POSIX E3 Agent removes a dApp whose connection closed, if the dApp had sent a message that names it on that connection. ZeroMQ cannot tell its peers apart, so there the idle time removes the dApp | `posix_connector.cpp:515`, `556`, `565-574`, `584-592`; `e3_interface.cpp:1356-1375` |
106+
| A POSIX E3 Agent binds a dApp identifier to the connection that first named it, and drops a later message that names it on another connection. A dApp that has not spoken yet is not bound: the first message wins | `e3_interface.cpp:652`, `1332-1354` |
107+
| A dApp that lost the E3 Agent registers again every `reconnect_interval_ms` (default 1000, 0 is off), with a new identifier and no subscriptions. `release()` and `stop()` end it | `e3_interface.cpp:1377-1426` |
107108
| ASN.1 encoder buffer of 65536 octets | `src/encoder/asn1_encoder.hpp:39` |
108109
| An empty RAN function list is omitted | `src/encoder/asn1_encoder.cpp:315` |
109110
| A zero timestamp is left out in APER and Protobuf | `asn1_encoder.cpp:233-243` |
@@ -127,7 +128,7 @@ Update the hex in `tests/test_asn1_golden.cpp` and add a row to the change ledge
127128

128129
These comments disagree with the code. They are not discrepancies of the protocol.
129130

130-
* `include/libe3/types.hpp:523` says dApp identifiers are 1 to 100. The range is 1 to 65535.
131+
* `include/libe3/types.hpp:538` says dApp identifiers are 1 to 100. The range is 1 to 65535.
131132
* `include/libe3/subscription_manager.hpp:114` says at most 101 dApps. `:148` says RAN function identifiers 0 to 255. `:34` and `:151` say that periodicity 0 means "the service model default".
132133
* `types.hpp:211` and `e3_encoder.hpp:81` use `0.0.0` as the version example. The default is `1.0.0`.
133134
* `types.hpp:442` and `include/libe3/c_api.h:166` leave Protobuf out of the encoding comments.

0 commit comments

Comments
 (0)