gRPC & Inter-service Communication

While satellites are Self-Contained Systems (SCS), they often need to communicate with the Shell or each other. In VENI-AI, we use Connect RPC (standardized as ignis-grpc) for type-safe, high-performance communication over plain HTTP.

---

🛰️ Why Connect RPC?

Traditional gRPC requires HTTP/2 and complex client libraries. Connect allows us to:

• Use Protobuf for strict contracts.
• Communicate over standard HTTP/1.1 or HTTP/2.
• Use simple fetch calls or generated type-safe clients.
• Debug easily using standard browser dev tools or Postman.

---

📑 1. Define the Service (Proto)

All contracts are defined in the protos/ directory.

// protos/auth/v1/auth.proto
syntax = "proto3";
package auth.v1;

service AuthService {
  rpc ExchangeToken(ExchangeTokenRequest) returns (ExchangeTokenResponse);
}

message ExchangeTokenRequest {
  string token = 1;
}

message ExchangeTokenResponse {
  string service_token = 1;
}

---

🛠️ 2. Implement the Handler

Implement the backend logic using BaseGrpcHandler from the Ignis framework.

// apps/your-app/api/src/grpc/auth.handler.ts
import { BaseGrpcHandler, GrpcMethod } from '@venizia/ignis-grpc';

export class AuthHandler extends BaseGrpcHandler {
  constructor() {
    super({ package: 'auth.v1', service: 'AuthService' });
  }

  @GrpcMethod('ExchangeToken')
  async exchangeToken(req: ExchangeTokenRequest) {
    // Logic to verify and exchange token
    return { service_token: '...' };
  }
}

---

🔗 3. Register the Handler

Register your gRPC handler in the application.ts of your satellite.

// application.ts
this.service(AuthHandler);

// In the initialization block
const authHandler = this.get<AuthHandler>({ key: 'services.AuthHandler' });
this.grpcComponent.registerHandler(authHandler);

---

📡 4. Calling from another Service

You can call the gRPC endpoint using a generated client or a simple fetch request.

Example using Fetch:

const response = await fetch('http://shell-api:3000/api/auth.v1.AuthService/ExchangeToken', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${shellToken}`
  },
  body: JSON.stringify({ token: '...' })
});

const data = await response.json();

---

🧪 5. Testing gRPC Endpoints

Since Connect uses standard HTTP, you can test endpoints directly:

curl -X POST http://localhost:3000/api/auth.v1.AuthService/ExchangeToken \
  -H "Content-Type: application/json" \
  -d '{"token": "ey..."}'