[message passing] first draft unit design

score/message_passing/dependability/software_unit_design/BUILD

@@ -13,17 +13,32 @@
 
 load("@score_tooling//bazel/rules/rules_score:rules_score.bzl", "unit_design")
 
+# Class diagrams are passed through directly to Sphinx (sphinxcontrib-plantuml
+# renders them at doc-build time). The RST wrapper references the .puml file
+# via '.. uml::' so both must be listed together in 'static'.
 unit_design(
     name = "client_connection_unit_design",
+    static = [
+        "client_connection_class_diagram.puml",
+        "client_connection_design.rst",
+    ],
     visibility = ["//score/message_passing:__pkg__"],
 )
 
 unit_design(
     name = "unix_domain_unit_design",
+    static = [
+        "unix_domain_class_diagram.puml",
+        "unix_domain_design.rst",
+    ],
     visibility = ["//score/message_passing:__pkg__"],
 )
 
 unit_design(
     name = "qnx_dispatch_unit_design",
+    static = [
+        "qnx_dispatch_class_diagram.puml",
+        "qnx_dispatch_design.rst",
+    ],
     visibility = ["//score/message_passing:__pkg__"],
 )

score/message_passing/dependability/software_unit_design/client_connection_class_diagram.puml

@@ -0,0 +1,119 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+
+' Unit design (static view) for the Client Connection unit.
+' Derived from the existing message-passing design in score/mw/com/design,
+' mapped onto the new score::message_passing units. The old mw::com roles are
+' shown as <<role: ...>> stereotypes to keep the design traceable.
+
+@startuml client_connection_class_diagram
+
+namespace score::message_passing {
+
+    ' Old: mw::com::message_passing::SenderFactory + MessagePassingControl::GetMessagePassingSender
+    interface IClientFactory <<role: SenderFactory>> {
+        + Create(protocol_config : ServiceProtocolConfig, client_config : ClientConfig) : IClientConnection
+    }
+
+    ' Old: mw::com::message_passing::ISender (Send) plus the client-side
+    ' request/result-message + callback pairing (subscribeEventResultCallbacks)
+    ' and the NotifyEventHandler notification callback, unified in one endpoint.
+    interface IClientConnection <<role: ISender + reply/notify>> {
+        + Send(message) : expected<Error>
+        + SendWaitReply(message, reply) : expected<Error>
+        + SendWithCallback(message, ReplyCallback) : expected<Error>
+        + Start(StateCallback, NotifyCallback) : void
+        + Stop() : void
+        + Restart() : void
+        + GetState() : State
+        + GetStopReason() : StopReason
+    }
+
+    enum State {
+        kStarting
+        kReady
+        kStopping
+        kStopped
+    }
+
+    enum StopReason {
+        kNone
+        kInit
+        kUserRequested
+        kPermission
+        kClosedByPeer
+        kIoError
+        kShutdown
+    }
+
+    ' Old: the fixed ShortMessage / MediumMessage split was dropped (premature
+    ' optimization); a per-service protocol now carries the max message sizes.
+    struct ServiceProtocolConfig <<replaces ShortMessage / MediumMessage>> {
+        + identifier
+        + max_send_size
+        + max_reply_size
+        + max_notify_size
+    }
+
+    ' Nested as IClientFactory::ClientConfig.
+    struct ClientConfig {
+        + max_async_replies
+        + max_queued_sends
+        + fully_ordered
+        + truly_async
+        + sync_first_connect
+    }
+
+    ' Old: lola::messaging::MessagePassingControl owned the senders map, the
+    ' send queue and the node identifier. Now a shared transport engine owns
+    ' the background thread and the OS-specific channels.
+    interface ISharedResourceEngine <<role: MessagePassingControl>> {
+        + TryOpenClientConnection(identifier) : fd
+        + SendProtocolMessage(fd, code, message) : expected<Error>
+        + ReceiveProtocolMessage(fd, code) : message
+        + RegisterPosixEndpoint(endpoint) : void
+        + EnqueueCommand(entry, until, callback, owner) : void
+    }
+
+}
+
+namespace score::message_passing::detail {
+
+    ' The unit: encapsulates the connection state machine and the
+    ' (pre-allocated) asynchronous send queue.
+    class ClientConnection <<unit>> {
+        + Send(message) : expected<Error>
+        + SendWaitReply(message, reply) : expected<Error>
+        + SendWithCallback(message, ReplyCallback) : expected<Error>
+        + Start(StateCallback, NotifyCallback) : void
+        + Stop() : void
+        + Restart() : void
+        + GetState() : State
+        + GetStopReason() : StopReason
+    }
+
+}
+
+ClientConnection ..|> IClientConnection
+ClientConnection o--> ISharedResourceEngine : shares transport & thread
+ClientConnection ..> ServiceProtocolConfig : bounded by
+ClientConnection ..> ClientConfig : configured by
+IClientConnection ..> State : reports
+IClientConnection ..> StopReason : reports
+IClientFactory ..> IClientConnection : creates
+IClientFactory *-- ClientConfig : nested config
+IClientFactory ..> ServiceProtocolConfig : uses
+
+note "Blend of mw/com: Send == old ISender::Send; old request + Result-message + callback becomes SendWaitReply / SendWithCallback; old per-ElementFqId notifications become NotifyCallback." as N1
+
+@enduml

