Crate dsh_sdk

Source
Expand description

§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, 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:

featuredefaultDescriptionExample
bootstrapCertificate signing process and fetch datastreams propertiesKafka / Kafka Proxy
kafkaEnable DshKafkaConfig trait and Config struct to connect to DSHKafka / Kafka Proxy
rdkafka-configEnable DshKafkaConfig implementation for RDKafkaKafka / Kafka Proxy
schema-storeInteract with DSH Schema StoreSchema Store API
protocol-tokenFetch 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-fetcherFetch tokens to use DSH Management APIToken fetcher
metricsEnable prometheus metrics including http serverExpose metrics
graceful-shutdownTokio based graceful shutdown handlerGraceful shutdown
dlqDead Letter Queue implementationFull 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.