JsonRpc
JsonRpc copied to clipboard
A modern JSON-RPC 2.0 server for PHP 8.0+
JsonRpc
A modern, object-oriented JSON-RPC 2.0 server for PHP 8.0+ featuring JSON Schema integration and middlewaring.
Table of Contents
- Installation
-
Basic Usage
- Creating Procedures
- Registering Services
- Running the Server
- Custom Validation
-
Middlewares
- Middleware guarantees
- Middleware ordering
- Middleware example
-
FAQ
- Does JSON-RPC 2.0 have any advantage over REST?
- How can I attach a middleware to specific procedures instead of the whole Server?
-
How do you integrate
uma/json-rpc
with other frameworks?
-
Best Practices
- Rely on JSON schemas to validate params
- Defer actual work whenever possible
- Cap the number of batch requests
Installation
$ composer require uma/json-rpc
Basic Usage
Setting up a JsonRpc\Server
involves three separate steps: coding the procedures you need,
registering them as services and finally configuring and running the server.
Creating Procedures
Procedures are akin to HTTP controllers in the MVC pattern, and must implement the UMA\JsonRpc\Procedure
interface.
This example shows a possible implementation of the subtract
procedure found in the JSON-RPC 2.0 specification examples:
declare(strict_types=1);
namespace Demo;
use stdClass;
use UMA\JsonRpc;
class Subtractor implements JsonRpc\Procedure
{
/**
* {@inheritdoc}
*/
public function __invoke(JsonRpc\Request $request): JsonRpc\Response
{
$params = $request->params();
if ($params instanceof stdClass) {
$minuend = $params->minuend;
$subtrahend = $params->subtrahend;
} else {
[$minuend, $subtrahend] = $params;
}
return new JsonRpc\Success($request->id(), $minuend - $subtrahend);
}
/**
* {@inheritdoc}
*/
public function getSpec(): ?stdClass
{
return \json_decode(<<<'JSON'
{
"$schema": "https://json-schema.org/draft-07/schema#",
"type": ["array", "object"],
"minItems": 2,
"maxItems": 2,
"items": { "type": "integer" },
"required": ["minuend", "subtrahend"],
"additionalProperties": false,
"properties": {
"minuend": { "type": "integer" },
"subtrahend": { "type": "integer" }
}
}
JSON
);
}
}
The logic assumes that $request->params()
is either an array of two integers,
or an stdClass
with a minuend
and subtrahend
attributes that are both integers.
This is perfectly safe because the Server
matches the JSON schema defined above against
$request->params()
before even calling __invoke()
. Whenever the input does not conform
to the spec, a -32602 (Invalid params)
error is returned and the procedure does not run.
Registering Services
The next step is defining the procedures in a PSR-11 compatible container and configuring
the server. In this example I used uma/dic
:
declare(strict_types=1);
use Demo\Subtractor;
use UMA\DIC\Container;
use UMA\JsonRpc\Server;
$c = new Container();
$c->set(Subtractor::class, function(): Subtractor {
return new Subtractor();
});
$c->set(Server::class, function(Container $c): Server {
$server = new Server($c);
$server->set('subtract', Subtractor::class);
return $server;
});
At this point we have a JSON-RPC server with one single method (subtract
) that is
mapped to the Subtractor::class
service. Moreover, the procedure definition is lazy,
so Subtractor
won't be actually instantiated unless subtract
is actually called in the server.
Arguably this is not very important in this example. But it'd be with tens of procedure definitions, each with their own dependency tree.
Running the Server
Once set up, the same server can be run any number of times, and it will handle most errors defined in the JSON-RPC spec on behalf of the user of the library:
declare(strict_types=1);
use UMA\JsonRpc\Server;
$server = $c->get(Server::class);
// RPC call with positional parameters
$response = $server->run('{"jsonrpc":"2.0","method":"subtract","params":[2,3],"id":1}');
// $response is '{"jsonrpc":"2.0","result":-1,"id":1}'
// RPC call with named parameters
$response = $server->run('{"jsonrpc":"2.0","method":"subtract","params":{"minuend":2,"subtrahend":3},"id":1}');
// $response is '{"jsonrpc":"2.0","result":-1,"id":1}'
// Notification (request with no id)
$response = $server->run('{"jsonrpc":"2.0","method":"subtract","params":[2,3]}');
// $response is NULL
// RPC call with invalid params
$response = $server->run('{"jsonrpc":"2.0","method":"subtract","params":{"foo":"bar"},"id":1}');
// $response is '{"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid params"},"id":1}'
// RPC call with invalid JSON
$response = $server->run('invalid input {?<derp');
// $response is '{"jsonrpc":"2.0","error":{"code":-32700,"message":"Parse error"},"id":null}'
// RPC call on non-existent method
$response = $server->run('{"jsonrpc":"2.0","method":"add","params":[2,3],"id":1}');
// $response is '{"jsonrpc":"2.0","error":{"code":-32601,"message":"Method not found"},"id":1}'
Custom Validation
Since version 4.0.0 you can override the Opis Validator through the container. This allows you to use custom Opis filters, formats and media types.
To do that simply define an Opis\JsonSchema\Validator::class
service in the PSR-11 container
and set it to a custom instance of the Validator class.
The following example defines a new "prime" format for integers that you can then use in your json schemas. (PrimeNumberFormat implementation is omitted for brevity):
$validator = new Opis\JsonSchema\Validator();
$formats = $validator->parser()->getFormatResolver();
$formats->register('integer', 'prime', new PrimeNumberFormat());
$psr11Container->set(Opis\JsonSchema\Validator::class, $validator);
$jsonServer = new UMA\JsonRpc\Server($psr11Container);
// ...
Middlewares
A middleware is a class implementing the UMA\JsonRPC\Middleware
interface, whose only method accepts an UMA\JsonRPC\Request
,
an UMA\JsonRPC\Procedure
and returns a UMA\JsonRPC\Response
. At some point within its body, this method MUST call $next($request)
,
otherwise the request won't reach the successive middlewares nor the final procedure. Middlewares are the preferred
option whenever you need to run a chunk of code right before or after every request, regardless of the method.
Here's the minimal skeleton of a middleware:
declare(strict_types=1);
namespace Demo;
use UMA\JsonRpc;
class SampleMiddleware implements JsonRpc\Middleware
{
public function __invoke(JsonRpc\Request $request, JsonRPC\Procedure $next): JsonRpc\Response
{
// Code run before procedure
$response = $next($request);
// Code run after procedure finished
return $response;
}
}
In order to activate a middleware you need to register it as a service in the dependency injection container, just like procedures.
declare(strict_types=1);
use Demo\SampleMiddleware;
use UMA\DIC\Container;
use UMA\JsonRpc\Server;
$c = new Container();
$c->set(SampleMiddleware::class, function(): SampleMiddleware {
return new SampleMiddleware();
});
$c->set(Server::class, function(Container $c): Server {
$server = new Server($c);
// method definitions would go here...
$server->attach(SampleMiddleware::class);
return $server;
});
Middleware guarantees
Whenever the flow of execution enters the __invoke
method of a user-defined middleware, the following can be assumed
about the request:
-
The original payload was a valid JSON-RPC 2.0 request.
-
Its
method
attribute points to a procedure that is actually registered in the server. -
Its
params
attribute conforms to the Json Schema defined in thegetSchema()
of said procedure.
In short, they are the same guarantees that can be made inside the procedure.
Middleware ordering
In a way, middlewares can be thought of as decorators of the Server, each one wrapping it in a new layer.
Hence, the last attached layer will be the first to run (and the last, when exiting out of the procedure).
The Slim framework documentation depicts their own middlewaring system with the following image. The same
principle applies to uma\json-rpc
.
Middleware example
Suppose you wanted to enqueue incoming notifications to a Beanstalk tube and execute these out of the HTTP context in a separate process. Recall that a notification is a JSON-RPC request with no ID attribute. According to the JSON-RPC 2.0 spec, when a server receives one of these it has to run the method normally, but not return any output.
Instead of placing that logic at the beginning of every procedure or in an awkward base class
you can use a middleware similar to this, leveraging the fact that Request
objects can be json-encoded back
to the original payload:
declare(strict_types=1);
namespace Demo;
use Pheanstalk\Pheanstalk;
use UMA\JsonRpc;
/**
* A middleware that enqueues all incoming notifications to a Beanstalkd tube,
* thus avoiding their execution overhead.
*/
class AsyncNotificationsMiddleware implements JsonRpc\Middleware
{
/**
* @var Pheanstalk
*/
private $producer;
public function __construct(Pheanstalk $producer)
{
$this->producer = $producer;
}
public function __invoke(JsonRpc\Request $request, JsonRPC\Procedure $next): JsonRpc\Response
{
if (null === $request->id()) {
$this->producer->put(\json_encode($request));
return new JsonRpc\Success(null);
}
return $next($request);
}
}
FAQ
Does JSON-RPC 2.0 have any advantage over REST?
Yes, some! The most significant is that the spec is built on top of JSON and nothing else (i.e. there
is no talk of HTTP verbs, headers or authentication schemes in it). As a result, JSON-RPC 2.0
is completely decoupled from the transport layer, it can run over HTTP, WebSockets, a console REPL or even
over avian carriers or sheets of paper. This is actually the reason why the interface of Server::run()
works
with plain strings.
Additionally, the spec is short and unambiguous and supports "fire and forget" calls and batch processing.
How can I attach a middleware to specific procedures instead of the whole Server?
I made the conscious decision of not including this feature, because it increased the complexity of the Server a lot. Therefore middlewares are always run for all requests.
However, as the user you can manually skip them when the method is not the one you want:
use UMA\JsonRpc;
class PickyMiddleware implements JsonRpc\Middleware
{
/**
* @var string[]
*/
private $targetMethods;
public function __construct(array $targetMethods)
{
$this->targetMethods = $targetMethods;
}
public function __invoke(JsonRpc\Request $request, JsonRPC\Procedure $next): JsonRpc\Response
{
if (!in_array($request->method(), $this->targetMethods)) {
return $next($request);
}
// Actual logic goes here
}
}
How do you integrate uma/json-rpc
with other frameworks?
I'm preparing a repo with a handful of examples. It will cover JSON-RPC 2.0 over HTTP, TCP, WebSockets and the command-line interface.
Best Practices
Rely on JSON schemas to validate params
While it is not mandatory to return a JSON Schema from your procedures it is highly recommended to do so, because then your procedures can assume that the input parameters it receives are valid, and this simplifies their logic a great deal.
If you are not familiar with JSON Schemas there's a very good introduction at Understanding JSON Schema.
Defer actual work whenever possible
Since PHP is a language that does not have "mainstream" support for concurrent programming, whenever the server receives a batch request it has to process every sub-request sequentially, and this can add up the total response time.
Hence, a JSON-RPC server served over HTTP should strive to defer any actual work by
relying, for instance, on a work queue such as Beanstalkd
or RabbitMQ
. A second, out-of-band
JSON-RPC server could then consume the queue and do the actual work.
The protocol actually supports this use case: whenever an incoming request does not have an id
,
the server must not send the response back (these kind of requests are called Notifications
in the spec).
Cap the number of batch requests
When a Server
is exposed over HTTP, batch requests are a denial of service vector (even if PHP was capable of processing them concurrently).
A malicious client can potentially send a batch request with thousands of sub-requests, effectively clogging the resources of the server.
To minimize that risk, Server
has an optional batchLimit
parameter that specifies the maximum number of
batch requests that the server can handle. Setting it to 1 effectively disables batch processing, if you don't
need that feature.
PS. An attacker could also send hundreds or thousands of single requests, clogging the server all the same. But given that these are all individual HTTP requests they can be rate-limited at the webserver level.
$server = new \UMA\JsonRpc\Server($container, 2);
$server->set('add', Adder::class);
$response = $server->run('[
{"jsonrpc": "2.0", "method": "add", "params": [], "id": 1},
{"jsonrpc": "2.0", "method": "add", "params": [1,2], "id": 2},
{"jsonrpc": "2.0", "method": "add", "params": [1,2,3,4], "id": 3}
]');
// $response is '{"jsonrpc":"2.0","error":{"code":-32000,"message":"Too many batch requests sent to server","data":{"limit":2}},"id":null}'