yaze/docs/internal/archive/completed_features/grpc-server-implementation.md

gRPC Server Implementation for Yaze AI Infrastructure

Overview

This document describes the implementation of the unified gRPC server hosting for AI agent control in the yaze GUI application.

Phase 1: gRPC Server Hosting (Complete)

Goal

Stand up a unified gRPC server that registers EmulatorService + RomService and starts when the application launches with the right flags.

Implementation Summary

Files Modified

1. src/cli/service/agent/agent_control_server.h

   • Updated constructor to accept Rom* and port parameters
   • Added IsRunning() and GetPort() methods for status checking
   • Added proper documentation

2. src/cli/service/agent/agent_control_server.cc

   • Modified to register both EmulatorService and RomService
   • Added configurable port support
   • Improved logging with service information
   • Added running state tracking

3. src/app/editor/editor_manager.h

   • Added StartAgentServer(int port) method
   • Added StopAgentServer() method
   • Added UpdateAgentServerRom(Rom* new_rom) method for ROM updates

4. src/app/editor/editor_manager.cc

   • Implemented server lifecycle methods
   • Added automatic ROM updates when session changes
   • Clean shutdown in destructor

5. src/app/controller.h & controller.cc

   • Added EnableGrpcServer(int port) method
   • Bridges command-line flags to EditorManager

6. src/app/main.cc

   • Added --enable-grpc flag to enable the server
   • Added --grpc-port flag (default: 50052)
   • Hooks server startup after controller initialization

Key Features

1. Unified Service Registration

• Both EmulatorService and RomService run on the same port
• Simplifies client connections
• Services registered conditionally based on availability

2. Dynamic ROM Updates

• Server automatically restarts when ROM changes
• Maintains port consistency during ROM switches
• Null ROM handling for startup without loaded ROM

3. Error Handling

• Graceful server shutdown on application exit
• Prevention of multiple server instances
• Proper cleanup in all code paths

4. Logging

• Clear startup messages showing port and services
• Warning for duplicate startup attempts
• Info logs for server lifecycle events

Usage

Starting the Application with gRPC Server

# Start with default port (50052)
./build/bin/yaze --enable-grpc

# Start with custom port
./build/bin/yaze --enable-grpc --grpc-port 50055

# Start with ROM and gRPC
./build/bin/yaze --rom_file=zelda3.sfc --enable-grpc

Testing the Server

# Check if server is listening
lsof -i :50052

# List available services (requires grpcurl)
grpcurl -plaintext localhost:50052 list

# Test EmulatorService
grpcurl -plaintext localhost:50052 yaze.proto.EmulatorService/GetState

# Test RomService (after loading ROM)
grpcurl -plaintext localhost:50052 yaze.proto.RomService/GetRomInfo

Architecture

Main Application
├── Controller
│   └── EnableGrpcServer(port)
│       └── EditorManager
│           └── StartAgentServer(port)
│               └── AgentControlServer
│                   ├── EmulatorServiceImpl
│                   └── RomServiceImpl

Thread Safety

• Server runs in separate thread via std::thread
• Uses atomic flag for running state
• gRPC handles concurrent requests internally

Future Enhancements (Phase 2+)

1. Authentication & Security

   • TLS support for production deployments
   • Token-based authentication for remote access

2. Service Discovery

   • mDNS/Bonjour for automatic discovery
   • Health check endpoints

3. Additional Services

   • CanvasAutomationService for GUI automation
   • ProjectService for project management
   • CollaborationService for multi-user editing

4. Configuration

   • Config file support for server settings
   • Environment variables for API keys
   • Persistent server settings

5. Monitoring

   • Prometheus metrics endpoint
   • Request logging and tracing
   • Performance metrics

Testing Checklist

• Server starts on default port
• Server starts on custom port
• EmulatorService accessible
• RomService accessible after ROM load
• Server updates when ROM changes
• Clean shutdown on application exit
• Multiple startup prevention
• Integration tests (requires build completion)
• Load testing with concurrent requests
• Error recovery scenarios

Dependencies

• gRPC 1.76.0+
• Protobuf 3.31.1+
• C++17 or later
• YAZE_WITH_GRPC build flag enabled

Build Configuration

Ensure CMake is configured with gRPC support:

cmake --preset mac-ai    # macOS with AI features
cmake --preset lin-ai    # Linux with AI features
cmake --preset win-ai    # Windows with AI features

Troubleshooting

Port Already in Use

If port is already in use, either:

1. Use a different port: --grpc-port 50053
2. Find and kill the process: lsof -i :50052 | grep LISTEN

Service Not Available

• Ensure ROM is loaded for RomService methods
• Check build has YAZE_WITH_GRPC enabled
• Verify protobuf files were generated

Connection Refused

• Verify server started successfully (check logs)
• Ensure firewall allows the port
• Try localhost instead of 127.0.0.1

Implementation Status

✅ Phase 1 Complete: Unified gRPC server hosting with EmulatorService and RomService is fully implemented and ready for testing.

Next Steps

1. Complete build and run integration tests
2. Document gRPC API endpoints for clients
3. Implement z3ed CLI client commands
4. Add authentication for production use