You Don't Know JSON: Part 5 - JSON-RPC: When REST Isn't Enough

1
2
3
4

GET    /users/user-5f9d88c          # Get user
PUT    /users/user-5f9d88c          # Update user
POST   /users/user-5f9d88c/follow   # Follow action (forced into REST)
GET    /users/search?q=alice        # Search (not really RESTful)

1
2
3
4

{"jsonrpc": "2.0", "method": "getUserById", "params": {"id": "user-5f9d88c"}, "id": 1}
{"jsonrpc": "2.0", "method": "updateUser", "params": {"id": "user-5f9d88c", "name": "Alice Smith"}, "id": 2}
{"jsonrpc": "2.0", "method": "followUser", "params": {"followerId": "user-abc123", "followeeId": "user-5f9d88c"}, "id": 3}
{"jsonrpc": "2.0", "method": "searchUsers", "params": {"query": "alice", "filters": {"verified": true}}, "id": 4}

1
2

// Local function
const result = calculator.add(5, 3);  // 8

1
2

// Remote function (same interface)
const result = await remoteCalculator.add(5, 3);  // 8

1
2
3
4

GET    /users/123      # Read
POST   /users          # Create
PUT    /users/123      # Update
DELETE /users/123      # Delete

1
2
3
4

POST /transfers
POST /route-calculations
POST /server-restarts
GET  /users?search=query&filter=...

1
2
3
4
5
6

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": [42, 23],
  "id": 1
}

1
2
3
4
5

{
  "jsonrpc": "2.0",
  "result": 19,
  "id": 1
}

1
2
3
4
5
6
7
8
9

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": "No method named 'subtract'"
  },
  "id": 1
}

1
2
3
4
5

{
  "jsonrpc": "2.0",
  "method": "logEvent",
  "params": {"level": "info", "message": "User logged in"}
}

1
2
3
4
5
6

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": [42, 23],
  "id": 1
}

1
2
3

function subtract(a, b) {
  return a - b;  // a=42, b=23
}

1
2
3
4
5
6

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": {"minuend": 42, "subtrahend": 23},
  "id": 1
}

1
2
3

function subtract({minuend, subtrahend}) {
  return minuend - subtrahend;
}

1
2
3
4
5
6
7

const ErrorCodes = {
  UNAUTHORIZED: -32001,
  RATE_LIMIT_EXCEEDED: -32002,
  RESOURCE_NOT_FOUND: -32003,
  VALIDATION_FAILED: -32004,
  INSUFFICIENT_FUNDS: -32005
};

1
2
3
4
5
6

