Crate dsh_sdk

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:

feature	default	Description	Example
bootstrap	✓	Certificate signing process and fetch datastreams properties	Kafka / Kafka Proxy
kafka	✓	Enable DshKafkaConfig trait and Config struct to connect to DSH	Kafka / Kafka Proxy
rdkafka-config	✓	Enable DshKafkaConfig implementation for RDKafka	Kafka / Kafka Proxy
schema-store	✗	Interact with DSH Schema Store	Schema Store API
protocol-token	✗	Fetch tokens to use DSH Protocol adapters (MQTT and HTTP)	Mqtt client / Mqtt websocket client / Token fetcher (full mediation) / Token fetcher (partial mediation)
management-api-token-fetcher	✗	Fetch tokens to use DSH Management API	Token fetcher
metrics	✗	Enable prometheus metrics including http server	Expose metrics
graceful-shutdown	✗	Tokio based graceful shutdown handler	Graceful shutdown
dlq	✗	Dead Letter Queue implementation	Full implementation example

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.

Modules

certificates

Handles DSH certificates and the bootstrap process.

datastream

Datastream properties for DSH.

dsh

High-level API for interacting with DSH when your container is running on DSH.

management_api

Fetch and store tokens for the DSH Management Rest API client

protocol_adapters

The DSH Protocol adapters (HTTP, Kafka, MQTT)

schema_store

Schema Store client

utils

Utilities for DSH

Structs

Dsh

Lazily initializes all related components to connect to DSH and Kafka.

ManagementApiTokenFetcher

A fetcher for obtaining and storing access tokens, enabling authenticated requests to DSH’s management (REST) API.

ManagementApiTokenFetcherBuilder

A builder for constructing a ManagementApiTokenFetcher.

Enums

DshError

Errors defined in Dsh.

Platform

Represents an available DSH platform and its related metadata.

Traits

DshKafkaConfig

Trait defining core DSH configurations for Kafka consumers and producers.