Standard Digital Twin and Service Discovery Adapters (#138)

Refactors the Ibeji and Chariott adapters to use them as standard adapters. Also includes a minor improvement to the spellcheck script to make identifying errors in workflow runs easier. Fixes #124
eclipse-ibeji · Feb 23, 2024 · b1986a4 · b1986a4
1 parent 3a94989
commit b1986a4
Show file tree

Hide file tree

Showing 23 changed files with 108 additions and 122 deletions.
diff --git a/.accepted_words.txt b/.accepted_words.txt
@@ -49,14 +49,15 @@ DataAdapterFactory
 depgen
 der
 dev
+DigitalTwinAdapter
 digitaltwins
 dir
+DiscoveryRequest
 DotNet
 dotnet
 DT
 DTDL
 dtdl
-DigitalTwinAdapter
 dyn
 ECA
 en
@@ -90,6 +91,7 @@ Impl
 InMemoryMockDigitalTwinAdapter
 InMemoryMockDataAdapter
 intellectualproperty
+invehicle
 io
 IoT
 iot

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -13,13 +13,13 @@ members = [
   "adapters/data/managed_subscribe_data_adapter",
   "adapters/data/mqtt_data_adapter",
   "adapters/data/sample_grpc_data_adapter",
-  "adapters/digital_twin/ibeji_adapter",
+  "adapters/digital_twin/grpc_digital_twin_adapter",
   "adapters/digital_twin/in_memory_mock_digital_twin_adapter",
   "adapters/digital_twin/mock_digital_twin_adapter",
   "adapters/mapping/in_memory_mock_mapping_adapter",
   "adapters/mapping/mock_mapping_service_adapter",
-  "adapters/service_discovery/chariott_service_discovery_adapter",
   "adapters/service_discovery/file_service_discovery_adapter",
+  "adapters/service_discovery/grpc_service_discovery_adapter",
   "build_common",
   "common",
   "freyja",
@@ -30,14 +30,14 @@ members = [
 ]
 
 [workspace.dependencies]
-# Freyja dependencies
-chariott-service-discovery-adapter = { path = "adapters/service_discovery/chariott_service_discovery_adapter" }
+# Freyja libraries from this workspace
 cloud-connector-proto = { path = "proto/cloud_connector" }
 file-service-discovery-adapter = { path = "adapters/service_discovery/file_service_discovery_adapter" }
 freyja-build-common = { path = "build_common" }
 freyja-common = { path = "common" }
+grpc-digital-twin-adapter = { path = "adapters/digital_twin/grpc_digital_twin_adapter" }
+grpc-service-discovery-adapter = { path = "adapters/service_discovery/grpc_service_discovery_adapter" }
 http-mock-data-adapter = { path = "adapters/data/http_mock_data_adapter" }
-ibeji-adapter = { path = "adapters/digital_twin/ibeji_adapter" }
 in-memory-mock-cloud-adapter = { path = "adapters/cloud/in_memory_mock_cloud_adapter" }
 in-memory-mock-data-adapter = { path = "adapters/data/in_memory_mock_data_adapter" }
 in-memory-mock-digital-twin-adapter = { path ="adapters/digital_twin/in_memory_mock_digital_twin_adapter" }

diff --git a/adapters/cloud/grpc_cloud_adapter/README.md b/adapters/cloud/grpc_cloud_adapter/README.md
@@ -6,7 +6,7 @@ The gRPC Cloud Adapter is intended to function as a "standard cloud adapter", en
 
 This adapter utilizes a gRPC client for the `CloudConnector` service in the [cloud connector v1 protobuf description](../../../interfaces/cloud_connector/v1/cloud_connector.proto). To integrate a cloud connector with this adapter, you will need to implement a gRPC server for this service. Samples can be found in the [Ibeji Example Applications Repository](https://github.com/eclipse-ibeji/ibeji-example-applications/tree/main/cloud_connectors/).
 
-## Config
+## Configuration
 
 This adapter supports the following configuration settings:
 

diff --git a/...ers/digital_twin/ibeji_adapter/Cargo.toml → ...twin/grpc_digital_twin_adapter/Cargo.toml b/...ers/digital_twin/ibeji_adapter/Cargo.toml → ...twin/grpc_digital_twin_adapter/Cargo.toml
@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 [package]
-name = "ibeji-adapter"
+name = "grpc-digital-twin-adapter"
 version = "0.1.0"
 edition = "2021"
 license = "MIT"

diff --git a/adapters/digital_twin/grpc_digital_twin_adapter/README.md b/adapters/digital_twin/grpc_digital_twin_adapter/README.md
@@ -0,0 +1,17 @@
+# gRPC Digital Twin Adapter
+
+The gRPC Digital Twin Adapter is intended to function as a "standard digital twin adapter". It can be used to integrate with in-vehicle digital twin services such as [Ibeji](https://github.com/eclipse-ibeji/ibeji). This adapter also supports service discovery to integrate with service discovery systems such as [Chariott](https://github.com/eclipse-chariott/chariott/blob/main/service_discovery/README.md).
+
+## Ibeji Integration
+
+This adapter implements the [Ibeji In-Vehicle Digital Twin Service API](https://github.com/eclipse-ibeji/ibeji/blob/main/interfaces/invehicle_digital_twin/v1/invehicle_digital_twin.proto) and therefore supports Ibeji integration. In order to use Ibeji with this adapter, you must ensure that the `service_discovery_id` in the config file identifies the Ibeji digital twin service in your service discovery system.
+
+## Configuration
+
+This adapter supports the following configuration settings:
+
+- `service_discovery_id`: The id of the in-vehicle digital twin service in your service discovery system.
+- `max_retries`: The maximum number of times to retry failed attempts to send data to the server.
+- `retry_interval_ms`: The interval between subsequent retry attempts, in milliseconds
+
+This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `grpc_digital_twin_adapter_config.json`, and the default config is located at `res/grpc_digital_twin_adapter_config.default.json`.
diff --git a/adapters/digital_twin/ibeji_adapter/build.rs → ...l_twin/grpc_digital_twin_adapter/build.rs b/adapters/digital_twin/ibeji_adapter/build.rs → ...l_twin/grpc_digital_twin_adapter/build.rs
@@ -4,7 +4,7 @@
 
 use freyja_build_common::copy_config;
 
-const CONFIG_FILE_STEM: &str = "ibeji_adapter_config";
+const CONFIG_FILE_STEM: &str = "grpc_digital_twin_adapter_config";
 
 fn main() {
     copy_config(CONFIG_FILE_STEM);

diff --git a/...ter/res/ibeji_adapter_config.default.json → ..._digital_twin_adapter_config.default.json b/...ter/res/ibeji_adapter_config.default.json → ..._digital_twin_adapter_config.default.json
diff --git a/.../digital_twin/ibeji_adapter/src/config.rs → ...n/grpc_digital_twin_adapter/src/config.rs b/.../digital_twin/ibeji_adapter/src/config.rs → ...n/grpc_digital_twin_adapter/src/config.rs
diff --git a/...l_twin/ibeji_adapter/src/ibeji_adapter.rs → ..._adapter/src/grpc_digital_twin_adapter.rs b/...l_twin/ibeji_adapter/src/ibeji_adapter.rs → ..._adapter/src/grpc_digital_twin_adapter.rs
@@ -26,13 +26,13 @@ use freyja_common::{
     service_discovery_adapter_selector::ServiceDiscoveryAdapterSelector,
 };
 
-/// Contacts the In-Vehicle Digital Twin Service in Ibeji
-pub struct IbejiAdapter {
+/// Communicates with an In-Vehicle Digital Twin Service
+pub struct GRPCDigitalTwinAdapter {
     client: InvehicleDigitalTwinClient<Channel>,
 }
 
 #[async_trait]
-impl DigitalTwinAdapter for IbejiAdapter {
+impl DigitalTwinAdapter for GRPCDigitalTwinAdapter {
     /// Creates a new instance of a DigitalTwinAdapter with default settings
     ///
     /// # Arguments
@@ -117,7 +117,7 @@ impl DigitalTwinAdapter for IbejiAdapter {
 }
 
 #[cfg(test)]
-mod ibeji_digital_twin_adapter_tests {
+mod grpc_digital_twin_adapter_tests {
     use core_protobuf_data_access::invehicle_digital_twin::v1::{
         invehicle_digital_twin_server::InvehicleDigitalTwin, EndpointInfo, EntityAccessInfo,
         FindByIdResponse as IbejiFindByIdResponse, RegisterRequest, RegisterResponse,
@@ -229,7 +229,7 @@ mod ibeji_digital_twin_adapter_tests {
 
             let request_future = async {
                 let client = create_test_grpc_client(bind_path.clone()).await;
-                let ibeji_digital_twin_adapter = IbejiAdapter { client };
+                let ibeji_digital_twin_adapter = GRPCDigitalTwinAdapter { client };
 
                 let request = FindByIdRequest {
                     entity_id: String::from("invalid_entity"),

diff --git a/...ers/digital_twin/ibeji_adapter/src/lib.rs → ...twin/grpc_digital_twin_adapter/src/lib.rs b/...ers/digital_twin/ibeji_adapter/src/lib.rs → ...twin/grpc_digital_twin_adapter/src/lib.rs
@@ -3,4 +3,4 @@
 // SPDX-License-Identifier: MIT
 
 mod config;
-pub mod ibeji_adapter;
+pub mod grpc_digital_twin_adapter;
diff --git a/adapters/digital_twin/ibeji_adapter/README.md b/adapters/digital_twin/ibeji_adapter/README.md
diff --git a/adapters/service_discovery/chariott_service_discovery_adapter/README.md b/adapters/service_discovery/chariott_service_discovery_adapter/README.md
diff --git a/adapters/service_discovery/file_service_discovery_adapter/README.md b/adapters/service_discovery/file_service_discovery_adapter/README.md
@@ -4,7 +4,7 @@ The File Service Discovery Adapter retrieves service URIs from a config file. Th
 
 ## Service Discovery ID Format
 
-There is no required format for service IDs for this adapter. The adapter will use the requested IDs to look up the service from the config. If using this adapter as a fallback for other service discovery adapters, it's recommended to use config keys which exactly match the IDs expected by the primary adapter(s). The default config for this adapter matches with the format expected by the [Chariott Service Discovery Adapter](../chariott_service_discovery_adapter/README.md).
+There is no required format for service IDs for this adapter. The adapter will use the requested IDs to look up the service from the config. If using this adapter as a fallback for other service discovery adapters, it's recommended to use config keys which exactly match the IDs expected by the primary adapter(s). The default config for this adapter matches with the format expected by the [gRPC Service Discovery Adapter](../grpc_service_discovery_adapter/README.md).
 
 ## Configuration
 

diff --git a/...iott_service_discovery_adapter/Cargo.toml → ...grpc_service_discovery_adapter/Cargo.toml b/...iott_service_discovery_adapter/Cargo.toml → ...grpc_service_discovery_adapter/Cargo.toml
@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 [package]
-name = "chariott-service-discovery-adapter"
+name = "grpc-service-discovery-adapter"
 version = "0.1.0"
 edition = "2021"
 license = "MIT"

diff --git a/adapters/service_discovery/grpc_service_discovery_adapter/README.md b/adapters/service_discovery/grpc_service_discovery_adapter/README.md
@@ -0,0 +1,30 @@
+# gRPC Service Discovery Adapter
+
+The gRPC Service Discovery Adapter is intended to function as a "standard service discovery adapter". It can be used to integrate with service discovery systems such as the [Chariott Service Discovery system](https://github.com/eclipse-chariott/chariott/blob/main/service_discovery/README.md).
+
+## Chariott Integration
+
+This adapter utilizes the `Discover` function of the [Chariott Service Registry API](https://github.com/eclipse-chariott/chariott/blob/main/service_discovery/proto/core/v1/service_registry.proto) and therefore supports Chariott integration. In order to use Chariott with this adapter, you must ensure that the `uri` entry in the config matches the URI configured for Chariott's service discovery system.
+
+## Service Discovery ID Format
+
+The gRPC Service Discovery Adapter expects service IDs to be in the following format:
+
+<!-- markdownlint-disable-next-line fenced-code-language -->
+```
+{namespace}/{name}/{version}
+```
+
+These parameters correspond to the `DiscoveryRequest` parameters of the same name.
+
+## Configuration
+
+This adapter supports the following configuration settings:
+
+- `uri`: The URI for Chariott's Service Discovery system.
+- `max_retries`: The maximum number of times to retry failed attempts to communicate with Chariott.
+- `retry_interval_ms`: The duration between retries in milliseconds.
+
+### Configuration Overrides
+
+This adapter supports [config overrides](../../../docs/tutorials/config-overrides.md). The override filename is `grpc_service_discovery_adapter_config.json`, and the default config is located at `res/grpc_service_discovery_adapter_config.default.json`.
diff --git a/...ariott_service_discovery_adapter/build.rs → ...y/grpc_service_discovery_adapter/build.rs b/...ariott_service_discovery_adapter/build.rs → ...y/grpc_service_discovery_adapter/build.rs
@@ -4,7 +4,7 @@
 
 use freyja_build_common::copy_config;
 
-const CONFIG_FILE_STEM: &str = "chariott_service_discovery_adapter_config";
+const CONFIG_FILE_STEM: &str = "grpc_service_discovery_adapter_config";
 
 fn main() {
     copy_config(CONFIG_FILE_STEM);

diff --git a/...ice_discovery_adapter_config.default.json → ...ice_discovery_adapter_config.default.json b/...ice_discovery_adapter_config.default.json → ...ice_discovery_adapter_config.default.json
diff --git a/...t_service_discovery_adapter/src/config.rs → ...c_service_discovery_adapter/src/config.rs b/...t_service_discovery_adapter/src/config.rs → ...c_service_discovery_adapter/src/config.rs
@@ -4,10 +4,10 @@
 
 use serde::{Deserialize, Serialize};
 
-/// Configuration for the File Service Discovery Adapter
+/// Configuration for the GRPCServiceDiscoveryAdapter
 #[derive(Clone, Serialize, Deserialize)]
 pub struct Config {
-    /// The Chariott uri
+    /// The service uri
     pub uri: String,
 
     /// The maximum number of retries for communication attempts

diff --git a/...src/chariott_service_discovery_adapter.rs → ...ter/src/grpc_service_discovery_adapter.rs b/...src/chariott_service_discovery_adapter.rs → ...ter/src/grpc_service_discovery_adapter.rs
@@ -21,17 +21,17 @@ use freyja_common::{
     },
 };
 
-/// Interfaces with the Eclipse Chariott service to perform service discovery
-pub struct ChariottServiceDiscoveryAdapter {
+/// Interfaces with a service discovery system to perform service discovery
+pub struct GRPCServiceDiscoveryAdapter {
     /// The adapter config
     config: Config,
 
-    /// The Chariott client
+    /// The service discovery client
     client: ServiceRegistryClient<Channel>,
 }
 
 #[async_trait]
-impl ServiceDiscoveryAdapter for ChariottServiceDiscoveryAdapter {
+impl ServiceDiscoveryAdapter for GRPCServiceDiscoveryAdapter {
     /// Creates a new instance of a `ServiceDiscoveryAdapter` with default settings
     fn create_new() -> Result<Self, ServiceDiscoveryAdapterError> {
         let config: Config = config_utils::read_from_files(

diff --git a/...iott_service_discovery_adapter/src/lib.rs → ...grpc_service_discovery_adapter/src/lib.rs b/...iott_service_discovery_adapter/src/lib.rs → ...grpc_service_discovery_adapter/src/lib.rs
@@ -2,5 +2,5 @@
 // Licensed under the MIT license.
 // SPDX-License-Identifier: MIT
 
-pub mod chariott_service_discovery_adapter;
 mod config;
+pub mod grpc_service_discovery_adapter;