JSON-RPC

An implementation of the JSON-RPC 2.0 specification. More...

Functions
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_is_server_error (const std::int64_t code) -> bool
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_is_batch (const sourcemeta::core::JSON &payload) -> bool
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_is_valid_batch (const sourcemeta::core::JSON &payload) -> bool
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_request_id (const sourcemeta::core::JSON &request) -> const sourcemeta::core::JSON *
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_is_request (const sourcemeta::core::JSON &request) -> bool
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_method (const sourcemeta::core::JSON &request) -> JSON::StringView
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_params (const sourcemeta::core::JSON &request) -> const sourcemeta::core::JSON *
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_is_notification (const sourcemeta::core::JSON &request) -> bool
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_make_success (const sourcemeta::core::JSON &identifier, sourcemeta::core::JSON result) -> sourcemeta::core::JSON
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_make_success_empty (const sourcemeta::core::JSON &identifier) -> sourcemeta::core::JSON
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_make_error (const sourcemeta::core::JSON *identifier, const std::int64_t code, const JSON::StringView message, std::optional< sourcemeta::core::JSON > data=std::nullopt) -> sourcemeta::core::JSON
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_make_error_parse () -> const sourcemeta::core::JSON &
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_make_error_invalid_request (const sourcemeta::core::JSON *identifier=nullptr) -> sourcemeta::core::JSON
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_make_error_method_not_found (const sourcemeta::core::JSON &identifier) -> sourcemeta::core::JSON
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_make_error_invalid_params (const sourcemeta::core::JSON &identifier, std::optional< sourcemeta::core::JSON > data=std::nullopt) -> sourcemeta::core::JSON
SOURCEMETA_CORE_JSONRPC_EXPORT auto	sourcemeta::core::jsonrpc_make_error_internal (const sourcemeta::core::JSON *identifier=nullptr) -> sourcemeta::core::JSON

Variables
constexpr std::int64_t	sourcemeta::core::JSONRPC_CODE_PARSE = -32700
constexpr std::int64_t	sourcemeta::core::JSONRPC_CODE_INVALID_REQUEST = -32600
constexpr std::int64_t	sourcemeta::core::JSONRPC_CODE_METHOD_NOT_FOUND = -32601
constexpr std::int64_t	sourcemeta::core::JSONRPC_CODE_INVALID_PARAMS = -32602
constexpr std::int64_t	sourcemeta::core::JSONRPC_CODE_INTERNAL = -32603
constexpr std::int64_t	sourcemeta::core::JSONRPC_CODE_SERVER_ERROR_MIN = -32099
constexpr std::int64_t	sourcemeta::core::JSONRPC_CODE_SERVER_ERROR_MAX = -32000

Detailed Description

An implementation of the JSON-RPC 2.0 specification.

This functionality is included as follows:

#include <sourcemeta/core/jsonrpc.h>

Function Documentation

jsonrpc_is_batch()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_is_batch

(

const sourcemeta::core::JSON &

payload

)

-> bool

Check whether the given JSON value is a JSON-RPC 2.0 batch envelope. This only verifies that the value is an array, so the caller remains responsible for the empty-batch single-error response and for omitting a response when a batch consists entirely of notifications. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto payload{sourcemeta::core::parse_json(R"([])")};
assert(sourcemeta::core::jsonrpc_is_batch(payload));

jsonrpc_is_notification()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_is_notification

(

const sourcemeta::core::JSON &

request

)

-> bool

Check whether the given JSON value is a well-formed JSON-RPC 2.0 notification (a request without an identifier). For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto request{sourcemeta::core::parse_json(
    R"({ "jsonrpc": "2.0", "method": "notifications/initialized" })")};
assert(sourcemeta::core::jsonrpc_is_notification(request));

jsonrpc_is_request()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_is_request

(

const sourcemeta::core::JSON &

request

)

-> bool

Check whether the given JSON value is a well-formed JSON-RPC 2.0 request. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto request{sourcemeta::core::parse_json(
    R"({ "jsonrpc": "2.0", "id": 1, "method": "ping" })")};
assert(sourcemeta::core::jsonrpc_is_request(request));

jsonrpc_is_server_error()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_is_server_error