[
  {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
  {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
  {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
  {"jsonrpc": "2.0", "method": "get_data", "id": "9"}
]

1
2
3
4
5

[
  {"jsonrpc": "2.0", "result": 7, "id": "1"},
  {"jsonrpc": "2.0", "result": 19, "id": "2"},
  {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
]

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

const express = require('express');
const app = express();

app.use(express.json());

// Define methods
const methods = {
  add: (a, b) => a + b,
  
  subtract: (a, b) => a - b,
  
  multiply: (a, b) => a * b,
  
  divide: (a, b) => {
    if (b === 0) {
      const error = new Error('Division by zero');
      error.code = -32000;
      throw error;
    }
    return a / b;
  },
  
  // Named parameters
  greet: ({name, title}) => {
    return `Hello, ${title} ${name}!`;
  }
};

// JSON-RPC handler
app.post('/rpc', (req, res) => {
  const request = req.body;
  
  // Validate request structure
  if (!request.jsonrpc || request.jsonrpc !== '2.0') {
    return res.json({
      jsonrpc: '2.0',
      error: {code: -32600, message: 'Invalid Request'},
      id: request.id || null
    });
  }
  
  // Handle batch requests
  if (Array.isArray(request)) {
    const responses = request
      .map(req => handleSingleRequest(req))
      .filter(resp => resp !== null); // Filter out notifications
    return res.json(responses);
  }
  
  // Handle single request
  const response = handleSingleRequest(request);
  if (response) {
    res.json(response);
  } else {
    res.status(204).end(); // Notification - no response
  }
});

function handleSingleRequest(request) {
  const {method, params, id} = request;
  
  // Notification - no response
  if (id === undefined) {
    if (methods[method]) {
      try {
        methods[method](...(Array.isArray(params) ? params : [params]));
      } catch (err) {
        // Notifications don't return errors
      }
    }
    return null;
  }
  
  // Check if method exists
  if (!methods[method]) {
    return {
      jsonrpc: '2.0',
      error: {code: -32601, message: 'Method not found'},
      id
    };
  }
  
  // Execute method
  try {
    let args;
    if (Array.isArray(params)) {
      args = params;
    } else if (typeof params === 'object') {
      args = [params]; // Named parameters
    } else {
      args = [];
    }
    
    const result = methods[method](...args);
    
    return {
      jsonrpc: '2.0',
      result,
      id
    };
  } catch (error) {
    return {
      jsonrpc: '2.0',
      error: {
        code: error.code || -32603,
        message: error.message
      },
      id
    };
  }
}

app.listen(3000, () => {
  console.log('JSON-RPC server on http://localhost:3000/rpc');
});

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"net/http"
)

// MathService provides mathematical operations
type MathService struct{}

// Args for basic math operations
type Args struct {
	A float64 `json:"a"`
	B float64 `json:"b"`
}

// Add two numbers
func (s *MathService) Add(args Args) (float64, error) {
	return args.A + args.B, nil
}

// Subtract two numbers
func (s *MathService) Subtract(args Args) (float64, error) {
	return args.A - args.B, nil
}

// Divide two numbers
func (s *MathService) Divide(args Args) (float64, error) {
	if args.B == 0 {
		return 0, errors.New("division by zero")
	}
	return args.A / args.B, nil
}

// JSON-RPC request structure
type Request struct {
	JsonRPC string          `json:"jsonrpc"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params"`
	ID      interface{}     `json:"id"`
}

// JSON-RPC response structure
type Response struct {
	JsonRPC string      `json:"jsonrpc"`
	Result  interface{} `json:"result,omitempty"`
	Error   *Error      `json:"error,omitempty"`
	ID      interface{} `json:"id"`
}

// Error structure
type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

var mathService = &MathService{}

func handleRPC(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
		return
	}

	var req Request
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		writeError(w, -32700, "Parse error", nil)
		return
	}

	if req.JsonRPC != "2.0" {
		writeError(w, -32600, "Invalid Request", req.ID)
		return
	}

	// Dispatch to method
	var result interface{}
	var err error

	switch req.Method {
	case "add":
		var args Args
		json.Unmarshal(req.Params, &args)
		result, err = mathService.Add(args)
	case "subtract":
		var args Args
		json.Unmarshal(req.Params, &args)
		result, err = mathService.Subtract(args)
	case "divide":
		var args Args
		json.Unmarshal(req.Params, &args)
		result, err = mathService.Divide(args)
	default:
		writeError(w, -32601, "Method not found", req.ID)
		return
	}

	if err != nil {
		writeError(w, -32000, err.Error(), req.ID)
		return
	}

	resp := Response{
		JsonRPC: "2.0",
		Result:  result,
		ID:      req.ID,
	}

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(resp)
}

func writeError(w http.ResponseWriter, code int, message string, id interface{}) {
	resp := Response{
		JsonRPC: "2.0",
		Error:   &Error{Code: code, Message: message},
		ID:      id,
	}
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK) // JSON-RPC errors use 200 status
	json.NewEncoder(w).Encode(resp)
}

func main() {
	http.HandleFunc("/rpc", handleRPC)
	fmt.Println("JSON-RPC server on http://localhost:8080/rpc")
	http.ListenAndServe(":8080", nil)
}

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

