Protoreg

protoreg provides a shared protobuf registry, enabling other plugins to access proto definitions at runtime, making it ideal for building custom gRPC interceptors, middleware, and dynamic message handling.

Features

• Parses and registers .proto files at startup

• Provides a shared protoregistry accessible by other plugins

• Supports multiple import paths for proto dependencies

• Automatically resolves and registers proto file dependencies

• Exposes service and method descriptors for reflection-based operations

• Thread-safe registry access

Use Cases

• Custom gRPC Interceptors: Build interceptors that need to inspect or modify messages based on their proto definitions

• Dynamic Message Handling: Deserialize and serialize protobuf messages without compile-time generated code

• Request/Response Validation: Validate gRPC requests against proto schemas

• Logging & Monitoring: Create detailed logs with field-level message inspection

Configuration

The protoreg plugin must be enabled alongside the grpc plugin in your configuration. Without the grpc plugin enabled, the protoreg plugin will not be started.

The plugin is configured under the protoreg section in your .rr.yaml configuration file:

version: '3'

protoreg:
  proto_path:
    - proto/commonapis
    - proto/serviceapis
  files:
    - service/v1/service.proto
    - user/v1/user.proto

Configuration Options

proto_path (required)

A list of directories where the plugin will search for proto files and their dependencies. These paths work similarly to the --proto-path/-I flag in protoc.

Why it's needed: Proto files often import other proto files (e.g., import "google/protobuf/timestamp.proto"). The import paths tell the parser where to find these dependencies. You typically need:

• A path containing your service definitions

• A path containing shared/common message definitions

• Paths to any third-party proto files (like Google's well-known types)

proto_path:
  - proto/commonapis     # Shared message definitions
  - proto/serviceapis    # Service-specific proto definitions
  - proto/third_party    # External dependencies (e.g., google/api)

files (required)

A list of proto files to parse and register. Paths are relative to the proto_path directories. This works similarly to passing variadic proto files argument in protoc.

Why it's needed: This explicitly declares which proto files define the services and messages you want to access at runtime. The plugin will:

1. Parse each listed proto file

2. Automatically resolve and register all imported dependencies

3. Build a registry of all services and their methods

files:
  - service/v1/service.proto    # Your gRPC service definitions
  - user/v1/user.proto          # Additional service definitions

Example: Project Structure

A typical project structure when using this plugin:

my-project/
├── .rr.yaml
├── proto/
│   ├── commonapis/
│   │   └── common/
│   │       └── v1/
│   │           └── message.proto
│   └── serviceapis/
│       └── service/
│           └── v1/
│               └── service.proto
└── ...

proto/commonapis/common/v1/message.proto:

syntax = "proto3";

package common.v1;

message Request {
  string id = 1;
  string payload = 2;
}

message Response {
  string id = 1;
  string result = 2;
}

proto/serviceapis/service/v1/service.proto:

syntax = "proto3";

package service.v1;

import "common/v1/message.proto";

service MyService {
  rpc Process (common.v1.Request) returns (common.v1.Response) {}
  rpc Ping (common.v1.Request) returns (common.v1.Response) {}
}

Configuration (.rr.yaml):

version: '3'

protoreg:
  proto_path:
    - proto/commonapis
    - proto/serviceapis
  files:
    - service/v1/service.proto

Using the Registry in Your Plugin

Other plugins can depend on protoreg to access the registry. Here's how to use it in a custom plugin:

package myplugin

import (
	"github.com/jhump/protoreflect/desc"
	"github.com/jhump/protoreflect/v2/protoresolve"
)

type Registry interface {
	Registry() *protoresolve.Registry
	Services() map[string]*desc.ServiceDescriptor
	FindMethodByFullPath(method string) (*desc.MethodDescriptor, error)
}

type Plugin struct {
    registry Registry
}

func (p *Plugin) Init(registry Registry) error {

    p.registry = registry

    // Access the underlying registry
    reg := p.registry.Registry()

    // Get all registered services
    services := p.registry.Services()

    // Find a specific method by its full path
    method, err := p.registry.FindMethodByFullPath("/service.v1.MyService/Process")
    if err != nil {
        return err
    }

    // Use the method descriptor for reflection
    inputType := method.GetInputType()
    outputType := method.GetOutputType()

    return nil
}

Registry Interface

The plugin exposes the following interface:

type Registry interface {
    // Registry returns the underlying protoresolve.Registry that
	// contains all the parsed descriptors
    Registry() *protoresolve.Registry

    // Services returns a map of all registered service descriptors
    // keyed by their fully qualified name
    Services() map[string]*desc.ServiceDescriptor

    // FindMethodByFullPath finds a method descriptor by its full gRPC path
    // Format: "/package.Service/Method" or "package.Service/Method"
    FindMethodByFullPath(method string) (*desc.MethodDescriptor, error)
}

Example: gRPC Interceptor

Here's an example of using the registry in a custom gRPC interceptor to log request details:

package interceptor

import (
    "context"
    "log"

    "github.com/roadrunner-server/protoreg/v5"
    "google.golang.org/grpc"
    "google.golang.org/protobuf/proto"
    "google.golang.org/protobuf/types/dynamicpb"
)

type Plugin struct {
    registry protoreg.Registry
}

func (i *Plugin) UnaryInterceptor(
    ctx context.Context,
    req interface{},
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (interface{}, error) {
    // Find the method descriptor
    method, err := i.registry.FindMethodByFullPath(info.FullMethod)
    if err != nil {
        log.Printf("Method not found in registry: %s", info.FullMethod)
        return handler(ctx, req)
    }

    // Log method information
    log.Printf("Method: %s", method.GetFullyQualifiedName())
    log.Printf("Input type: %s", method.GetInputType().GetFullyQualifiedName())
    log.Printf("Output type: %s", method.GetOutputType().GetFullyQualifiedName())

    // You can also dynamically inspect the message fields
    inputDesc := method.GetInputType()
    for _, field := range inputDesc.GetFields() {
        log.Printf("  Field: %s (type: %s)", field.GetName(), field.GetType().String())
    }

    return handler(ctx, req)
}

Troubleshooting

"proto path does not exist"

Ensure all paths in proto_path exist and are accessible. Paths can be absolute or relative to the RoadRunner working directory.

"proto file does not exist"

The proto file must exist in one of the configured proto_path. Check that:

1. The file path in files is relative to an import path, not an absolute path

2. The directory structure matches the import path

"file already registered"

This occurs when the same proto file is included multiple times (e.g., listed in files and also imported by another file). The plugin handles dependencies automatically, so you typically only need to list your top-level service definitions in the files section.

License

MIT License - see LICENSE file for details.