Updated adapter model (#48)

Converts the Freyja binary into a library and requires users to author the final binary application. This doesn't require any unusual build steps like dependency generation or complex environment config, and should make integration and setup much more flexible. Includes the following changes:

- `freyja_main` function and `freyja_main!` macro for integration
- remove dependency generator and related items
- documentation overhaul
- minor change: provide default implementation for `MappingClient::send_inventory`

Closes #45
Also revises #35

.accepted_words.txt

@@ -57,6 +57,7 @@ en
 env
 ESDV
 EntityConfig
+fn
 Fólkvangr
 FREYJA
 Freyja
@@ -87,6 +88,7 @@ IoT
 iot
 IsAirConditioningActive
 json
+kbd
 KeyVault
 keygen
 launchSetting
@@ -99,12 +101,14 @@ MappingClientImpl
 md
 microsoft
 min
+mock's
 MockDigitalTwin
 MockMappingService
 MQTTProviderProxyImpl
 MSRC
 msrc
 mqtt
+mul
 myADT
 myDigitalTwinsName
 myEventgridNamespace
@@ -135,6 +139,7 @@ PrivateKeyName
 proto
 protobuf
 pushd
+queryable
 quickstart
 repo
 req
@@ -151,13 +156,15 @@ signkey
 snapd
 src
 SSL
+stdout
 STRUCT
 struct
 structs
 sudo
 svg
 Thumbprint
 thumbprint
+tokio
 toml
 toolchain
 URI

.github/workflows/rust-ci.yml

@@ -27,8 +27,6 @@ jobs:
           components: clippy rustfmt
       - name: Cache Dependencies
         uses: Swatinem/rust-cache@v2
-      - name: Freyja depgen
-        uses: ./.github/actions/freyja-depgen
       - name: Cargo check workspace
         uses: actions-rs/cargo@v1
         with:
@@ -71,8 +69,6 @@ jobs:
         uses: ./.github/actions/install-rust-toolchain
       - name: Cache Dependencies
         uses: Swatinem/rust-cache@v2
-      - name: Freyja depgen
-        uses: ./.github/actions/freyja-depgen
       - name: Build
         uses: actions-rs/cargo@v1
         with:

.github/workflows/security-audit.yml

@@ -21,8 +21,6 @@ jobs:
           submodules: recursive
       - name: Install Rust toolchain
         uses: ./.github/actions/install-rust-toolchain
-      - name: Freyja depgen
-        uses: ./.github/actions/freyja-depgen
       - name: Cargo audit
         uses: actions-rs/cargo@v1
         with:

.gitignore

@@ -352,8 +352,5 @@ MigrationBackup/
 # Rust build artifacts
 target/
 
-# Files generated by the dependency generator
-__generated/
-
 # Cargo.lock isn't checked in because it doesn't work well with how dependencies are being managed
 Cargo.lock

Cargo.toml

@@ -24,8 +24,6 @@ members = [
   "provider_proxies/in_memory_mock_provider_proxy",
   "provider_proxy_selector",
 ]
-# The workspace will fail to validate before the depgen step, so it must be exlucded in order to run independently
-exclude = ["depgen"]
 
 [workspace.dependencies]
 # Freyja dependencies

README.md

@@ -8,8 +8,7 @@
 - [Introduction](#introduction)
 - [Getting Started](#getting-started)
   - [Prerequisites](#prerequisites)
-  - [Build](#build)
-  - [Run](#run)
+  - [Using Freyja](#using-freyja)
 - [Why "Freyja"?](#why-freyja)
 - [Trademarks](#trademarks)
 
@@ -37,42 +36,13 @@ The rust toolchain version is managed by the `rust-toolchain.toml` file, so once
 
 1. Clone this repository with `git clone`
 
-### Build
+### Using Freyja
 
-Freyja supports the use of custom library implementations for many of the interfaces with external components. To accomplish this, there is a code generation step that is a required prerequisite for the build.
+To use Freyja, you will need to implement some adapters and write the main executable that will run the Freyja application.
 
-#### Pre-Build
+For a guide on how to get started quickly by running some minimal examples, see the [Quickstart Guide](docs/quickstart.md).
 
-1. Set up your environment. The instructions below are the recommended way to do this, but any other method of setting environment variables will also work if you prefer not to edit your personal Cargo config file(s).
-    1. Copy the template file from `<repo-root>/depgen/res/config.template.toml` to your personal Cargo config at `$CARGO_HOME/cargo.toml` (defaults to `$HOME/.cargo/cargo.toml` on Linux if `$CARGO_HOME` is not set). If you don't already have a Cargo config file you can copy the entire contents of the template; otherwise copy the contents of the `[env]` section into your own config file's `[env]` table. Note that this environment config will only be applied when using Cargo to run the application.
-    1. Modify the values to configure the dependencies you want to use. By default, the template specifies the in-memory mocks. For more information on how to author your own dependencies and configure your environment to use them, see [the documentation on using external libraries](docs/external-libs.md).
-1. Starting from the repo root, build and run the dependency generator application:
-
-```shell
-pushd depgen
-cargo run
-popd
-```
-
-This step only needs to be executed again if the environment variables in your Cargo config change to use different dependencies.
-
-#### Build
-
-Once the pre-build steps are completed, you can build the Freyja application with Cargo:
-
-```shell
-cargo build
-```
-
-### Run
-
-You can run the Freyja application using Cargo:
-
-```shell
-cargo run --bin freyja
-```
-
-Note that the dependencies chosen during the pre-build steps may require other applications to be started as well. In general, everything other than the in-memory libraries will require some kind of external endpoint to be set up.
+For more advanced topics on how to implement and use your own adapters, see the [Custom Adapters Guide](docs/custom-adapters.md).
 
 <!--alex disable he-she her-him brothers-sisters-->
 ## Why "Freyja"?

cloud_adapters/in_memory_mock_cloud_adapter/README.md

@@ -0,0 +1,9 @@
+# In-Memory Mock Cloud Adapter
+
+The In-Memory Mock Cloud Adapter mocks the behavior of the cloud connector from within the memory of the Freyja application. Data which is sent to this adapter will be printed to stdout. This enables a minimal example scenario when working with Freyja. This library contains an implementation of the `CloudAdapter` trait from the contracts.
+
+## Config
+
+The adapter's config is located at `res/config.json` and will be copied to the build output automatically. This file contains the following properties:
+
+- `cloud_service_name` and `host_connection_string`: these are fake values and serve no functional purpose. They are only logged in the output and changing them does not affect the fundamental behavior of the adapter.

contracts/src/mapping_client.rs

@@ -35,8 +35,10 @@ pub trait MappingClient {
     /// - `inventory`: the request to send
     async fn send_inventory(
         &self,
-        inventory: SendInventoryRequest,
-    ) -> Result<SendInventoryResponse, MappingClientError>;
+        _inventory: SendInventoryRequest,
+    ) -> Result<SendInventoryResponse, MappingClientError> {
+        Ok(SendInventoryResponse {})
+    }
 
     /// Gets the mapping from the mapping service
     ///