Response Handler

The Reply Handler encodes outgoing server payloads into a standardized mRPC transmission envelope. This structure ensures cryptographic integrity and direct compatibility with the frontend colby-jack parsing engine.

Method Signature

public function send(
    array $data,
    string $action = "none",
    string $request_tag = "",
    string|bool $session_token = false,
    bool $success = true
): void

• $data: The main payload object (or error metadata array when $success is false).
• $action: Directive string triggering specific client-side behavior in colby-jack (e.g., "logout", "refresh_token", or "none" / "Generic").
• $request_tag: Unique correlation identifier mirrored directly from the client's original request.
• $session_token: Token used to calculate the HMAC signature. Pass false (default) to utilize the internal server secret for public routes.
• $success: Operational state flag. Defaults to true. Set to false when returning an error payload.

Response Envelope Structure

All outgoing mRPC response packets generated by send() conform to the following JSON geometry:

Field	Type	Description
success	boolean	Indicates whether the request succeeded (true) or encountered an error (false).
action	string	Optional client directive passed to colby-jack.
request_tag	string	Mirrored identifier matching the originating request packet.
timestamp	integer	Server UTC timestamp generated in milliseconds.
seed	string	High-entropy 64-character random cryptographic nonce.
data	object	Response payload on success, or structured error metadata on failure.
auth	string	Hex-encoded HMAC-SHA256 signature generated over the packet.

Basic Usage & Examples

Successful Response

To return requested resources, pass the data array alongside the matching request_tag:

public function get_user() {
$data = $this->REQUEST_DATA["data"];
$model = new \models\Example_Model();
$user_raw = $model->get_user($this->DB, $data["id"]);

    if ($user_raw && count($user_raw) > 0) {
        $this->RESP->send(
            ["response" => $user_raw[0]], 
            "Generic", 
            $this->REQUEST_DATA["request_tag"], 
            false
        );
    }
}

Encoded Wire Format Output:

{
  "success": true,
  "action": "Generic",
  "request_tag": "46588f3a1b9c",
  "timestamp": 1724185200150,
  "seed": "f4c8996fb92427ae41e4649b934ca495991b7852b855e3b0c44298fc1c149afb",
  "data": {
    "id": 42,
    "username": "drawfig"
  },
  "auth": "b4e9a8f27...32f1"
}

Error Handling

When returning errors, pass the failure details within the $data parameter and set $success to false. The payload will be serialized inside the envelope's data field while marking success: false.

else {
    $this->RESP->send(
        ["api_message" => "Database failed to find requested User"],
        "Generic",
        $this->REQUEST_DATA["request_tag"],
        false,
        false
    );
}

Encoded Wire Format Output:

{
  "success": false,
  "action": "Generic",
  "request_tag": "46588f3a1b9c",
  "timestamp": 1724185200199,
  "seed": "a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef0",
  "data": {
    "api_message": "Database failed to find requested User"
  },
  "auth": "e7c4f1a...90b2"
}