update dev

Author: rodber

developer/README.md

@@ -6,66 +6,112 @@ sidebar: false
 
 A client library for xrDebug is easy to implement as any HTTP API. Client libraries are HTTP wrappers for interacting with xrDebug, making the configuration and usage trivial to end-users.
 
+## Design considerations
+
+- The client software is responsible for formatting the debug information.
+- The "ID" field is used to identify messages and pauses. It should be unique for each message or pause, and it's up to the client to generate it.
+
 ## Message
 
-To send messages is required to `POST /messages`. Code below outlines a `sendMessage` function.
+To send messages use the `POST /messages` endpoint. In xrDebug is the client software which formats the debug information, so the server doesn't enforce any specific format. You can send any data you want, but it's recommended to use HTML.
 
-```php
-function sendMessage($data): void
-{
-    // POST /messages
-    $curl = new Curl(/** on data **/);
-    $curl->exec();
-    // ...
-}
-```
+## Pauses
+
+Pauses allow you to temporarily halt program execution until a specific condition is met. They work in a two-state system:
 
-## Pause
+1. When a pause is created (`POST /pauses`), it starts with `stop: false`
+2. The program enters a polling loop, checking the pause status (`GET /pauses/{id}`)
+3. The pause can be released in two ways:
+   - Stopped (`PATCH /pauses/{id}`) - Sets `stop: true`, program should terminate
+   - Deleted (`DELETE /pauses/{id}`) - Removes the pause, program should continue
 
-To implement pause is required to `POST /pauses` and sleep/wait while the `id` is paused. Code below outlines a `sendPause` and `isPaused` functions used on the PHP client.
+### Example pause loop
 
 ```php
-function sendPause(...$args): void
+class PauseException extends Exception {}
+
+function waitForPause(string $id): void
 {
-    // POST /pauses
-    $curl = new Curl(/** on id **/);
-    $curl->exec();
-    $curlError = $curl->error();
-    // Ignore on error
-    if ($curlError !== '') {
-        return;
-    }
-    // Sleep while id is paused
-    do {
+    while (true) {
+        $response = http_get("/pauses/{$id}");
+        if (!$response) {
+            // Pause was deleted, continue execution
+            return;
+        }
+        if ($response->stop === true) {
+            // Pause was stopped, terminate execution
+            throw new PauseException("Execution stopped by debugger");
+        }
+        // Wait before next check
         sleep(1);
-    } while (isPaused($id));
+    }
 }
 
-function isPaused($id): bool
+try {
+    // Create pause
+    http_post("/pauses", ["id" => "debug-123"]);
+    // Wait for pause to be released
+    waitForPause("debug-123");
+    // Continue execution if pause was deleted
+    echo "Continuing...";
+} catch (PauseException $e) {
+    echo "Execution stopped";
+    exit(1);
+}
+```
+
+## Signed requests
+
+Request signing using Ed25519 digital signatures to verify message origin authenticity.
+
+To sign a request, the client must include the `X-Signature` header on requests made to the xrDebug server. The signature is a base64 encoded string generated by signing the serialized post fields with the private key. If there's no fields sign an empty string.
+
+### Sign workflow
+
+To sign a request server expect the following data workflow:
+
+1. Sort the post fields by key
+2. Concatenate the key-value pairs
+3. Sign the concatenated string
+4. Base64 encode the signature at `X-Signature` header
+
+Example in PHP:
+
+```php
+function serialize(array $data): string
 {
-    // POST /pauses/$id
-    $curl = new Curl(/** on id **/);
-    $curlExec = $curl->exec();
-    // Free pause on error
-    if (! $curlExec || $curl->error() !== '') {
-        return false;
-    }
-    // Read response {stop: true|false}
-    $response = json_decode($curlExec);
-    $stop = $response->stop ?? false;
-    // Stop execution on stop: true
-    if ($stop) {
-        throw new Exception();
+    $result = '';
+    ksort($data);
+    foreach ($data as $key => $value) {
+        $result .= $key . $value;
     }
 
-    return true;
+    return $result;
 }
+
+$serialized = serialize($data);
+$signature = $privateKey->sign($serialized);
+$signHeader = base64_encode($signature);
 ```
 
-## Singing requests
+Example in Python:
 
-`🚧 Work in progress`
+```python
+def serialize(data: dict) -> str:
+    return ''.join(f'{k}{v}' for k, v in sorted(data.items()))
 
-## End-to-end encryption
+serialized = serialize(data)
+signature = private_key.sign(serialized)
+signHeader = base64.b64encode(signature).decode()
+```
+
+The `X-Signature` header should contain the base64 encoded signature generated by the client.
 
-`🚧 Work in progress`
+```sh
+curl --fail -X POST \
+    --data "body=My signed message" \
+    --data "file_path=file" \
+    --data "file_line=1" \
+    -H "X-Signature: <signHeader>" \
+    http://127.0.0.1:27420/messages
+```