# RPC Protocol

## JSON-RPC 2.0

The server implements **JSON-RPC 2.0** over TCP with length-prefixed framing (see [Architecture → Wire framing](architecture.md#wire-framing)).

Batch requests are not supported — only single request objects are processed.

### Request format

```json
{
  "jsonrpc": "2.0",
  "method": "<method_name>",
  "params": {},
  "id": <integer|string>
}
```

The `params` field is accepted but currently ignored by all implemented methods. The `id` field is required; requests without it receive a `-32600 Invalid Request` error.

### Success response

```json
{
  "jsonrpc": "2.0",
  "result": <method_specific_result>,
  "id": <matching_request_id>
}
```

### Error response

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": <integer>,
    "message": "<string>"
  },
  "id": <matching_request_id>
}
```

### Error codes

| Code | Meaning | When |
|---|---|---|
| `-32700` | Parse error | Request is not valid JSON |
| `-32600` | Invalid Request | Missing `jsonrpc`, `method`, or `id` fields, or `jsonrpc != "2.0"` |
| `-32601` | Method not found | No handler registered for the requested method name |
| `-32000` | Server error | Handler threw an exception |

> **Known issue**: Non-object JSON (arrays, strings, numbers, null) causes a `nlohmann::json::type_error` instead of a clean `-32600` response. See `tests/test_rpc_edge_cases.cpp`.

Source: `src/rpc_server.cpp` — `RpcServer::process()` and `create_error()`.

## Methods

### `get-intrinsic-params`

Retrieves intrinsic camera parameters as a flat 3×3 matrix (row-major, 9 doubles).

**Request:**
```json
{"jsonrpc": "2.0", "method": "get-intrinsic-params", "id": 1}
```

**Response:**
```json
{"jsonrpc": "2.0", "result": <base64-encoded-array>, "id": 1}
```

Result type: `vector<double>` (size 9), Base64-encoded.

### `get-extrinsic-params`

Retrieves extrinsic camera parameters as a flat 4×4 matrix (row-major, 16 doubles).

**Request:**
```json
{"jsonrpc": "2.0", "method": "get-extrinsic-params", "id": 2}
```

**Response:**
```json
{"jsonrpc": "2.0", "result": <base64-encoded-array>, "id": 2}
```

Result type: `vector<double>` (size 16), Base64-encoded.

### `get-cloud-point`

Retrieves the current field-of-view point cloud.

**Request:**
```json
{"jsonrpc": "2.0", "method": "get-cloud-point", "id": 3}
```

**Response:**
```json
{"jsonrpc": "2.0", "result": {"width": int, "height": int, "data": <base64-encoded-array>}, "id": 3}
```

Result type: `matrix WxH` (list of `[x, y, z]` points), Base64-encoded.

> **Note**: The standalone mock server (`server_main.cpp`) returns these as raw JSON arrays (not Base64-encoded) via `Service`. The Base64 encoding is expected to be implemented on the Unity side per `API.md`.

## Handler registration

Handlers are registered with `RpcServer::register_method()`. Two forms exist:

### C++ handler

```cpp
rpc_server.register_method("get-intrinsic-params", [&](const json& params) {
    return service.get_intrinsic_params();  // returns vector<double>
});
```

The handler returns `std::variant<nlohmann::json, std::string>`. If a `json` is returned, it is placed directly in the `result` field. If a `std::string` is returned, it is placed as-is.

### C callback handler

```cpp
rpc_string* my_callback(rpc_string* params_json) {
    // params_json->s contains the JSON params as a string
    // return a result string (JSON or raw)
    return crpc_str_create("result_data", 11);
}

rpc_server.register_method("my-method", my_callback);
```

The C callback receives the JSON `params` as a string in `rpc_string->s`. The return value's string is parsed as JSON if possible; otherwise it is used as a raw string in the `result` field.

Source: `src/rpc_server.cpp` — `register_method(name, callback_t)` overload.

## Base64 encoding

`include/cloud_point_rpc/rpc_coder.hpp`, `src/rpc_coder.cpp`

- `Base64RPCCoder` implements the `IRPCCoder` interface with `encode()` and `decode()` methods.
- Uses the [aklomp/base64](https://github.com/aklomp/base64) library (Meson wrap `subprojects/aklomp-base64.wrap`).
- `encode(vector<char>) → string` and `decode(string) → vector<char>`.
- Includes overflow protection: throws `std::length_error` if input exceeds safe size limits.

> Per `API.md`, Base64 encoding/decoding of camera data is expected to be done on the **Unity side**. The `Base64RPCCoder` class is available for C++ consumers but is not used by the mock server's response path.

## Client-side usage

`include/cloud_point_rpc/rpc_client.hpp`

`RpcClient` wraps `jsonrpccxx::JsonRpcClient` and provides typed access:

```cpp
score::TCPConnector connector(ip, port);
score::RpcClient client(connector);

auto intrinsic = client.get_intrinsic_params();   // vector<double>
auto extrinsic = client.get_extrinsic_params();   // vector<double>
auto cloud     = client.get_cloud_point();        // vector<vector<double>>
```

The interactive CLI (`src/cli.cpp`) and `minimal_client` (`src/minimal_client.cpp`) demonstrate client usage.