Documentation
¶
Overview ¶
Package jhttp implements a bridge from HTTP to JSON-RPC. This permits requests to be submitted to a JSON-RPC server using HTTP as a transport.
Example ¶
package main
import (
"context"
"fmt"
"log"
"net/http/httptest"
"strings"
"github.com/creachadair/jrpc2"
"github.com/creachadair/jrpc2/handler"
"github.com/creachadair/jrpc2/jhttp"
)
func main() {
// Set up a bridge exporting a simple service.
b := jhttp.NewBridge(handler.Map{
"Test": handler.New(func(ctx context.Context, ss []string) string {
return strings.Join(ss, " ")
}),
}, nil)
defer b.Close()
// The bridge can be used as the handler for an HTTP server.
hsrv := httptest.NewServer(b)
defer hsrv.Close()
// Set up a client using an HTTP channel, and use it to call the test
// service exported by the bridge.
ch := jhttp.NewChannel(hsrv.URL, nil)
cli := jrpc2.NewClient(ch, nil)
var result string
if err := cli.CallResult(context.Background(), "Test", []string{
"full", "plate", "and", "packing", "steel",
}, &result); err != nil {
log.Fatalf("Call failed: %v", err)
}
fmt.Println("Result:", result)
}
Output: Result: full plate and packing steel
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseBasic ¶ added in v0.36.0
ParseBasic parses a request URL and query parameters to obtain a method name and parameters. The URL path identifies the method name, with leading and trailing slashes removed. Query values are packed into a map[string]string.
This is the default query parser used by a Getter if none is specified in its GetterOptions.
func ParseQuery ¶ added in v0.35.4
ParseQuery parses a request URL and constructs a parameter map from the query values encoded in the URL and/or request body.
The method name is the URL path, with leading and trailing slashes trimmed. Query values are converted into argument values by these rules:
Double-quoted values are interpreted as JSON string values, with the same encoding and escaping rules (UTF-8 with backslash escapes). Examples:
"" "foo\nbar" "a \"string\" of text"
Values that consist of decimal digits and an optional leading sign are treated as either int64 (if there is no decimal point) or float64 values. Examples:
25 -16 3.259
The unquoted strings "true" and "false" are converted to the corresponding Boolean values. The unquoted string "null" is converted to nil.
To express arbitrary bytes, use a singly-quoted string encoded in base64. For example:
'aGVsbG8sIHdvcmxk' -- represents "hello, world"
All values not matching any of the above are treated as literal strings.
On success, the result has concrete type map[string]any and the method name is not empty.
Types ¶
type Bridge ¶
type Bridge struct {
// contains filtered or unexported fields
}
A Bridge is a http.Handler that bridges requests to a JSON-RPC server.
By default, the bridge accepts only HTTP POST requests with the complete JSON-RPC request message in the body, with Content-Type application/json. Either a single request object or a list of request objects is supported.
If the HTTP request method is not "POST", the bridge reports 405 (Method Not Allowed). If the Content-Type is not application/json, the bridge reports 415 (Unsupported Media Type).
If a ParseRequest hook is set, these requirements are disabled, and the hook is entirely responsible for checking request structure.
If a ParseGETRequest hook is set, HTTP "GET" requests are handled by a Getter using that hook; otherwise "GET" requests are handled as above.
If the request completes, whether or not there is an error, the HTTP response is 200 (OK) for ordinary requests or 204 (No Response) for notifications, and the response body contains the JSON-RPC response.
func NewBridge ¶
func NewBridge(mux jrpc2.Assigner, opts *BridgeOptions) Bridge
NewBridge constructs a new Bridge that starts a server on mux and dispatches HTTP requests to it. The server will run until the bridge is closed.
Note that a bridge is not able to push calls or notifications from the server back to the remote client. The bridge client is shared by multiple active HTTP requests, and has no way to know which of the callers the push should be forwarded to. You can enable push on the bridge server and set hooks on the bridge client as usual, but the remote client will not see push messages from the server.
type BridgeOptions ¶ added in v0.24.0
type BridgeOptions struct {
// Options for the bridge client (default nil).
Client *jrpc2.ClientOptions
// Options for the bridge server (default nil).
Server *jrpc2.ServerOptions
// If non-nil, this function is called to parse JSON-RPC requests from the
// HTTP request body. If this function reports an error, the request fails.
// By default, the bridge uses jrpc2.ParseRequests on the HTTP request body.
//
// Setting this hook disables the default requirement that the request
// method be POST and the content-type be application/json.
ParseRequest func(*http.Request) ([]*jrpc2.ParsedRequest, error)
// If non-nil, this function is used to parse a JSON-RPC method name and
// parameters from the URL of an HTTP GET request. If this function reports
// an error, the request fails.
//
// If this hook is set, all GET requests are handled by a Getter using this
// parse function, and are not passed to a ParseRequest hook even if one is
// defined.
ParseGETRequest func(*http.Request) (string, any, error)
}
BridgeOptions are optional settings for a Bridge. A nil pointer is ready for use and provides default values as described.
type Channel ¶ added in v0.1.1
type Channel struct {
// contains filtered or unexported fields
}
A Channel implements a channel.Channel that dispatches requests via HTTP to a user-provided URL. Each message sent to the channel is an HTTP POST request with the message as its body.
func NewChannel ¶ added in v0.1.1
func NewChannel(url string, opts *ChannelOptions) *Channel
NewChannel constructs a new channel that posts to the specified URL.
func (*Channel) Close ¶ added in v0.1.1
Close shuts down the channel, discarding any pending responses.
type ChannelOptions ¶ added in v0.13.0
type ChannelOptions struct {
// The HTTP client to use to send requests. If nil, uses http.DefaultClient.
Client HTTPClient
}
ChannelOptions gives optional parameters for constructing an HTTP channel. A nil *ChannelOptions is ready for use, and provides default options as described.
type Getter ¶ added in v0.35.0
type Getter struct {
// contains filtered or unexported fields
}
A Getter is a http.Handler that bridges GET requests to a JSON-RPC server.
The JSON-RPC method name and parameters are decoded from the request URL. The results from a successful call are encoded as JSON in the response body with status 200 (OK). In case of error, the response body is a JSON-RPC error object, and the HTTP status is one of the following:
Condition HTTP Status ----------------------- ----------------------------------- Parsing request 400 (Bad request) Method not found 404 (Not found) (other errors) 500 (Internal server error)
By default, a Getter uses ParseBasic to convert the HTTP request. The URL path identifies the JSON-RPC method, and the URL query parameters are converted into a JSON object for the parameters. Query values are sent as JSON strings. For example, this URL:
http://site.org:2112/some/method?param1=xyzzy¶m2=apple
produces the method name "some/method" and this parameter object:
{"param1":"xyzzy", "param2":"apple"}
To override the default behaviour, set a ParseRequest hook in GetterOptions. See also the jhttp.ParseQuery function for a more expressive translation.
func NewGetter ¶ added in v0.35.0
func NewGetter(mux jrpc2.Assigner, opts *GetterOptions) Getter
NewGetter constructs a new Getter that starts a server on mux and dispatches HTTP requests to it. The server will run until the getter is closed.
Note that a getter is not able to push calls or notifications from the server back to the remote client even if enabled.
type GetterOptions ¶ added in v0.35.0
type GetterOptions struct {
// Options for the getter client (default nil).
Client *jrpc2.ClientOptions
// Options for the getter server (default nil).
Server *jrpc2.ServerOptions
// If set, this function is called to parse a method name and request
// parameters from an HTTP request. If this is not set, the default handler
// uses the URL path as the method name and the URL query as the method
// parameters.
ParseRequest func(*http.Request) (string, any, error)
}
GetterOptions are optional settings for a Getter. A nil pointer is ready for use and provides default values as described.
Source Files