Name
Date
Size
#Lines
LOC

..--

client/H--309237

mocks/H--9766

LICENSEH A D24-Oct-20231.4 KiB2721

MakefileH A D28-Sep-2023755 2312

README.mdH A D10-Jan-20242.9 KiB10965

clientIntegration.goH A D09-Aug-20232.9 KiB10571

go.modH A D24-Oct-2023280 139

go.sumH A D28-Sep-20231.6 KiB1918

README.md

1# JSON-RPC 2.0 client in Go
2
3[![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg)](http://godoc.org/github.com/spdk/spdk/go/rpc)
4[![Go Report Card](https://goreportcard.com/badge/github.com/spdk/spdk/go/rpc)](https://goreportcard.com/report/github.com/spdk/spdk/go/rpc)
5
6This directory contains JSON-RPC client written in Go. The main goal is to ease communication with
7SPDK over Unix and TCP socket in Go. In addition, this repository provides integration of a client
8with `rpc.py` - Go client replaces Python client.
9
10## Client integration with rpc.py
11
12### Build
13
14Requirements:
15
16* `go` (v1.21 or above)
17
18There are two ways to build files required for client replacement:
19
201. Manual - go to [go/rpc](./) and invoke
21
22```shell
23make
24```
25
262. During configuration part of SPDK add `--with-golang` flag.
27
28### Usage
29
30After successful installation you will be able to use Go client from within `rpc.py`
31
32```shell
33rpc.py --go-client RPC_COMMAND
34```
35
36If you want to use Go client for every RPC command of `rpc.py` without adding `--go-client` flag
37you can define a new environment
38variable
39
40```bash
41SPDK_JSONRPC_GO_CLIENT=1
42```
43
44## Examples
45
46Examples how to integrate this client into your Go code can be
47found [here](../../examples/go/hello_gorpc)
48
49## API
50
51### Client
52
53Client is a main component of RPC client. It is responsible for sending and receiving JSON-RPC 2.0
54calls.
55
56#### Call
57
58Sends RPC call with specified method and parameters.
59
60Input:
61
62- `method`: Name of the method to be invoked.
63- `params`: Set of parameters to be used during invocation of the method.
64
65Output:
66
67- `response`: Response for rpc call. Contains version of JSON-RPC protocol, id, error or result.
68- `error`: Contains error if something goes wrong during creation of a request or
69 sending/receiving rpc call. Otherwise `nil`.
70
71#### Close
72
73Close method closes connection with underlying stream.
74
75Output:
76
77- `error`: Contains error when closing a stream fails. Otherwise `nil`.
78
79### Request
80
81Struct represents JSON-RPC 2.0 Request object. For more information please visit
82[jsonrpc.org/specification#request_object](https://www.jsonrpc.org/specification#request_object)
83
84### Response
85
86Struct represents JSON-RPC 2.0 Response object. For more information please visit
87[jsonrpc.org/specification#response_object](https://www.jsonrpc.org/specification#response_object)
88
89### Error
90
91Struct represents JSON-RPC 2.0 Error object. For more information please visit
92[jsonrpc.org/specification#error_object](https://www.jsonrpc.org/specification#error_object)
93
94### Other
95
96#### CreateClientWithJsonCodec
97
98This method creates a new JSON-RPC 2.0 client. Both Unix and TCP sockets are supported.
99
100Input:
101
102- `network`: Type of network. Both `unix` and `tcp` are supported.
103- `address`: Address to given network.
104
105Output:
106
107- `client`: New [Client](#client) struct.
108- `error`: Contains error if something goes wrong during creation of a client. Otherwise `nil`.
109