<!-- SPDX-FileCopyrightText: 2023 the cable.js authors SPDX-License-Identifier: CC0-1.0 -->

cable.js

status: alpha (subject to changes)

This library contains everything needed to generate all posts and message types of the Cable protocol.

Reponsibilities:

• Encoding and decoding binary payloads corresponding to all cable posts and messages
  • each post and message type can be encoded to binary with create(<required fields>) and decoded with toJSON(buf)
• Validating the requirements of each post and message type, adhering to cable specification's defined values (see ./validation.js)
• Encapsulates all cryptography needed for interacting with cable (see ./cryptography.js) peers
• Encapsulates all constants needed for interacting with cable (see ./constants.js)

Non-responsibilities:

• Does not take care of storage, indexing or any kind of persistence functions (see cable-core.js)
• Does not provide any client specific functions (the upcoming cable-client.js library will take care of that)
• Does not handle networking (up and coming for cable-core.js)

Usage

const cable = require("cable")
// each class is exported and all of its methods are static, so you can alias the
// class name to save a bit of typing
const POST_REQUEST = cable.POST_REQUEST
const TEXT_POST = cable.TEXT_POST

Create a binary payload

To create a binary payload, call the .create() method of the corresponding post or message type you want with the parameters required by that type. The result will be a b4a-produced buffer meaning it will be a:

• nodejs Buffer when running in node
• a Uint8Array when running in the browser

Request-type messages

const buf = POST_REQUEST.create(reqid, ttl, hashes)
const buf = CANCEL_REQUEST.create(reqid, ttl, cancelid)
const buf = TIME_RANGE_REQUEST.create(reqid, ttl, channel, timeStart, timeEnd, limit)
const buf = CHANNEL_STATE_REQUEST.create(reqid, ttl, channel, future)
const buf = CHANNEL_LIST_REQUEST.create(reqid, ttl, argOffset, limit)
const buf = MODERATION_STATE_REQUEST.create(reqid, ttl, channels, future, oldest)

Response-type messages

const buf = HASH_RESPONSE.create(reqid, hashes)
const buf = POST_RESPONSE.create(reqid, posts)
const buf = CHANNEL_LIST_RESPONSE.create(reqid, channels)

Post types

const buf = TEXT_POST.create(publicKey, secretKey, links, channel, timestamp, text)
const buf = DELETE_POST.create(publicKey, secretKey, links, timestamp, hashes)
const buf = INFO_POST.create(publicKey, secretKey, links, timestamp, key, value)
const buf = TOPIC_POST.create(publicKey, secretKey, links, channel, timestamp, topic)
const buf = JOIN_POST.create(publicKey, secretKey, links, channel, timestamp)
const buf = LEAVE_POST.create(publicKey, secretKey, links, channel, timestamp)
const buf = ROLE_POST.create(publicKey, secretKey, links, channel, timestamp, recipient, role, reason, privacy)
const buf = MODERATION_POST.create(publicKey, secretKey, links, channel, timestamp, recipients, action, reason, privacy)
const buf = BLOCK_POST.create(publicKey, secretKey, links, timestamp, recipients, drop, notify, reason, privacy)
const buf = UNBLOCK_POST.create(publicKey, secretKey, links, timestamp, recipients, undrop, reason, privacy)

Decode a binary payload into a JSON object

All decoding works the same way, regardless of the message type or post type. The method .toJSON(buf) takes as its single argument the binary buffer to decode, and returns a JSON object.

For the fields of each produced object, see section Examples below.

Request-type messages

const obj = POST_REQUEST.toJSON(buf)
const obj = CANCEL_REQUEST.toJSON(buf)
const obj = TIME_RANGE_REQUEST.toJSON(buf)
const obj = CHANNEL_STATE_REQUEST.toJSON(buf)
const obj = CHANNEL_LIST_REQUEST.toJSON(buf)
const obj = MODERATION_STATE_REQUEST.toJSON(buf)

Response-type messages

const obj = HASH_RESPONSE.toJSON(buf)
const obj = POST_RESPONSE.toJSON(buf)
const obj = CHANNEL_LIST_RESPONSE.toJSON(buf)

Post types

const obj = TEXT_POST.toJSON(buf)
const obj = DELETE_POST.toJSON(buf)
const obj = INFO_POST.toJSON(buf)
const obj = TOPIC_POST.toJSON(buf)
const obj = JOIN_POST.toJSON(buf)
const obj = LEAVE_POST.toJSON(buf)
const obj = ROLE_POST.toJSON(buf)
const obj = MODERATION_POST.toJSON(buf)
const obj = BLOCK_POST.toJSON(buf)
const obj = UNBLOCK_POST.toJSON(buf)

Examples

The following example shows each post type, request type, and response type alongside the parameters (see initial-parameters) necessary for generating them. You can generate this output yourself by running node complete-examples.js

How to understand the example:

Each json object (not including initial-parameters) describes a particular post or message cable is capable of generating.

• Fields name and type of each object describes the post/message type.
• Field id is the canonical numerical description corresponding to what msg_type (requests/responses) or post_type (posts) is being presented. See the cable spec for the full listing of types.
• Field binary is the hex-encoded binary representation of the full post/message.
• Field obj is the json representation produced by this repository's library when parsing the corresponding binary representation.
• Field posthash is the hex-encoded hash produced when hashing the entire post/message with Blake2b. That is, it's the Blake2b hash of the contents represented by field binary.

