Doip server 1.0 by VinaykumarRS1995 · Pull Request #29 · eclipse-opensovd/uds2sovd-proxy

VinaykumarRS1995 · 2026-05-28T11:01:45Z

Summary

This PR adds a DoIP server (ISO 13400-2) that sits between a UDS diagnostic tester and a SOVD backend. It handles vehicle discovery over UDP and diagnostic sessions over TCP, parsing the DoIP wire format and dispatching to per-message-type handlers.

The SOVD proxy layer is stubbed for now — it returns NRC 0x11 (serviceNotSupported). The idea is that once the real SOVD backend is available, we just swap in a concrete implementation of the SovdProxy trait without touching any protocol or transport code.

README.md has the full architecture diagram, message type table, and build/run instructions.

Checklist

I have tested my changes locally
I have added or updated documentation
I have linked related issues or discussions
I have added or updated tests

Notes for Reviewers

I've structured the commits to be reviewable layer by layer. If you follow the commit order, each one builds on the previous without jumping between concerns:

README + sequence diagrams — start here for the big picture
Cargo project setup
Configuration module (ConfigProvider trait, TOML + in-memory)
DoIP wire format, header parsing, message type enums
PayloadHandler trait + Dispatcher (routes messages to handlers)
SovdProxy trait + stub/mock
7a. UDP handlers (vehicle identification, entity status)
7b. Stateless TCP handlers (alive check, routing activation)
7c. DiagnosticsHandler + dispatcher factory wiring
8a. Async TCP/UDP transport with DoIP framing
8b. Session manager (atomic counter + RAII guard)
8c. Server struct tying both transports together
main.rs entry point + doip_tester example

Document DoIP server block diagram, supported message types, and build instructions. Include PlantUML diagrams for startup, TCP connection, UDP request, and graceful shutdown flows. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Define crate as library and binary. Add tokio, serde, toml, tracing, and thiserror dependencies. Declare top-level modules. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Introduce ServerConfig for TCP, UDP, and ECU identity settings. Provide InMemoryProvider for defaults and TomlProvider for file-based configuration loading. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Implement 8-byte header parsing with version validation. Define TcpPayloadType and UdpPayloadType enums for all supported message types (0x0001-0x8003) per ISO 13400-2. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Introduce PayloadHandler<PayloadType, Request> trait for handler implementations. Build Dispatcher with HashMap-based routing from payload type to handler, generic over transport. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Define SovdProxy trait with forward() for UDS byte translation. StubProxy returns NRC 0x11 pending real backend integration. MockProxy echoes input for unit testing. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Add handlers for VehicleIdentification (0x0001-0x0003), VIN request (0x0004), and EntityStatus (0x4001). Vehicle ID handlers share common announcement-building logic. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Add AliveCheck (0x0007) responding to keep-alive pings. RoutingActivation (0x0005) returns 0x10 as placeholder until full state-machine logic is implemented. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Add DiagnosticsHandler (0x8001) forwarding UDS bytes via SovdProxy and returning DiagnosticMessagePositiveAck. Wire all handlers into build_tcp_dispatcher() and build_udp_dispatcher(). Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Add TCP listener with per-connection task spawning. DoIP framer reconstructs complete messages from partial reads. UDP uses simple recv-parse-dispatch loop with no framing needed. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Enforce max concurrent TCP connections using atomic counter. SessionSlot acts as RAII guard that auto-releases on drop, ensuring cleanup on disconnection or task cancellation. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Add Server struct that starts both listeners concurrently and coordinates graceful shutdown via cancellation token. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Wire all layers in main(): load config, build dispatchers, start transports, handle SIGINT shutdown. Include DoIP tester for manual integration testing against a running server. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

bharatGoswami8 · 2026-05-28T14:21:33Z

+    session resources released automatically
+end note
+
+@enduml


missing new line

bharatGoswami8

I believe we should consider providing users with greater flexibility to build each component independently. By components, I am referring to the server application, DoIP library, and client example application.
Additionally, I request the following improvements:

Please update the README to clearly reflect the intended usage and component structure.
Review the codebase to identify areas where naming conventions and error handling can be improved for better clarity and consistency.
Ensure that types defined within a crate are not unnecessarily exposed using pub unless required.

