# Granc Core
[](https://crates.io/crates/granc_core)
[](https://docs.rs/granc_core)
[](https://github.com/JasterV/granc/blob/main/LICENSE)
**`granc-core`** is the foundational library powering the [Granc CLI](https://crates.io/crates/granc). 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.
```rust
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.
```rust
// 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`
```rust
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.
```rust
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.