Finalize release, minor improvements (#117)

* update README and examples

* add note upgrade to v0.6

* Add AccessToken to public API

* Into instead of AsRef

* improve some minor stuff

* add fav-icon and kpn logo to docs

* cargo fmt

dsh_rest_api_client/README.md

@@ -37,15 +37,15 @@ It is recommended to use the Rest Token Fetcher from the `dsh_sdk` crate. To do
 
 ```toml
 [dependencies]
-dsh_rest_api_client = "0.2.0"
-dsh_sdk = { version = "0.4", features = ["rest-token-fetcher"], default-features = false }
+dsh_rest_api_client = "0.3.0"
+dsh_sdk = { version = "0.5", features = ["management-api-token-fetcher"], default-features = false }
 tokio = { version = "1", features = ["full"] }
 ```
 
 To use the client in your project:
 ```rust
 use dsh_rest_api_client::Client;
-use dsh_sdk::{Platform, RestTokenFetcherBuilder};
+use dsh_sdk::{Platform, ManagementApiTokenFetcherBuilder};
 
 const CLIENT_SECRET: &str = "";
 const TENANT: &str = "tenant-name";
@@ -55,7 +55,7 @@ async fn main() {
     let platform = Platform::NpLz;
     let client = Client::new(platform.endpoint_rest_api());
 
-    let tf = RestTokenFetcherBuilder::new(platform)
+    let tf = ManagementApiTokenFetcherBuilder::new(platform)
         .tenant_name(TENANT.to_string())
         .client_secret(CLIENT_SECRET.to_string())
         .build()

dsh_sdk/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.5.0] - unreleased
+## [0.5.0] - 2025-01-21
 ### Added
 - DSH Kafka Config trait to configure kafka client with RDKafka implementation
 - DSH Schema store API Client
@@ -31,7 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Private module `dsh_sdk::dsh::bootstrap` and `dsh_sdk::dsh::pki_config_dir` are now part of `certificates` module
 - **Breaking change:** Moved `dsh_sdk::mqtt_token_fetcher` to `dsh_sdk::protocol_adapters::token` and renamed to `ApiClientTokenFetcher`
   - **NOTE** The code is refactored to follow the partial mediation and full mediation pattern
-  - **NOTE** Cargo.toml feature flag `mqtt-token-fetcher`  renamed to `protocol-token-fetcher`
+  - **NOTE** Cargo.toml feature flag `mqtt-token-fetcher`  renamed to `protocol-token`
 - **Breaking change:** Renamed  `dsh_sdk::Platform` methods to more meaningful names
 - **Breaking change:** Moved `dsh_sdk::dlq` to `dsh_sdk::utils::dlq` 
 - **Breaking change:** Moved `dsh_sdk::graceful_shutdown` to `dsh_sdk::utils::graceful_shutdown`

dsh_sdk/Cargo.toml

@@ -9,7 +9,7 @@ license.workspace = true
 name = "dsh_sdk"
 readme = 'README.md'
 repository.workspace = true
-version = "0.5.0-rc.2"
+version = "0.5.0"
 
 [package.metadata.docs.rs]
 all-features = true
@@ -48,13 +48,16 @@ rdkafka-config = ["rdkafka", "kafka"] # Impl of config trait only
 schema-store = ["bootstrap", "reqwest", "serde_json", "apache-avro", "protofish"]
 graceful-shutdown = ["tokio", "tokio-util"]
 management-api-token-fetcher = ["reqwest"]
-protocol-token-fetcher = ["base64", "reqwest", "serde_json", "sha2", "tokio/sync"]
+protocol-token = ["base64", "reqwest", "serde_json", "sha2", "tokio/sync"]
 metrics = [ "hyper/server", "hyper/http1" , "hyper-util", "http-body-util", "tokio", "bytes"]
 dlq = ["tokio", "bootstrap", "rdkafka-config", "rdkafka/cmake-build", "rdkafka/ssl-vendored", "rdkafka/libz", "rdkafka/tokio", "graceful-shutdown"]
 
-# http-protocol-adapter = ["protocol-token-fetcher"]
-# mqtt-protocol-adapter = ["protocol-token-fetcher"]
+# http-protocol-adapter = ["protocol-token"]
+# mqtt-protocol-adapter = ["protocol-token"]
 # hyper-client = ["hyper", "hyper-util", "hyper-rustls", "rustls", "http", "rustls-pemfile"]
+# deprecated!
+mqtt-token-fetcher = ["protocol-token"]
+rest-token-fetcher = ["management-api-token-fetcher"]
 
 
 [dev-dependencies]

dsh_sdk/README.md

@@ -8,9 +8,6 @@
 
 A Rust SDK to interact with the DSH Platform. This library provides convenient building blocks for services that need to connect to DSH Kafka, fetch tokens for various protocols, manage Prometheus metrics, and more.
 
-> **Note**  
-> This library (v0.5.x) is a _release candidate_. It may contain incomplete features and/or bugs. Future updates might introduce breaking changes. Please report any issues you find.
-
 ---
 
 ## Table of Contents
@@ -31,7 +28,9 @@ A Rust SDK to interact with the DSH Platform. This library provides convenient b
 
 ## Migration Guide 0.4.X -> 0.5.X
 
-If you are migrating from `0.4.X` to `0.5.X`, please see the [migration guide](https://github.com/kpn-dsh/dsh-sdk-platform-rs/wiki/Migration-guide-(v0.4.X-%E2%80%90--v0.5.X)) for details on breaking changes and how to update your code accordingly.
+If you are migrating from `v0.4.X` to `v0.5.X`(or `v0.6.X`), please see the [migration guide](https://github.com/kpn-dsh/dsh-sdk-platform-rs/wiki/Migration-guide-(v0.4.X-%E2%80%90--v0.5.X)) for details on breaking changes and how to update your code accordingly.
+
+`v0.6.0` will not contain any breaking changes, except for the removal of deprecated code. You can use `v0.5.X` as a stepping stone to `v0.6.0` by following the deprecation warnings the compiler gives.
 
 ---
 
@@ -52,7 +51,7 @@ The `dsh-sdk-platform-rs` library offers:
   - **RDKafka** implementation
 
 - **Common Utilities**  
-  - Prometheus metrics (built-in HTTP server, plus re-export of the `metrics` crate).  
+  - Lightweight HTTP server for exposing Metircs.  
   - Tokio-based graceful shutdown handling.  
   - Dead Letter Queue (DLQ) functionality.
 
@@ -64,7 +63,7 @@ To get started, add the following to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-dsh_sdk = "0.5.0-rc.2"
+dsh_sdk = "0.5"
 rdkafka = { version = "0.37", features = ["cmake-build", "ssl-vendored"] }
 ```
 
@@ -118,7 +117,7 @@ Below is an overview of the available features:
 | `kafka`                        | ✓           | Enable `DshKafkaConfig` trait and Config struct to connect to DSH | [Kafka](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/kafka_example.rs) / [Kafka Proxy](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/kafka_proxy.rs) |
 | `rdkafka-config`               | ✓           | Enable `DshKafkaConfig` implementation for RDKafka                | [Kafka](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/kafka_example.rs) / [Kafka Proxy](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/kafka_proxy.rs) |
 | `schema-store`                 | ✗           | Interact with DSH Schema Store                                    | [Schema Store API](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/schema_store_api.rs)                                                                                   |
-| `protocol-token-fetcher`       | ✗           | Fetch tokens to use DSH Protocol adapters (MQTT and HTTP)         | [Mqtt client](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/mqtt_example.rs.rs) / [Mqtt websocket client](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/mqtt_example.rs.rs) /<br>[token fetcher (full mediation)](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/protocol_authentication_full_mediation.rs) / [token fetcher (partial mediation)](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/protocol_authentication_partial_mediation.rs) |
+| `protocol-token`       | ✗           | Fetch tokens to use DSH Protocol adapters (MQTT and HTTP)         | [Mqtt client](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/mqtt_example.rs.rs) / [Mqtt websocket client](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/mqtt_example.rs.rs) /<br>[Token fetcher (full mediation)](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/protocol_authentication_full_mediation.rs) / [Token fetcher (partial mediation)](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/protocol_authentication_partial_mediation.rs) |
 | `management-api-token-fetcher` | ✗           | Fetch tokens to use DSH Management API                            | [Token fetcher](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/management_api_token_fetcher.rs)     |
 | `metrics`                      | ✗           | Enable prometheus metrics including http server                   | [Expose metrics](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/expose_metrics.rs)                  |
 | `graceful-shutdown`            | ✗           | Tokio based graceful shutdown handler                             | [Graceful shutdown](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/dsh_sdk/examples/graceful_shutdown.rs)            |
@@ -130,7 +129,7 @@ To pick only the features you need, disable the default features and enable spec
 
 ```toml
 [dependencies]
-dsh_sdk = { version = "0.5.0-rc.2", default-features = false, features = ["management-api-token-fetcher"] }
+dsh_sdk = { version = "0.5", default-features = false, features = ["management-api-token-fetcher"] }
 ```
 
 ---
@@ -151,7 +150,7 @@ A more complete example is provided in the [`example_dsh_service/`](https://gith
 
 - How to build the Rust project
 - How to package and push it to Harbor
-- An end-to-end setup of a DSH service
+- An end-to-end setup of a DSH service uising Kafka
 
 See the [README](https://github.com/kpn-dsh/dsh-sdk-platform-rs/blob/main/example_dsh_service/README.md) in that directory for more information.
 

dsh_sdk/examples/mqtt_ws_example.rs

@@ -31,7 +31,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // Start logger to Stdout to show what is happening
     env_logger::builder()
-        .filter_level(log::LevelFilter::Trace)
+        .filter(Some("dsh_sdk"), log::LevelFilter::Trace)
         .target(env_logger::Target::Stdout)
         .init();
 

dsh_sdk/examples/protocol_authentication_full_mediation.rs

@@ -33,9 +33,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Assume the API Authentication service receives a request from an external client.
     // We want to delegate a DataAccessToken with the following properties:
     // - Valid for 10 minutes
-    // - Allows fetching another DataAccessToken with:
-    //   - Maximum expiration of 5 minutes
-    //   - Usage restricted to the external client ID "External-client-id"
+    // - Allows subscribing to the topic "state/app/{tenant_name}" in the "amp" stream
 
     // Instantiate the API Client Token Fetcher
     let token_fetcher = ApiClientTokenFetcher::new(api_key, PLATFORM);

dsh_sdk/src/dsh.rs

@@ -40,7 +40,7 @@ use crate::protocol_adapters::kafka_protocol::config::KafkaConfig;
 // TODO: Remove at v0.6.0
 pub use crate::dsh_old::*;
 
-/// Lazily initializes all related components to connect to DSH:
+/// Lazily initializes all related components to connect to DSH and Kafka.
 /// - Information from `datastreams.json`
 /// - Metadata of the running container/task
 /// - Certificates for Kafka and DSH Schema Registry

dsh_sdk/src/error.rs

@@ -5,7 +5,7 @@
 //! includes a helper function, [`report`], for generating a more readable error
 //! trace by iterating over source causes.
 
-/// The main error type for the DSH SDK.
+/// Errpors defined in [`Dsh`](super::Dsh).
 ///
 /// This enum wraps more specific errors from different parts of the SDK:
 /// - [`CertificatesError`](crate::certificates::CertificatesError)