class JSONRPCClient {
  constructor(url, options = {}) {
    this.url = url;
    this.requestId = 0;
    this.timeout = options.timeout || 30000;
    this.headers = options.headers || {};
  }
  
  /**
   * Call a remote method
   * @param {string} method - Method name
   * @param {Array|Object} params - Parameters
   * @returns {Promise<any>} Result
   */
  async call(method, params = []) {
    const request = {
      jsonrpc: '2.0',
      method,
      params,
      id: ++this.requestId
    };
    
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
    
    try {
      const response = await fetch(this.url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          ...this.headers
        },
        body: JSON.stringify(request),
        signal: controller.signal
      });
      
      clearTimeout(timeoutId);
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
      
      const data = await response.json();
      
      if (data.error) {
        const error = new Error(data.error.message);
        error.code = data.error.code;
        error.data = data.error.data;
        throw error;
      }
      
      return data.result;
    } catch (error) {
      clearTimeout(timeoutId);
      if (error.name === 'AbortError') {
        throw new Error(`Request timeout after ${this.timeout}ms`);
      }
      throw error;
    }
  }
  
  /**
   * Send a notification (no response expected)
   * @param {string} method - Method name
   * @param {Array|Object} params - Parameters
   */
  notify(method, params = []) {
    const request = {
      jsonrpc: '2.0',
      method,
      params
    };
    
    // Fire and forget
    fetch(this.url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        ...this.headers
      },
      body: JSON.stringify(request)
    }).catch(() => {
      // Ignore errors for notifications
    });
  }
  
  /**
   * Send batch request
   * @param {Array<{method, params}>} calls - Array of calls
   * @returns {Promise<Array>} Array of results
   */
  async batch(calls) {
    const requests = calls.map(call => ({
      jsonrpc: '2.0',
      method: call.method,
      params: call.params || [],
      id: ++this.requestId
    }));
    
    const response = await fetch(this.url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        ...this.headers
      },
      body: JSON.stringify(requests)
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const data = await response.json();
    
    // Map responses back to call order
    return requests.map(req => {
      const resp = data.find(r => r.id === req.id);
      if (!resp) {
        throw new Error(`No response for request ${req.id}`);
      }
      if (resp.error) {
        const error = new Error(resp.error.message);
        error.code = resp.error.code;
        throw error;
      }
      return resp.result;
    });
  }
}

// Usage examples
const client = new JSONRPCClient('http://localhost:3000/rpc', {
  timeout: 5000,
  headers: {
    'Authorization': 'Bearer token123'
  }
});

// Simple call
const sum = await client.call('add', [5, 3]);
console.log('Sum:', sum);  // 8

// Named parameters
const greeting = await client.call('greet', {name: 'Alice', title: 'Dr.'});
console.log(greeting);  // "Hello, Dr. Alice!"

// Notification
client.notify('logEvent', {level: 'info', message: 'User action'});

// Batch request
const results = await client.batch([
  {method: 'add', params: [1, 2]},
  {method: 'multiply', params: [3, 4]},
  {method: 'subtract', params: [10, 5]}
]);
console.log(results);  // [3, 12, 5]

// Error handling
try {
  await client.call('divide', [10, 0]);
} catch (error) {
  console.error(`Error ${error.code}: ${error.message}`);
}

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"sync/atomic"
)

type JSONRPCClient struct {
	url    string
	client *http.Client
	id     int64
}

type Request struct {
	JsonRPC string      `json:"jsonrpc"`
	Method  string      `json:"method"`
	Params  interface{} `json:"params"`
	ID      int64       `json:"id,omitempty"`
}