score/message_passing/dependability/software_unit_design/qnx_dispatch_class_diagram.puml

@@ -0,0 +1,130 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+
+' Unit design (static view) for the QNX Dispatch dispatch/transport unit.
+' Derived from the existing message-passing design in score/mw/com/design,
+' mapped onto the new score::message_passing units. The old mw::com roles are
+' shown as <<role: ...>> stereotypes to keep the design traceable.
+
+@startuml qnx_dispatch_class_diagram
+
+namespace score::message_passing {
+
+    interface IClientFactory <<role: SenderFactory>> {
+        + Create(protocol_config, client_config) : IClientConnection
+    }
+
+    ' Old: mw::com::message_passing::ReceiverFactory
+    interface IServerFactory <<role: ReceiverFactory>> {
+        + Create(protocol_config, server_config) : IServer
+    }
+
+    ' Old: mw::com::message_passing::IReceiver (StartListening + Register handlers).
+    interface IServer <<role: IReceiver>> {
+        + StartListening(ConnectCallback, DisconnectCallback, sent : MessageCallback, sentWithReply : MessageCallback) : expected<Error>
+        + StopListening() : void
+    }
+
+    ' Old: the server-side message dispatch performed inside MessagePassingFacade.
+    interface IServerConnection <<role: server message dispatch>> {
+        + GetClientIdentity() : ClientIdentity
+        + GetUserData() : UserData
+        + Reply(message) : expected<Error>
+        + Notify(message) : expected<Error>
+        + RequestDisconnect() : void
+    }
+
+    ' Old: the user-provided handlers the facade dispatched to.
+    interface IConnectionHandler <<user provided>> {
+        + OnMessageSent(connection, message) : expected<Error>
+        + OnMessageSentWithReply(connection, message) : expected<Error>
+        + OnDisconnect(connection) : void
+    }
+
+    interface ISharedResourceEngine <<role: MessagePassingControl>> {
+        + TryOpenClientConnection(identifier) : fd
+        + SendProtocolMessage(fd, code, message) : expected<Error>
+        + ReceiveProtocolMessage(fd, code) : message
+        + RegisterPosixEndpoint(endpoint) : void
+    }
+
+    ' Old: the OS-specific ISender/IReceiver implementation ("OS specific IPC,
+    ' QNX pulse"). Realized here by native QNX messaging via a resource manager
+    ' and a single shared dispatch loop (ASIL-qualified transport).
+    class QnxDispatchEngine <<transport: native QNX messaging>> {
+        + GetOsResources() : OsResources&
+    }
+
+    ' Resource-manager base classes hosted by the engine and reused by the
+    ' server and its connections (native QNX dispatch framework).
+    class ResourceManagerServer <<resmgr base>> {
+        + Start(path) : expected<Error>
+        + Stop() : void
+    }
+
+    class ResourceManagerConnection <<resmgr base>> {
+        + GetServer() : ResourceManagerServer&
+    }
+
+    class QnxDispatchClientFactory <<role: SenderFactory>> {
+        + Create(protocol_config, client_config) : IClientConnection
+        + GetEngine() : QnxDispatchEngine
+    }
+
+    class QnxDispatchServerFactory <<role: ReceiverFactory>> {
+        + Create(protocol_config, server_config) : IServer
+        + GetEngine() : QnxDispatchEngine
+    }
+
+}
+
+namespace score::message_passing::detail {
+
+    class QnxDispatchServer <<unit>> {
+        + StartListening(ConnectCallback, DisconnectCallback, sent, sentWithReply) : expected<Error>
+        + StopListening() : void
+    }
+
+    ' Nested class of QnxDispatchServer; one endpoint per accepted client;
+    ' dispatches incoming messages to the server callbacks or to the user
+    ' IConnectionHandler.
+    class ServerConnection <<nested in QnxDispatchServer>> {
+        + GetClientIdentity() : ClientIdentity
+        + GetUserData() : UserData
+        + Reply(message) : expected<Error>
+        + Notify(message) : expected<Error>
+        + RequestDisconnect() : void
+    }
+
+}
+
+QnxDispatchEngine ..|> ISharedResourceEngine
+QnxDispatchClientFactory ..|> IClientFactory
+QnxDispatchServerFactory ..|> IServerFactory
+QnxDispatchServer ..|> IServer
+QnxDispatchServer --|> ResourceManagerServer
+ServerConnection ..|> IServerConnection
+ServerConnection --|> ResourceManagerConnection
+
+QnxDispatchClientFactory o--> QnxDispatchEngine : shared transport
+QnxDispatchServerFactory o--> QnxDispatchEngine : shared transport
+QnxDispatchEngine ..> ResourceManagerServer : hosts
+QnxDispatchEngine ..> ResourceManagerConnection : hosts
+ResourceManagerConnection --> ResourceManagerServer : belongs to
+QnxDispatchServerFactory ..> QnxDispatchServer : creates
+QnxDispatchServer *--> ServerConnection : owns per client
+ServerConnection ..> IConnectionHandler : dispatches to
+
+note "Blend of mw/com: old ReceiverFactory/IReceiver + OS-specific ISender (QNX pulse) become a native QNX messaging engine shared by both factories; the facade message dispatch becomes ServerConnection + IConnectionHandler." as N1
+
+@enduml