gRPC Gateway SDK

A lightweight SDK that allows you to expose your gRPC services over HTTP/JSON.
This SDK accepts HTTP requests, invokes the corresponding gRPC service methods, and returns JSON responses generated from protobuf messages.

👉 No .proto files are required to use your gRPC services with this SDK.

🚀 New in v0.1.5

This release introduces JWT Token Authentication with automatic refresh capabilities alongside existing API Key authentication.

🔐 Enhanced Authentication Features

• JWT Token Authentication with automatic token refresh
• Pull-based orchestration for token management
• Runtime token validation on every API call
• Centralized protobuf protocol for refresh operations
• Zero downtime token refresh

👉 See full details in the Authentication System README.

🚀 Features

• Expose gRPC services via HTTP endpoints.
• Automatically translates:
  • HTTP request → gRPC method call
  • Protobuf response → JSON response
• Advanced Authentication support for internal communication between Gateway ↔ Service:
  • Supported auth types:
    • API_KEY - Simple static authentication
    • JWT_TOKEN - Dynamic authentication with auto-refresh
  • Automatic token refresh when JWT tokens expire
  • Services can define their own header name and authentication configuration during registration.
  • Runtime token validation ensures secure communication
  • Services can re-register with new tokens anytime, and the Gateway will automatically use the updated configuration.
• Service Registry with health monitoring
• Simple service registration API with comprehensive configuration options
• Runs as a standalone HTTP service.
• Easy integration with existing gRPC applications.

🔑 Authentication Support

The Gateway now supports two authentication methods for secure service communication.
When a service registers itself, it can specify the authentication type and provide the required configuration.

Currently supported auth types

• API_KEY - Static authentication with custom headers
• JWT_TOKEN - Dynamic authentication with automatic token refresh

Example: Registering a Service with API_KEY Authentication

let result = gateway.service_registry.register(ServiceRegisterRequest {
    service_name: String::from("users.UserService"),
    host: String::from("127.0.0.1"),
    port: String::from("50051"),
    health_check_endpoint: String::from("/health"),
    oauth_config: InternalAuthConfig {
        auth_type: AuthType::ApiKey,
        auth_refresh_config: None,
    },
});

Example: Registering a Service with JWT_TOKEN Authentication

let result = gateway.service_registry.register(ServiceRegisterRequest {
    service_name: String::from("payment.PaymentService"),
    host: String::from("127.0.0.1"),
    port: String::from("50052"),
    health_check_endpoint: String::from("/health"),
    oauth_config: InternalAuthConfig {
        auth_type: AuthType::JwtToken,
        auth_refresh_config: Some(AuthRefreshConfig {
            service_name: String::from("auth-service"),
            method: String::from("RefreshAuth"),
            header_name: String::from("Authorization"),
            access_token: String::from("initial_jwt_token"),
            expired_at: 1641024000, // Unix timestamp
            refresh_token: String::from("refresh_jwt_token"),
        }),
    },
});

🔄 JWT Token Auto-Refresh

The new JWT authentication system features automatic token refresh:

• Runtime Validation: Token expiry checked on every API call
• Automatic Refresh: Gateway automatically refreshes expired tokens
• Pull-based Orchestration: Gateway initiates refresh when needed
• Standardized Protocol: All services must implement the same refresh protobuf service
• Zero Downtime: Seamless operation during token refresh

Required Protobuf Implementation

All services using JWT authentication must implement this exact protobuf service:

syntax = "proto3";
package refresh;

message RefreshAuthTokenRequest {
    string refresh_token = 1;
}

message RefreshAuthTokenResponse {
    string access_token = 1;
    string refresh_token = 2;
    uint64 expired_at = 3;
}

service RefreshAuthService {
    rpc RefreshAuth (RefreshAuthTokenRequest) returns (RefreshAuthTokenResponse);
}

📋 Quick Start Guide

1. Choose Authentication Method

For Simple Services (API Key):

• Use AuthType::ApiKey
• Set static header name and value
• No additional implementation required

For Production Services (JWT Token):

• Use AuthType::JwtToken
• Implement the required refresh protobuf service
• Configure initial tokens and refresh endpoint

2. Register Your Service

Services must register before starting to enable Gateway communication.

3. Start Your Service

Once registered, the Gateway will:

• Route HTTP requests to your gRPC service
• Handle authentication automatically
• Refresh tokens when needed (JWT only)
• Monitor service health

🔍 Configuration Types

Static Configuration

• Service connection details (host, port)
• Authentication type selection
• Health check endpoints

Dynamic Configuration (JWT only)

• Access tokens (auto-refreshed)
• Token expiry times (auto-updated)
• Refresh tokens (auto-rotated)

📚 Documentation

• Complete Authentication Guide - Detailed setup and configuration
• Migration Guide - Upgrading from API Key to JWT
• Troubleshooting - Common issues and solutions

🚨 Important Notes

• Service Registration Required: All services must register before starting
• Protocol Compliance: JWT services must implement the exact protobuf definition
• Backward Compatibility: Existing API Key authentication continues to work
• Recommended: JWT Token authentication for new production services

Version: v0.1.6
Compatibility: Supports both API Key and JWT Token authentication
Migration: Seamless upgrade path from API Key to JWT authentication