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

• func NewHandler(e harpy.Exchanger, options ...HandlerOption) http.Handler
• 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 HandlerOption
  • func WithZapLogger(logger *zap.Logger) HandlerOption
• 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

Functions

func NewHandler

func NewHandler(e harpy.Exchanger, options ...HandlerOption) http.Handler

NewHandler returns a new HTTP handler that provides an HTTP-based JSON-RPC transport.

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,
	options ...harpy.UnmarshalOption,
) 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 {
	// contains filtered or unexported fields
}

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 HandlerOption

type HandlerOption func(*Handler)

HandlerOption configures the behavior of a handler.

func WithZapLogger

func WithZapLogger(logger *zap.Logger) HandlerOption

WithZapLogger is a HandlerOption that configures the handler to use a harpy.ZapExchangeLogger for logging requests and responses.

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.