laravel-natsrpc-server

Laravel NATSRPC Server

This package implements a JSON-RPC server over a NATS transport.

You can call methods on other services without changing your workflow too much

composer require dpniel_ch/laravel-natsrpc-server

Compiling NATS-RPC Runner

The runner is implemented in go as it is better suited to holding open long lived connections to the nats server. But as a result we inherit a build step to build the runner if ever the go code is modified.

$ make compile
Compiling for all OS types
GOOS=linux go build -o bin/natsrunner-linux
GOOS=darwin go build -o bin/natsrunner

This builds runners for both mac and linux targets. The laravel console command picks the correct one at run time when running the artisan nats:listen command.

Running the test suite

Because we are using both go and php here and they both use vendor/ directory for dependencies we hit a conflict. So instead the composer.json has been adjusted to use the directory vendor_php/ which obviouslly affects calling php unit.

So to make it easier to remember there is a make test command that will just do the right thing and trigger a test run.

$ make test
Running composer tests
composer test
> vendor_php/bin/phpunit
PHPUnit 8.5.15 by Sebastian Bergmann and contributors.

Runtime:       PHP 7.2.34
Configuration: /Users/dan/PhpstormProjects/laravel-natsrpc-server/phpunit.xml

.............                                                     13 / 13 (100%)

Time: 308 ms, Memory: 14.00 MB

OK (13 tests, 23 assertions)

Running the NATS-RPC Server

This package includes a server binary that manages the long lived connections with a nats server and offloads requests and events to a pool of php workers it manages.

The php workers transform a nats-rpc payload into an Illuminate\Http\Request and pass this off to laravels kernel to be handled by an \App\Nats\Controller which has been configured in routes/nats.php

To run the server you need to create a config file for the natsrunner (or vendor:publish if laravel).

Create a file called config/natsrpc.php in your project s config directory

<?php

return [
    "service" => env("NATSRPC_SERVICE_NAME", "com.service.test"),
    "server" => [
        "command" => env("NATSRPC_WORKER_CMD", "php vendor/bin/natsrunner.php"),
        "pool" => [
            "num_workers" => env("NATSRPC_NUM_WORKERS", 5),
            "max_jobs" => env("NATSRPC_MAX_JOBS", 100)
        ]
    ],
    "nats" => [
        "host" => env("NATS_HOST", "nats://127.0.0.1"),
        "user" => env("NATS_USER", ""),
        "pass" => env("NATS_PASS", "")
    ],
    // String list of service names to event subscribe to.
    "subscribe" => [

    ]
];

Once that's in place you can start the service with

$ php artisan nats:listen

If all is well you should now have a functioning server ready to accept requests through nats.

NatsRPC Controllers

$ php artisan make:nats-controller FooController

This will create a basic controller in app/Nats/Controllers with an index method. Now with Nats-RPC we just have to return an array of data from the controller method which the calling route dispatcher will wrap into a JsonRpcResponse to send back.

// ...
class FooController
{
    public function index(RequestParams $params)
    {
        // echo it back
        return $params->all();
    }
}

To make this controller accessable we need to bind it in the nats route file routes/nats.php (You will need to create this)

// in routes/nats.php

// This binds all public controller methods to the given prefix of "foo"
// So calling "foo.bar" would call the bar function in the bound FooController.
$router->bindController("foo", "FooController");
// Or to bind just a single method
$router->bind("foo.index", "FooController@index");

NatsRPC Service Client

Now to call this method in the new controller above we can use the included NatsRPC Client.

use NatsRPC\Client\Service;

$service = Service::create("com.service.test"); // The service we want to talk to
$resp = $service->request("foo", ["test" => "data"]);
// Or
$resp = $service->request("foo.index", ["test" => "data"]);

if (!$resp->hasError() && $resp->hasResult()) {
    dd($resp->result());
}

Broadcast Events over nats

You can either use the nats() helper function to broadcast an event or get an instance of the NatsRPC Client and publish

nats("user.login", ["user" => $user->id]);
// Or
use NatsRPC\Client\Client;
app()->make(Client::class)->publish("user.login", [...])

Any service that is listening on a services events will fire a NatsRPC\Events\ServiceEvent which applications can listen on and react to in the normal laravel Listener flow.