Ir para o conteúdo

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 into modules/federated-digital-twin-broker), br.ufma.lsdi.restclient.RestSseGateway implements MqttGateway, AutoCloseable (JVM), plus an Android-only reimplementation br.ufma.lsdi.fedandroid.core.net.RestSseGateway (module federated-android-client/core, over HttpURLConnection since java.net.http.HttpClient is 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's AdminWebServer gained POST /api/rounds/publish?topic=... / GET /api/rounds/events?topicFilter=..., backed by TopicFilteredSseEventBus — 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 as event: {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: ErgonomicRiskFederatedSession was the only *FederatedSession actually 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.requireClientCertificate added 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).