add-rpc

Adding RPC Calls Guide

Overview

Wave Terminal uses a WebSocket-based RPC (Remote Procedure Call) system for communication between different components. The RPC system allows the frontend, backend, electron main process, remote servers, and terminal blocks to communicate with each other through well-defined commands.

This guide covers how to add a new RPC command to the system.

Key Files

• pkg/wshrpc/wshrpctypes.go - RPC interface and type definitions
• pkg/wshrpc/wshserver/wshserver.go - Main server implementation (most common)
• emain/emain-wsh.ts - Electron main process implementation
• frontend/app/store/tabrpcclient.ts - Frontend tab implementation
• pkg/wshrpc/wshremote/wshremote.go - Remote server implementation
• frontend/app/view/term/term-wsh.tsx - Terminal block implementation

RPC Command Structure

RPC commands in Wave Terminal follow these conventions:

• Method names must end with Command
• First parameter must be context.Context
• Remaining parameters are a regular Go parameter list (zero or more typed args)
• Return values can be either just an error, or one return value plus an error
• Streaming commands return a channel instead of a direct value

Adding a New RPC Call

Step 1: Define the Command in the Interface

Add your command to the WshRpcInterface in pkg/wshrpc/wshrpctypes.go:

type WshRpcInterface interface {
    // ... existing commands ...
    
    // Add your new command
    YourNewCommand(ctx context.Context, data CommandYourNewData) (*YourNewResponse, error)
}

Method Signature Rules:

• Method name must end with Command
• First parameter must be ctx context.Context
• Remaining parameters are a regular Go parameter list (zero or more)
• Return either error or (ReturnType, error)
• For streaming, return chan RespOrErrorUnion[T]

Step 2: Define Request and Response Types

If your command needs structured input or output, define types in the same file: