SRPC is a JSON-based RPC protocol for clients, like webpages, to call a server via a standardized JSON interface. It requires a carrier protocol, like HTTP.

The keywords SHOULD, MAY, MUST, etc. are defined in RFC 2119.

Scope

• Successful response
• Successful response with warnings
• Error response
• Access control is not handled by SRPC
• Request deduplication is not handled by SRPC
• Rate limiting is not handled by SRPC

Comparison with SPJC

SPJC is a similar protocol, but it encourages bad practices in the client code.

• SPJC requires more complex code for both the server, and the client
• SPJC doesn’t require any kind of error handling in the client
• SRPC doesn’t describe any request aggregation or batching

Schemas

Request

{
  "action": "string|undefined",
  "payload": "number|string|array|object|null"
  // all other properties are forbidden
}

Response

{
  "payload": "number|string|array|object|null|undefined",
  "error": "string|undefined",
  "warnings": "array<string>|undefined",
  "debug": "array<string|object>|undefined" // SHOULD not be used in a production environment

  // all other properties are forbidden
  // additionally, `payload`, and `error` are mutually exclusive, and at least one must be present
}

Clients MUST handle errors and warnings.

Efficient Payload Encoding

This requires the carrier protocol to support Request and Response headers.

This spec does not describe a negotiation protocol; whether to use efficient payload encoding is an implementation detail.

When sending a large string, like a fragment of HTML, JSON-encoding it will cause it to expand in byte count by up to three times ($json \approx 3 \times plain$). To counter this, the sender MAY send the payload directly, without JSONizing it, if (and only if) there isn’t an error, and there aren’t any warnings or debug messages.

1. When sending only the payload, the sender MUST set a header to indicate that the payload is not JSONized: X-SRPC-Raw-Payload: 1.
2. The request action is moved to the X-SRPC-Action header.

Implementation

Below are some example implementations of the SRPC client and server.

Client

// this reference code assumes a few functions are set:
// display_error_to_user(string) - display an error to the user
// display_warning_to_user(string) - display a warning to the user

/**
 * @param {string} path
 * @param {string|null} action
 * @param {number|string|array|object|null} payload
 * @returns {Promise<number|string|array|object|null|undefined>} the response payload or undefined if there was an error
 */
async function srpc(path, action, payload) {
  try {
    if (
      typeof payload == "string" &&
      payload.length > 1024 &&
      action?.length < 200
    ) {
      // efficient payload encoding

      let response = await fetch(path, {
        method: "POST",
        headers: {
          Accept: "application/json, application/octet-stream",
          "Content-Type": "application/octet-stream",
          "X-SRPC-Action": action ?? "", // maybe just don't set this header if action is null
          "X-SRPC-Raw-Payload": "1",
        },
        body: payload,
        redirect: "error",
      });
    } else {
      // JSON-encoding

      let response = await fetch(path, {
        method: "POST",
        headers: {
          Accept: "application/json, application/octet-stream",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ action, payload }),
        redirect: "error",
      });
    }

    if (response.headers.get("X-SRPC-Raw-Payload") == "1") {
      return await response.text();
    }

    response = await response.json();

    if (response.error) {
      console.error(response.error);
      display_error_to_user(response.error);
      return undefined;
    }

    if (response.warnings) {
      for (let warning of response.warnings) {
        console.warn(warning);
        display_warning_to_user(warning);
      }
    }

    if (response.debug) {
      for (let debug of response.debug) {
        console.debug(debug);
      }
    }

    return response.payload;
  } catch (err) {
    display_error_to_user("An error occurred: " + err.message);
  }
}

Server

// written for Laravel, but should be portable to other frameworks

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Symfony\Component\HttpFoundation\Request;

// this class handles receiving requests from a client, not sending a request to another server
final class SrpcRequest extends Request {
  public readonly string|null $action;
  public readonly int|float|array|object|string|null $payload;

  public function __construct(...$params) {
    if (count($params) < 1) {
      parent::__construct(
        query: request()->query->all(),
        request: request()->request->all(),
        attributes: request()->attributes->all(),
        cookies: request()->cookies->all(),
        files: request()->files->all(),
        server: request()->server->all(),
        content: request()->getContent(),
      );
    } else {
      parent::__construct(...$params);
    }

    $this->action = parent::get("action", null);
    $this->payload = parent::get("payload", null);
  }

