granc/granc-core

Granc Core

granc-core is the foundational library powering the Granc CLI. It provides a dynamic gRPC client capability that allows you to interact with any gRPC server without needing compile-time Protobuf code generation.

Instead of strictly typed Rust structs, this library bridges standard serde_json::Value payloads directly to Protobuf binary wire format at runtime.

🚀 High-Level Usage

The primary entry point is the [GrancClient]. It acts as an orchestrator that connects to a gRPC server and provides methods for both executing requests and inspecting the server's schema.

1. Making a Dynamic Call

The dynamic method handles the full request lifecycle:

1. Resolves the schema (either from a local file or via Server Reflection).
2. Determines the method type (Unary, Server Streaming, etc.).
3. Executes the request using JSON.

use granc_core::client::{GrancClient, DynamicRequest, DynamicResponse};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the server
    let mut client = GrancClient::connect("http://localhost:50051").await?;

    // Prepare the request
    // If you don't provide a file_descriptor_set, the client will attempt
    // to fetch the schema from the server's reflection service automatically.
    let request = DynamicRequest {
        service: "helloworld.Greeter".to_string(),
        method: "SayHello".to_string(),
        body: json!({ "name": "World" }),
        headers: vec![],
        file_descriptor_set: None, // Uses Server Reflection
    };

    let response = client.dynamic(request).await?;

    match response {
        DynamicResponse::Unary(Ok(value)) => {
            println!("Response: {}", value);
        }
        DynamicResponse::Unary(Err(status)) => {
            eprintln!("gRPC Error: {:?}", status);
        }
        DynamicResponse::Streaming(Ok(stream)) => {
            for msg in stream {
                println!("Stream Msg: {:?}", msg);
            }
        }
        _ => eprintln!("Unexpected response type"),
    }

    Ok(())
}

2. Schema Introspection

GrancClient exposes several methods to inspect the server's available services and types using reflection.

// List all services exposed by the server
let services = client.list_services().await?;
println!("Available Services: {:?}", services);

// Get the descriptor for a specific type
let descriptor = client.get_descriptor_by_symbol("helloworld.Greeter").await?;

match descriptor {
    Descriptor::MessageDescriptor(descriptor)) => println!("{}", descriptor.name())
    Descriptor::ServiceDescriptor(descriptor)) => println!("{}", descriptor.name())
    Descriptor::EnumDescriptor(descriptor)) => println!("{}", descriptor.name())
}

🛠️ Internal Components

We expose the internal building blocks of granc for developers who need more granular control or want to build their own tools on top of our dynamic transport layer.

1. GrpcClient (Generic Transport)

Standard tonic clients are strongly typed (e.g., client.say_hello(HelloRequest)). GrpcClient is a generic wrapper around tonic::client::Grpc that works strictly with serde_json::Value and prost_reflect::MethodDescriptor.

It handles the raw HTTP/2 path construction and metadata mapping, providing specific methods for all four gRPC access patterns:

• unary
• server_streaming
• client_streaming
• bidirectional_streaming

use granc_core::grpc::client::GrpcClient;
// You need a method_descriptor from prost_reflect::DescriptorPool
// let method_descriptor = ...; 

let mut grpc = GrpcClient::new(channel);
let result = grpc.unary(method_descriptor, json_value, headers).await?;

2. JsonCodec

The magic behind the dynamic serialization. This implementation of tonic::codec::Codec validates and transcodes JSON to Protobuf bytes (and vice versa) on the fly.

• Encoder: Validates serde_json::Value against the input MessageDescriptor and serializes it.
• Decoder: Deserializes bytes into a DynamicMessage and converts it back to serde_json::Value.

3. ReflectionClient

A client for grpc.reflection.v1. It enables runtime schema discovery.

The ReflectionClient is smart enough to handle dependencies. When you ask for a symbol (e.g., my.package.Service), it recursively fetches the file defining that symbol and all its transitive imports, building a complete prost_types::FileDescriptorSet ready for use. It also supports listing available services.

use granc_core::reflection::client::ReflectionClient;

let mut reflection = ReflectionClient::new(channel);

// List services
let services = reflection.list_services().await?;

// Fetch full schema for a symbol
let fd_set = reflection.file_descriptor_set_by_symbol("my.package.Service").await?;

You can then build a prost_reflect::DescriptorPool with the returned prost_types::FileDescriptorSet to be able to inspect in detail the descriptor.

⚖️ License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.