JSON-RPC 2.0 API server for @Laravel framework

Hello @tabuna Thanks for this awesome package!

I have two simple questions

1. According to the specification, id in RPC request described as

id
An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2]
The Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects.

[1] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.

[2] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.

What is the reason for the current validation rule, which is

'id'      => 'regex:/^\d*(\.\d{2})?$/|nullable',

2. method delimiter How can I change default @ to the . (dot) or : (colon)?

I am experiencing issues combining a notification and a call in the same batch.

I expected to get one result, ( id 1 ) and no response for the notification at all. Below you can see 2 tests, the first test gets 2 responses for each call. The second is the same, except for the last in the batch, its a notification without id. it shouldn't give a response. but the first in the batch should.

Am i missing something here?

Test without notification:

$ curl -s 'http://127.0.0.1:80/api/v1' --data-binary '[{"jsonrpc":"2.0","method":"Resource@get","params":{"id":2},"id":1}, "jsonrpc":"2.0","method":"Resource@get","params":{"id":2},"id":1}]' | jq
[
  {
    "id": "1",
    "result": {
      "id": 2,
      "name": "Dr. Sheldon Nikolaus",
      "attribute1": "morgMoa64F",
      "attribute2": "Dh3dN11Jbf",
      "created_at": "2021-08-13T12:39:49.000000Z",
      "updated_at": "2021-08-13T12:39:49.000000Z"
    },
    "jsonrpc": "2.0"
  },
  {
    "id": "1",
    "result": {
      "id": 2,
      "name": "Dr. Sheldon Nikolaus",
      "attribute1": "morgMoa64F",
      "attribute2": "Dh3dN11Jbf",
      "created_at": "2021-08-13T12:39:49.000000Z",
      "updated_at": "2021-08-13T12:39:49.000000Z"
    },
    "jsonrpc": "2.0"
  }
]

Test with notification:

$ curl -s 'http://127.0.0.1:80/api/v1' --data-binary\
 '[{"jsonrpc":"2.0","method":"Resource@get","params":{"id":2},"id":1},{"jsonrpc":"2.0","method":"Resource@get","params":{"id":2}}]' | jq
[
  {
    "id": "1",
    "result": null,
    "jsonrpc": "2.0"
  },
  {
    "id": null,
    "result": null,
    "jsonrpc": "2.0"
  }
]

Hi, as described in the example on the docs all works for basic, but if I add some params to curl request, ive an error that i cannot understand:

{"id":null,"error":{"code":-32700,"message":"Parse error","data":null,"file":"/home/natty/workspace/farmacie/vendor/sajya/server/src/Http/Parser.php","line":133,"trace":"#0 /home/natty/workspace/farmacie/vendor/sajya/server/src/Http/Parser.php(104): Sajya\Server\Http\Parser->checkValidation()\n#1 /home/natty/workspace/farmacie/vendor/sajya/server/src/Guide.php(49): Sajya\Server\Http\Parser->makeRequests()\n#2 /home/natty/workspace/farmacie/vendor/sajya/server/src/JsonRpcController.php(27): Sajya\Server\Guide->handle()\n#3 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/ControllerDispatcher.php(48): Sajya\Server\JsonRpcController->__invoke()\n#4 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Route.php(255): Illuminate\Routing\ControllerDispatcher->dispatch()\n#5 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Route.php(197): Illuminate\Routing\Route->runController()\n#6 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Router.php(691): Illuminate\Routing\Route->run()\n#7 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(128): Illuminate\Routing\Router->Illuminate\Routing\{closure}()\n#8 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Middleware/SubstituteBindings.php(41): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#9 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\Routing\Middleware\SubstituteBindings->handle()\n#10 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Middleware/ThrottleRequests.php(127): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#11 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Middleware/ThrottleRequests.php(103): Illuminate\Routing\Middleware\ThrottleRequests->handleRequest()\n#12 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Middleware/ThrottleRequests.php(55): Illuminate\Routing\Middleware\ThrottleRequests->handleRequestUsingNamedLimiter()\n#13 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\Routing\Middleware\ThrottleRequests->handle()\n#14 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(103): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#15 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Router.php(693): Illuminate\Pipeline\Pipeline->then()\n#16 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Router.php(668): Illuminate\Routing\Router->runRouteWithinStack()\n#17 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Router.php(634): Illuminate\Routing\Router->runRoute()\n#18 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Routing/Router.php(623): Illuminate\Routing\Router->dispatchToRoute()\n#19 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(166): Illuminate\Routing\Router->dispatch()\n#20 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(128): Illuminate\Foundation\Http\Kernel->Illuminate\Foundation\Http\{closure}()\n#21 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/TransformsRequest.php(21): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#22 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\Foundation\Http\Middleware\TransformsRequest->handle()\n#23 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/TransformsRequest.php(21): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#24 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\Foundation\Http\Middleware\TransformsRequest->handle()\n#25 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/ValidatePostSize.php(27): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#26 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\Foundation\Http\Middleware\ValidatePostSize->handle()\n#27 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/PreventRequestsDuringMaintenance.php(87): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#28 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance->handle()\n#29 /home/natty/workspace/farmacie/vendor/fruitcake/laravel-cors/src/HandleCors.php(57): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#30 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Fruitcake\Cors\HandleCors->handle()\n#31 /home/natty/workspace/farmacie/vendor/fideloper/proxy/src/TrustProxies.php(57): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#32 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Fideloper\Proxy\TrustProxies->handle()\n#33 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(103): Illuminate\Pipeline\Pipeline->Illuminate\Pipeline\{closure}()\n#34 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(141): Illuminate\Pipeline\Pipeline->then()\n#35 /home/natty/workspace/farmacie/vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(110): Illuminate\Foundation\Http\Kernel->sendRequestThroughRouter()\n#36 /home/natty/workspace/farmacie/public/index.php(52): Illuminate\Foundation\Http\Kernel->handle()\n#37 /home/natty/workspace/farmacie/server.php(21): require_once('/home/natty/wor...')\n#38 {main}"},"jsonrpc":"2.0"}

