Skip to content

Commit 561ca1f

Browse files
ammarheidariammarheidari
committed
Add long-running M3UA runtime
1 parent 8201387 commit 561ca1f

12 files changed

Lines changed: 1457 additions & 8 deletions

‎README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ The current RC engineering track focuses on:
6565

6666
| Area | Current Direction |
6767
| --- | --- |
68-
| M3UA | Codec, routing, ASP state, diagnostics, and external peer evidence are available; production runtime orchestration is the next gate. |
68+
| M3UA | Codec, routing, ASP state, long-running `IMtp3Network` runtime, bounded queues, heartbeat supervision, reconnect/failover hooks, diagnostics, and external peer evidence are available. |
6969
| SCTP | Native Linux SCTP evidence validates stream id, PPID, receive metadata, reconnect, metrics, graceful shutdown, and external peer traffic. |
7070
| M2PA | Official MTP2 contract exists; production M2PA runtime is planned. |
7171
| SCCP | Connectionless codec and routing foundation exists; a stateful service layer and external evidence remain. |
@@ -148,6 +148,7 @@ Start here:
148148
- [Architecture](docs/ARCHITECTURE.md)
149149
- [Layer contracts](docs/LAYER_CONTRACTS.md)
150150
- [M3UA implementation notes](docs/M3UA.md)
151+
- [Phase 47 M3UA runtime](docs/PHASE47_M3UA_RUNTIME.md)
151152
- [SCTP transport](docs/SCTP_TRANSPORT.md)
152153
- [Phase 45 native SCTP production transport](docs/PHASE45_NATIVE_SCTP_PRODUCTION_TRANSPORT.md)
153154
- [Phase 46 evidence and readiness reconciliation](docs/PHASE46_EVIDENCE_READINESS_RECONCILIATION.md)
@@ -201,7 +202,7 @@ Stable production support requires:
201202

202203
- Retained Linux SCTP verification evidence.
203204
- External SIGTRAN peer interoperability evidence.
204-
- Production M3UA and M2PA runtime paths.
205+
- Production M2PA runtime path.
205206
- Stateful SCCP, TCAP, and MAP SMS service validation.
206207
- End-to-end protocol trace validation.
207208
- Operator-sized capacity and resilience evidence.

‎docs/COMMERCIAL_READINESS_REPORT.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,9 @@ retained manifests instead of stale hard-coded flags.
3939
- Package publication evidence is closed for the public RC prerelease. Stable commercial release gates are foundation-complete, but live stable publication still requires retained stable release evidence, a completed protected stable publication run, and verified stable NuGet publication evidence.
4040
- Public/stable signing must use the organization's approved trusted certificate in the protected release environment; the current signing evidence is internal self-signed RC evidence.
4141
- Hosted GitHub provenance/SBOM attestations were skipped for dry-run and prerelease because private repository or organization attestation persistence can require a supported plan or public repository. These runs retained local provenance markers; stable runs keep hosted attestation reserved for the protected stable gate.
42-
- A production M3UA runtime service still needs lifecycle orchestration, failover,
43-
bounded queueing, restart handling, and runtime observability.
42+
- The production M3UA runtime service now provides lifecycle orchestration,
43+
failover hooks, bounded queueing, heartbeat supervision, cancellation, and
44+
runtime observability through `M3uaRuntime`.
4445
- M2PA is not yet available as a production `IMtp2Link` path.
4546
- SCCP, TCAP, and MAP SMS require stateful service/session implementations and
4647
independent end-to-end peer evidence.

‎docs/M3UA.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,3 +125,22 @@ Routing Keys require a Local-RK-Identifier and at least one Destination Point Co
125125
- UInt32 lists must be non-empty and aligned to four bytes.
126126
- Duplicate singleton parameters are rejected.
127127
- Required parameters are checked before typed messages are returned.
128+
129+
## Long-Running Runtime
130+
131+
`M3uaRuntime` is the production-oriented service API for applications that need a
132+
continuously active ASP. It implements `IMtp3Network`, so SCCP and other MTP3
133+
users depend on the official contract instead of coordinating
134+
`M3uaTransportSession` directly.
135+
136+
The runtime provides:
137+
138+
- ASP startup and graceful shutdown sends.
139+
- A single receive owner that prevents competing receive calls.
140+
- Bounded traffic queues with cancellation-aware backpressure.
141+
- Heartbeat request/acknowledgement correlation and peer heartbeat responses.
142+
- Reconnect and association failover through `IM3uaRuntimeSessionFactory`.
143+
- Runtime events and metrics.
144+
145+
See [Phase 47 M3UA Runtime](PHASE47_M3UA_RUNTIME.md) for composition and
146+
operational details.