{
  "name": "initial-parameters",
  "type": "generated-data",
  "id": -1,
  "binary": null,
  "obj": {
    "keypair": {
      "publicKey": "25b272a71555322d40efe449a7f99af8fd364b92d350f1664481b2da340a02d0",
      "secretKey": "f12a0b72a720f9ce6898a1f4c685bee4cc838102143db98f467c5512a726e69225b272a71555322d40efe449a7f99af8fd364b92d350f1664481b2da340a02d0"
    },
    "hashes": [
      "20265674e8aac2dfddd78f86fe5a3dd68d976ca3f5ba23645ec7381480921d0d",
      "10705340e5528f2ef03a6797b72b1bb9f37f9009ad408247387c4bcc4d2a3371",
      "af700793dd51d4cb3c18a6df46f88bfe1665fba9b277487ddecd1e031441d69d"
    ],
    "reqid": "95050429",
    "cancelid": "58b041b1",
    "links": [
      "5049d089a650aa896cb25ec35258653be4df196b4a5e5b6db7ed024aaa89e1b3"
    ],
    "ttl": 1,
    "limit": 20,
    "timestamp": 80,
    "timeStart": 0,
    "timeEnd": 100,
    "future": 0,
    "channels": [
      "default",
      "dev",
      "introduction"
    ],
    "channel": "default",
    "username": "cabler",
    "offset": 0,
    "text": "h€llo world",
    "topic": "introduce yourself to the friendly crowd of likeminded folx",
    "oldest": 40,
    "recipients": [
      "a6bac4f48e10f3e036e3915a583977b900e048304f7527b6bf299356219d1e91",
      "2abcc76c670e32d37fd4233a6ea60fd39a3b246c4ac4bfd43a74639360ff7688",
      "89d1baf8b98a135e7a9ab7720dbd809e234a61054187ed8bc1022c44e45010d6"
    ],
    "recipient": "a6bac4f48e10f3e036e3915a583977b900e048304f7527b6bf299356219d1e91",
    "action": 0,
    "role": 0,
    "reason": "the reason is entirely mine own",
    "privacy": 0,
    "drop": 0,
    "undrop": 1,
    "notify": 1
  },
  "posthash": null
}
{
  "name": "post request",
  "type": "request",
  "id": 2,
  "binary": "6b020000000095050429010320265674e8aac2dfddd78f86fe5a3dd68d976ca3f5ba23645ec7381480921d0d10705340e5528f2ef03a6797b72b1bb9f37f9009ad408247387c4bcc4d2a3371af700793dd51d4cb3c18a6df46f88bfe1665fba9b277487ddecd1e031441d69d",
  "obj": {
    "msgLen": 107,
    "msgType": 2,
    "reqid": "95050429",
    "ttl": 1,
    "hashes": [
      "20265674e8aac2dfddd78f86fe5a3dd68d976ca3f5ba23645ec7381480921d0d",
      "10705340e5528f2ef03a6797b72b1bb9f37f9009ad408247387c4bcc4d2a3371",
      "af700793dd51d4cb3c18a6df46f88bfe1665fba9b277487ddecd1e031441d69d"
    ]
  },
  "posthash": "000ec3d4c9c9fbc5522ba54fb7ebe97781d222869003ced25e8617e2e373d620"
}
{
  "name": "cancel request",
  "type": "request",
  "id": 3,
  "binary": "0e0300000000950504290158b041b1",
  "obj": {
    "msgLen": 14,
    "msgType": 3,
    "reqid": "95050429",
    "ttl": 1,
    "cancelid": "58b041b1"
  },
  "posthash": "6730710ddb5defadc7ff4a16cfc02a0ada947eb2a50c3c8c277a122f37b8e72a"
}
{
  "name": "channel time range request",
  "type": "request",
  "id": 4,
  "binary": "15040000000095050429010764656661756c74006414",
  "obj": {
    "msgLen": 21,
    "msgType": 4,
    "reqid": "95050429",
    "ttl": 1,
    "channel": "default",
    "timeStart": 0,
    "timeEnd": 100,
    "limit": 20
  },
  "posthash": "b20a8aef8b489fec5fcd84ef0f48c8ed7a9c45673f1e6307150f50accdd74330"
}
{
  "name": "channel state request",
  "type": "request",
  "id": 5,
  "binary": "13050000000095050429010764656661756c7400",
  "obj": {
    "msgLen": 19,
    "msgType": 5,
    "reqid": "95050429",
    "ttl": 1,
    "channel": "default",
    "future": 0
  },
  "posthash": "b54fb8c60c642d49d9072ab750cebb7525550abd3f1a51b36bbb095c5b8977db"
}
{
  "name": "channel list request",
  "type": "request",
  "id": 6,
  "binary": "0c060000000095050429010014",
  "obj": {
    "msgLen": 12,
    "msgType": 6,
    "reqid": "95050429",
    "ttl": 1,
    "offset": 0,
    "limit": 20
  },
  "posthash": "f0878f4a7dff80ce1936212b773c305128df0c3d0e1dae1b17f83d03771cd9e2"
}
{
  "name": "moderation state request",
  "type": "request",
  "id": 8,
  "binary": "26080000000095050429010764656661756c74036465760c696e74726f64756374696f6e000028",
  "obj": {
    "msgLen": 38,
    "msgType": 8,
    "reqid": "95050429",
    "ttl": 1,
    "channels": [
      "default",
      "dev",
      "introduction"
    ],
    "futu