dsh-sdk-platform-rs

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.

Table of Contents

1. Migration Guide
2. Description
3. Usage
4. Connecting to DSH
5. Feature Flags
6. Environment Variables
7. Examples
8. Changelog
9. Contributing
10. License
11. Security

Migration Guide

If you are migrating from v0.4.X, please see the migration guide for details on breaking changes and how to update your code accordingly.

Description

The dsh-sdk-platform-rs library offers:

• DSH Kafka Connectivity

  • Trait for getting DSH Compatible Kafka Clients (DSH, Proxy, VPN and Local)
    • RDKafka implementation included
  • Handles datastream information retrieval, certificate signing (bootstrap), and PKI configuration.

• Certificates

  • Sign certificates which can be used for secure communication with DSH Kafka and (m)TLS transport between containers.

• Token Fetchers

  • Management API Token Fetcher: For use with dsh_rest_api_client.
  • Protocol Token Fetcher: Obtain tokens for MQTT and HTTP protocol adapters.

• Schema Store Interaction

  • Fetch and manage schema from the DSH Schema Store.

• Common Utilities

  • Lightweight HTTP server for exposing Metrics.
  • Tokio-based graceful shutdown handling.
  • Dead Letter Queue (DLQ) functionality.

Usage

To get started, add the following to your Cargo.toml:

[dependencies]
dsh_sdk = "0.7"
rdkafka = { version = "0.38", features = ["cmake-build", "ssl-vendored"] }

Note
By default, this SDK enables several features (see Feature Flags). If you do not need them all, you can disable default features to reduce compile times and dependencies.

Example

use dsh_sdk::DshKafkaConfig; // Trait for applying DSH-specific configurations
use rdkafka::consumer::{Consumer, StreamConsumer};
use rdkafka::ClientConfig;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure an rdkafka consumer with DSH settings
    let consumer: StreamConsumer = ClientConfig::new()
        .set_dsh_consumer_config()
        .create()?;

    // Your application logic here

    Ok(())
}

Connect to DSH

This SDK accommodates multiple deployment environments:

• Running in a container on a DSH tenant
• Running in DSH System Space
• Running on a machine with Kafka Proxy/VPN
• Running locally with a local Kafka instance

For more information, see the CONNECT_PROXY_VPN_LOCAL.md document.

Feature Flags

Important
The feature flags have changed since the v0.5.X update. Check the migration guide for details.

Below is an overview of the available features:

Selecting Features

To pick only the features you need, disable the default features and enable specific ones. For instance, if you only want the Management API Token Fetcher:

[dependencies]
dsh_sdk = { version = "0.7", default-features = false, features = ["management-api-token-fetcher"] }

Environment Variables

This SDK uses certain environment variables to configure connections to DSH. For a full list of supported variables and their usage, see ENV_VARIABLES.md.

Examples

You can find simple usage examples in the examples/ directory.

Full Service Example

A more complete example is provided in the example_dsh_service/ directory, showcasing:

• How to build the Rust project
• How to package and push it to Harbor
• An end-to-end setup of a DSH service uising Kafka

See the README in that directory for more information.

Changelog

All changes per version are documented in CHANGELOG.md.

Contributing

Contributions are welcome! For details on how to help improve this project, please see CONTRIBUTING.md.

License

This project is licensed under the Apache License 2.0.

Security

For information about the security policy of this project, including how to report vulnerabilities, see SECURITY.md.

© Koninklijke KPN N.V.