bharatGoswami8 · 2026-05-29T04:10:32Z

where is your lib build ?
I would suggest keep seperate toml file for both app and lib and from main toml you can build both.

Thanks for adding separate toml file for app in same way we need to create toml file for src folder which is library build,

bharatGoswami8 · 2026-05-29T04:13:59Z

-It accepts UDS requests over DoIP (Diagnostics over IP), resolves the corresponding SOVD service
-using the diagnostic description (MDD) of the ECU, and translates them into SOVD REST API calls.
-The SOVD responses are then encoded back into UDS format and returned to the requesting tool.
+It accepts UDS requests over DoIP (Diagnostics over IP, [ISO 13400-2](https://www.iso.org/standard/74785.html)), resolves the corresponding SOVD service using the diagnostic description (MDD) of the ECU, and translates them into SOVD REST API calls. The SOVD responses are then encoded back into UDS format and returned to the requesting tool.


diagnostic description (MDD) ? what is M here ?

this will be updated in future integration, deleting for now

bharatGoswami8 · 2026-05-29T04:52:15Z

+//! from different sources (in-memory, TOML file).
+
+pub mod in_memory;
+pub mod toml;


toml is not ideal name in my opinion.

Any update on this ?

I have aliased as Toml_provider.

bharatGoswami8 · 2026-05-29T04:57:30Z

+};
+
+/// 17 (VIN) + 2 (addr) + 6 (EID) + 6 (GID) + 1 (action byte) = 32
+pub(super) const VI_RESPONSE_LEN: usize = 32;


how about keeping in constants ?

Good point. VI_RESPONE_LEN is only used in create_vi_response() in common.rs so its local implementation rather than protocol level constant.

in that case why it is pub ?

Agree. It doesn't need to public: I've made as Private.

Thank you

bharatGoswami8 · 2026-05-29T04:59:29Z

where is toml file for this ?

Agreed. A separate Cargo.toml has been added for the client, It's now its own binary crate in the workspace.

rpreddyhv

Completed my initial review.

rpreddyhv · 2026-05-29T06:36:29Z

+pub const NACK_OUT_OF_MEMORY: u8 = 0x03;
+
+/// Payload length field does not match actual payload size.
+pub const NACK_INVALID_PAYLOAD_LENGTH: u8 = 0x04;


thought: These are different variation of Nack. I think it is better to group them in an enum and belong to message.rs like TcpPayloadType & UdpPayloadType.

Agree. Grouping the NACK codes into an enum would be cleaner. Will add as a future improvement.

I think introducing an enum makes code better with respect to readability, collection of similar things into one, keeps related concerns together and avoid disinformation. We can consider incorporating this instead of differing if not a huge effort.

Yes, I’ve created the Enum in message.rs and grouped the NACK codes there for better readability and type safety.

rpreddyhv · 2026-05-29T06:42:52Z

+        let result = dispatcher.dispatch(make_req(TcpPayloadType::DiagnosticMessage));
+        assert!(matches!(result, Err(Error::UnknownPayloadType(0x8001))));
+    }
+}


suggestion: There are no tests to show that we can't register UdpHandler to TcpDispatcher or vice-versa.

If you try to register a UDP handler on a TCP dispatcher, the code simply won't compile — Rust's type system enforces this at compile time. I can add a compile_fail doc test to document this. Open for suggestions.

That would help future developer as registering a handler to dispatcher is critical part of extension.

rpreddyhv · 2026-05-29T07:22:15Z

nitpick: I guess you didn't need to remove the existing entries in this file.

yeah. reverted

VinaykumarRS1995

I have incorporated the review feedback and pushed the updates. Thanks for taking the time to review the changes.

VinaykumarRS1995 · 2026-05-29T05:54:42Z

+    session resources released automatically
+end note
+
+@enduml


VinaykumarRS1995 · 2026-05-29T13:23:09Z

