grpc-api

Files (1)

• SKILL.md

SKILL.md (first lines)

# gRPC API Development

Build efficient gRPC services using Protocol Buffers for contract-first API design, with support for
unary calls, server streaming, client streaming, and bidirectional streaming.

## When to Use

- Building microservices that require high-performance binary communication.
- Defining strict service contracts with Protocol Buffers (`.proto` files).
- Implementing real-time bidirectional or server-push streaming.
- Creating internal service-to-service APIs in polyglot architectures.
- Optimizing bandwidth in constrained or high-throughput environments.

## Critical Patterns

- **Contract First:** Always define your `.proto` file before writing any server or client code. The
  proto IS your API contract.
- **Use Proper Status Codes:** Map domain errors to gRPC status codes (`NOT_FOUND`,
  `ALREADY_EXISTS`, `INVALID_ARGUMENT`, etc.). Never return raw exceptions.
- **Field Numbering is Forever:** Once a proto field number is assigned and released, NEVER reuse
  it. Add new fields with new numbers; deprecate old ones.
- **Streaming for Large Data:** Use server streaming for large result sets and client streaming for
  bulk uploads. Avoid sending massive unary payloads.
- **Deadlines Over Timeouts:** Always set deadlines on client calls. A missing deadline can hang
  forever in production.
- **TLS in Production:** Never use `createInsecure()` credentials outside of local development.
- **Keep Messages Flat:** Avoid deeply nested message types. Flatten where possible for better wire
  efficiency and readability.

## Proto Definition Patterns

### Complete Service Definition

```protobuf
syntax = "proto3";

package user.service;

message User {
  string id = 1;
  string email = 2;
  string first_name = 3;
  string last_name = 4;
  string role = 5;
  int64 created_at = 6;
  int64 updated_at = 7;
}

message CreateUserRequest {
  string email = 1;
  string first_name = 2;
  string last_name = 3;
  string role = 4;
}

message UpdateUserRequest {
  string id = 1;
  string email = 2;
  string first_name = 3;
  string last_name = 4;
}

message GetUserRequest {
  string id = 1;
}

message ListUsersRequest {
  int32 page = 1;
  int32 limit = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  int32 total = 2;
  int32 page = 3;
}

message DeleteUserRequest {
  string id = 1;
}

message Empty {}

// Four RPC patterns: unary, server streaming, client streaming, bidirectional
service UserService {
  rpc GetUser(GetUserRequest) returns (User);              // Unary
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse); // Unary
  rpc CreateUser(CreateUserRequest) returns (User);        // Unary
  rpc UpdateUser(UpdateUserRequest) returns (User);        // Unary
  rpc DeleteUser(DeleteUserRequest) returns (Empty);       // Unary
  rpc StreamUsers(Empty) returns (stream User);            // Server streaming
  rpc BulkCreateUsers(stream CreateUserRequest) returns (ListUsersResponse); // Client streaming
}
```

### Event Streaming Service

```protobuf
message Event {
  string type = 1;
  string user_id = 2;
  string data = 3;
  int64 timestamp = 4;
}

service EventService {
  rpc Subscribe(Empty) returns (stream Event);   // Server streaming
  rpc PublishEvent(Event) returns (Empty);        // Unary
}
```

## Node.js Server Implementation

### Loading Proto and Implementing Handlers

```javascript
const grpc = require("@grpc/grpc-js");
const protoLoader = require("@grpc/proto-loader");
const path = require("path");

From dallay/agents-skills, MIT.

More from dallay/agents-skills