mattermost/server/public/pluginapi/grpc/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with the Mattermost Python plugin gRPC infrastructure.

Repository Purpose

This directory contains the Go-side gRPC infrastructure enabling Python plugins to communicate with the Mattermost server. It provides:

• Protocol buffer definitions for Plugin API and hooks
• gRPC server implementation for API callbacks
• Type conversion between Go models and protobuf
• ServeHTTP bidirectional streaming

Key Commands

Code Generation

# From server/ directory:

# Generate Go code from proto files
make -C public proto-gen

# Generate both Go and Python code
make -C public proto-gen-all

Testing

# Run gRPC server tests
go test ./public/pluginapi/grpc/server/... -v

# Run Python supervisor tests
go test ./public/plugin/... -v -run Python

# Run integration tests
go test ./public/pluginapi/grpc/server/... -v -run Integration

Architecture Overview

Directory Structure

server/public/pluginapi/grpc/
├── proto/                    # Protocol buffer definitions
│   ├── common.proto          # Shared types (AppError, StringMap)
│   ├── user.proto            # User type
│   ├── channel.proto         # Channel type
│   ├── post.proto            # Post type
│   ├── team.proto            # Team type
│   ├── file.proto            # File types
│   ├── api.proto             # PluginAPI service definition
│   ├── api_*.proto           # API method groups
│   ├── hooks.proto           # PluginHooks service definition
│   └── hooks_*.proto         # Hook method groups
├── generated/go/pluginapiv1/ # Generated Go code (do not edit)
└── server/                   # gRPC server implementation
    ├── api_server.go         # Server startup and registration
    ├── handlers_*.go         # RPC method handlers
    ├── convert_*.go          # Go model <-> proto conversion
    ├── serve_http.go         # ServeHTTP streaming handler
    └── errors.go             # Error conversion utilities

Key Components

1. Python Supervisor (plugin/python_supervisor.go)

   • Spawns Python plugin subprocess
   • Sets up go-plugin gRPC connection
   • Passes API server address via env var

2. Hooks gRPC Client (plugin/hooks_grpc_client.go)

   • Implements plugin.Hooks interface
   • Dispatches hooks to Python via gRPC
   • Converts Go types to proto messages

3. API Server (grpc/server/api_server.go)

   • gRPC server Python plugins connect to
   • Implements PluginAPI service
   • Calls actual plugin.API methods

4. ServeHTTP (grpc/server/serve_http.go)

   • Bidirectional streaming for HTTP
   • 64KB chunks for request/response bodies
   • Handles flush signals

Proto File Organization

File	Purpose
api.proto	PluginAPI service (all RPC definitions)
api_user_team.proto	User and Team API messages
api_channel_post.proto	Channel and Post API messages
api_kv_config.proto	KV Store and Config messages
api_file_bot.proto	File and Bot messages
api_remaining.proto	All other API messages
hooks.proto	PluginHooks service definition
hooks_*.proto	Hook messages by category

Best Practices

1. Proto Changes: Always regenerate Go AND Python code after proto changes
2. Type Conversion: Add converters in convert_*.go for new types
3. Error Handling: Use ToAppErrorProto/FromAppErrorProto for errors
4. Testing: Add tests in *_test.go for new handlers
5. JSON Blobs: Use bytes *_json for complex types (Config, License)

Adding a New API Method

1. Add RPC to api.proto service definition
2. Add request/response messages to appropriate api_*.proto
3. Run make -C public proto-gen-all
4. Add handler method to appropriate handlers_*.go
5. Add conversion functions to convert_*.go if new types
6. Add test in handlers_test.go
7. Update Python SDK client (see python-sdk/CLAUDE.md)

Adding a New Hook

1. Add RPC to hooks.proto service definition
2. Add request/response messages to appropriate hooks_*.proto
3. Run make -C public proto-gen-all
4. Add handler in plugin/hooks_grpc_client.go
5. Update Python SDK hooks (see python-sdk/CLAUDE.md)

Common Patterns

Response-Embedded Errors

All RPC responses include optional AppError:

message GetUserResponse {
  User user = 1;
  AppError error = 2;
}

Handlers check for errors from API calls and populate the error field:

user, appErr := s.api.GetUser(req.UserId)
if appErr != nil {
    return &pb.GetUserResponse{Error: ToAppErrorProto(appErr)}, nil
}
return &pb.GetUserResponse{User: ToUserProto(user)}, nil

ServeHTTP Streaming

ServeHTTP uses bidirectional streaming with message types:

• HTTPRequestInit - Initial request metadata
• HTTPRequestBody - Request body chunks
• HTTPResponseInit - Response status and headers
• HTTPResponseBody - Response body chunks

See serve_http.go and serve_http_test.go for implementation details.