-It accepts UDS requests over DoIP (Diagnostics over IP), resolves the corresponding SOVD service
-using the diagnostic description (MDD) of the ECU, and translates them into SOVD REST API calls.
-The SOVD responses are then encoded back into UDS format and returned to the requesting tool.
+It accepts UDS requests over DoIP (Diagnostics over IP, [ISO 13400-2](https://www.iso.org/standard/74785.html)), resolves the corresponding SOVD service using the diagnostic description (MDD) of the ECU, and translates them into SOVD REST API calls. The SOVD responses are then encoded back into UDS format and returned to the requesting tool.


this will be updated in future integration, deleting for now

rpreddyhv

re-review findings

rpreddyhv · 2026-05-29T14:08:15Z

+        let src = u16::from_be_bytes([req.payload()[0], req.payload()[1]]);
+        let tgt = u16::from_be_bytes([req.payload()[2], req.payload()[3]]);
+        self.forward(src, tgt, &req.payload()[4..])


IMO, variable names must be descriptive and there shouldn't any scope for (mis)interpretation. It is okay to use abbreviations if it is well known (widely used and adopted) acronym like TCP or UDP.

bharatGoswami8 · 2026-06-01T03:51:06Z

+}
+</style>
+
+participant "Main" as Main


I think the Main you mentioned which is from app (main) which is like doip server app, please change from main to server app or some other proper name.

agree. Updated as doip server app

bharatGoswami8 · 2026-06-01T03:55:20Z

I think you no need to create sequence for shutdown because we do not have signal handling.

bharatGoswami8 · 2026-06-01T04:02:43Z

+}
+
+#[cfg(test)]
+pub(super) mod fixtures {


I did not get this why test related data is in pub

The test data is inside a cfg(test) module and marked pub(super) only so other test modules(in request.rs , request_by_eid.rs and request_by_vin.rs) can reuse it without duplicating the same VIN/EID/GID setup. That visibility is limited to the parent module tree, so it is not exposed outside the vehicle identification tests.

bharatGoswami8 · 2026-06-01T04:03:44Z

+/// [25..31] GID
+/// [31]     further action required (0x00 = none)
+/// ```
+pub(super) fn create_vi_response(


no test for this function, and why this is free function ?

Since this is a helper function, it only combines the EcuConfig and logical address into a response payload.
I agree that there is no direct unit test for this function, but its behavior is indirectly covered by the handler tests.

bharatGoswami8 · 2026-06-01T04:11:46Z

+
+//! Handler for VehicleIdentificationRequest (0x0001, ISO 13400-2 §7.6.1).
+
+use super::common::create_vi_response;


Why we want to use free function ?

Because the logic is stateless, small, and shared across multiple handlers, it is kept in one place to avoid duplication. To keep the code simple and maintainable, we implemented it as a free function.

bharatGoswami8 · 2026-06-01T04:15:57Z

+            req.payload()[5],
+        ]);
+        if requested != self.ecu_config.eid() {
+            return Err(Error::NoMatch);


Suggested change

return Err(Error::NoMatch);

return Err(Error::EIDNotMatched);

I agree, clearer naming.

bharatGoswami8 · 2026-06-01T04:30:39Z

+   ```
+2. Or with a TOML config file (see [`sample-doip-server.toml`](sample-doip-server.toml)):
+   ```sh
+   cargo run -p doip-server -- path/to/config.toml


Suggested change

cargo run -p doip-server -- path/to/config.toml

cargo run -p doip-server -- <path of config toml file>

bharatGoswami8 · 2026-06-01T04:33:18Z

-### testing
+### Testing

-#### unit tests
+#### Unit Tests

-Unittests are placed in the relevant module as usual in rust:
+Unit tests are placed in the relevant module as usual in Rust:
 ```rust
 ...
 #[cfg(test)]
-mod test {
+mod tests {
    ...
 }
 ```

 Run unit tests with:
-```shell
+```sh
 cargo test --locked --lib


I don't know whether we should keep this in README file or not, please check once.

I placed same place as CDA

bharatGoswami8 · 2026-06-01T04:34:35Z

+
+Start the proxy, then run the E2E tester:
+```sh
+cargo run -p doip-server &


why &, you should ask user to run in separate terminal to debug and check logs.

yes, that's cleaner

bharatGoswami8

@VinaykumarRS1995 , please check some latest comment and reply to older comment which is not addressed.

- Convert to Cargo workspace (lib + app + client) - Narrow tokio features to specific set - Refactor handlers to accept EcuConfig directly - Tighten visibility (pub(super), pub(in crate::...)) - Remove DEFAULT_ prefix in defaults module - Add compile_fail doc test for transport segregation - Add TODO comments for future improvements - Update README (headings, commands, abbreviations) - Add sample-doip-server.toml - Regenerate SVGs from updated puml sources

VinaykumarRS1995 added 14 commits May 28, 2026 15:14

Add project README and sequence diagrams

1a78b66

Document DoIP server block diagram, supported message types, and build instructions. Include PlantUML diagrams for startup, TCP connection, UDP request, and graceful shutdown flows. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Set up Cargo project with dependencies and module structure

2dbe504

Define crate as library and binary. Add tokio, serde, toml, tracing, and thiserror dependencies. Declare top-level modules. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Add configuration module with pluggable provider trait

f1ef360

Introduce ServerConfig for TCP, UDP, and ECU identity settings. Provide InMemoryProvider for defaults and TomlProvider for file-based configuration loading. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Define DoIP protocol data model and message types

018e678

Implement 8-byte header parsing with version validation. Define TcpPayloadType and UdpPayloadType enums for all supported message types (0x0001-0x8003) per ISO 13400-2. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Add SOVD proxy trait with stub and mock implementations

36d9971

Define SovdProxy trait with forward() for UDS byte translation. StubProxy returns NRC 0x11 pending real backend integration. MockProxy echoes input for unit testing. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Implement alive check and routing activation TCP handlers

762050b

Add AliveCheck (0x0007) responding to keep-alive pings. RoutingActivation (0x0005) returns 0x10 as placeholder until full state-machine logic is implemented. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Add session manager with RAII connection tracking

e265972

Enforce max concurrent TCP connections using atomic counter. SessionSlot acts as RAII guard that auto-releases on drop, ensuring cleanup on disconnection or task cancellation. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Wire server struct combining TCP and UDP transports

5c9b43e

Add Server struct that starts both listeners concurrently and coordinates graceful shutdown via cancellation token. Signed-off-by: VinaykumarRS1995 <Vinaykumarrs1995@gmail.com>

Merge upstream main

b97d7af

bharatGoswami8 reviewed May 28, 2026

View reviewed changes

Comment thread docs/Graceful Shutdown.svg Outdated

bharatGoswami8 reviewed May 28, 2026

View reviewed changes

Comment thread docs/01-startup.puml Outdated

bharatGoswami8 reviewed May 28, 2026

View reviewed changes

Comment thread docs/02-tcp-connection.puml Outdated

bharatGoswami8 reviewed May 28, 2026

View reviewed changes

Comment thread docs/03-udp-request.puml Outdated

bharatGoswami8 reviewed May 29, 2026

View reviewed changes

rpreddyhv suggested changes May 29, 2026

View reviewed changes

VinaykumarRS1995 commented May 29, 2026

View reviewed changes

rpreddyhv suggested changes May 29, 2026

View reviewed changes

VinaykumarRS1995 force-pushed the doip-server-1.0 branch from 14f01bf to c89333a Compare May 30, 2026 02:22

bharatGoswami8 reviewed Jun 1, 2026

View reviewed changes

bharatGoswami8 suggested changes Jun 1, 2026

View reviewed changes

VinaykumarRS1995 force-pushed the doip-server-1.0 branch from c89333a to a0fd1bf Compare June 1, 2026 11:58


		//! Handler for VehicleIdentificationRequest (0x0001, ISO 13400-2 §7.6.1).

		use super::common::create_vi_response;

	return Err(Error::NoMatch);
	return Err(Error::EIDNotMatched);

	cargo run -p doip-server -- path/to/config.toml
	cargo run -p doip-server -- <path of config toml file>

Conversation

VinaykumarRS1995 commented May 28, 2026

Summary

Checklist

Related

Notes for Reviewers

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bharatGoswami8 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bharatGoswami8 Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rpreddyhv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

bharatGoswami8 Jun 1, 2026 •

edited

Loading

rpreddyhv May 29, 2026 •

edited

Loading