README

Simple server SDK to convert a json-rpc request string into json-rpc response string.

See yoanm/symfony-jsonrpc-http-server for automatic dependency injection.

See yoanm/jsonrpc-params-symfony-validator-sdk for params validation.

See yoanm/jsonrpc-server-doc-sdk for documentation generation.

How to use

Sdk requires only two things :

A method resolver : must implements JsonRpcMethodResolverInterface, resolving logic's is your own.
Methods : JsonRpc methods which implements JsonRpcMethodInterface

Sdk optionally provide :

Events dispatch
Params validation

Simple Example

JSON-RPC Method

use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;

class DummyMethod implements JsonRpcMethodInterface
{
    /**
     * {@inheritdoc}
     */
    public function apply(array $paramList = null)
    {
        // Handle the request
        ...
        // Then return a result
        return [
            'status' => 'done',
        ];
        // Or
        return null;
        // Or
        return 12345;
    }
}

Array method resolver (simple example)

You can use the one used for behat tests or this Psr11 method resolver as example

use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;
use Yoanm\JsonRpcServer\Domain\JsonRpcMethodResolverInterface;

class ArrayMethodResolver implements JsonRpcMethodResolverInterface
{
    /** @var JsonRpcMethodInterface[] */
    private $methodList = [];

    /**
     * {@inheritdoc}
     */
    public function resolve(string $methodName) : ?JsonRpcMethodInterface
    {
        return array_key_exists($methodName, $this->methodList)
            ? $this->methodList[$methodName]
            : null
        ;
    }

    /**
     * @param JsonRpcMethodInterface $method
     * @param string                 $methodName
     */
    public function addMethod(JsonRpcMethodInterface $method, string $methodName)
    {
        $this->methodList[$methodName] = $method;
    }
}

Then add your method to the resolver and create the endpoint :

use Yoanm\JsonRpcServer\App\Creator\ResponseCreator;
use Yoanm\JsonRpcServer\App\Handler\ExceptionHandler;
use Yoanm\JsonRpcServer\App\Handler\JsonRpcRequestHandler;
use Yoanm\JsonRpcServer\App\Serialization\JsonRpcCallDenormalizer;
use Yoanm\JsonRpcServer\App\Serialization\JsonRpcCallResponseNormalizer;
use Yoanm\JsonRpcServer\App\Serialization\JsonRpcCallSerializer;
use Yoanm\JsonRpcServer\App\Serialization\JsonRpcRequestDenormalizer;
use Yoanm\JsonRpcServer\App\Serialization\JsonRpcResponseErrorNormalizer;
use Yoanm\JsonRpcServer\App\Serialization\JsonRpcResponseNormalizer;
use Yoanm\JsonRpcServer\Infra\Endpoint\JsonRpcEndpoint;

$resolver = new ArrayMethodResolver();
$resolver->addMethod('dummy-method', new DummyMethod());

$jsonRpcSerializer = new JsonRpcCallSerializer(
    new JsonRpcCallDenormalizer(
        new JsonRpcRequestDenormalizer()
    ),
    new JsonRpcCallResponseNormalizer(
        new JsonRpcResponseNormalizer() 
        // Or `new JsonRpcResponseNormalizer(new JsonRpcResponseErrorNormalizer())` for debug purpose
        // To also dump arguments, be sure 'zend.exception_ignore_args' ini option is not at true/1
    )
);
$responseCreator = new ResponseCreator();
$requestHandler = new JsonRpcRequestHandler($resolver, $responseCreator);
$exceptionHandler = new ExceptionHandler($responseCreator);

$endpoint = new JsonRpcEndpoint($jsonRpcSerializer, $requestHandler, $exceptionHandler);

Once endpoint is ready, you can send it request string :

$requestString = <<<JSONRPC
{
    "jsonrpc": "2.0",
    "id": 1
    "method": "dummy-method"
}
JSONRPC;

$responseString = $endpoint->index($requestString);

$responseString will be the following string depending of method returned value :

{"jsonrpc":"2.0","id":1,"result":{"status":"done"}}

```
{"jsonrpc":"2.0","id":1,"result":null}
```
```
{"jsonrpc":"2.0","id":1,"result":12345}
```

Events dispatch example

Simple event dispatcher

You can use the one used for behat tests as example

use Yoanm\JsonRpcServer\Domain\Event\JsonRpcServerEvent;
use Yoanm\JsonRpcServer\Domain\JsonRpcServerDispatcherInterface;

/**
 * Class SimpleDispatcher
 */
class SimpleDispatcher implements JsonRpcServerDispatcherInterface
{
    /** @var callable[] */
    private $listenerList = [];