‎docs/PHASE47_M3UA_RUNTIME.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Phase 47 M3UA Runtime
2+
3+
## Objective
4+
5+
Provide a long-running M3UA ASP service that upper layers can consume through
6+
`IMtp3Network` without coordinating transport reads, ASP handshakes, heartbeat
7+
responses, reconnects, or queue pressure themselves.
8+
9+
## Runtime API
10+
11+
`M3uaRuntime` implements `IMtp3Network` and owns:
12+
13+
- ASP Up and ASP Active startup.
14+
- ASP Inactive and ASP Down graceful shutdown sends.
15+
- A single inbound M3UA receive loop.
16+
- Bounded inbound and outbound MTP3 transfer channels.
17+
- Automatic response to peer heartbeats.
18+
- Correlated heartbeat supervision with timeout handling.
19+
- Session replacement and failover through `IM3uaRuntimeSessionFactory`.
20+
- Reconnect backoff through `SctpReconnectPolicy`.
21+
- Runtime lifecycle, traffic, heartbeat, reconnect, shutdown, and fault events.
22+
- Queue, transfer, heartbeat, reconnect, and fault metrics.
23+
- Cancellation for startup, traffic waits, reconnect delays, and shutdown.
24+
25+
## Session Factory
26+
27+
`IM3uaRuntimeSessionFactory.OpenAsync` returns an
28+
`M3uaRuntimeSessionLease`. The factory owns endpoint selection and can rotate
29+
between primary and secondary associations after a fault.
30+
31+
The returned `M3uaTransportSession` should share one `M3uaAspSession` between its
32+
inbound and outbound processors. Production payload policy should require an
33+
active ASP.
34+
35+
```csharp
36+
M3uaAspSession aspSession = new();
37+
M3uaInboundProcessor inbound = new(
38+
aspSession,
39+
requireActiveAspForPayload: true);
40+
M3uaOutboundProcessor outbound = new(
41+
aspSession,
42+
networkAppearance: 7,
43+
routingContext: 100,
44+
requireActiveAspForPayload: true);
45+
46+
IM3uaRuntimeSessionFactory factory = new M3uaDelegateRuntimeSessionFactory(
47+
async ct =>
48+
{
49+
ISctpTransport transport = await OpenSctpTransportAsync(ct);
50+
M3uaTransportSession session = new(
51+
transport,
52+
inbound,
53+
outbound);
54+
return new M3uaRuntimeSessionLease("primary-sg", session);
55+
});
56+
57+
await using M3uaRuntime runtime = new(
58+
factory,
59+
new M3uaRuntimeOptions(
60+
startupOptions: new M3uaAspStartupOptions(
61+
aspIdentifier: 42,
62+
trafficModeType: M3uaTrafficModeType.Loadshare)));
63+
64+
await runtime.StartAsync();
65+
IMtp3Network network = runtime;
66+
```
67+
68+
The session factory delegate should create new processor instances for each
69+
replacement session when reconnect and failover are enabled.
70+
71+
## Backpressure
72+
73+
Both runtime channels use `BoundedChannelFullMode.Wait`. Producers are suspended
74+
when the outbound queue is full and the receiver loop is suspended when an upper
75+
layer does not drain the inbound queue. Both waits honor caller cancellation.
76+
77+
`M3uaRuntimeMetrics` reports both queue depths so operators can alert before
78+
traffic latency becomes unacceptable.
79+
80+
## Heartbeats
81+
82+
Only the runtime receive loop reads M3UA messages. Heartbeat requests carry a
83+
monotonic 64-bit token, and the receive loop correlates the echoed
84+
`Heartbeat Ack`. A timeout faults the active session and activates the reconnect
85+
policy.
86+
87+
Inbound peer heartbeats are acknowledged automatically.
88+
89+
## Completion Criteria
90+
91+
Phase 47 is complete because:
92+
93+
- The runtime implements `IMtp3Network`.
94+
- ASP activation, heartbeat supervision, traffic, and shutdown are covered by an
95+
executable loopback test.
96+
- Queue pressure, events, and metrics are public and documented.
97+
- Reconnect/failover is delegated through a replaceable session factory.
98+
- Product readiness no longer reports the M3UA runtime implementation blocker.
99+
- Build, tests, and package validation pass.
100+

