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

grpc_gateway 0.1.6