Component: REST+SSE Gateway (internal microbroker hop)¶
Status: round-protocol use reverted (BL-259); gateway classes are part of federated-digital-twin-broker¶
This document originally described a REST+SSE transport for the client↔orchestrator/aggregator
round protocol (namespace fl/: RoundConfig, RoundFinalizationSignal, ClientUpdateMessage,
ClientAnnouncePayload, ContractPublishedPayload), introduced by BL-241/BL-242 and extended to
Android by BL-240/BL-254. That migration has been reverted end to end (JVM/Docker composition
roots, the Android client, and the AdminWebServer/TlsConfig server side) at the user's
explicit request. The round protocol is MQTT-only again — see
06-federated-client.md, 04-orchestrator.md, and
docs/mqtt/02-topics-and-payloads.md for the current (and, for
the topics themselves, never-actually-changed) design.
What was removed as part of the revert:
- The POST /api/rounds/publish / GET /api/rounds/events HTTP+SSE endpoints on AdminWebServer
(federated-rest-api), and TopicFilteredSseEventBus.
- The Android br.ufma.lsdi.fedandroid.core.net.RestSseGateway (module
federated-android-client/core) and its dual-gateway (mqtt/roundGateway) split in
FederatedMqttService — Android is back to a single MQTT gateway for iot/ and fl/ alike.
- The mTLS client-truststore config for the round-protocol endpoints
(ADMIN_TLS_CLIENT_TRUSTSTORE/_PASSWORD in TlsConfig).
- The dual external gateway (externalMqttGateway/externalRestSseGateway) in
DigitalTwinBridge/LocalDigitalTwinRuntime (federated-digital-twin-broker) — back to one
externalGateway, MQTT, for every payload type including TwinValidationDecisionMessage.
- The pilot wiring in ErgonomicRiskFederatedSession (and the ingestGateway/gateway split it
required) — reverted to a single MQTT gateway for both sensor ingestion and the round protocol.
What was NOT removed, and remains exactly as BL-243 left it — out of scope for this revert:
the RestSseGateway/EmbeddedRestSseBroker classes (package br.ufma.lsdi.restclient), now merged into federated-digital-twin-broker, and their use as the internal transport
between DigitalTwinBridge/DigitalTwinClientCommandAdapter/DigitalTwinValidatorAdapter and the
embedded local microbroker (EmbeddedTwinBroker) inside federated-digital-twin-broker. That
internal loopback hop (http://127.0.0.1:{port}) has nothing to do with the client↔server round
protocol — it is purely local to a single client process/container, replacing what used to be an
embedded Moquette MQTT broker (BL-238) before BL-243 swapped it for this same HTTP+SSE mechanism.
The full, current description of that surviving internal hop lives in
17-local-digital-twin-broker.md (see its "Architecture"
diagram and the EmbeddedTwinBroker/LocalDigitalTwinRuntime sections) — this document is not
duplicated there and is kept only as a historical record of the now-reverted round-protocol
transport design.
Historical record (BL-241/BL-240/BL-254, reverted by BL-259) — round-protocol REST+SSE design¶
The sections below describe the transport as it existed between BL-241 and this revert. They are preserved for audit-trail purposes only; do not use them as a guide to the current system.
- Client-side module/class: historically
hdt-federated-interface-rest-client(now merged intomodules/federated-digital-twin-broker),br.ufma.lsdi.restclient.RestSseGateway implements MqttGateway, AutoCloseable(JVM), plus an Android-only reimplementationbr.ufma.lsdi.fedandroid.core.net.RestSseGateway(modulefederated-android-client/core, overHttpURLConnectionsincejava.net.http.HttpClientis unavailable on ART) — the Android class was deleted by the revert; the JVM class survives only for the BL-243 internal hop described above. - Server-side:
modules/federated-rest-api'sAdminWebServergainedPOST /api/rounds/publish?topic=.../GET /api/rounds/events?topicFilter=..., backed byTopicFilteredSseEventBus— both endpoints and that class were removed by the revert. - Wire format: topic as a URL query parameter, body =
MqttPayloadCodec.encode(envelope)bytes, SSE frames asevent: {topic}\ndata: {envelope JSON}\n\n— this convention is unchanged and still used by the surviving BL-243 internal hop (see 17-local-digital-twin-broker.md). - Pilot wiring:
ErgonomicRiskFederatedSessionwas the only*FederatedSessionactually migrated to REST+SSE for the round protocol; the other four (HAR/ECG/MIMIC/MNIST) were never migrated. All five are MQTT-only again after the revert. - mTLS:
TlsConfig/AdminWebServer.requireClientCertificateadded opt-in client-certificate enforcement scoped to/api/rounds/**only — removed along with the endpoints.
For exact prior wording and diagrams, see the git history of this file and of
06-federated-client.md, 17-local-digital-twin-broker.md,
and 04-orchestrator.md at commits ddf54fb (BL-241), 5f1a810/7888e47
(BL-242), d240ec7/ec54fff (Android BL-240/BL-249/BL-254).