‎docs/PHASE47_SUMMARY.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Phase 47 Summary - M3UA Runtime
2+
3+
Phase 47 is complete.
4+
5+
`M3uaRuntime` is a long-running ASP service and implements `IMtp3Network`. It
6+
coordinates ASP startup, bounded inbound/outbound queues, a single receive loop,
7+
heartbeat request/acknowledgement correlation, automatic peer heartbeat
8+
responses, reconnect/failover through a session factory, runtime events, metrics,
9+
cancellation, and graceful shutdown sends.
10+
11+
The runtime is validated with an executable M3UA loopback peer covering
12+
ASPUP/ASPUP_ACK, ASPACTIVE/ASPACTIVE_ACK, MTP3 DATA, heartbeat acknowledgement,
13+
queue metrics, events, and shutdown.
14+
15+
Independent end-to-end SCCP/TCAP/MAP peer evidence remains a later gate.
16+

‎docs/PHASE_INDEX.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
5151
| 44 | Layer contracts and package boundaries | [Phase 44 Layer Contracts](PHASE44_LAYER_CONTRACTS.md), [Phase 44 Summary](PHASE44_SUMMARY.md), [Layer Contracts](LAYER_CONTRACTS.md) | Complete; official layer interfaces and adapters are available |
5252
| 45 | Native SCTP production transport | [Phase 45 Native SCTP Production Transport](PHASE45_NATIVE_SCTP_PRODUCTION_TRANSPORT.md), [Phase 45 Summary](PHASE45_SUMMARY.md), [SCTP Transport](SCTP_TRANSPORT.md) | Evidence complete for Linux SCTP loopback; external peer evidence is tracked separately |
5353
| 46 | Evidence and readiness reconciliation | [Phase 46 Evidence And Readiness Reconciliation](PHASE46_EVIDENCE_READINESS_RECONCILIATION.md), [Phase 46 Summary](PHASE46_SUMMARY.md) | Complete; retained SCTP/M3UA evidence is reflected by readiness APIs |
54-
| 47 | M3UA production runtime API | Planned | Pending |
54+
| 47 | M3UA production runtime API | [Phase 47 M3UA Runtime](PHASE47_M3UA_RUNTIME.md), [Phase 47 Summary](PHASE47_SUMMARY.md), [M3UA](M3UA.md) | Complete; long-running ASP runtime implements IMtp3Network |
5555
| 48 | M2PA production path | Planned | Pending |
5656
| 49 | SCCP stateful service layer | Planned | Pending |
5757
| 50 | TCAP dialogue manager | Planned | Pending |
@@ -66,6 +66,6 @@ This index is the complete phase map for Sigtran.NET. It links each phase to the
6666
The retained verification catalog now reports native Linux SCTP, external SCTP
6767
peer traffic, M3UA interoperability, RC SBOM/provenance/API baseline, and
6868
prerelease publication evidence. Full product readiness remains blocked on the
69-
production M3UA runtime, M2PA, stateful SCCP/TCAP/MAP services, end-to-end
69+
M2PA, stateful SCCP/TCAP/MAP services, end-to-end
7070
independent peer traffic, operator-sized performance, production operations, a
7171
trusted release identity, and protected stable publication.

‎docs/SDK_ROADMAP.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -420,7 +420,10 @@ report passing evidence, while full product readiness remains blocked.
420420
reconnect, failover, and fault recovery.
421421
- Expose bounded queues, runtime events, metrics, and graceful shutdown.
422422

423-
Status: Pending.
423+
Status: Complete. `M3uaRuntime` implements `IMtp3Network` and provides a
424+
single-reader ASP runtime with bounded traffic queues, heartbeat supervision,
425+
session replacement, reconnect/failover policy, runtime events, metrics,
426+
cancellation, and graceful shutdown sends.
424427

425428
## Phase 48 - M2PA Production Path
426429

0 commit comments

Comments
 (0)