type Response struct {
	JsonRPC string          `json:"jsonrpc"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *RPCError       `json:"error,omitempty"`
	ID      int64           `json:"id"`
}

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    interface{} `json:"data,omitempty"`
}

func (e *RPCError) Error() string {
	return fmt.Sprintf("JSON-RPC error %d: %s", e.Code, e.Message)
}

func NewClient(url string) *JSONRPCClient {
	return &JSONRPCClient{
		url:    url,
		client: &http.Client{},
	}
}

func (c *JSONRPCClient) Call(method string, params interface{}, result interface{}) error {
	id := atomic.AddInt64(&c.id, 1)
	
	request := Request{
		JsonRPC: "2.0",
		Method:  method,
		Params:  params,
		ID:      id,
	}
	
	body, err := json.Marshal(request)
	if err != nil {
		return err
	}
	
	resp, err := c.client.Post(c.url, "application/json", bytes.NewReader(body))
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	
	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("HTTP %d: %s", resp.StatusCode, resp.Status)
	}
	
	var response Response
	if err := json.NewDecoder(resp.Body).Decode(&response); err != nil {
		return err
	}
	
	if response.Error != nil {
		return response.Error
	}
	
	if result != nil {
		return json.Unmarshal(response.Result, result)
	}
	
	return nil
}

func (c *JSONRPCClient) Notify(method string, params interface{}) {
	request := Request{
		JsonRPC: "2.0",
		Method:  method,
		Params:  params,
	}
	
	body, _ := json.Marshal(request)
	c.client.Post(c.url, "application/json", bytes.NewReader(body))
}

// Usage
func main() {
	client := NewClient("http://localhost:8080/rpc")
	
	// Call method
	var sum float64
	err := client.Call("add", map[string]float64{"a": 5, "b": 3}, &sum)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	fmt.Printf("Sum: %v\n", sum)
	
	// Notification
	client.Notify("logEvent", map[string]string{
		"level": "info",
		"message": "Application started",
	})
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', (ws) => {
  console.log('Client connected');
  
  // Handle incoming requests
  ws.on('message', (data) => {
    try {
      const request = JSON.parse(data);
      const response = handleRequest(request);
      if (response) {
        ws.send(JSON.stringify(response));
      }
    } catch (error) {
      ws.send(JSON.stringify({
        jsonrpc: '2.0',
        error: {code: -32700, message: 'Parse error'},
        id: null
      }));
    }
  });
  
  // Server can initiate requests to client
  function notifyClient(event, data) {
    ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: event,
      params: data
    }));
  }
  
  // Example: Send notification to client every 5 seconds
  const interval = setInterval(() => {
    notifyClient('serverTime', { time: new Date().toISOString() });
  }, 5000);
  
  ws.on('close', () => {
    clearInterval(interval);
    console.log('Client disconnected');
  });
});

function handleRequest(request) {
  const methods = {
    ping: () => 'pong',
    echo: (message) => message,
    getServerInfo: () => ({
      version: '1.0.0',
      uptime: process.uptime()
    })
  };
  
  if (request.id === undefined) {
    // Notification - no response
    if (methods[request.method]) {
      methods[request.method](...(request.params || []));
    }
    return null;
  }
  
  if (!methods[request.method]) {
    return {
      jsonrpc: '2.0',
      error: {code: -32601, message: 'Method not found'},
      id: request.id
    };
  }
  
  try {
    const result = methods[request.method](...(request.params || []));
    return {
      jsonrpc: '2.0',
      result,
      id: request.id
    };
  } catch (error) {
    return {
      jsonrpc: '2.0',
      error: {code: -32000, message: error.message},
      id: request.id
    };
  }
}

console.log('WebSocket JSON-RPC server on ws://localhost:8080');

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

class JSONRPCWebSocketClient {
  constructor(url) {
    this.url = url;
    this.ws = null;
    this.requestId = 0;
    this.pendingRequests = new Map();
    this.eventHandlers = new Map();
  }
  
  connect() {
    return new Promise((resolve, reject) => {
      this.ws = new WebSocket(this.url);
      
      this.ws.onopen = () => {
        console.log('Connected');
        resolve();
      };
      
      this.ws.onerror = (error) => {
        reject(error);
      };
      
      this.ws.onmessage = (event) => {
        const message = JSON.parse(event.data);
        
        if (message.id) {
          // Response to our request
          const pending = this.pendingRequests.get(message.id);
          if (pending) {
            this.pendingRequests.delete(message.id);
            if (message.error) {
              pending.reject(new Error(message.error.message));
            } else {
              pending.resolve(message.result);
            }
          }
        } else {
          // Server-initiated notification
          this.handleNotification(message);
        }
      };
      
      this.ws.onclose = () => {
        console.log('Disconnected');
        // Reject all pending requests
        for (const [id, pending] of this.pendingRequests) {
          pending.reject(new Error('Connection closed'));
        }
        this.pendingRequests.clear();
      };
    });
  }
  
  call(method, params = []) {
    return new Promise((resolve, reject) => {
      const id = ++this.requestId;
      
      this.pendingRequests.set(id, { resolve, reject });
      
      this.ws.send(JSON.stringify({
        jsonrpc: '2.0',
        method,
        params,
        id
      }));
      
      // Timeout after 30 seconds
      setTimeout(() => {
        if (this.pendingRequests.has(id)) {
          this.pendingRequests.delete(id);
          reject(new Error('Request timeout'));
        }
      }, 30000);
    });
  }
  
  notify(method, params = []) {
    this.ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method,
      params
    }));
  }
  
  on(method, handler) {
    this.eventHandlers.set(method, handler);
  }
  
  handleNotification(message) {
    const handler = this.eventHandlers.get(message.method);
    if (handler) {
      handler(...(message.params || []));
    }
  }
  
  close() {
    this.ws.close();
  }
}

// Usage
const client = new JSONRPCWebSocketClient('ws://localhost:8080');

await client.connect();

// Register handler for server notifications
client.on('serverTime', (data) => {
  console.log('Server time:', data.time);
});

// Call server method
const info = await client.call('getServerInfo');
console.log('Server info:', info);

// Send notification to server
client.notify('clientStatus', { status: 'active' });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// Get account balance
const balance = await client.call('eth_getBalance', [
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  'latest'
]);

// Get current block number
const blockNumber = await client.call('eth_blockNumber', []);

// Send transaction
const txHash = await client.call('eth_sendTransaction', [{
  from: '0x...',
  to: '0x...',
  value: '0x9184e72a000', // 10000000000000 wei
  gas: '0x5208'           // 21000 gas
}]);

// Get transaction receipt
const receipt = await client.call('eth_getTransactionReceipt', [txHash]);

// Call smart contract (read-only)
const result = await client.call('eth_call', [{
  to: '0x...',      // Contract address
  data: '0x...'     // Encoded function call
}, 'latest']);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

// Client → Server: Request code completion
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "textDocument/completion",
  "params": {
    "textDocument": {
      "uri": "file:///path/to/file.ts"
    },
    "position": {
      "line": 10,
      "character": 15
    }
  }
}

// Server → Client: Completion results
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "items": [
      {
        "label": "console",
        "kind": 6,
        "detail": "Console object"
      },
      {
        "label": "const",
        "kind": 14,
        "detail": "const keyword"
      }
    ]
  }
}

// Server → Client: Publish diagnostics (notification)
{
  "jsonrpc": "2.0",
  "method": "textDocument/publishDiagnostics",
  "params": {
    "uri": "file:///path/to/file.ts",
    "diagnostics": [
      {
        "range": {
          "start": {"line": 5, "character": 10},
          "end": {"line": 5, "character": 20}
        },
        "severity": 1,
        "message": "Variable 'x' is not defined"
      }
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// Get blockchain info
const info = await client.call('getblockchaininfo', []);

// Get wallet balance
const balance = await client.call('getbalance', []);

// Send Bitcoin
const txid = await client.call('sendtoaddress', [
  '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',  // Address
  0.01,                                    // Amount in BTC
  'Payment for services'                   // Comment
]);

// Generate new address
const address = await client.call('getnewaddress', ['', 'bech32']);

// Get transaction details
const tx = await client.call('gettransaction', [txid]);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// Register command handler
client.on('sendMessage', async ({channelId, content}) => {
  // Send message to Discord channel
  await discord.channels.get(channelId).send(content);
  return {success: true};
});

// Bot receives command from Discord
await rpcClient.call('onMessage', {
  author: 'User#1234',
  content: '!hello',
  channelId: '123456789'
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// User service
const userService = new JSONRPCClient('http://user-service/rpc');

// Order service calls user service
const user = await userService.call('getUserById', {id: 123});
const address = await userService.call('getUserAddress', {
  userId: 123,
  addressType: 'shipping'
});

// Batch request for efficiency
const [user, orders, preferences] = await userService.batch([
  {method: 'getUserById', params: {id: 123}},
  {method: 'getUserOrders', params: {userId: 123, limit: 10}},
  {method: 'getUserPreferences', params: {userId: 123}}
]);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Bad: Positional parameters
{"method": "createUser", "params": ["alice", "alice@example.com", 30, true]}

// Good: Named parameters
{"method": "createUser", "params": {
  "username": "alice",
  "email": "alice@example.com",
  "age": 30,
  "active": true
}}

1
2
3
4
5

// Version in method name
client.call('v2.getUser', {id: 123});

// Or use a parameter
client.call('getUser', {version: 2, id: 123});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

const ErrorCodes = {
  // Standard JSON-RPC codes
  PARSE_ERROR: -32700,
  INVALID_REQUEST: -32600,
  METHOD_NOT_FOUND: -32601,
  INVALID_PARAMS: -32602,
  INTERNAL_ERROR: -32603,
  
  // Application codes (start at -32000 or use positive)
  UNAUTHORIZED: -32001,
  FORBIDDEN: -32002,
  NOT_FOUND: -32003,
  VALIDATION_ERROR: -32004,
  RATE_LIMIT: -32005
};

1
2
3
4
5

// Client-side timeout
const result = await client.call('longOperation', {}, {timeout: 60000});

// Server-side timeout
app.post('/rpc', timeout('30s'), handleRPC);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

app.use((req, res, next) => {
  if (req.path === '/rpc') {
    const start = Date.now();
    const requestId = generateId();
    
    console.log('RPC Request', {
      id: requestId,
      method: req.body.method,
      params: req.body.params
    });
    
    res.on('finish', () => {
      console.log('RPC Response', {
        id: requestId,
        duration: Date.now() - start,
        status: res.statusCode
      });
    });
  }
  next();
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Instead of 100 separate requests
for (const id of userIds) {
  await client.call('getUser', {id});
}

// Single batch request
const calls = userIds.map(id => ({
  method: 'getUser',
  params: {id}
}));
const users = await client.batch(calls);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const schemas = {
  'createUser': {
    username: {type: 'string', minLength: 3, maxLength: 20},
    email: {type: 'string', format: 'email'},
    age: {type: 'number', minimum: 0}
  }
};

function validateParams(method, params) {
  const schema = schemas[method];
  if (!schema) return true;
  
  return validate(params, schema);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

const rateLimit = require('express-rate-limit');

app.use('/rpc', rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,                  // 100 requests per window
  handler: (req, res) => {
    res.json({
      jsonrpc: '2.0',
      error: {
        code: -32005,
        message: 'Rate limit exceeded'
      },
      id: req.body.id
    });
  }
}));

1
2
3
4
5
6
7

// HTTP client with connection pooling
const client = new JSONRPCClient('http://api/rpc', {
  agent: new http.Agent({
    keepAlive: true,
    maxSockets: 50
  })
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

/**
 * Get user by ID
 * @method getUser
 * @param {number} id - User ID
 * @returns {Object} User object with id, username, email
 * @throws {-32003} User not found
 */
methods['getUser'] = async ({id}) => {
  const user = await db.users.findById(id);
  if (!user) {
    const error = new Error('User not found');
    error.code = -32003;
    throw error;
  }
  return user;
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

app.post('/rpc', authenticateToken, handleRPC);

function authenticateToken(req, res, next) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  
  if (!token) {
    return res.json({
      jsonrpc: '2.0',
      error: {code: -32001, message: 'Unauthorized'},
      id: req.body.id
    });
  }
  
  try {
    req.user = verifyJWT(token);
    next();
  } catch (err) {
    return res.json({
      jsonrpc: '2.0',
      error: {code: -32001, message: 'Invalid token'},
      id: req.body.id
    });
  }
}

1
2
3
4
5

const client = new JSONRPCClient('http://api/rpc', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  }
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

const methodPermissions = {
  'getUser': ['user', 'admin'],
  'createUser': ['admin'],
  'deleteUser': ['admin']
};

function authorize(method, user) {
  const required = methodPermissions[method];
  if (!required) return true; // No restrictions
  
  return required.includes(user.role);
}

// In handler
if (!authorize(request.method, req.user)) {
  return {
    jsonrpc: '2.0',
    error: {code: -32002, message: 'Forbidden'},
    id: request.id
  };
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

const Joi = require('joi');

const schemas = {
  'createUser': Joi.object({
    username: Joi.string().alphanum().min(3).max(20).required(),
    email: Joi.string().email().required(),
    age: Joi.number().integer().min(0).max(150)
  })
};

function validateInput(method, params) {
  const schema = schemas[method];
  if (!schema) return {valid: true};
  
  const {error, value} = schema.validate(params);
  return error ? {valid: false, error: error.message} : {valid: true, value};
}

1
2
3
4
5
6
7
8

const cors = require('cors');

app.use('/rpc', cors({
  origin: 'https://yourdomain.com',
  credentials: true,
  methods: ['POST'],
  allowedHeaders: ['Content-Type', 'Authorization']
}));

1
2
3
4
5
6
7

// Redirect HTTP to HTTPS
app.use((req, res, next) => {
  if (!req.secure && process.env.NODE_ENV === 'production') {
    return res.redirect(`https://${req.headers.host}${req.url}`);
  }
  next();
});

