Skip to content

Latest commit

 

History

History

dsh_sdk

README.md

dsh-sdk-platform-rs

Build Status codecov dependency status License

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 to v0.5.X(or v0.6.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

    • Supports both direct DSH, Kafka Proxy, VPN, and local Kafka.
    • Handles datastream information retrieval, certificate signing (bootstrap), and PKI configuration.

  • Token Fetchers

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

  • DSH Kafka Configuration

    • Trait for getting DSH Compatible Kafka Clients (DSH, Proxy, VPN and Local)
    • RDKafka implementation

  • 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.6"
rdkafka = { version = "0.37", 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.6", 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.