Detailed Design#

Datarouter Detailed Design		status: draft security: NO safety: QM
version: 1 realizes: wp__sw_implementation

doc__datarouter_detailed_design		Generic Document

Description#

The Datarouter (Datarouter (comp__datarouter)) is the DLT daemon. It reads the log records of the clients from shared memory, filters them, and sends them as DLT messages over UDP multicast. A client (mw::log) connects through a message passing channel. The Datarouter asks the client to hand over a buffer by a notification and reads it from the shared memory. It never blocks on a client.

The design documents and PlantUML diagrams are in score/datarouter/doc/design. This folder links them by symbolic links, so that the files stay at their place in the source tree. The source code is in score/datarouter. Paths in this document are relative to this directory unless noted otherwise.

Design Decisions#

The diagrams show how the design addresses the requirements and concerns.

Requirement or concern	Diagram
Freedom from interference: the Datarouter is a separate process and only reads the shared memory of the clients	`detail-ipc.puml` and `context-highlevel.puml` in Logging: architecture and SW design
A client that does not answer must not stall the other clients	`client_session_interaction_sequence.puml` in Dynamic Diagrams for Unit Interactions
Stale sessions are cleaned up without losing readable data	`activity_watchdog_session_lifecycle.puml` in Logging: architecture and SW design
A client that crashes while its session is created	`sequence_early_disconnect_race.puml` in Logging: architecture and SW design
Reduce the traffic early, own level per channel	`dlt_message_filtering_backend.puml` in Logging: architecture and SW design
Bandwidth quota per source (DLT Quota Bandwidth Reduction (comp_req__data_router__dlt_quota_bw_reduction))	No diagram shows the quota, see IMPL_01_03 in Implementation Inspection Checklist
One code base for different deployments, stubs keep the interfaces	`file_transfer_feature_class_diagram.puml` in Logging: architecture and SW design and `package-datarouter.puml` in Static Diagrams for Unit Interactions
Deployment-specific configuration without a rebuild (DLT Multiple Channel Support (comp_req__data_router__dlt_multiple_channels))	`dlt_message_filtering_backend.puml` in Logging: architecture and SW design and `seq_kvs_threads_sequence_diagram.puml` in Dynamic Diagrams for Unit Interactions
The persistent storage is provided by the platform	`seq_kvs_threads_sequence_diagram.puml` in Dynamic Diagrams for Unit Interactions

Design Constraints#

All requirements of the component apply, see Datarouter Component Requir... (doc__data_router_requirements). The diagrams show the constraints per building block.

Building block	Constraint	Diagram
DLT output	UDP multicast only (Datarouter DLT Server (comp_req__data_router__dlt_server))	`context-highlevel.puml` in Logging: architecture and SW design
Configuration	`log-channels.json` is mandatory, `class-id.json` is optional	`dlt_message_filtering_backend.puml` in Logging: architecture and SW design
Sessions	One worker thread serves all sessions, the notification is non-blocking	`client_session_interaction_sequence.puml` in Dynamic Diagrams for Unit Interactions
Watchdog	A session is removed after a limited number of missed acquire deadlines	`activity_watchdog_session_lifecycle.puml` in Logging: architecture and SW design
Configuration sessions	Changes are not persistent in this repository (stub dictionary)	`seq_kvs_threads_sequence_diagram.puml` in Dynamic Diagrams for Unit Interactions

External Dependencies#

External dependencies and their relationships are defined in the Bazel BUILD targets. The dependency analysis and its findings are part of the checklist item IMPL_01_04 in Implementation Inspection Checklist.

Rationale Behind Decomposition into Units#

The component is split by responsibility so that each unit can be tested and replaced independently. The units and their relations are shown in datarouter_units.puml and package-datarouter.puml in Static Diagrams for Unit Interactions.

Static Diagrams for Unit Interactions#

The units that appear in the sequence diagrams and their bindings:

The diagrams are validated by the architectural_design target //score/datarouter/doc/design:datarouter_architectural_design. The interface names in the unit diagram follow the convention of the validator (I<caller><callee>) and are not interfaces of the code.

Further static diagrams are part of Logging: architecture and SW design.

Dynamic Diagrams for Unit Interactions#

The session handling between a client and the Datarouter:

The configuration session:

Further dynamic diagrams (early disconnect, watchdog, filtering) are part of Logging: architecture and SW design.

Units within the Component#

The decomposition into units is given by the directory and file structure; a unit belongs to this component through its location. Attributes, behavior and the interfaces of a unit are documented in the source code (public headers). Paths are relative to score/datarouter of this repository.

Interfaces of the Component#

The interfaces of the component architecture and the external interfaces are realized by the following source code interfaces. The interface documentation is part of the headers.

Architecture interface	Source code interface	Realizing units
Log Record Shared-Memory (logic_arc_int__logging__shm)	`ISharedMemoryReader` (`score_logging` `score/mw/log`), used by `SourceSession`	Data router core
Control Channel (logic_arc_int__logging__session_ctrl_channel)	`MessagePassingServer` with `MessagePassingServer::ISession` and `ISessionHandle`, messages in `data_router_messages.h`	Message passing server, data router core
DLT over UDP multicast (Datarouter DLT Server (comp_req__data_router__dlt_server))	`UdpStreamOutput`, `DltLogChannel`	DLT server and channels
Configuration client (Unix domain socket)	`UnixDomainServer::ISession`, `IDiagnosticJobHandler`	Unix domain server, configuration
Command line (`-c`, `-C`)	`Options`	Configuration