httptransport

Documentation

Overview

Package httptransport provides a simple HTTP-based JSON-RPC transport.

Requests are sent by making an HTTP post request. The implementation integrates with Go's native HTTP package.

Index

• type Client
  • func (c *Client) Call(ctx context.Context, method string, params, result any) error
  • func (c *Client) Notify(ctx context.Context, method string, params any) error
• type Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type RequestSetReader
  • func (r *RequestSetReader) Read(_ context.Context) (harpy.RequestSet, error)
• type ResponseWriter
  • func (w *ResponseWriter) Close() error
  • func (w *ResponseWriter) WriteBatched(res harpy.Response) error
  • func (w *ResponseWriter) WriteError(res harpy.ErrorResponse) error
  • func (w *ResponseWriter) WriteUnbatched(res harpy.Response) error

Types

type Client

type Client struct {
	// HTTPClient is the HTTP client used to make requests. If it is nil,
	// http.DefaultClient is used.
	HTTPClient *http.Client

	// URL is the URL of the JSON-RPC server.
	URL string
	// contains filtered or unexported fields
}

Client is a HTTP-based JSON-RPC client.

func (*Client) Call

func (c *Client) Call(
	ctx context.Context,
	method string,
	params, result any,
) error

Call invokes a JSON-RPC method.

func (*Client) Notify

func (c *Client) Notify(
	ctx context.Context,
	method string,
	params any,
) error

Notify sends a JSON-RPC notification.

type Handler

type Handler struct {
	// Exchanger performs JSON-RPC exchanges.
	Exchanger harpy.Exchanger

	// Logger is the target for log messages about JSON-RPC requests and
	// responses.
	Logger logging.Logger
}

Handler is an implementation of http.Handler that provides an HTTP-based transport for a JSON-RPC server.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles the HTTP request.

type RequestSetReader

type RequestSetReader struct {
	Request *http.Request
}

RequestSetReader is an implementation of harpy.RequestSetReader that reads a JSON-RPC request set from an HTTP request.

func (*RequestSetReader) Read

func (r *RequestSetReader) Read(_ context.Context) (harpy.RequestSet, error)

Read reads the next RequestSet that is to be processed.

It returns ctx.Err() if ctx is canceled while waiting to read the next request set. If request set data is read but cannot be parsed a native JSON-RPC Error is returned. Any other error indicates an IO error.

type ResponseWriter

type ResponseWriter struct {
	// Target is the writer used to send JSON-RPC responses.
	Target http.ResponseWriter
	// contains filtered or unexported fields
}

ResponseWriter is an implementation of harpy.ResponseWriter that writes responses to an http.ResponseWriter.

func (*ResponseWriter) Close

func (w *ResponseWriter) Close() error

Close is called to signal that there are no more responses to be sent.

If batched responses have been written, it writes the closing bracket of the array that encapsulates the responses.

func (*ResponseWriter) WriteBatched

func (w *ResponseWriter) WriteBatched(res harpy.Response) error

WriteBatched writes a response to an individual request that was part of a batch.

If this is the first response of the batch, it immediately writes the HTTP response headers and the opening bracket of the array that encapsulates the batch of responses.

The HTTP status code is always 200 (OK), as even if res is an ErrorResponse, other responses in the batch may indicate a success.

func (*ResponseWriter) WriteError

func (w *ResponseWriter) WriteError(res harpy.ErrorResponse) error

WriteError writes an error response that is a result of some problem with the request set as a whole.

It immediately writes the HTTP response headers followed by the HTTP body.

If the error code is pre-defined by the JSON-RPC specification the HTTP status code is set to the most appropriate equivalent, otherwise it is set to 500 (Internal Server Error).

func (*ResponseWriter) WriteUnbatched

func (w *ResponseWriter) WriteUnbatched(res harpy.Response) error

WriteUnbatched writes a response to an individual request that was not part of a batch.

It immediately writes the HTTP response headers followed by the HTTP body.

If res is an ErrorResponse and its error code is pre-defined by the JSON-RPC specification the HTTP status code is set to the most appropriate equivalent.

Application-defined JSON-RPC errors always result in a HTTP 200 (OK), as they considered part of normal operation of the transport.