Improve the docs

Author: andrewdalpino

CHANGELOG.md

@@ -4,7 +4,7 @@
     - Added HTTP Access Log Generator middleware
     - Added command methods to client interfaces
     - Added Bzip2 message serializer
-    - Optimize HTTP routing
+    - Optimized HTTP routing
 
 - 0.2.1-beta
     - Support PSR-15 Server Request Handler interface

README.md

@@ -23,6 +23,7 @@ $ composer require rubix/server
 	- [REST Server](#rest-server)
 	- [RPC Server](#rpc-server)
 - [Clients](#clients)
+	- [REST Client](#rest-client)
 	- [RPC Client](#rpc-client)
 - [HTTP Middleware](#http-middleware)
 	- [Access Log Generator](#access-log-generator)
@@ -47,7 +48,7 @@ $server = new RESTServer('127.0.0.1', 8080);
 
 $estimator = new KNearestNeighbors(5);
 
-// Import the training set
+// Import a dataset
 
 $estimator->train($dataset);
 
@@ -83,12 +84,12 @@ Interfaces: [Server](#servers)
 #### HTTP Routes
 | Method | URI | JSON Params | Description |
 |--|--|--|--|
-| POST | /model/predictions | `samples` | Return the predictions given by the model. |
-| POST | /model/predictions/sample | `sample` | Make a prediction on a single sample. |
-| POST | /model/probabilities | `samples` | Predict the probabilities of each outcome. |
-| POST | /model/probabilities/sample | `sample` | Return the probabilities of a single sample. |
-| POST | /model/scores | `samples` | Assign an anomaly score to each sample. |
-| POST | /model/scores/sample | `sample` | Assign an anomaly score to a single sample. |
+| POST | /model/predictions | `samples` | Make a set of predictions on a dataset. |
+| POST | /model/predictions/sample | `sample` | Make a single prediction on a sample. |
+| POST | /model/probabilities | `samples` | Return the joint probabilities of each sample in a dataset. |
+| POST | /model/probabilities/sample | `sample` | Return the joint probabilities of a single sample. |
+| POST | /model/scores | `samples` | Return the anomaly scores of each sample in a dataset. |
+| POST | /model/scores/sample | `sample` | Return the anomaly score of a single sample. |
 
 #### Example
 
@@ -139,7 +140,7 @@ $server = new RPCServer('127.0.0.1', 8888, null, [
 
 ---
 ### Clients
-Clients allow you to communicate directly with a model server over the wire using a friendly object-oriented interface inside your PHP applications.
+Clients allow you to communicate directly with a model server using a friendly object-oriented interface inside your PHP applications. Under the hood, clients handle all the networking communication and content negotiation for you so you can write programs *as if* the model was directly accessible in your applications.
 
 Return the predictions from the model:
 ```php
@@ -151,6 +152,8 @@ use Rubix\Server\RPCClient;
 
 $client = new RPCClient('127.0.0.1', 8888);
 
+// Import a dataset
+
 $predictions = $client->predict($dataset);
 ```
 
@@ -180,7 +183,7 @@ public scoreSample(array $sample) : array
 ```
 
 #### Async Clients
-Clients that implement the Async Client interface have asynchronous versions of all the command methods. All asynchronous methods return a [Promises/A+](https://promisesaplus.com/) promise that resolves to the return value of the response.
+Clients that implement the Async Client interface have asynchronous versions of all the standard client methods. All asynchronous methods return a [Promises/A+](https://promisesaplus.com/) object that resolves to the return value of the response.
 
 ```php
 public predictAsync(Dataset $dataset) : Promise
@@ -298,7 +301,7 @@ $middleware = new AccessLog(new Screen());
 ### Basic Authenticator
 An implementation of HTTP Basic Auth as described in [RFC7617](https://tools.ietf.org/html/rfc7617).
 
-> **Note**: This authorization strategy is only secure over an encrypted communication channel such as HTTPS with SSL or TLS.
+> **Note:** This authorization strategy is only secure over an encrypted communication channel such as HTTPS with SSL or TLS.
 
 #### Parameters
 | # | Param | Default | Type | Description |
@@ -320,7 +323,7 @@ $middleware = new BasicAuthenticator([
 ### Shared Token Authenticator
 Authenticates incoming requests using a shared key that is kept secret between the client and server. It uses the `Authorization` header with the `Bearer` prefix to indicate the shared key.
 
-> **Note**: This authorization strategy is only secure over an encrypted communication channel such as HTTPS with SSL or TLS.
+> **Note:** This authorization strategy is only secure over an encrypted communication channel such as HTTPS with SSL or TLS.
 
 #### Parameters
 | # | Param | Default | Type | Description |

composer.json

@@ -6,11 +6,11 @@
     "license": "MIT",
     "readme": "README.md",
     "keywords": [
-        "api", "cloud", "distributed", "inference", "inference engine", "inference server",
+        "ai", "api", "cloud", "distributed", "inference", "inference engine", "inference server",
         "infrastructure", "json api", "machine learning", "microservice", "ml", "ml infrastructure",
-        "model server", "model deployment", "php", "php machine learning", "php ml", "prediction",
-        "rest api", "rest server", "rpc client", "rpc server", "rubix", "rubix ml", "rubixml",
-        "server"
+        "ml server", "model server", "model deployment", "php", "pap ai", "php machine learning",
+        "php ml", "prediction", "rest api", "rest server", "rest client", "rpc client", "rpc server",
+        "rubix", "rubix ml", "rubixml", "server"
     ],
     "authors": [
         {

examples/RPC/client.php

@@ -18,10 +18,10 @@
 
 $dataset = $generator->generate(10)->randomize();
 
-$predictions = $client->predict($dataset);
+$promise1 = $client->predictAsync($dataset);
 
-$probabilities = $client->proba($dataset);
+$promise2 = $client->probaAsync($dataset);
 
-print_r($predictions);
+print_r($promise1->wait());
 
-print_r($probabilities);
+print_r($promise2->wait());

src/Http/Controllers/CommandsController.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Rubix\Server\Http\Controllers;
+
+use Rubix\Server\Services\CommandBus;
+use Rubix\Server\Commands\Command;
+use Rubix\Server\Serializers\Serializer;
+use Rubix\Server\Responses\ErrorResponse;
+use Rubix\Server\Exceptions\ValidationException;
+use Psr\Http\Message\ServerRequestInterface as Request;
+use Psr\Http\Message\ResponseInterface as Response;
+use React\Http\Message\Response as ReactResponse;
+use Exception;
+
+use const Rubix\Server\Http\HTTP_OK;
+
+class CommandsController extends RPCController
+{
+    /**
+     * The command bus.
+     *
+     * @var \Rubix\Server\Services\CommandBus
+     */
+    protected $bus;
+
+    /**
+     * @param \Rubix\Server\Services\CommandBus $bus
+     * @param \Rubix\Server\Serializers\Serializer $serializer
+     */
+    public function __construct(CommandBus $bus, Serializer $serializer)
+    {
+        $this->bus = $bus;
+
+        parent::__construct($serializer);
+    }
+
+    /**
+     * Handle the request.
+     *
+     * @param \Psr\Http\Message\ServerRequestInterface $request
+     * @param mixed[]|null $params
+     * @return \Psr\Http\Message\ResponseInterface
+     */
+    public function handle(Request $request, ?array $params = null) : Response
+    {
+        try {
+            $payload = $request->getBody()->getContents();
+
+            $command = $this->serializer->unserialize($payload);
+
+            if (!$command instanceof Command) {
+                throw new ValidationException('Command could not be reconstituted.');
+            }
+
+            $response = $this->bus->dispatch($command);
+
+            $status = HTTP_OK;
+        } catch (Exception $exception) {
+            $response = ErrorResponse::fromException($exception);
+
+            $status = $exception->getCode();
+        }
+
+        $data = $this->serializer->serialize($response);
+
+        return new ReactResponse($status, $this->serializer->headers(), $data);
+    }
+}

src/Http/Controllers/RPCController.php

@@ -2,27 +2,10 @@
 
 namespace Rubix\Server\Http\Controllers;
 
-use Rubix\Server\Services\CommandBus;
-use Rubix\Server\Commands\Command;
 use Rubix\Server\Serializers\Serializer;
-use Rubix\Server\Responses\ErrorResponse;
-use Rubix\Server\Exceptions\ValidationException;
-use Psr\Http\Message\ServerRequestInterface as Request;
-use Psr\Http\Message\ResponseInterface as Response;
-use React\Http\Message\Response as ReactResponse;
-use Exception;
 
-use const Rubix\Server\Http\HTTP_OK;
-
-class RPCController extends Controller
+abstract class RPCController extends Controller
 {
-    /**
-     * The command bus.
-     *
-     * @var \Rubix\Server\Services\CommandBus
-     */
-    protected $bus;
-
     /**
      * The message serializer.
      *
@@ -31,44 +14,10 @@ class RPCController extends Controller
     protected $serializer;
 
     /**
-     * @param \Rubix\Server\Services\CommandBus $bus
      * @param \Rubix\Server\Serializers\Serializer $serializer
      */
-    public function __construct(CommandBus $bus, Serializer $serializer)
+    public function __construct(Serializer $serializer)
     {
-        $this->bus = $bus;
         $this->serializer = $serializer;
     }
-
-    /**
-     * Handle the request.
-     *
-     * @param \Psr\Http\Message\ServerRequestInterface $request
-     * @param mixed[]|null $params
-     * @return \Psr\Http\Message\ResponseInterface
-     */
-    public function handle(Request $request, ?array $params = null) : Response
-    {
-        try {
-            $payload = $request->getBody()->getContents();
-
-            $command = $this->serializer->unserialize($payload);
-
-            if (!$command instanceof Command) {
-                throw new ValidationException('Command could not be reconstituted.');
-            }
-
-            $response = $this->bus->dispatch($command);
-
-            $status = HTTP_OK;
-        } catch (Exception $exception) {
-            $response = ErrorResponse::fromException($exception);
-
-            $status = $exception->getCode();
-        }
-
-        $data = $this->serializer->serialize($response);
-
-        return new ReactResponse($status, $this->serializer->headers(), $data);
-    }
 }

src/Http/Middleware/Middleware.php

@@ -8,7 +8,7 @@
 interface Middleware
 {
     /**
-     * Allow an instance to be called like a function.
+     * Process the request and return a response.
      *
      * @param Request $request
      * @param callable $next

src/RPCServer.php

@@ -6,7 +6,7 @@
 use Rubix\ML\Estimator;
 use Rubix\Server\Services\Router;
 use Rubix\Server\Services\CommandBus;
-use Rubix\Server\Http\Controllers\RPCController;
+use Rubix\Server\Http\Controllers\CommandsController;
 use Rubix\Server\Http\Middleware\Middleware;
 use Rubix\Server\Serializers\JSON;
 use Rubix\Server\Serializers\Serializer;
@@ -143,7 +143,7 @@ public function serve(Estimator $estimator) : void
 
         $this->router = new Router([
             '/commands' => [
-                'POST' => new RPCController($bus, $this->serializer),
+                'POST' => new CommandsController($bus, $this->serializer),
             ],
         ]);
 

src/Services/CommandBus.php

@@ -50,7 +50,7 @@ class CommandBus
      *
      * @var callable[]
      */
-    protected $mapping;
+    protected $handlers;
 
     /**
      * A PSR-3 logger instance.
@@ -68,41 +68,41 @@ class CommandBus
      */
     public static function boot(Estimator $estimator, ?LoggerInterface $logger = null) : self
     {
-        $mapping = [
+        $handlers = [
             Predict::class => new PredictHandler($estimator),
         ];
 
         if ($estimator instanceof Learner) {
-            $mapping += [
+            $handlers += [
                 PredictSample::class => new PredictSampleHandler($estimator),
             ];
         }
 
         if ($estimator instanceof Probabilistic) {
-            $mapping += [
+            $handlers += [
                 Proba::class => new ProbaHandler($estimator),
                 ProbaSample::class => new ProbaSampleHandler($estimator),
             ];
         }
 
         if ($estimator instanceof Ranking) {
-            $mapping += [
+            $handlers += [
                 Score::class => new ScoreHandler($estimator),
                 ScoreSample::class => new ScoreSampleHandler($estimator),
             ];
         }
 
-        return new self($mapping, $logger);
+        return new self($handlers, $logger);
     }
 
     /**
-     * @param callable[] $mapping
+     * @param callable[] $handlers
      * @param \Psr\Log\LoggerInterface|null $logger
      * @throws \Rubix\Server\Exceptions\InvalidArgumentException
      */
-    public function __construct(array $mapping, ?LoggerInterface $logger = null)
+    public function __construct(array $handlers, ?LoggerInterface $logger = null)
     {
-        foreach ($mapping as $class => $handler) {
+        foreach ($handlers as $class => $handler) {
             if (!class_exists($class)) {
                 throw new InvalidArgumentException("Class $class does not exist.");
             }
@@ -112,7 +112,7 @@ public function __construct(array $mapping, ?LoggerInterface $logger = null)
             }
         }
 
-        $this->mapping = $mapping;
+        $this->handlers = $handlers;
         $this->logger = $logger;
     }
 
@@ -128,11 +128,11 @@ public function dispatch(Command $command) : Response
     {
         $class = get_class($command);
 
-        if (empty($this->mapping[$class])) {
+        if (empty($this->handlers[$class])) {
             throw new HandlerNotFound($command);
         }
 
-        $handler = $this->mapping[$class];
+        $handler = $this->handlers[$class];
 
         try {
             return call_user_func($handler, $command);