gRPC Service Mechanism

Monibuca provides gRPC service support, allowing plugins to offer services via the gRPC protocol. This document explains the implementation mechanism and usage of gRPC services.

Service Registration Mechanism

1. Service Registration

Plugins need to pass ServiceDesc and Handler when calling InstallPlugin to register gRPC services:

// Example: Registering gRPC service in a plugin
type MyPlugin struct {
    pb.UnimplementedApiServer
    m7s.Plugin
}

var _ = m7s.InstallPlugin[MyPlugin](
    m7s.DefaultYaml(`your yaml config here`),
    &pb.Api_ServiceDesc,           // gRPC service descriptor
    pb.RegisterApiHandler,         // gRPC gateway handler
    // ... other parameters
)

2. Proto File Specifications

All gRPC services must follow these Proto file specifications:

• Response structs must include code, message, and data fields
• Error handling should return errors directly, without manually setting code and message
• Run sh scripts/protoc.sh to generate pb files after modifying global.proto
• Run sh scripts/protoc.sh {pluginName} to generate corresponding pb files after modifying plugin-related proto files

Service Implementation Mechanism

1. Server Configuration

gRPC services use port settings from the global TCP configuration:

global:
  tcp:
    listenaddr: :8080     # gRPC service listen address and port
    listentls: :8443      # gRPC TLS service listen address and port (if enabled)

Configuration items include:

• Listen address and port settings (specified in global TCP configuration)
• TLS/SSL certificate configuration (if enabled)

2. Error Handling

Error handling follows these principles:

• Return errors directly, no need to manually set code and message
• The system automatically handles errors and sets response format

Best Practices

1. Service Definition

   • Clear service interface design
   • Appropriate method naming
   • Complete interface documentation

2. Performance Optimization

   • Use streaming for large data
   • Set reasonable timeout values

3. Security Considerations

   • Enable TLS encryption as needed
   • Implement necessary access controls