    /**
     * {@inheritdoc}
     */
    public function dispatchJsonRpcEvent(string $eventName, JsonRpcServerEvent $event = null) : void
    {
        if (!array_key_exists($eventName, $this->listenerList)) {
            return;
        }

        foreach ($this->listenerList[$eventName] as $listener) {
            $listener($event, $eventName);
        }
    }

    /**
     * {@inheritdoc}
     */
    public function addJsonRpcListener(string $eventName, $listener) : void
    {
        $this->listenerList[$eventName][] = $listener;
    }
}

Then bind your listeners to your dispatcher:

use Yoanm\JsonRpcServer\Domain\Event\Acknowledge\OnRequestReceivedEvent;
use Yoanm\JsonRpcServer\Domain\Event\Acknowledge\OnResponseSendingEvent;
use Yoanm\JsonRpcServer\Domain\Event\Action\OnMethodSuccessEvent;

$dispatcher = new SimpleDispatcher();

$listener = function ($event, $eventName) {
    echo sprintf(
        'Received %s with event class "%s"',
        $eventName,
        get_class($event)
    );
};

$dispatcher->addJsonRpcListener(OnRequestReceivedEvent::EVENT_NAME, $listener);
$dispatcher->addJsonRpcListener(OnResponseSendingEvent::EVENT_NAME, $listener);
$dispatcher->addJsonRpcListener(OnMethodSuccessEvent::EVENT_NAME, $listener);

And bind dispatcher like following :

$endpoint->setJsonRpcServerDispatcher($dispatcher);
$requestHandler->setJsonRpcServerDispatcher($dispatcher);
$exceptionHandler->setJsonRpcServerDispatcher($dispatcher);

Events dispatched

Basic request lifecycle

json_rpc_server_skd.on_request_received / Acknowledge\OnRequestReceivedEvent

Dispatched when a request has been passed to the endpoint and successfully deserialized.
N.B. : Lonely cases where this event is not dispatched are when the request string is not a valid JSON-RPC request.

It include :
- Parse error exception (malformed json string)
- For simple request only, in case of Invalid request (not an object / missing required properties / ...).
  
  ⚠️ For batch request containing Invalid SubRequest, this event will still be dispatched
Either
- json_rpc_server_skd.on_method_success / Action\OnMethodSuccessEvent
  
  Dispatched only in case JSON-RPC method has been successfully executed.
- json_rpc_server_skd.on_method_failure / Action\OnMethodFailureEvent
  
  Dispatched only in case JSON-RPC method throw an exception during execution.
json_rpc_server_skd.on_response_sending / Acknowledge\OnResponseSendingEvent

Dispatched when a response has been successfully serialized by the endpoint and will be returned.

Additional events

Batch request

json_rpc_server_skd.on_batch_sub_request_processing / Acknowledge\OnBatchSubRequestProcessingEvent

Dispatched before that a sub request will be processed.
json_rpc_server_skd.on_batch_sub_request_processed / Acknowledge\OnBatchSubRequestProcessedEvent

Dispatched after that a sub request has been processed (regardless of the success or failure of the sub request method execution).

Exception

json_rpc_server_skd.on_exception / Action\OnExceptionEvent

Dispatched when an exception occurred during sdk execution

Action vs Acknowledge events

Acknowledge

They have only an acknowledge purpose.

They are grouped under Yoanm\JsonRpcServer\Domain\Event\Acknowledge namespace.

Action

They allow you to override stuffs.

They are grouped under Yoanm\JsonRpcServer\Domain\Event\Action namespace.

Here, the list :

Action\OnMethodSuccessEvent allow you to update/change the result of the method.
Action\OnMethodFailureEvent allow you to update/change the exception thrown by the method.
Action\OnExceptionEvent allow you to update/change the exception thrown.

Params validation example

You can use this JSON-RPC params symfony validator as example

To validate params for a given method, do the following :

use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;
use Yoanm\JsonRpcServer\Domain\JsonRpcMethodParamsValidatorInterface;
use Yoanm\JsonRpcServer\Domain\Model\JsonRpcRequest;

$validator = new class implements JsonRpcMethodParamsValidatorInterface
{
    public function validate(JsonRpcRequest $jsonRpcRequest, JsonRpcMethodInterface $method) : array
    {
        if (!(/** Skip unexpected method */)) {
            return [];
        }

        // Create your violations based on what you want
        $paramList = $jsonRpcRequest->getParamList();
        $violation = "???";

        return [$violation];
    }
};

$requestHandler->setMethodParamsValidator($validator);

Contributing

See contributing note

yoanm / jsonrpc-server-sdk

Maintainers

Details