gRPC API Reference¶

This document describes the gRPC API used for communication between Gateway and Core processes.

Overview¶

The Core service is the main game service exposed by the Core process. Gateway connects to this service over gRPC with mTLS authentication.

Protocol: gRPC over mTLS (TLS 1.3) Default Address: localhost:9000 Proto Package: holomush.core.v1

Service Definition¶

service Core {
  rpc Authenticate(AuthRequest) returns (AuthResponse);
  rpc HandleCommand(CommandRequest) returns (CommandResponse);
  rpc Subscribe(SubscribeRequest) returns (stream Event);
  rpc Disconnect(DisconnectRequest) returns (DisconnectResponse);
}

Common Types¶

RequestMeta¶

Metadata included with every request for correlation and debugging.

ResponseMeta¶

Metadata echoed back in every response.

RPCs¶

Authenticate¶

Validates credentials and creates a session for the authenticated character.

Request: AuthRequest

Response: AuthResponse

Error Handling:

Example:

resp, err := client.Authenticate(ctx, &corev1.AuthRequest{
    Meta: &corev1.RequestMeta{
        RequestId: ulid.Make().String(),
        Timestamp: timestamppb.Now(),
    },
    Username: "testuser",
    Password: "password",
})
if err != nil {
    // Handle gRPC error
}
if !resp.Success {
    // Handle authentication failure
    fmt.Println("Auth failed:", resp.Error)
}
// Use resp.SessionId for subsequent requests

HandleCommand¶

Processes a game command from an authenticated session.

Request: CommandRequest

Response: CommandResponse

Error Handling:

Supported Commands:

Subscribe¶

Opens a server-streaming connection to receive events for a session.

Request: SubscribeRequest

If streams is empty, the server subscribes to default streams based on the character's current location and subscriptions.

Response: stream Event

The server streams events as they occur. Each event contains:

Stream Types:

Event Types:

Error Handling:

Disconnect¶

Ends a session and cleans up resources.

Request: DisconnectRequest

Response: DisconnectResponse

Error Handling¶

The API uses standard gRPC status codes for transport-level errors:

Application-level errors are returned in the response's error field with success=false.

OpenTelemetry Integration¶

All RPC calls propagate OpenTelemetry trace context automatically via gRPC metadata. This enables distributed tracing across Gateway and Core.

Trace Context¶

Logs from both Gateway and Core include:

Enable trace export with the --otlp-endpoint flag on both processes.

Security¶

mTLS Requirements¶

All connections require mutual TLS authentication:

1. Gateway presents client certificate signed by Root CA
2. Core verifies Gateway certificate against Root CA
3. Gateway verifies Core certificate contains expected game_id in SAN

Certificate Validation¶

Connection Lifecycle¶

Gateway Startup¶

1. Load TLS certificates from $XDG_CONFIG_HOME/holomush/certs/
2. Read game_id from $XDG_CONFIG_HOME/holomush/gateway.yaml
3. Connect to Core at --core-addr (default: localhost:9000)
4. Verify Core certificate SAN contains expected game_id
5. Begin accepting client connections

Reconnection¶

Gateway automatically reconnects to Core when:

• Core restarts
• Network interruption occurs
• gRPC connection drops

During reconnection:

• Client connections remain open
• Commands queue until Core is available
• Subscribe streams automatically re-establish

Proto File Location¶

The complete proto definition is at:

api/proto/holomush/core/v1/core.proto

Generated Go code is in:

pkg/proto/holomush/core/v1/