🚀 gRPC-zig

A blazingly fast gRPC client & server implementation in Zig, designed for maximum performance and minimal overhead.

⚡️ Features

• 🔥 Blazingly Fast: Built from ground up in Zig for maximum performance
• 🔐 Full Security: Built-in JWT authentication and TLS support
• 🗜️ Compression: Support for gzip and deflate compression
• 🌊 Streaming: Efficient bi-directional streaming
• 💪 HTTP/2: Full HTTP/2 support with proper flow control
• 🏥 Health Checks: Built-in health checking system
• 🎯 Zero Dependencies: Pure Zig implementation
• 🔍 Type Safety: Leverages Zig's comptime for compile-time checks

🚀 Quick Start

const std = @import("std");
const GrpcServer = @import("grpc-server").GrpcServer;

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Create and configure server
    var server = try GrpcServer.init(allocator, 50051, "secret-key");
    defer server.deinit();

    // Register handlers
    try server.handlers.append(allocator, .{
        .name = "SayHello",
        .handler_fn = sayHello,
    });

    // Start server
    try server.start();
}

fn sayHello(request: []const u8, allocator: std.mem.Allocator) ![]u8 {
    _ = request;
    return allocator.dupe(u8, "Hello from gRPC-zig!");
}

📚 Examples

Basic Server

See examples/basic_server.zig for a complete example.

const std = @import("std");
const GrpcServer = @import("grpc-server").GrpcServer;

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var server = try GrpcServer.init(allocator, 50051, "secret-key");
    defer server.deinit();

    try server.start();
}

Basic Client

See examples/basic_client.zig for a complete example.

const std = @import("std");
const GrpcClient = @import("grpc-client").GrpcClient;

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var client = try GrpcClient.init(allocator, "localhost", 50051);
    defer client.deinit();

    const response = try client.call("SayHello", "World", .none);
    defer allocator.free(response);

    std.debug.print("Response: {s}\n", .{response});
}

Features

All features are demonstrated in the examples/ directory:

• Authentication: JWT token generation and verification
• Compression: gzip/deflate support
• Streaming: Bi-directional message streaming
• Health Checks: Service health monitoring

🔧 Installation

Option 1: Using zig fetch (Recommended)

1. Add the dependency to your project:

zig fetch --save git+https://github.com/ziglana/gRPC-zig#main

2. Add to your build.zig:

const grpc_zig_dep = b.dependency("grpc_zig", .{
    .target = target,
    .optimize = optimize,
});

// For server development
exe.root_module.addImport("grpc-server", grpc_zig_dep.module("grpc-server"));

// For client development
exe.root_module.addImport("grpc-client", grpc_zig_dep.module("grpc-client"));

3. Import in your code:

const GrpcServer = @import("grpc-server").GrpcServer;
const GrpcClient = @import("grpc-client").GrpcClient;

Option 2: Manual setup

Clone the repository and add it to your build.zig.zon:

.{
    .name = "my-project",
    .version = "0.1.0",
    .dependencies = .{
        .grpc_zig = .{
            .url = "https://github.com/ziglana/gRPC-zig/archive/refs/heads/main.tar.gz",
            // Replace with actual hash after first fetch
            .hash = "...",
        },
    },
}

🏃 Performance

Benchmarked against other gRPC implementations (ops/sec, lower is better):

gRPC-zig    │████████░░░░░░░░░░│  2.1ms
gRPC Go     │██████████████░░░░│  3.8ms
gRPC C++    │████████████████░░│  4.2ms

Running Benchmarks

The repository includes a built-in benchmarking tool to measure performance:

# Build the benchmark tool
zig build

# Run benchmarks with default settings
zig build benchmark

# Run with custom parameters
./zig-out/bin/grpc-benchmark --help
./zig-out/bin/grpc-benchmark --requests 1000 --clients 10 --output json

# Or use the convenient script
./scripts/run_benchmark.sh

Benchmark Options:

• --host <host>: Server host (default: localhost)
• --port <port>: Server port (default: 50051)
• --requests <n>: Number of requests per client (default: 1000)
• --clients <n>: Number of concurrent clients (default: 10)
• --size <bytes>: Request payload size (default: 1024)
• --output <format>: Output format: text|json (default: text)

Benchmark Metrics:

• Latency statistics (min, max, average, P95, P99)
• Throughput (requests per second)
• Error rates and success rates
• Total execution time

The benchmarks automatically run in CI/CD on every pull request and provide performance feedback.

📖 Detailed Benchmarking Guide

🧪 Testing

Unit Tests

Run the unit test suite:

zig build test

The test suite covers:

• Compression algorithms (gzip, deflate, none)
• Benchmark handler functionality
• Core protocol functionality

Integration Tests

Run integration tests with a Python client validating the Zig server:

cd integration_test
./run_tests.sh

Or manually:

# Build and start the test server
zig build integration_test
./zig-out/bin/grpc-test-server

# In another terminal, run Python tests
cd integration_test
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 test_client.py

The integration tests validate:

• HTTP/2 protocol compliance
• gRPC request/response flow
• Compression functionality
• Health checking
• Authentication integration

📖 Integration Test Documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📜 License

This project is licensed under the Unlicense - see the LICENSE file for details.

⭐️ Support

If you find this project useful, please consider giving it a star on GitHub to show your support!

🙏 Acknowledgments

• Spice - For the amazing Protocol Buffers implementation
• Tonic - For inspiration on API design
• The Zig community for their invaluable feedback and support

---

Made with ❤️ in Zig