1
2
3
4
5
6
7
8
9

const crypto = require('crypto');

function safeCompare(a, b) {
  // Use constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(a),
    Buffer.from(b)
  );
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Don't expose internal details
try {
  await db.query('SELECT * FROM users WHERE id = ?', [id]);
} catch (err) {
  // Bad: exposes database structure
  throw new Error(err.message);
  
  // Good: generic message
  throw new Error('Database error');
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

const request = require('supertest');
const app = require('./app');

describe('JSON-RPC Server', () => {
  test('should add two numbers', async () => {
    const response = await request(app)
      .post('/rpc')
      .send({
        jsonrpc: '2.0',
        method: 'add',
        params: [5, 3],
        id: 1
      });
    
    expect(response.status).toBe(200);
    expect(response.body.result).toBe(8);
    expect(response.body.id).toBe(1);
  });
  
  test('should return error for unknown method', async () => {
    const response = await request(app)
      .post('/rpc')
      .send({
        jsonrpc: '2.0',
        method: 'unknownMethod',
        params: [],
        id: 1
      });
    
    expect(response.body.error.code).toBe(-32601);
    expect(response.body.error.message).toContain('Method not found');
  });
  
  test('should handle batch requests', async () => {
    const response = await request(app)
      .post('/rpc')
      .send([
        {jsonrpc: '2.0', method: 'add', params: [1, 2], id: 1},
        {jsonrpc: '2.0', method: 'subtract', params: [5, 3], id: 2}
      ]);
    
    expect(response.body).toHaveLength(2);
    expect(response.body[0].result).toBe(3);
    expect(response.body[1].result).toBe(2);
  });
  
  test('should handle notifications', async () => {
    const response = await request(app)
      .post('/rpc')
      .send({
        jsonrpc: '2.0',
        method: 'logEvent',
        params: {level: 'info', message: 'test'}
      });
    
    expect(response.status).toBe(204);
  });
});