Multiple Changes

Composer:
- Bump php dep to 8.2
- Add ext-json as requirement

Response:
- move error package describing error member to response package

Server:
- Split notification and request middleware

Documentation:
- add links and test from json-RPC 2.0 spec to phpdocs

Client:
- add client Interface

Author: dhaeckel

composer.json

@@ -33,6 +33,7 @@
         ]
     },
     "require": {
-        "php": "^8.1"
+        "php": "^8.2",
+        "ext-json": "*"
     }
 }

composer.lock

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Haeckel\JsonRpcServerContract;
+
+use Haeckel\JsonRpcServerContract\{Message, Response};
+
+interface ClientIface
+{
+    public function sendRequest(
+        Message\RequestIface $request,
+    ): Response\SuccessIface|Response\ErrorIface;
+
+    public function sendBatch(
+        Message\BatchRequestIface $batchRequest,
+    ): null|Response\BatchIface|Response\ErrorIface;
+
+    public function sendNotification(Message\NotificationIface $notification): void;
+}

src/ClientIface.php

@@ -22,10 +22,10 @@
 
 namespace Haeckel\JsonRpcServerContract\Exception;
 
-use Haeckel\JsonRpcServerContract\Message;
+use Haeckel\JsonRpcServerContract\{Message, Response};
 
 interface JsonRpcErrorIface extends \Throwable
 {
-    public function getErrorObject(): Message\ErrorObjectIface;
+    public function getErrorObject(): Response\Error\ErrObjectIface;
     public function getRequest(): ?Message\RequestIface;
 }

src/Exception/JsonRpcErrorIface.php

