Skip to content
Back to search

gRPC-zig

blazigly fast gRPC/MCP client & server implementation in zig

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ziglana--grpc-zig/badge.svg)](/listings/ziglana--grpc-zig)

HTML

<a href="/listings/ziglana--grpc-zig"><img src="/api/listings/ziglana--grpc-zig/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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!");
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 270 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🚀 gRPC-zig
  2. A blazingly fast gRPC client & server implementation in Zig, designed for maximum performance and minimal overhead.
  3. [![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](http://unlicense.org/)
  4. [![Zig](https://img.shields.io/badge/Zig-%23F7A41D.svg?style=flat&logo=zig&logoColor=white)](https://ziglang.org/)
  5. [![HTTP/2](https://img.shields.io/badge/HTTP%2F2-Supported-success)](https://http2.github.io/)
  6. ## ⚡️ Features
  7. - 🔥 **Blazingly Fast**: Built from ground up in Zig for maximum performance
  8. - 🔐 **Full Security**: Built-in JWT authentication and TLS support
  9. - 🗜️ **Compression**: Support for gzip and deflate compression
  10. - 🌊 **Streaming**: Efficient bi-directional streaming
  11. - 💪 **HTTP/2**: Full HTTP/2 support with proper flow control
  12. - 🏥 **Health Checks**: Built-in health checking system
  13. - 🎯 **Zero Dependencies**: Pure Zig implementation
  14. - 🔍 **Type Safety**: Leverages Zig's comptime for compile-time checks
  15. ## 🚀 Quick Start
  16. ```zig
  17. const std = @import("std");
  18. const GrpcServer = @import("grpc-server").GrpcServer;
  19. pub fn main() !void {
  20. var gpa = std.heap.GeneralPurposeAllocator(.{}){};
  21. defer _ = gpa.deinit();
  22. const allocator = gpa.allocator();
  23. // Create and configure server
  24. var server = try GrpcServer.init(allocator, 50051, "secret-key");
  25. defer server.deinit();
  26. // Register handlers
  27. try server.handlers.append(allocator, .{
  28. .name = "SayHello",
  29. .handler_fn = sayHello,
  30. });
  31. // Start server
  32. try server.start();
  33. }
  34. fn sayHello(request: []const u8, allocator: std.mem.Allocator) ![]u8 {
  35. _ = request;
  36. return allocator.dupe(u8, "Hello from gRPC-zig!");
  37. }
  38. ```
  39. ## 📚 Examples
  40. ### Basic Server
  41. See [examples/basic_server.zig](examples/basic_server.zig) for a complete example.
  42. ```zig
  43. const std = @import("std");
  44. const GrpcServer = @import("grpc-server").GrpcServer;
  45. pub fn main() !void {
  46. var gpa = std.heap.GeneralPurposeAllocator(.{}){};
  47. defer _ = gpa.deinit();
  48. const allocator = gpa.allocator();
  49. var server = try GrpcServer.init(allocator, 50051, "secret-key");
  50. defer server.deinit();
  51. try server.start();
  52. }
  53. ```
  54. ### Basic Client
  55. See [examples/basic_client.zig](examples/basic_client.zig) for a complete example.
  56. ```zig
  57. const std = @import("std");
  58. const GrpcClient = @import("grpc-client").GrpcClient;
  59. pub fn main() !void {
  60. var gpa = std.heap.GeneralPurposeAllocator(.{}){};
  61. defer _ = gpa.deinit();
  62. const allocator = gpa.allocator();
  63. var client = try GrpcClient.init(allocator, "localhost", 50051);
  64. defer client.deinit();
  65. const response = try client.call("SayHello", "World", .none);
  66. defer allocator.free(response);
  67. std.debug.print("Response: {s}\n", .{response});
  68. }
  69. ```
  70. ### Features
  71. All features are demonstrated in the [examples/](examples/) directory:
  72. - **[Authentication](examples/auth.zig)**: JWT token generation and verification
  73. - **[Compression](examples/compression.zig)**: gzip/deflate support
  74. - **[Streaming](examples/streaming.zig)**: Bi-directional message streaming
  75. - **[Health Checks](examples/health.zig)**: Service health monitoring
  76. ## 🔧 Installation
  77. ### Option 1: Using zig fetch (Recommended)
  78. 1. Add the dependency to your project:
  79. ```sh
  80. zig fetch --save git+https://github.com/ziglana/gRPC-zig#main
  81. ```
  82. 2. Add to your `build.zig`:
  83. ```zig
  84. const grpc_zig_dep = b.dependency("grpc_zig", .{
  85. .target = target,
  86. .optimize = optimize,
  87. });
  88. // For server development
  89. exe.root_module.addImport("grpc-server", grpc_zig_dep.module("grpc-server"));
  90. // For client development
  91. exe.root_module.addImport("grpc-client", grpc_zig_dep.module("grpc-client"));
  92. ```
  93. 3. Import in your code:
  94. ```zig
  95. const GrpcServer = @import("grpc-server").GrpcServer;
  96. const GrpcClient = @import("grpc-client").GrpcClient;
  97. ```
  98. ### Option 2: Manual setup
  99. Clone the repository and add it to your `build.zig.zon`:
  100. ```zig
  101. .{
  102. .name = "my-project",
  103. .version = "0.1.0",
  104. .dependencies = .{
  105. .grpc_zig = .{
  106. .url = "https://github.com/ziglana/gRPC-zig/archive/refs/heads/main.tar.gz",
  107. // Replace with actual hash after first fetch
  108. .hash = "...",
  109. },
  110. },
  111. }
  112. ```
  113. ## 🏃 Performance
  114. Benchmarked against other gRPC implementations (ops/sec, lower is better):
  115. ```
  116. gRPC-zig │████████░░░░░░░░░░│ 2.1ms
  117. gRPC Go │██████████████░░░░│ 3.8ms
  118. gRPC C++ │████████████████░░│ 4.2ms
  119. ```
  120. ### Running Benchmarks
  121. The repository includes a built-in benchmarking tool to measure performance:
  122. ```bash
  123. # Build the benchmark tool
  124. zig build
  125. # Run benchmarks with default settings
  126. zig build benchmark
  127. # Run with custom parameters
  128. ./zig-out/bin/grpc-benchmark --help
  129. ./zig-out/bin/grpc-benchmark --requests 1000 --clients 10 --output json
  130. # Or use the convenient script
  131. ./scripts/run_benchmark.sh
  132. ```
  133. **Benchmark Options:**
  134. - `--host <host>`: Server host (default: localhost)
  135. - `--port <port>`: Server port (default: 50051)
  136. - `--requests <n>`: Number of requests per client (default: 1000)
  137. - `--clients <n>`: Number of concurrent clients (default: 10)
  138. - `--size <bytes>`: Request payload size (default: 1024)
  139. - `--output <format>`: Output format: text|json (default: text)
  140. **Benchmark Metrics:**
  141. - Latency statistics (min, max, average, P95, P99)
  142. - Throughput (requests per second)
  143. - Error rates and success rates
  144. - Total execution time
  145. The benchmarks automatically run in CI/CD on every pull request and provide performance feedback.
  146. 📖 **[Detailed Benchmarking Guide](docs/benchmarking.md)**
  147. ## 🧪 Testing
  148. ### Unit Tests
  149. Run the unit test suite:
  150. ```bash
  151. zig build test
  152. ```
  153. The test suite covers:
  154. - Compression algorithms (gzip, deflate, none)
  155. - Benchmark handler functionality
  156. - Core protocol functionality
  157. ### Integration Tests
  158. Run integration tests with a Python client validating the Zig server:
  159. ```bash
  160. cd integration_test
  161. ./run_tests.sh
  162. ```
  163. Or manually:
  164. ```bash
  165. # Build and start the test server
  166. zig build integration_test
  167. ./zig-out/bin/grpc-test-server
  168. # In another terminal, run Python tests
  169. cd integration_test
  170. python3 -m venv venv
  171. source venv/bin/activate
  172. pip install -r requirements.txt
  173. python3 test_client.py
  174. ```
  175. The integration tests validate:
  176. - HTTP/2 protocol compliance
  177. - gRPC request/response flow
  178. - Compression functionality
  179. - Health checking
  180. - Authentication integration
  181. 📖 **[Integration Test Documentation](integration_test/README.md)**
  182. ## 🤝 Contributing
  183. 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.
  184. ## 📜 License
  185. This project is licensed under the Unlicense - see the [LICENSE](LICENSE) file for details.
  186. ## ⭐️ Support
  187. If you find this project useful, please consider giving it a star on GitHub to show your support!
  188. ## 🙏 Acknowledgments
  189. - [Spice](https://github.com/judofyr/spice) - For the amazing Protocol Buffers implementation
  190. - [Tonic](https://github.com/hyperium/tonic) - For inspiration on API design
  191. - The Zig community for their invaluable feedback and support
  192. ---
  193. Made with ❤️ in Zig

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.