1 // Copyright 2018 Adam S Levy
2 //
3 // Permission is hereby granted, free of charge, to any person obtaining a copy
4 // of this software and associated documentation files (the "Software"), to
5 // deal in the Software without restriction, including without limitation the
6 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
7 // sell copies of the Software, and to permit persons to whom the Software is
8 // furnished to do so, subject to the following conditions:
9 //
10 // The above copyright notice and this permission notice shall be included in
11 // all copies or substantial portions of the Software.
12 //
13 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
19 // IN THE SOFTWARE.
20 21 // Package jsonrpc2 is a complete and strictly conforming implementation of the
22 // JSON-RPC 2.0 protocol for both clients and servers.
23 //
24 // The full specification can be found at https://www.jsonrpc.org.
25 //
26 // Clients
27 //
28 // The simplest way to make a JSON-RPC 2.0 request is to use the provided
29 // Client.Request.
30 //
31 // var c jsonrpc2.Client
32 // params := []float64{1, 2, 3}
33 // var result int
34 // err := c.Request(nil, "http://localhost:8080", "sum", params, &result)
35 // if _, ok := err.(jsonrpc2.Error); ok {
36 // // received Error Request
37 // }
38 // if err != nil {
39 // // some JSON marshaling or network error
40 // }
41 // fmt.Printf("The sum of %v is %v.\n", params, result)
42 //
43 // For clients that do not wish to use the provided Client, the Request and
44 // Response types can be used directly.
45 //
46 // req, _ := json.Marshal(jsonrpc2.Request{Method: "subtract",
47 // Params: []int{5, 1},
48 // ID: 0,
49 // })
50 // httpRes, _ := http.Post("www.example.com", "application/json",
51 // bytes.NewReader(req))
52 // resBytes, _ := ioutil.ReadAll(httpRes.Body)
53 // res := jsonrpc2.Response{Result: &MyCustomResultType{}, ID: new(int)}
54 // json.Unmarshal(respBytes, &res)
55 //
56 // Servers
57 //
58 // Servers define their own MethodFuncs and associate them with a name in a
59 // MethodMap that is passed to HTTPRequestHandler() to return a corresponding
60 // http.HandlerFunc. See HTTPRequestHandler for more details.
61 //
62 // func getUser(ctx context.Context, params json.RawMessage) interface{} {
63 // var u User
64 // if err := json.Unmarshal(params, &u); err != nil {
65 // return jsonrpc2.InvalidParams(err)
66 // }
67 // conn, err := mydbpkg.GetDBConn()
68 // if err != nil {
69 // // The handler will recover, print debug info if enabled, and
70 // // return an Internal Error to the client.
71 // panic(err)
72 // }
73 // if err := u.Select(conn); err != nil {
74 // return jsonrpc2.NewError(-30000, "user not found", u.ID)
75 // }
76 // return u
77 // }
78 //
79 // func StartServer() {
80 // methods := jsonrpc2.MethodMap{"version": versionMethod}
81 // http.ListenAndServe(":8080", jsonrpc2.HTTPRequestHandler(methods,
82 // log.New(os.Stderr, "", 0)))
83 // }
84 package jsonrpc2
85