(

const std::int64_t

code

)

-> bool

Check whether the given code lies within the JSON-RPC 2.0 reserved range for implementation-defined server errors. For example:

#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
assert(sourcemeta::core::jsonrpc_is_server_error(-32050));
assert(!sourcemeta::core::jsonrpc_is_server_error(-32603));

jsonrpc_is_valid_batch()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_is_valid_batch

(

const sourcemeta::core::JSON &

payload

)

-> bool

Check whether the given JSON value is a non-empty JSON-RPC 2.0 batch envelope. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto payload{sourcemeta::core::parse_json(
    R"([ { "jsonrpc": "2.0", "method": "ping" } ])")};
assert(sourcemeta::core::jsonrpc_is_valid_batch(payload));

jsonrpc_make_error()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_make_error	(	const sourcemeta::core::JSON *	identifier,
		const std::int64_t	code,
		const JSON::StringView	message,
		std::optional< sourcemeta::core::JSON >	data = std::nullopt ) -> sourcemeta::core::JSON

Construct a JSON-RPC 2.0 error response envelope. Passing nullptr for the identifier writes an "id": null member, as the specification requires when the originating request could not be parsed. The optional data carries implementation-specific extra information. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto identifier{sourcemeta::core::JSON{1}};
const auto envelope{sourcemeta::core::jsonrpc_make_error(
    &identifier, -32000, "Server error")};
assert(envelope.at("error").at("code").to_integer() == -32000);

jsonrpc_make_error_internal()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_make_error_internal

(

const sourcemeta::core::JSON *

identifier = nullptr

)

-> sourcemeta::core::JSON

Construct a JSON-RPC 2.0 internal-error envelope, optionally carrying the offending request identifier. For example:

#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto envelope{sourcemeta::core::jsonrpc_make_error_internal()};
assert(envelope.at("error").at("code").to_integer() == -32603);

jsonrpc_make_error_invalid_params()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_make_error_invalid_params	(	const sourcemeta::core::JSON &	identifier,
		std::optional< sourcemeta::core::JSON >	data = std::nullopt ) -> sourcemeta::core::JSON

Construct a JSON-RPC 2.0 invalid-params error envelope for the given request identifier, optionally carrying implementation-specific data. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto identifier{sourcemeta::core::JSON{"req-7"}};
const auto envelope{
    sourcemeta::core::jsonrpc_make_error_invalid_params(identifier)};
assert(envelope.at("error").at("code").to_integer() == -32602);

jsonrpc_make_error_invalid_request()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_make_error_invalid_request

(

const sourcemeta::core::JSON *

identifier = nullptr

)

-> sourcemeta::core::JSON

Construct a JSON-RPC 2.0 invalid-request error envelope, optionally carrying the offending request identifier. For example:

#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto envelope{sourcemeta::core::jsonrpc_make_error_invalid_request()};
assert(envelope.at("error").at("code").to_integer() == -32600);

jsonrpc_make_error_method_not_found()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_make_error_method_not_found

(

const sourcemeta::core::JSON &

identifier

)

-> sourcemeta::core::JSON

Construct a JSON-RPC 2.0 method-not-found error envelope for the given request identifier. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto identifier{sourcemeta::core::JSON{2}};
const auto envelope{
    sourcemeta::core::jsonrpc_make_error_method_not_found(identifier)};
assert(envelope.at("error").at("code").to_integer() == -32601);

jsonrpc_make_error_parse()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_make_error_parse

(

)

-> const sourcemeta::core::JSON &

Get the canonical JSON-RPC 2.0 parse-error envelope. The returned reference is to a static instance that lives for the duration of the program. For example:

#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto &envelope{sourcemeta::core::jsonrpc_make_error_parse()};
assert(envelope.at("error").at("code").to_integer() == -32700);

jsonrpc_make_success()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_make_success	(	const sourcemeta::core::JSON &	identifier,
		sourcemeta::core::JSON	result ) -> sourcemeta::core::JSON

Construct a successful JSON-RPC 2.0 response envelope with the given identifier and result. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
#include <utility>
 
