Crate hemmer_provider_sdk 

Hemmer Provider SDK

This crate provides the gRPC protocol types and server helpers for building Hemmer providers.

Overview

The SDK provides:

• Protocol Buffers types: Pre-compiled Rust types from the canonical provider protocol
• Schema types: Types for describing provider, resource, and data source schemas
• ProviderService trait: A high-level trait that providers implement
• Server helpers: Functions to start a gRPC server with the handshake protocol
• Error types: Common error types for provider implementations
• Logging: Integration with tracing for structured logging

Quick Start

use hemmer_provider_sdk::{
    serve, ProviderService, ProviderError, PlanResult,
    schema::{ProviderSchema, Schema, Attribute, Diagnostic},
};

struct MyProvider;

#[async_trait::async_trait]
impl ProviderService for MyProvider {
    fn schema(&self) -> ProviderSchema {
        ProviderSchema::new()
            .with_resource("example_resource", Schema::v0()
                .with_attribute("name", Attribute::required_string())
                .with_attribute("id", Attribute::computed_string()))
    }

    async fn configure(
        &self,
        config: serde_json::Value,
    ) -> Result<Vec<Diagnostic>, ProviderError> {
        Ok(vec![])
    }

    async fn plan(
        &self,
        resource_type: &str,
        prior_state: Option<serde_json::Value>,
        proposed_state: serde_json::Value,
        config: serde_json::Value,
    ) -> Result<PlanResult, ProviderError> {
        Ok(PlanResult::no_change(proposed_state))
    }

    async fn create(
        &self,
        resource_type: &str,
        planned_state: serde_json::Value,
    ) -> Result<serde_json::Value, ProviderError> {
        Ok(planned_state)
    }

    async fn read(
        &self,
        resource_type: &str,
        current_state: serde_json::Value,
    ) -> Result<serde_json::Value, ProviderError> {
        Ok(current_state)
    }

    async fn update(
        &self,
        resource_type: &str,
        prior_state: serde_json::Value,
        planned_state: serde_json::Value,
    ) -> Result<serde_json::Value, ProviderError> {
        Ok(planned_state)
    }

    async fn delete(
        &self,
        resource_type: &str,
        current_state: serde_json::Value,
    ) -> Result<(), ProviderError> {
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = MyProvider;
    serve(provider).await
}

Handshake Protocol

When a provider starts via serve, it outputs a handshake string to stdout:

HEMMER_PROVIDER|1|127.0.0.1:50051

Format: HEMMER_PROVIDER|<protocol_version>|<address>

This allows Hemmer to spawn the provider as a subprocess and connect via gRPC.

Provider Protocol

The SDK implements a complete provider protocol with the following RPCs:

• GetMetadata: Returns provider capabilities and resource/data source names
• GetSchema: Returns full schema for provider config, resources, and data sources
• ValidateProviderConfig: Validates provider configuration
• Configure: Configures the provider with credentials
• Stop: Gracefully shuts down the provider
• ValidateResourceConfig: Validates resource configuration
• UpgradeResourceState: Migrates state from older schema versions
• Plan: Calculates required changes
• Create/Read/Update/Delete: CRUD operations for resources
• ImportResourceState: Imports existing infrastructure
• ValidateDataSourceConfig: Validates data source configuration
• ReadDataSource: Reads data from external sources

Re-exports

pub use error::ProviderError;

pub use logging::init_logging;

pub use logging::init_logging_with_default;

pub use logging::try_init_logging;

pub use schema::ProviderSchema;

pub use server::serve;

pub use server::serve_on;

pub use server::serve_on_with_options;

pub use server::serve_with_options;

pub use server::ProviderService;

pub use server::ServeOptions;

pub use types::check_protocol_version;

pub use types::AttributeChange;

pub use types::ImportedResource;

pub use types::PlanResult;

pub use types::ProviderMetadata;

pub use types::ServerCapabilities;

pub use types::HANDSHAKE_PREFIX;

pub use types::MIN_PROTOCOL_VERSION;

pub use types::PROTOCOL_VERSION;

pub use validation::is_valid;

pub use validation::validate;

pub use validation::validate_result;

pub use testing::ProviderTester;

pub use testing::TestError;

pub use serde_json;

pub use tonic;

pub use tracing;

Modules

error

Error types for the Hemmer Provider SDK.

generated

logging

Logging and tracing utilities for providers.

schema

Schema types for describing provider and resource structure.

server

Server helpers for running providers.

testing

Testing utilities for provider implementations.

types

Convenience types for provider implementations.

validation

Schema validation helpers.

Type Aliases

Result

A convenience type alias for Results with ProviderError.

Attribute Macros

async_trait