@@ -25,9 +25,13 @@
 use Haeckel\JsonRpcServerContract\{DataStruct, Response};
 
 /**
- * @extends DataStruct\CollectionIface<RequestIface|NotificationIface>
+ * To send several Request objects at the same time,
+ * the Client MAY send an Array filled with Request objects.
  *
  * @link https://www.jsonrpc.org/specification#batch
+ *
+ * @extends DataStruct\CollectionIface<RequestIface|NotificationIface>
+ *
  */
 interface BatchRequestIface extends DataStruct\CollectionIface
 {

src/Message/BatchRequestIface.php

@@ -22,17 +22,52 @@
 
 namespace Haeckel\JsonRpcServerContract\Message;
 
-/** @link https://www.jsonrpc.org/specification#notification */
+/**
+ * A Notification is a Request object without an "id" member.
+ * A Request object that is a Notification signifies the Client's lack of interest in the
+ * corresponding Response object, and as such no Response object needs to be returned to the client.
+ * The Server MUST NOT reply to a Notification, including those that are within a batch request.
+ *
+ * Notifications are not confirmable by definition,
+ * since they do not have a Response object to be returned.
+ * As such, the Client would not be aware of any errors
+ * (like e.g. "Invalid params","Internal error").
+ * @link https://www.jsonrpc.org/specification#notification
+ */
 interface NotificationIface extends \JsonSerializable
 {
     public function getJsonRpc(): string;
-    public function withJsonRpc(string $jsonRpc): static;
+    /**
+     * @param string $jsonrpc
+     * A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
+     */
+    public function withJsonRpc(string $jsonrpc): static;
 
     public function getMethod(): string;
+    /**
+     * @param string $method
+     * A String containing the name of the method to be invoked.
+     * Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46)
+     * are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else.
+     */
     public function withMethod(string $method): static;
 
-    /** @return null|object|array<mixed> */
+    /** @return null|object|list<mixed> */
     public function getParams(): null|array|object;
-    /** @param null|object|array<mixed> $params */
+    /**
+     * @param null|object|list<mixed> $params
+     * A Structured value that holds the parameter values to be used during the invocation of the
+     * method. This member MAY be omitted (in this case with null).
+     *
+     * If present, parameters for the rpc call MUST be provided as a Structured value.
+     * Either by-position through an Array or by-name through an Object.
+     *
+     * by-position: params MUST be an Array, containing the values in the Server expected order.
+     * by-name: params MUST be an Object, with member names that match the Server expected parameter
+     * names. The absence of expected names MAY result in an error being generated.
+     * The names MUST match exactly, including case, to the method's expected parameters.
+     *
+     * @link https://www.jsonrpc.org/specification#parameter_structures
+     */
     public function withParams(null|array|object $params): static;
 }

src/Message/NotificationIface.php

@@ -22,9 +22,23 @@
 
 namespace Haeckel\JsonRpcServerContract\Message;
 
-/** @link https://www.jsonrpc.org/specification#request_object */
+/**
+ * A rpc call is represented by sending a Request object to a Server.
+ *
+ * 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.
+ * @link https://www.jsonrpc.org/specification#request_object
+ */
 interface RequestIface extends NotificationIface
 {
     public function getId(): int|string;
+    /**
+     * @param int|string $id
+     * An identifier established by the Client that MUST contain a String, Number, or NULL value.
+     * The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2]
+     *
+     * ATTENTION: this implementation is strict with the with the interpretation of allowable types
+     * and only allows string and int as it's type.
+     */
     public function withId(int|string $id): static;
 }

src/Message/RequestIface.php

@@ -1,14 +1,49 @@
 <?php
 
+/**
+ * This file is part of haeckel/json-rpc-server-contracts.
+ *
+ * haeckel/json-rpc-server-contracts is free software:
+ * you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of the License,
+ * or (at your option) any later version.
+ *
+ * haeckel/json-rpc-server-contracts is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License along with
+ * haeckel/json-rpc-server-contracts.
+ * If not, see <https://www.gnu.org/licenses/>.
+ */
+
 declare(strict_types=1);
 
 namespace Haeckel\JsonRpcServerContract\Response;
 
+/**
+ * When a rpc call is made, the Server MUST reply with a Response,
+ * except for in the case of Notifications.
+ * The Response is expressed as a single JSON Object
+ *
+ * @link https://www.jsonrpc.org/specification#response_object
+ */
 interface BaseIface extends \JsonSerializable
 {
     public function getId(): null|int|string;
+    /**
+     * @param null|int|string $id
+     * It MUST be the same as the value of the id member in the Request Object.
+     * If there was an error in detecting the id in the Request object
+     * (e.g. Parse error/Invalid Request), it MUST be Null.
+     */
     public function withId(null|int|string $id): static;
 
     public function getJsonrpc(): string;
+    /**
+     * @param string $jsonrpc
+     * A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
+     */
     public function withJsonrpc(string $jsonrpc): static;
 }

src/Response/BaseIface.php

@@ -25,9 +25,25 @@
 use Haeckel\JsonRpcServerContract\DataStruct\CollectionIface;
 
 /**
- * @extends CollectionIface<ErrorIface|SuccessIface>
+ * The Server should respond with an Array containing the corresponding Response objects,
+ * after all of the batch Request objects have been processed.
+ * A Response object SHOULD exist for each Request object,
+ * except that there SHOULD NOT be any Response objects for notifications.
+ * The Server MAY process a batch rpc call as a set of concurrent tasks,
+ * processing them in any order and with any width of parallelism.
+ *
+ * The Response objects being returned from a batch call MAY be returned in any order within the
+ * Array. The Client SHOULD match contexts between the set of Request objects and the resulting set
+ * of Response objects based on the id member within each Object.
+ *
+ * If the batch rpc call itself fails to be recognized as an valid JSON or as an Array with at least
+ * one value, the response from the Server MUST be a single Response object.
+ * If there are no Response objects contained within the Response array as it is to be sent to the
+ * client, the server MUST NOT return an empty Array and should return nothing at all.
  *
  * @link https://www.jsonrpc.org/specification#batch
+ *
+ * @extends CollectionIface<ErrorIface|SuccessIface>
  */
 interface BatchIface extends CollectionIface
 {

src/Response/BatchIface.php

@@ -20,7 +20,7 @@
 
 declare(strict_types=1);
 
-namespace Haeckel\JsonRpcServerContract\Message\ErrObj;
+namespace Haeckel\JsonRpcServerContract\Response\Error;
 
 /** @link @link https://www.jsonrpc.org/specification#error_object */
 interface ErrCodeIface