1. #38 Finally, I figured out that it's not necessarily rendering exception with error handler. Expected exceptions need to transform must extend RpcException. What I need is just error reporting.
2. All exceptions will be caught by Exception, these is no need to catch HttpException or RuntimeException.

        } catch (HttpException | RuntimeException | Exception $exception) {

origin code

Consider this use case:

Authentication happens in headers with api tokens. I'd like to test through a procedure call attempt, that the headers successfully require auth, and thus return a 401 HTTP code.

I know I could bypass the trait methods and make my own setup that rips out the assertOk, but specifically I'd like to use the original callProcedure method to test all my procedures. It would just be nice if I could use the same calling of a procedure test, to test the auth for the procedure routes as well.

Maybe enlighten me if I am missing a bit of the philosophy behind this. I understand that jrpc must return http 200, and error key for application errors. However I thought it is reasonable to want to test the procedure call, and fail auth, and thus have a http response code that is not 200 (this is not a failure/error or mistake of JRPC, but of the authentication in the headers trying to POST to hit a procedure).

Please let me know! I didn't make the PR yet just because I wanted to see & understand if it was a desired change for the package.

Let's try to imagine a proxy service that receives a request or requests as input and forwards them to other third-party services, depending on the request parameters. As a result, it returns a list of responses that third-party services returned.

Some example of idea:

Input request into RPC-proxy:

[
  {
    "jsonrpc": "2.0",
    "method": "service1:procedure@sum", // this request will be forwarded to the service1 as procedure@sum
    "params": [
      1,
      2,
      3
    ],
    "id": 2
  },
  {
    "jsonrpc": "2.0",
    "method": "service2:procedure@avg", // this request will be forwarded to the service2 as procedure@avg
    "params": [
      1,
      2,
      3
    ],
    "id": 3
  },
  {
    "jsonrpc": "2.0",
    "method": "service3:procedure@min, // this request will be forwarded to the service3 as procedure@min,
    "params": [
      1,
      2,
      3
    ],
    "id": 4
  }
]

And response from RPC-proxy:

[
  {
    "id": "2",
    "result": {"sum":6}, // this is response from the service1 for procedure@sum
    "jsonrpc": "2.0",
    "method": "procedure@sum"
  },
  {
    "id": "3",
    "result": {"avg":2}, // this is response from the service2 for procedure@avg
    "jsonrpc": "2.0",
    "method": "procedure@avg"
  },
  {
    "id": "4",
    "result": {"min":1}, // this is response from the service3 for procedure@min,
    "jsonrpc": "2.0",
    "method": "procedure@min"
  }
]

The main question is this: is it possible to parse all input requests using the Sajya\Server\Http\Parser and forward them through the Guzzle as is?

Maybe you can give some advice or point me in the right direction?

whenever I try to clear the route caches with rpc endpoint, i get the InvalidArgumentException exception

   InvalidArgumentException 

  Attribute [rpc] does not exist.

  at vendor/laravel/framework/src/Illuminate/Routing/RouteRegistrar.php:107
    103▕      */
    104▕     public function attribute($key, $value)
    105▕     {
    106▕         if (! in_array($key, $this->allowedAttributes)) {
  ➜ 107▕             throw new InvalidArgumentException("Attribute [{$key}] does not exist.");
    108▕         }
    109▕ 
    110▕         if ($key === 'middleware') {
    111▕             foreach ($value as $index => $middleware) {

      +2 vendor frames 
  3   routes/api.php:28
      Illuminate\Support\Facades\Facade::__callStatic()

      +4 vendor frames 
  8   app/Providers/RouteServiceProvider.php:46
      Illuminate\Routing\RouteRegistrar::group()

When calling to a method which procedure doesn't have, it turns out into an internal exception.

local.ERROR: Method App\Http\Procedures\TennisProcedure::pinga() does not exist {"exception":"[object] (ReflectionException(code: 0): Method App\Http\Procedures\TennisProcedure::pinga() does not exist at /app/vendor/sajya/server/src/Guide.php:144)

Procedure Class

<?php
declare(strict_types=1);

namespace App\Http\Procedures;

use Illuminate\Http\Request;
use Sajya\Server\Procedure;

class TennisProcedure extends Procedure
{
    public static string $name = 'tennis';

    public function ping(): string
    {
        return 'pong';
    }
}

Call a method not exists

<?php
namespace App\Http\Controllers;
use Illuminate\Support\Facades\Http;
use Sajya\Client\Client;

class TennisController extends Controller
{
    public function index(): mixed
    {
        $request = Http::withoutVerifying()
            ->baseUrl(route('rpc.endpoint'));
        $client = new Client($request);
        $response = $client->execute('tennis@pinga');
        return $response->result();
    }
}

Bumps actions/cache from 3.0.11 to 3.2.1.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Updates the requirements on vimeo/psalm to permit the latest version.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

This pull request contains changes for upgrading to PHPUnit 9 automated by the PHPUnit 9 Shift.

Before merging, you should review all comments and commit any changes to the shift-75073 branch.

If there were changes you felt could have been automated, please reply to the follow-up email with your feedback or on Twitter.

Hi , Thanks for your work !

I'm using your package for simulate another rpc-endpoint , like i have another system who send json rpc request with method "ping" but since the method start with producer name its fail with

 "error": {
    "code": -32601,
    "message": "Method not found",

I have try to overwrite the method name by middleware like this

use Illuminate\Http\Request
 public function handle(Request $request, Closure $next)
    {
        $input = $request->all();
        Log::info("Request method ", [$input["method"], $request->method]); // Shows original request
        $request->merge([
            'method' =>  "message@" . $input['method']
        ]);
        $input = $request->all();
        $request->setMethod("message@" . $input['method']);
        Log::info("After Request method ", [$input["method"], $request->method]); // Shows modified request




        return $next($request);
    }

Bur i think its been ignored at all ..

Do you have any clues ?

Thanks

All exceptions are catched by Sajya\Server\HandleProcedure::handle without reporting. It will be a better way to use Illuminate\Contracts\Debug\ExceptionHandler to deal with exceptions.

As a benifit of this, all exceptions will be reported, such as logging and instant messaging, most useful for debugging. On the other hand, we can transform them into json-rpc format.

Maybe procedure name can be set from class name and relative namespace.

<?php

declare(strict_types=1);

namespace Sajya\Server;

use Illuminate\Support\Str;

abstract class Procedure
{
    public static function guessProcedureName(): string
    {
        return Str::snake(substr(class_basename(static::class), 0, -strlen('Procedure')));
    }

class TennisProcedure extends Procedure
{
    /**
     * The name of the procedure that will be
     * displayed and taken into account in the search
     *
     * @var string
     */
    public static string $name = 'tennis';

    /**
     * Execute the procedure.
     *
     * @param Request $request
     *
     * @return array|string|integer
     */
    public function ping(Request $request)
    {
        return "pong";
    }
}

and my route in api.php

Route::rpc('/v1/endpoint', [TennisProcedure::class])->name('rpc.endpoint');

and my request:

request url:
http://127.0.0.1:8006/api/v1/endpoint

request  body
{
    "jsonrpc": "2.0",
    "method": "tennis@ping",
    "id": 1
}

Smaller request works well, but larger ones (10MB+ payload, for example large email sets) hangs on processing side. The problem caused by the Arr::dot() call in \Sayja\Server\Binding bindResolve() function line 76

Introduction

I've been a bit disappointed to loose the ability to automatically bind method parameters based on the requests. With a REST-ish interface Laravel provides the Route Model Binding feature, which makes it convenient to just type-hint models on the controller methods, and let them be automatically resolved and injected to be used. I could see an explicit mention of a workaround in the documentation, but I wanted to achieve something which provides a more elegant syntax to do it so.

Considerations

I've been looking at how the default Route Model Binding works and tried to achieve a similar level of convenience, however since with the RPC route definition all Procedure classes are listed together, defining the parameter bindings in the route files would create convoluted and hard to read syntax. Also while the default Route Model Binding provides the Route::model() and the Route::bind() methods, they require the registration of a new Service and Facade accessors and I wanted to keep the solution to minimal and to implement with adding the least overhead to the library.

Solution

Since the official recommentation to work around the problem was already to use custom FormRequest instances on the Procedure methods, I think it is kind of easy to add the additional binding definitions there too. This way the implementer gets the full control over how to resolve the custom parameters, but can rely on the service container to help with the binding and after all simply just type hint what they need on the Procedure methods.

The entry point of the solution is the HandleProcedure::handle() method, where I've replaced App::call($this->procedure); with BoundMethod::call(app(), $this->procedure); which is pretty much the same, however by this change we can extend the \Illuminate\Container\BoundMethod::addDependencyForCallParameter() with the custom logic needed to inject the parameters.

The only catch is that the FormRequest parameter must come before any of the type hinted parameters that need custom resolution logic to apply. This is because addDependencyForCallParameter() resolves the parameters in the order they are needed for the Procedure method. So the first parameter is a FormRequest (or in fact any class) that implements the new BindsParameters Interface. During the resolution of the subsequent parameters, addDependencyForCallParameter() first checks each previously resolved parameters if they implement the BindsParameters Interface, and if so, uses them for the resolution. If there is no such parameters or no matches to be resolved, it passes the resolution back to parent::addDependencyForCallParameter() ensuring the implementation stays compatible with the original behaviour, if someone does not use custom FormRequests or the BindsParameters Interface.

Now the BindsParameters Interface defines two methods to be used for the resolution.

• resolveParameter() is the "replacement" for Route::bind(). It receives the name of the argument of the Procedure method, and expects the dependency instance to be returned. False can be returned to indicate to proceed with the rest of the resolution methods. null can be also used, if the parameter is optional.
• getBindings() is the "replacement" for the default Implicit Binding. Since the Route files do not define how request parameters corresponds to Model parameters, "implicit" binding is not possible: it must be explicit. On the other hand, while Route::model() really matches the route parameters to Model types, in our case this is not needed, since the Model type can always be determined by the type hint on the Procedure method. What we need instead is a way to explicitly specify which parameters of the RPC request correspond to which parameter of the Processor method: the getBindings() therefore should return an array mapping the Processor method parameters to the RPC request parameters. The resolution follows the same logic as for route parameters. By default the request parameter is expected to contain a primary key (id or whatever is defined as the key of the given Model), or may contain other keys, in the same fashion as for route model binding using custom keys; the parameter and the key separated using a colon, e.g.: post:slug.

Resolution by resolveParameter() takes precedence over resolution based on the getBindings(), and getBindings() takes precedence over the default resolution by the service container.

Note

Since any parameter that implements the BindsParameters interface can resolve subsequent dependencies, it is also possible to use a separate Request or FormRequest and another dependency of a BindsParameters class, effectively separating the Request from the Resolution, but this is more like a sideefect than a feature, tho someone may find it useful to use different FormRequest casses with the same BindsParametersClass or using the same FormRequest with a different BindsParametersClass for different methods.

Examples

You can find the tests in the PR, which indicates how to use the bindings:

• FixtureRequest demonstrates the implementation of BindsParameters::getBindings() and BindsParameters::resolveParameter().
• FixtureProcedure has been extended with few new getUserName... methods, which utilise the parameter resolution (and suit the test cases).

In the Test cases I've user the Illuminate\Foundation\Auth\User as the type to be resolved to avoid adding an additional fixture class to the library just for the tests' sake.

Questions

Error codes

I've read the error code section of the JSON:RPC documentation, but couldn't truly figure out what the ranges really mean. I came to the conclusion that the library implementing the standard may use the codes between -32000 to -32099 so I've assigned few of those in the new BoundMethod class to various resolution issues, but please advice if this usage is correct or should it use different codes?

Documentation

The contribution guide says documentation is expected with patches, but would that mean to submit a separate PR against the https://github.com/sajya/sajya.github.io repo with the documentation?

Please let me know what do you think. I hope you find the addition useful! Let me know if something should be changed!