cable-core.js

Status: alpha (api surface still in flux)

The core library powering a cable peer.
This specific implementation is written in node.js, we anticipate cable implementations in other
languages to follow. (Interested? See cable's spec)

Responsibilities:

* Provides a clean api for interacting with cable peers
* Maintains database indexes for all of cable's facets
* Handles deletes, including updating all affected indexes
* Keeps track of message causality using cable's links concept
* Provides methods for creating all of cable's post types
* Capable of receiving and generating responses to all of cable's request & response messages

Non-responsibilities:

* Does not handle serializing & deserializing cable's binary buffers (cable.js does that)
* Does not fully take care of all concerns required for a client application (cable-client.js services that)
* Networking primitives (up & coming)

Example

This slightly longer example shows how to setup an end-to-end response-request cycle between
two different cable instances. What it lacks in brevity it hopefully makes up for in terms of
elucidation.

For the nitty gritty details, read the tests.

``js
/ NOTE: require "cable.js" and not just "cable" (the latter is a completely unrelated module!!) /

const crypto = require("cable.js/cryptography.js")
const cable = require("cable.js/index.js")
const { humanizeMessageType } = require("cable-core/util.js")
const kp = crypto.generateKeypair()
const CableCore = require("cable-core/index.js").CableCore
const requester = new CableCore({kp})
const responder = new CableCore()

const ttl = 0
const channel = "introduction"
const text = "Hello hello."
const start = +(new Date("2023-03-01"))
const end = 0
const limit = 1500

/ phase 1: hook up requester and responder to each other (we're basically simulating a two way network connection :)/
// each request should reach and be handled by the responder
requester.on("request", reqBuf => {
console.log(requester: emitted ${humanizeMessageType(cable.peekMessage(reqBuf))}, reqBuf)
console.log(cable.parseMessage(reqBuf))
console.log()
// responder receives the request and reacts to it
responder.handleRequest(reqBuf)
})

// each response should reach and be handled by the requester
responder.on("response", resBuf => {
console.log(responder: emitted ${humanizeMessageType(cable.peekMessage(resBuf))}, resBuf)
console.log(cable.parseMessage(resBuf))
console.log()
// requester receives the response and reacts to it
requester.handleResponse(resBuf)
})

/ phase 2: let's kick this show off! /
// responder makes a post that requester will end up with eventually
responder.postText(channel, text, () => {
// regarding this callback: we want to start the request & responses after
// we're certain that the post/text has finished indexing for responder!

// requester initiates a request
const buf = requester.requestPosts(channel, start, end, ttl, limit)
// in this example, we don't do anything with buf bc we have hooked things up already above.
// just showing off that it's possible to use it :)

// we wait a little bit for the back and forth of the request and response cycle to be resolved :)
//
// the timeout is necessary because it's a standalone example. without it the process
// would be closed before we get to see anything, due to the asynchronous action going on.
// in a long-lived application, we would never need to set a timeout like this

setTimeout(() => {
console.log("now: get some chat messages!")
requester.getChat(channel, start, end, limit, (err, chat) => {
if (err) console.log("error", err)
chat.forEach(msg => {
console.log("get chat:", msg)
})
})
}, 50)
})
``

License

agpl-3.0-or-later