  /**
   * Validate the contents of the payload. Assumes the payload is an object.
   */
  public function validate($rules, ...$params): array {
    $newRules = [];
    foreach ($rules as $key => $rule) {
      $newRules["payload." . $key] = $rule;
    }
    return parent::validate($newRules, ...$params);
  }

  /**
   * Call Laravel's validator on the payload.
   */
  public function validatePayload(string $rules): void {
    parent::validate(["payload" => $rules]);
  }

  /**
   * Fallback: Get a value from the payload. Not recommended; use ->payload->key instead.
   */
  public function __get($key): int|float|null|array|object|string {
    return $this->get("payload." . $key, null);
  }
}

final class SrpcResponse extends Response {
  private bool $payloadOrErrorIsSet = false;
  private mixed $payload = null;
  private string|null $error = null;
  private array $warnings = [];
  private array $debug = [];

  // Recommended use in your controller:
  // return $response->withPayload("Saved successfully");
  public function withPayload(mixed $payload): self {
    if ($this->payloadOrErrorIsSet) {
      throw new \Exception("Payload or error already set");
    }

    $this->payload = $payload;
    $this->payloadOrErrorIsSet = true;
    return $this;
  }

  // Recommended use in your controller:
  // return $response->withError("Couldn't save: collision");
  public function withError(string $error): self {
    if ($this->payloadOrErrorIsSet) {
      throw new \Exception("Payload or error already set");
    }

    $this->error = $error;
    $this->payloadOrErrorIsSet = true;
    return $this;
  }

  // Recommended use in your controller:
  // $response->addWarning('Format of postal code was corrected to "A1A 1A1"');
  public function addWarning(string $warning): void {
    $this->warnings[] = $warning;
  }

  // Recommended use in your controller:
  // $response->addDebug("Your user ID is " . Auth::id());
  public function addDebug(string|object $debug): void {
    $this->debug[] = $debug;
  }

  // called by Laravel automatically
  public function prepare(Request $request): static {
    if ($this->payloadOrErrorIsSet == false) {
      throw new \Exception("Payload or error not set");
    }

    if (
      gettype($this->payload) == "string" &&
      strlen($this->payload) > 1024 &&
      empty($this->warnings) &&
      empty($this->debug)
    ) {
      $this->headers->set("X-SRPC-Raw-Payload", "1");
      $this->headers->set("Content-Type", "application/octet-stream");
      $this->setContent($this->payload);
    } else {
      $this->headers->set("Content-Type", "application/json");

      $theResponse = [];
      if ($this->error != null) {
        $theResponse["error"] = $this->error;
      } else {
        $theResponse["payload"] = $this->payload;
      }
      if (!empty($this->warnings)) {
        $theResponse["warnings"] = $this->warnings;
      }
      if (!empty($this->debug)) {
        $theResponse["debug"] = $this->debug;
      }

      $this->setContent(json_encode($theResponse));
    }

    return parent::prepare($request);
  }
}

While working on a project of mine, I needed to add functionality to parse JSON. As it turns out, it’s not very hard once you figure out how std.json wants to do it.

Q: What do you mean, “it’s not very hard”? I know std.json exists, but it’s very tedious, isn’t it? You get an iterator of “tokens” that you have to match to your preferred type, yourself, right?

A: Yes, but actually no.

You could handle the token stream yourself if you really wanted to, but if your JSON document is relatively small, you could pass it as a []u8 to std.json.parseFromSlice, or ...parseFromSliceLeaky, depending or your memory situation, like this:

const std = @import("std");

test "parseFromSliceLeaky u16" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    const allocator = arena.allocator();
    const result = try std.json.parseFromSliceLeaky(u16, allocator, "1234", .{});
    try std.testing.expect(result == 1234);
}

In fact, it even handles structs:

const std = @import("std");

const Contact = struct {
    id: u64,
    first_name: []u8,
    last_name: ?[]u8 = null,
    phone_numbers: []struct {
        type: enum { home, mobile, work },
        number: []u8,
    },
    custom_fields: std.json.ArrayHashMap([]u8),
};

