jhttp

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"
	"io/ioutil"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"

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

func main() {
	// Set up a local server to demonstrate the API.
	srv := jrpc2.NewServer(handler.Map{
		"Test": handler.New(func(ctx context.Context, ss ...string) (string, error) {
			return strings.Join(ss, " "), nil
		}),
	}, nil)

	b := jhttp.NewBridge(srv, nil)
	defer b.Close()

	hsrv := httptest.NewServer(b)
	defer hsrv.Close()

	rsp, err := http.Post(hsrv.URL, "application/json", strings.NewReader(`{
  "jsonrpc": "2.0",
  "id": 10235,
  "method": "Test",
  "params": ["full", "plate", "and", "packing", "steel"]
}`))
	if err != nil {
		log.Fatalf("POST request failed: %v", err)
	}
	body, err := ioutil.ReadAll(rsp.Body)
	rsp.Body.Close()
	if err != nil {
		log.Fatalf("Reading response body: %v", err)
	}

	fmt.Println(string(body))
}

Output:

{"jsonrpc":"2.0","id":10235,"result":"full plate and packing steel"}

Index

• type Bridge
  • func NewBridge(srv *jrpc2.Server, opts *BridgeOptions) Bridge
  • func (b Bridge) Close() error
  • func (b Bridge) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type BridgeOptions
• type Channel
  • func NewChannel(url string, opts *ChannelOptions) *Channel
  • func (c *Channel) Close() error
  • func (c *Channel) Recv() ([]byte, error)
  • func (c *Channel) Send(msg []byte) error
• type ChannelOptions
• type HTTPClient

Examples

• Package

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.

The body of the HTTP POST request must contain the complete JSON-RPC request message, encoded with Content-Type: application/json. Either a single request object or a list of request objects is supported.

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.

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).

func NewBridge

func NewBridge(srv *jrpc2.Server, opts *BridgeOptions) Bridge

NewBridge constructs a new Bridge that starts srv and dispatches HTTP requests to it. The server must be unstarted or NewBridge will panic. The server will run until the bridge is closed.

func (Bridge) Close

func (b Bridge) Close() error

Close closes the channel to the server, waits for the server to exit, and reports the exit status of the server.

func (Bridge) ServeHTTP

func (b Bridge) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements the required method of http.Handler.

type BridgeOptions

type BridgeOptions struct {
	// If non-nil, this function is called to check whether the HTTP request's
	// declared content-type is valid. If this function returns false, the
	// request is rejected. If nil, the default check requires a content type of
	// "application/json".
	CheckContentType func(contentType string) bool
}

BridgeOptions are optional settings for a Bridge. A nil pointer is ready for use and provides default values as described.

type Channel

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

func NewChannel(url string, opts *ChannelOptions) *Channel

NewChannel constructs a new channel that posts to the specified URL.

func (*Channel) Close

func (c *Channel) Close() error

Close shuts down the channel, discarding any pending responses.

func (*Channel) Recv

func (c *Channel) Recv() ([]byte, error)

Recv receives the next available response and reports its body.

func (*Channel) Send

func (c *Channel) Send(msg []byte) error

Send forwards msg to the server as the body of an HTTP POST request.

type ChannelOptions

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 HTTPClient

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPClient is the interface to an HTTP client used by a Channel. It is compatible with the standard library http.Client type.