handler

func Check ¶ added in v0.21.2

func Check(fn any) (*FuncInfo, error)

Check checks whether fn can serve as a jrpc2.Handler. The concrete value of fn must be a function with one of the following type signature schemes, for JSON-marshalable types X and Y:

func(context.Context) error
func(context.Context) Y
func(context.Context) (Y, error)
func(context.Context, X) error
func(context.Context, X) Y
func(context.Context, X) (Y, error)
func(context.Context, *jrpc2.Request) error
func(context.Context, *jrpc2.Request) Y
func(context.Context, *jrpc2.Request) (Y, error)
func(context.Context, *jrpc2.Request) (any, error)

If fn does not have one of these forms, Check reports an error.

If the type of X is a struct or a pointer to a struct, the generated wrapper accepts JSON parameters as either an object or an array. The caller may disable array support by calling AllowArray(false). When enabled, array parameters are mapped to the fields of X in the order of field declaration, save that unexported fields are skipped. If a field has a `json:"-"` tag, it is also skipped. Anonymous fields are skipped unless they are tagged.

For other (non-struct) argument types, the accepted format is whatever the json.Unmarshal function can decode into the value. Note, however, that the JSON-RPC standard restricts encoded parameter values to arrays and objects. Check will accept argument types that cannot accept arrays or objects, but the wrapper will report an error when decoding the request. The recommended solution is to define a struct type for your parameters.

For a single arbitrary type, another approach is to use a 1-element array:

func(ctx context.Context, sp [1]string) error {
   s := sp[0] // pull the actual argument out of the array
   // ...
}

For more complex positional signatures, see also handler.Positional.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/creachadair/jrpc2/handler"
)

func main() {
	fi, err := handler.Check(func(_ context.Context, ss []string) int { return len(ss) })
	if err != nil {
		log.Fatalf("Check failed: %v", err)
	}
	fmt.Printf("Argument type: %v\n", fi.Argument)
	fmt.Printf("Result type:   %v\n", fi.Result)
	fmt.Printf("Reports error? %v\n", fi.ReportsError)
	fmt.Printf("Wrapped type:  %T\n", fi.Wrap())
}

Output:

Argument type: []string
Result type:   int
Reports error? false
Wrapped type:  func(context.Context, *jrpc2.Request) (interface {}, error)

func Positional ¶ added in v0.28.3

func Positional(fn any, names ...string) (*FuncInfo, error)

Positional checks whether fn can serve as a jrpc2.Handler. The concrete value of fn must be a function with one of the following type signature schemes:

func(context.Context, X1, X2, ..., Xn) (Y, error)
func(context.Context, X1, X2, ..., Xn) Y
func(context.Context, X1, X2, ..., Xn) error

for JSON-marshalable types X_i and Y. If fn does not have one of these forms, Positional reports an error. The given names must match the number of non-context arguments exactly. Variadic functions are not supported.

In contrast to Check, this function allows any number of arguments, but the caller must provide names for them. Positional creates an anonymous struct type whose fields correspond to the non-context arguments of fn. The names are used as the JSON field keys for the corresponding parameters.

When converted into a jrpc2.Handler, the wrapped function accepts either a JSON array with exactly n members, or a JSON object with the field keys named. For example, given:

func add(ctx context.Context, x, y int) int { return x + y }

fi, err := handler.Positional(add, "first", "second")
// ...
call := fi.Wrap()

the resulting handler by default accepts a JSON array with with (exactly) the same number of elements as the positional parameters:

[17, 23]

No arguments can be omitted in this format, but the caller can use a JSON "null" in place of any argument. The caller may also disable array support by setting AllowArray(false) on the resulting FuncInfo.

The handler will also accept a parameter object like:

{"first": 17, "second": 23}

where "first" is mapped to argument x and "second" to argument y. In this form, fields may be omitted, but unknown field keys generate an error. The object keys are taken from the arguments to Positional, not the parameter names declared on the function.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/creachadair/jrpc2"
	"github.com/creachadair/jrpc2/handler"
	"github.com/creachadair/jrpc2/internal/testutil"
)

func describe(_ context.Context, name string, age int, isOld bool) error {
	fmt.Printf("%s is %d (old: %v)\n", name, age, isOld)
	return nil
}

func main() {
	call := handler.NewPos(describe, "name", "age", "isOld")

	req := mustParseReq(`{
	  "jsonrpc": "2.0",
	  "id": 1,
	  "method": "foo",
	  "params": ["Marvin", 973000, true]
	}`)
	if _, err := call(context.Background(), req); err != nil {
		log.Fatalf("Call: %v", err)
	}
}

func mustParseReq(s string) *jrpc2.Request {
	req, err := testutil.ParseRequest(s)
	if err != nil {
		log.Fatalf("ParseRequest: %v", err)
	}
	return req
}

Output:

Marvin is 973000 (old: true)

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/creachadair/jrpc2"
	"github.com/creachadair/jrpc2/handler"
	"github.com/creachadair/jrpc2/internal/testutil"
)

func describe(_ context.Context, name string, age int, isOld bool) error {
	fmt.Printf("%s is %d (old: %v)\n", name, age, isOld)
	return nil
}

func main() {
	call := handler.NewPos(describe, "name", "age", "isOld")

	req := mustParseReq(`{
	  "jsonrpc": "2.0",
	  "id": 1,
	  "method": "foo",
	  "params": {
	    "name":  "Dennis",
	    "age":   37,
	    "isOld": false
	  }
	}`)
	if _, err := call(context.Background(), req); err != nil {
		log.Fatalf("Call: %v", err)
	}
}

func mustParseReq(s string) *jrpc2.Request {
	req, err := testutil.ParseRequest(s)
	if err != nil {
		log.Fatalf("ParseRequest: %v", err)
	}
	return req
}

Output:

Dennis is 37 (old: false)