Add package example test (#68)

README.md

@@ -3,9 +3,8 @@
 
 Package jsonrpc2 provides a [Go](https://golang.org) implementation of [JSON-RPC 2.0](http://www.jsonrpc.org/specification).
 
-This package is **experimental** until further notice.
+* [Documentation](https://pkg.go.dev/github.com/sourcegraph/jsonrpc2)
-
+* [Open the code in Sourcegraph](https://sourcegraph.com/github.com/sourcegraph/jsonrpc2)
-[**Open the code in Sourcegraph**](https://sourcegraph.com/github.com/sourcegraph/jsonrpc2)
 
 ## Known issues
 

example_params_test.go

@@ -0,0 +1,78 @@
+package jsonrpc2_test
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net"
+	"os"
+
+	"github.com/sourcegraph/jsonrpc2"
+)
+
+// Send a JSON-RPC notification with its params member omitted.
+func ExampleConn_Notify_paramsOmitted() {
+	ctx := context.Background()
+
+	connA, connB := net.Pipe()
+	defer connA.Close()
+	defer connB.Close()
+
+	rpcConn := jsonrpc2.NewConn(ctx, jsonrpc2.NewPlainObjectStream(connA), nil)
+
+	// Send the JSON-RPC notification.
+	go func() {
+		// Set params to nil.
+		if err := rpcConn.Notify(ctx, "foo", nil); err != nil {
+			fmt.Fprintln(os.Stderr, "notify:", err)
+		}
+	}()
+
+	// Read the raw JSON-RPC notification on connB.
+	//
+	// Reading the raw JSON-RPC request is for the purpose of this example only.
+	// Use a jsonrpc2.Handler to read parsed requests.
+	buf := make([]byte, 64)
+	n, err := connB.Read(buf)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "read:", err)
+	}
+
+	fmt.Printf("%s\n", buf[:n])
+
+	// Output: {"jsonrpc":"2.0","method":"foo"}
+}
+
+// Send a JSON-RPC notification with its params member set to null.
+func ExampleConn_Notify_nullParams() {
+	ctx := context.Background()
+
+	connA, connB := net.Pipe()
+	defer connA.Close()
+	defer connB.Close()
+
+	rpcConn := jsonrpc2.NewConn(ctx, jsonrpc2.NewPlainObjectStream(connA), nil)
+
+	// Send the JSON-RPC notification.
+	go func() {
+		// Set params to the JSON null value.
+		params := json.RawMessage("null")
+		if err := rpcConn.Notify(ctx, "foo", params); err != nil {
+			fmt.Fprintln(os.Stderr, "notify:", err)
+		}
+	}()
+
+	// Read the raw JSON-RPC notification on connB.
+	//
+	// Reading the raw JSON-RPC request is for the purpose of this example only.
+	// Use a jsonrpc2.Handler to read parsed requests.
+	buf := make([]byte, 64)
+	n, err := connB.Read(buf)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "read:", err)
+	}
+
+	fmt.Printf("%s\n", buf[:n])
+
+	// Output: {"jsonrpc":"2.0","method":"foo","params":null}
+}

example_test.go

@@ -2,77 +2,63 @@ package jsonrpc2_test
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
+	"log"
 	"net"
 	"os"
 
 	"github.com/sourcegraph/jsonrpc2"
 )
 
-// Send a JSON-RPC notification with its params member omitted.
+func Example() {
-func ExampleConn_Notify_paramsOmitted() {
 	ctx := context.Background()
 
+	// Create an in-memory network connection. This connection is used below to
+	// transport the JSON-RPC messages. However, any io.ReadWriteCloser may be
+	// used to send/receive JSON-RPC messages.
 	connA, connB := net.Pipe()
-	defer connA.Close()
-	defer connB.Close()
 
-	rpcConn := jsonrpc2.NewConn(ctx, jsonrpc2.NewPlainObjectStream(connA), nil)
+	// The following JSON-RPC connection is both a client and a server. It can
+	// send requests as well as receive requests. The incoming requests are
+	// handled by myHandler.
+	jsonrpcConnA := jsonrpc2.NewConn(ctx, jsonrpc2.NewPlainObjectStream(connA), &myHandler{})
+	defer jsonrpcConnA.Close()
 
-	// Send the JSON-RPC notification.
+	// The following JSON-RPC connection has no handler, meaning that it is
-	go func() {
+	// configured to only be a client. It can send requests and receive the
-		// Set params to nil.
+	// responses to those requests, but it will ignore any incoming requests.
-		if err := rpcConn.Notify(ctx, "foo", nil); err != nil {
+	jsonrpcConnB := jsonrpc2.NewConn(ctx, jsonrpc2.NewPlainObjectStream(connB), nil)
-			fmt.Fprintln(os.Stderr, "notify:", err)
+	defer jsonrpcConnB.Close()
-		}
-	}()
 
-	// Read the raw JSON-RPC notification on connB.
+	// Send a request from jsonrpcConnB to jsonrpcConnA. The result of a
-	//
+	// successful call is stored in the result variable.
-	// Reading the raw JSON-RPC request is for the purpose of this example only.
+	var result string
-	// Use a jsonrpc2.Handler to read parsed requests.
+	if err := jsonrpcConnB.Call(ctx, "sayHello", nil, &result); err != nil {
-	buf := make([]byte, 64)
+		fmt.Fprintln(os.Stderr, err)
-	n, err := connB.Read(buf)
+		return
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "read:", err)
 	}
 
-	fmt.Printf("%s\n", buf[:n])
+	fmt.Println(result)
 
-	// Output: {"jsonrpc":"2.0","method":"foo"}
+	// Output: hello world
 }
 
-// Send a JSON-RPC notification with its params member set to null.
+// myHandler is the jsonrpc2.Handler used by jsonrpcConnA.
-func ExampleConn_Notify_nullParams() {
+type myHandler struct{}
-	ctx := context.Background()
 
-	connA, connB := net.Pipe()
+// Handle implements the jsonrpc2.Handler interface.
-	defer connA.Close()
+func (h *myHandler) Handle(ctx context.Context, c *jsonrpc2.Conn, r *jsonrpc2.Request) {
-	defer connB.Close()
+	switch r.Method {
-
+	case "sayHello":
-	rpcConn := jsonrpc2.NewConn(ctx, jsonrpc2.NewPlainObjectStream(connA), nil)
+		if err := c.Reply(ctx, r.ID, "hello world"); err != nil {
-
+			log.Println(err)
-	// Send the JSON-RPC notification.
+			return
-	go func() {
+		}
-		// Set params to the JSON null value.
+	default:
-		params := json.RawMessage("null")
+		err := &jsonrpc2.Error{Code: jsonrpc2.CodeMethodNotFound, Message: "Method not found"}
-		if err := rpcConn.Notify(ctx, "foo", params); err != nil {
+		if err := c.ReplyWithError(ctx, r.ID, err); err != nil {
-			fmt.Fprintln(os.Stderr, "notify:", err)
+			log.Println(err)
+			return
 		}
-	}()
-
-	// Read the raw JSON-RPC notification on connB.
-	//
-	// Reading the raw JSON-RPC request is for the purpose of this example only.
-	// Use a jsonrpc2.Handler to read parsed requests.
-	buf := make([]byte, 64)
-	n, err := connB.Read(buf)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "read:", err)
 	}
-
-	fmt.Printf("%s\n", buf[:n])
-
-	// Output: {"jsonrpc":"2.0","method":"foo","params":null}
 }