OpenSOVD / SCORE Integration Concept

[lh-sag]

This document describes how the Eclipse OpenSOVD projects are integrated into Eclipse SCORE,
using inc_diagnostics as the integration repository.

It is a starting point. It captures the integration approach as discussed during the integration
workshop (#103).

The aspects described here cover the clean split, the binary implementation strategy, the Bazel
consumption approach, and the open points. They need to be reviewed and confirmed by the workshop
participants, and nothing here is final until that review.

Reference design: https://github.com/eclipse-opensovd/opensovd/blob/main/docs/design/design.md

1. Repositories and their roles

Repository	Eclipse project	Role
opensovd-core	OpenSOVD	Gateway/server library (+ reference opensovd-gateway binary). Upstream.
classic-diagnostic-adapter (CDA)	OpenSOVD	SOVD<->UDS adapter library (+ reference opensovd-cda binary). Upstream.
inc_diagnostics	SCORE	Integration repository. Hosts the two SCORE binaries + Bazel + SCORE-specific parts.
reference_integration	SCORE	Template/pattern for how a SCORE repo consumes upstream projects via Bazel.

2. Clean split and repository structure

Each Eclipse project keeps its own responsibility:

• Upstream (OpenSOVD) owns all diagnostic functionality and stays framework-agnostic.
  SCORE adds nothing to upstream except the build files needed to consume it.
• SCORE (inc_diagnostics) owns integration only: the binary implementations (built on the
  upstream APIs), the Bazel build, CI/packaging, and SCORE cross-cutting concerns (logging,
  persistency, config).

inc_diagnostics/
├── MODULE.bazel        # bazel_dep + git_override → opensovd-core, CDA (pinned)
├── score/
│   ├── opensovd-gateway/
│   │   ├── src/main.rs # SOVD Gateway: uses opensovd-core API
│   │   ├── BUILD       # rust_binary
│   │   ├── tests/      # unit + integration tests
│   │   └── ...
│   └── opensovd-cda/
│       ├── src/main.rs # SOVD CDA: uses classic-diagnostic-adapter API
│       ├── BUILD       # rust_binary
│       ├── tests/      # unit + integration tests
│       └── ...
├── tests/              # rust_test / cc_test scaffolding
├── docs/               # this concept + generated docs (SCORE docs-as-code)
├── .github/            # SCORE central CI (copyright, format, DASH license, docs)
└── ...                 # other SCORE-mandatory files (project_config.bzl, NOTICE, ...)

(Illustrative, not the complete structure.)

Integration tests use the Eclipse SCORE itf (Integration Test Framework), under each component's tests/.

Besides the Bazel build, CI, tests and docs, the only application code SCORE writes lives in the two
main.rs files: they implement the SCORE binaries on top of the upstream library APIs, while all
diagnostic functionality stays in the upstream libraries. How much they add at the SCORE boundary is
subject to further investigation.

3. Runtime architecture

        HTTP (SOVD), vehicle-external           HTTP (SOVD), vehicle-internal               UDS / DoIP
 tester ────────────────────► opensovd-gateway ──────────────────────────────► opensovd-cda ──────► classic ECUs

• opensovd-gateway is the SOVD entry point: it terminates SOVD requests and routes them to the
  diagnostic backends, built on opensovd-core.
• opensovd-cda is the classic diagnostic adapter: it translates SOVD requests into UDS toward
  legacy ECUs, built on classic-diagnostic-adapter.

Both upstream projects already ship equivalent reference binaries; the SCORE binaries exist so SCORE can
inject its own logging/persistency/config at the binary boundary without forking upstream.

4. How upstream is consumed (Bazel)

The two projects use different build systems: OpenSOVD builds with Cargo, SCORE with Bazel. The concept
is to add Bazel build support in the upstream projects (alongside Cargo, which keeps working) and to consume it from the SCORE side as a pinned dependency. The build definitions live upstream; SCORE
only references them, so the clean split is preserved.

This work has started, proving the pattern on the CDA first:

• Upstream (CDA) gains a native Bazel build:
  Add basic bazel build (S-Core Integration) classic-diagnostic-adapter#348.
• SCORE consumes it as a pinned dependency, demonstrated in reference_integration:
  Add classic-diagnostic-adapter dependency with git override eclipse-score/reference_integration#240.

reference_integration is the initial proving ground; inc_diagnostics adopts the same mechanism. Both
sides are still in progress, with open points around toolchain alignment and cross-compilation.

5. SCORE cross-cutting concerns

Referenced now, wired later. The SCORE binaries reserve the hook points:

• Rust baselibs - the SCORE Rust base libraries,
  the common dependency the SCORE binaries build on (also used by reference_integration).
• Logging - bridges upstream tracing usage.
• Persistency - CDA Diagnostic DB; gateway topology.
• Config - SCORE may unify this.

6. First iteration: scaffolding / build only

Scope of the initial integration:

• Both binaries build and run as hello-world stubs that link the upstream libs, green in SCORE CI.
• No real discovery/data wiring, no CDA<->gateway connection, no cross-cutting implementation yet.

Sequence:

1. Update inc_diagnostics to sync with the tempalte https://github.com/eclipse-score/module_template
2. Add Bazel build files to CDA - in progress (PR Add basic bazel build (S-Core Integration) classic-diagnostic-adapter#348). SCORE-side consumption being proven in
   reference_integration (PR Add classic-diagnostic-adapter dependency with git override eclipse-score/reference_integration#240).
3. Add Bazel build files to opensovd-core (pure Rust - easiest) - not yet started.
4. Wire both as pinned deps in inc_diagnostics.
5. Add the two rust_binary targets.
6. Get SCORE CI green (build/test/copyright/format/DASH license).

7. Open points

• Transport for the SOVD links (see section 3, Runtime architecture). The links are drawn as
  HTTP over TCP/IP. For the vehicle-internal link especially, Unix domain sockets could be used
  instead of TCP/IP to improve security and authentication (local-only access, filesystem
  permissions, peer credentials). Unix socket support is already available in opensovd-core and
  in axum; the CDA (classic-diagnostic-adapter) would need to support it as well for the
  gateway<->CDA link. To be discussed.

8. References

• OpenSOVD design document: https://github.com/eclipse-opensovd/opensovd/blob/main/docs/design/design.md
• Integration workshop discussion: S-CORE x OpenSOVD Diagnostics Architecture & Integration Workshop #103
• OpenSOVD core (gateway/server library): https://github.com/eclipse-opensovd/opensovd
• Classic Diagnostic Adapter (CDA): https://github.com/eclipse-opensovd/classic-diagnostic-adapter
• CDA Bazel build (upstream, ongoing): Add basic bazel build (S-Core Integration) classic-diagnostic-adapter#348
• CDA consumption in reference_integration (ongoing): Add classic-diagnostic-adapter dependency with git override eclipse-score/reference_integration#240
• SCORE Rust baselibs: https://github.com/eclipse-score/baselibs_rust
• SCORE integration test framework (itf): https://github.com/eclipse-score/itf
• SCORE logging: https://github.com/eclipse-score/logging
• SCORE persistency: https://github.com/eclipse-score/persistency

[RolandJentschETAS]

For the repo structure (2.): Did you had a look into the S-CORE repo structure definition for a module ? Maybe it would be a good idea to follow that one.

[RolandJentschETAS]

Isn't also the S-CORE communication to be named ? Because the picture main/docs/design/design.md names an "IPC", which is then mw::com (communication) in S-CORE ?

[lh-sag]

For the repo structure (2.): Did you had a look into the S-CORE repo structure definition for a module ? Maybe it would be a good idea to follow that one.

Yes. It is actually based on the SCORE repository template. I tried not to add too much in addition. My goal was to have a starting point and have clear responsibilities/roles for the individual repositories/eclipse projects.

[akshaylg0314]

Hey @lh-sag What should the two main.rs files actually do beyond calling the upstream library? Is there a list of what SCORE adds at the binary level?

[lh-sag]

Hey @lh-sag What should the two main.rs files actually do beyond calling the upstream library? Is there a list of what SCORE adds at the binary level?

An incomplete list is mentioned in 5. SCORE cross-cutting concerns. This way we can utilize e.g. libraries (logging, persistency), testing framework, release artifacts, and processes as documented and offered by SCORE.

Of course we could do all of this in OpenSOVD itself e.g. import/reference SCORE deps. But this integration proposal is about clear separation of responsibilities and processes.
This does not rule out that the same team/member will work on them though.

[akshaylg0314]

Hey @lh-sag What should the two main.rs files actually do beyond calling the upstream library? Is there a list of what SCORE adds at the binary level?

An incomplete list is mentioned in 5. SCORE cross-cutting concerns. This way we can utilize e.g. libraries (logging, persistency), testing framework, release artifacts, and processes as documented and offered by SCORE.

Of course we could do all of this in OpenSOVD itself e.g. import/reference SCORE deps. But this integration proposal is about clear separation of responsibilities and processes. This does not rule out that the same team/member will work on them though.

Thanks for clarifying! To make sure we scope the first iteration correctly — from Section 6, the goal is hello-world stubs that just build and link. Does that mean logging/persistency/config wiring comes in a later iteration, or should at least one of them (e.g. logging init) be wired even in the stub phase to prove the integration pattern works end-to-end?

[lh-sag]

Isn't also the S-CORE communication to be named ? Because the picture main/docs/design/design.md names an "IPC", which is then mw::com (communication) in S-CORE ?

The objective is to align on integration. The scope has therefore been deliberately narrowed accordingly. We will stick to the plan to re-/use components and architecture as documented in the design document without repeating this information here.

[lh-sag]

Hey @lh-sag What should the two main.rs files actually do beyond calling the upstream library? Is there a list of what SCORE adds at the binary level?

An incomplete list is mentioned in 5. SCORE cross-cutting concerns. This way we can utilize e.g. libraries (logging, persistency), testing framework, release artifacts, and processes as documented and offered by SCORE.
Of course we could do all of this in OpenSOVD itself e.g. import/reference SCORE deps. But this integration proposal is about clear separation of responsibilities and processes. This does not rule out that the same team/member will work on them though.

Thanks for clarifying! To make sure we scope the first iteration correctly — from Section 6, the goal is hello-world stubs that just build and link. Does that mean logging/persistency/config wiring comes in a later iteration, or should at least one of them (e.g. logging init) be wired even in the stub phase to prove the integration pattern works end-to-end?

This was just to have something build-able asap and incrementally work on it. We can however extend it and wire one or more libraries from SCORE.

[alexmohr]

The scope has therefore been deliberately narrowed accordingly.

Which also means we see i.e. logging as 2nd step once we get the initial setup running?

[lh-sag]

The scope has therefore been deliberately narrowed accordingly.

Which also means we see i.e. logging as 2nd step once we get the initial setup running?

@alexmohr As simple as it gets for both gateway and cda. We can always add more content:

async fn main() {
    let () = std::future::pending().await;
    unreachable!();
}

Just to get both https://github.com/eclipse-score/inc_diagnostics/ and eclipse-score/reference_integration#240 green.

We should also update inc_diagnostics to reflect the latest template here https://github.com/eclipse-score/module_template.

[alexmohr]

Also probably a topic for somewhat in the future, but it probably would be cool to have an opensovd common devcontainer, so we can build all tools with one container. Most likely this means only minor adjustments to the devcontainer of core.

[FScholPer]

Drafted first integration: eclipse-score/inc_diagnostics#6