const auto identifier{sourcemeta::core::JSON{1}};
auto result{sourcemeta::core::JSON::make_object()};
result.assign("foo", sourcemeta::core::JSON{42});
const auto envelope{
    sourcemeta::core::jsonrpc_make_success(identifier, std::move(result))};
assert(envelope.at("id").to_integer() == 1);

jsonrpc_make_success_empty()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_make_success_empty

(

const sourcemeta::core::JSON &

identifier

)

-> sourcemeta::core::JSON

Construct a successful JSON-RPC 2.0 response envelope with the given identifier and an empty object result. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto identifier{sourcemeta::core::JSON{1}};
const auto envelope{
    sourcemeta::core::jsonrpc_make_success_empty(identifier)};
assert(envelope.at("result").is_object());
assert(envelope.at("result").empty());

jsonrpc_method()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_method

(

const sourcemeta::core::JSON &

request

)

-> JSON::StringView

Extract the method name from a JSON-RPC 2.0 envelope, or an empty view when the method field is missing or not a string. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto request{sourcemeta::core::parse_json(
    R"({ "jsonrpc": "2.0", "id": 1, "method": "ping" })")};
assert(sourcemeta::core::jsonrpc_method(request) == "ping");

jsonrpc_params()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_params

(

const sourcemeta::core::JSON &

request

)

-> const sourcemeta::core::JSON *

Extract the params from a JSON-RPC 2.0 envelope, or nullptr when the value is missing or not an object or array. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto request{sourcemeta::core::parse_json(R"JSON({
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subtract",
  "params": [ 42, 23 ]
})JSON")};
const auto *parameters{sourcemeta::core::jsonrpc_params(request)};
assert(parameters != nullptr);
assert(parameters->is_array());

jsonrpc_request_id()

SOURCEMETA_CORE_JSONRPC_EXPORT auto sourcemeta::core::jsonrpc_request_id

(

const sourcemeta::core::JSON &

request

)

-> const sourcemeta::core::JSON *

Extract the request identifier from a JSON-RPC 2.0 envelope. Returns a pointer to the identifier (string, number, or null per the specification) or nullptr when the field is missing or not one of those types. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonrpc.h>
#include <cassert>
 
const auto request{sourcemeta::core::parse_json(
    R"({ "jsonrpc": "2.0", "id": 7, "method": "ping" })")};
const auto *identifier{sourcemeta::core::jsonrpc_request_id(request)};
assert(identifier != nullptr);
assert(identifier->to_integer() == 7);

Variable Documentation

JSONRPC_CODE_INTERNAL

std::int64_t sourcemeta::core::JSONRPC_CODE_INTERNAL = -32603

constexpr

The pre-defined JSON-RPC 2.0 error code for internal server errors.

JSONRPC_CODE_INVALID_PARAMS

std::int64_t sourcemeta::core::JSONRPC_CODE_INVALID_PARAMS = -32602

constexpr

The pre-defined JSON-RPC 2.0 error code for invalid method parameters.

JSONRPC_CODE_INVALID_REQUEST

std::int64_t sourcemeta::core::JSONRPC_CODE_INVALID_REQUEST = -32600

constexpr

The pre-defined JSON-RPC 2.0 error code for a malformed request envelope.

JSONRPC_CODE_METHOD_NOT_FOUND

std::int64_t sourcemeta::core::JSONRPC_CODE_METHOD_NOT_FOUND = -32601

constexpr

The pre-defined JSON-RPC 2.0 error code for unknown methods.

JSONRPC_CODE_PARSE

std::int64_t sourcemeta::core::JSONRPC_CODE_PARSE = -32700

constexpr

The pre-defined JSON-RPC 2.0 error code for invalid JSON received by the server.

JSONRPC_CODE_SERVER_ERROR_MAX

std::int64_t sourcemeta::core::JSONRPC_CODE_SERVER_ERROR_MAX = -32000

constexpr

The upper bound of the JSON-RPC 2.0 reserved range for implementation-defined server errors.

JSONRPC_CODE_SERVER_ERROR_MIN

std::int64_t sourcemeta::core::JSONRPC_CODE_SERVER_ERROR_MIN = -32099

constexpr

The lower bound of the JSON-RPC 2.0 reserved range for implementation-defined server errors.