test "parseFromSliceLeaky Contact" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    const allocator = arena.allocator();
    const result = try std.json.parseFromSliceLeaky(Contact, allocator,
        \\{
        \\  "id": 1234,
        \\  "first_name": "John",
        \\  "phone_numbers": [
        \\      { "type": "home", "number": "+18885550123" },
        \\      { "type": "mobile", "number": "+18885550189" }
        \\  ],
        \\  "custom_fields": {
        \\      "Hat size": "7\u00bc"
        \\  }
        \\}
    , .{});
    try std.testing.expect(result.id == 1234);
    try std.testing.expect(std.mem.eql(u8, result.first_name, "John"));
    try std.testing.expect(result.last_name == null);
    try std.testing.expect(result.phone_numbers[0].type == .home);
    try std.testing.expect(std.mem.eql(u8, result.phone_numbers[0].number, "+18885550123"));
    try std.testing.expect(result.phone_numbers[1].type == .mobile);
    try std.testing.expect(std.mem.eql(u8, result.phone_numbers[1].number, "+18885550189"));
    try std.testing.expect(std.mem.eql(u8, result.custom_fields.map.get("Hat size") orelse "", "7¼"));
}

I tried to include every type of data that you’d want to parse from a JSON document.

TIP
There are some gotchas here: Nothing has a default value out-of-the-box. Even if you define something as being optional, if the JSON document doesn’t specify a value for it, it won’t default to null; it’ll cause std.json.<whatever> to return a MissingField error.

Single endPoint JSON Communication (SPJC) is a simple application-layer message-passing protocol that uses HTTP (RFC 9110) and is intended for web2 applications. The passing of a message always begins with the client. The server is unable to send messages without being called (the client will have to poll the server).

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

1. Message from a client

A message from a client is an HTTP SPJC request, with a JSON body.

1. The request method SHOULD be SPJC (see §3 below), but MAY be POST
   1. The request method MUST NOT be anything other than SPJC or POST
2. The body MUST be JSON format
3. The request path SHOULD NOT contain any IDs
4. This request header SHOULD be sent: Content-Type: application/json
5. This request header SHOULD be sent: Cache-Control: no-cache
6. The server MUST ignore all request headers, except where impractical*, except
   1. The server MAY consider the value of the Authorization header

This document does not impose any limits to the length/size of the request, although keep in mind that servers MAY impose their own limits.

*where impractical: for example, infrastructure headers, like Host

2. Message from a server

A message from a server is an HTTP response, with a JSON body.

1. The HTTP status code SHOULD be 200
2. The HTTP status code MUST be ignored by the client, except
   1. Iff the message from the client was sent via an SPJC request, the status code 501 MAY be considered for deciding to repeat the message via a POST request
3. The body MUST be JSON format
4. This response header SHOULD be sent: Content-Type: application/json
5. This response header SHOULD be sent: Cache-Control: max-age=0, no-cache, must-revalidate, proxy-revalidate or equivalent-in-spirit
6. The body (after parsing), SHOULD be an object
   1. The object SHOULD have a success key/value
      1. The value of success SHOULD be a boolean indicating whether or not something went wrong when generating the response
   2. When success is false, the object SHOULD have a message key/value
      1. The value of message SHOULD be a string.

3. SPJC Method

SPJC is a non-standard HTTP method. See also RFC 9110 § 16.1. Method Extensibility

• SPJC method is not “safe”
• SPJC method is not “idempotent”
• Responses to SPJC method are not cachable

Example Code

Client helper function

/**
 * Send data to the server, and get its response
 *
 * @param path string
 * @param data any
 * @return object|false
 */
async function spjc(path, data) {
    try {
        let response = await fetch(path, {
            method: "SPJC",
            headers: {
                "Content-Type": "application/json",
                "Cache-Control": "no-cache",
            },
            body: JSON.stringify(data),
            redirect: "manual", // ignore redirections
        });
        let body = await response.json();
        if (typeof body != "object") return false;
        if (typeof body.success != "boolean") return false;
        if (body.success != true) return false;
        return body;
    } catch (e) {
        console.error(e);
        return false;
    }
}

• The arrow heads are easier to remember
• There aren’t redundant / badly described arrow heads
• A full entity definition isn’t required

Arrow Heads

Examples

Example 1

• Users each have exactly one language
• Languages can each have many users

user O||----| language

Example 2

• Users each have at least one email address
• Email addresses each have at most one user

user O|----|| email_address

The last time I checked, the official wiki was very broken, so my brother and I brute-forced our way through the game, and wrote this recipe book while we were at it. This page is incomplete.

Recipes tested on NodeCore release 5310 (game.conf) with a few mods:

• nc_light
• nc_stucco
• nc_ziprunes