@streamorchard/grapevine 0.0.0-stage → 0.1.1

package/schemas/common.json

@@ -0,0 +1,40 @@
+{
+  "description": "Types every capability shares. Lists marked x-open may gain values: an app must accept a value it doesn't know.",
+  "defs": {
+    "Timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601, in UTC" },
+    "Platform": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]{1,32}$",
+      "x-open": ["kick", "twitch", "youtube"],
+      "description": "A streaming site"
+    },
+    "Channel": {
+      "type": "object",
+      "required": ["platform", "slug"],
+      "properties": {
+        "platform": { "$ref": "common:Platform" },
+        "slug": { "type": "string", "minLength": 1, "maxLength": 100, "description": "As in the channel's address" },
+        "name": { "type": "string", "maxLength": 200, "description": "As shown on the site" }
+      }
+    },
+    "Account": {
+      "type": "object",
+      "required": ["platform", "user"],
+      "description": "Who an app is signed in as: the username only, never a token or cookie",
+      "properties": {
+        "platform": { "$ref": "common:Platform" },
+        "user": { "type": "string", "minLength": 1, "maxLength": 100 }
+      }
+    },
+    "Progress": {
+      "type": "object",
+      "required": ["done", "total", "unit"],
+      "properties": {
+        "done": { "type": "number", "minimum": 0 },
+        "total": { "type": "number", "minimum": 0 },
+        "unit": { "type": "string", "x-open": ["minutes"] }
+      }
+    },
+    "Empty": { "type": "object" }
+  }
+}

package/schemas/drops.farming/1.json

@@ -0,0 +1,45 @@
+{
+  "capability": "drops.farming",
+  "major": 1,
+  "minor": 0,
+  "description": "What a drops app is farming. Provided by Pear Drops.",
+  "events": {
+    "drops.farming.changed": { "$ref": "#State" }
+  },
+  "methods": {
+    "drops.farming.get": { "params": { "$ref": "common:Empty" }, "result": { "$ref": "#State" } }
+  },
+  "defs": {
+    "State": {
+      "type": "object",
+      "required": ["seq", "at", "state", "account", "channel", "drop"],
+      "properties": {
+        "seq": { "type": "integer", "minimum": 0, "description": "Counts up with each change; 0 for a reply to drops.farming.get" },
+        "at": { "$ref": "common:Timestamp" },
+        "state": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 32,
+          "x-open": ["farming", "waiting", "paused", "done", "signed-out"],
+          "description": "farming: its player is watching a stream for drop credit. Any other value, known or not, means it isn't."
+        },
+        "account": { "anyOf": [{ "$ref": "common:Account" }, { "type": "null" }] },
+        "channel": { "anyOf": [{ "$ref": "common:Channel" }, { "type": "null" }], "description": "The stream being watched, while farming" },
+        "drop": {
+          "anyOf": [
+            {
+              "type": "object",
+              "required": ["campaign", "category", "progress"],
+              "properties": {
+                "campaign": { "type": "string", "maxLength": 200 },
+                "category": { "type": "string", "maxLength": 200 },
+                "progress": { "$ref": "common:Progress" }
+              }
+            },
+            { "type": "null" }
+          ]
+        }
+      }
+    }
+  }
+}

package/schemas/players/1.json

@@ -0,0 +1,43 @@
+{
+  "capability": "players",
+  "major": 1,
+  "minor": 0,
+  "description": "An app's stream players, by site: whether they're signed in, and which channels are open. Provided by Stream Multiview.",
+  "events": {
+    "players.changed": { "$ref": "#State" }
+  },
+  "methods": {
+    "players.get": { "params": { "$ref": "common:Empty" }, "result": { "$ref": "#State" } }
+  },
+  "defs": {
+    "State": {
+      "type": "object",
+      "required": ["seq", "at", "platforms"],
+      "properties": {
+        "seq": { "type": "integer", "minimum": 0 },
+        "at": { "$ref": "common:Timestamp" },
+        "platforms": {
+          "type": "object",
+          "description": "Keyed by Platform; a site with no players open may be left out",
+          "additionalProperties": { "$ref": "#Site" }
+        }
+      }
+    },
+    "Site": {
+      "type": "object",
+      "required": ["signedIn", "mode", "account", "open"],
+      "properties": {
+        "signedIn": { "type": "boolean", "description": "Whether the players play as the account right now" },
+        "mode": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 32,
+          "x-open": ["signed-in", "signed-out", "auto"],
+          "description": "auto: signed in, except while a connected drops app is farming"
+        },
+        "account": { "anyOf": [{ "$ref": "common:Account" }, { "type": "null" }] },
+        "open": { "type": "array", "maxItems": 100, "items": { "$ref": "common:Channel" } }
+      }
+    }
+  }
+}

package/src/connection.js

@@ -0,0 +1,316 @@
+// One connection to another app, from the hello to the end: pairing and proofs, then requests and
+// events for the capabilities both apps agreed on, a ping to notice a hung app, and a message limit.
+'use strict';
+
+const { EventEmitter } = require('events');
+const { LineReader, encode } = require('./framing');
+const { Rpc } = require('./rpc');
+const { CODES, GrapevineError } = require('./errors');
+const hs = require('./handshake');
+
+const TIMING = Object.freeze({
+  handshakeMs: 3000, // the hello and the proofs must be done by then
+  pingMs: 20_000, // the connecting app pings this often
+  pongMs: 10_000, // and closes if there's no answer in this long
+  rateMax: 50, // messages a second
+  strikes: 3, // over the limit this many times in a minute closes the connection
+});
+
+/**
+ * What a connection needs from the link that owns it.
+ * @typedef {object} Host
+ * @property {object} self this app's description (the hello's "app")
+ * @property {{provides: Record<string, string[]>, uses: Record<string, string[]>}} mine
+ * @property {{get(id: string): {key: string, pairedAt?: string} | null, set(id: string, key: string): void, delete(id: string): void}} keys
+ * @property {(id: string) => boolean} allowed whether this app's switch for that app is on
+ * @property {import('./schema').Schemas} schemas
+ * @property {(conn: Connection, method: string, params: any) => Promise<any>} call runs a capability method
+ * @property {(conn: Connection, events: string[]) => string[]} subscribe
+ * @property {(conn: Connection) => void} [afterSubscribe] sends the latest state to a new subscriber
+ * @property {(level: string, text: string) => void} log
+ * @property {typeof TIMING} timing
+ */
+
+class Connection extends EventEmitter {
+  /**
+   * @param {import('net').Socket} socket
+   * @param {Host} host
+   * @param {{initiator: boolean, expectedId?: string}} role
+   */
+  constructor(socket, host, { initiator, expectedId }) {
+    super();
+    this.socket = socket;
+    this.host = host;
+    this.initiator = initiator;
+    this.expectedId = expectedId ?? null;
+    this.state = 'hello'; // hello -> auth -> ready -> closed (the connecting app: hello -> authing -> ready)
+    this.peer = null; // the other app's description, from its hello
+    this.peerId = null;
+    this.agreed = { incoming: new Map(), outgoing: new Map(), missing: [] };
+    this.protocol = null;
+    this.subscribed = new Set(); // events the other app subscribed to
+    this.queue = []; // messages that came while finishing the proofs
+    this.rate = { windowStart: Date.now(), count: 0, strikes: [] };
+    this.lastHeard = Date.now();
+    this.closeReason = null;
+
+    this.rpc = new Rpc((m) => this.send(m), {
+      onRequest: (m) => this.onRequest(m),
+      onNotification: (m) => this.onNotification(m),
+    });
+    this.reader = new LineReader(
+      (m) => this.onMessage(m),
+      (why) => {
+        if (why === 'too-long') this.close('A message was too long');
+        else
+          this.rpc.fail(
+            null,
+            new GrapevineError(why === 'parse' ? CODES.PARSE_ERROR : CODES.INVALID_REQUEST, why === 'parse' ? 'Not JSON' : 'Not a JSON object'),
+          );
+      },
+    );
+    socket.on('data', (d) => this.reader.push(d));
+    socket.on('error', (/** @type {NodeJS.ErrnoException} */ e) => this.close(`Socket error: ${e.code ?? e.message}`));
+    socket.on('close', () => this.close('The other app closed the connection'));
+    this.handshakeTimer = setTimeout(() => this.close('The hello took too long'), host.timing.handshakeMs);
+    this.handshakeTimer.unref?.();
+  }
+
+  send(message) {
+    if (this.state !== 'closed' && !this.socket.destroyed) this.socket.write(encode(message));
+  }
+
+  // ------------------------------------------------------------------ the connecting app
+
+  /** Says hello, checks the reply's proof, proves itself, and is ready. */
+  async start() {
+    const { self, mine, keys } = this.host;
+    const stored = keys.get(this.expectedId);
+    const clientNonce = hs.nonce();
+    let res;
+    try {
+      res = await this.rpc.request(
+        'link.hello',
+        { protocol: hs.PROTOCOL, app: self, capabilities: hs.helloCapabilities(mine.provides, mine.uses), auth: { nonce: clientNonce, pair: !stored } },
+        { timeout: this.host.timing.handshakeMs },
+      );
+    } catch (err) {
+      return this.refused(err);
+    }
+    const problems = hs.checkApp(res?.app);
+    if (problems.length) return this.close(`Its hello reply isn't valid: ${problems.join('; ')}`);
+    if (this.expectedId && res.app.id !== this.expectedId) return this.close(`Expected ${this.expectedId}, but ${res.app.id} answered`);
+    if (hs.agreeProtocol(hs.PROTOCOL, { min: res.protocol, max: res.protocol }) === null)
+      return this.close(`It chose protocol ${res.protocol}, which this app doesn't speak`);
+    const key = stored?.key ?? res.auth?.key;
+    if (typeof key !== 'string' || Buffer.from(key, 'base64').length !== 32) return this.close('No pairing key');
+    if (!hs.proofOk(key, 'server', clientNonce, res.auth?.proof)) {
+      this.emit('status', { status: 'pair-again', keyHeldBy: stored ? 'us' : 'them' });
+      return this.close("Its proof was wrong: the pairing doesn't match");
+    }
+    this.peer = res.app;
+    this.peerId = res.app.id;
+    this.protocol = res.protocol;
+    this.agreed = hs.agree(mine, res.capabilities);
+    this.state = 'authing';
+    try {
+      await this.rpc.request('link.auth', { proof: hs.proof(key, 'client', res.auth.nonce) }, { timeout: this.host.timing.handshakeMs });
+    } catch (err) {
+      return this.refused(err);
+    }
+    if (!stored) keys.set(this.peerId, key);
+    this.ready();
+    for (const m of this.queue.splice(0)) this.onMessage(m);
+  }
+
+  refused(err) {
+    if (err.code === CODES.NOT_PAIRED && err.data?.reason === 'pair-again') {
+      this.emit('status', { status: 'pair-again', keyHeldBy: err.data.keyHeldBy === 'listener' ? 'them' : 'us' });
+    } else if (err.code === CODES.SWITCHED_OFF) this.emit('status', { status: 'waiting', reason: 'switched-off' });
+    else if (err.code === CODES.UNSUPPORTED) this.emit('status', { status: 'incompatible', theirProtocol: err.data?.protocol ?? null });
+    this.close(`Refused: ${err.message}`);
+  }
+
+  // ------------------------------------------------------------------ the listening app
+
+  handleHello(id, params) {
+    const problems = hs.checkHello(params);
+    if (problems.length) return this.reject(id, new GrapevineError(CODES.INVALID_PARAMS, 'Invalid hello', { problems }));
+    const protocol = hs.agreeProtocol(hs.PROTOCOL, params.protocol);
+    if (protocol === null) {
+      this.emit('status', { status: 'incompatible', peer: params.app, theirProtocol: params.protocol });
+      return this.reject(id, new GrapevineError(CODES.UNSUPPORTED, 'No protocol version in common', { protocol: hs.PROTOCOL }));
+    }
+    const peerId = params.app.id;
+    if (!this.host.allowed(peerId))
+      return this.reject(id, new GrapevineError(CODES.SWITCHED_OFF, `${this.host.self.name} isn't set to connect with ${params.app.name}`));
+    const stored = this.host.keys.get(peerId);
+    let key;
+    if (params.auth.pair) {
+      // An app asking to pair while this one still has a key: only once you press Pair again here.
+      if (stored) {
+        this.emit('status', { status: 'pair-again', peer: params.app, keyHeldBy: 'us' });
+        return this.reject(id, new GrapevineError(CODES.NOT_PAIRED, 'Already paired with a different key', { reason: 'pair-again', keyHeldBy: 'listener' }));
+      }
+      key = hs.newKey();
+    } else {
+      if (!stored) {
+        this.emit('status', { status: 'pair-again', peer: params.app, keyHeldBy: 'them' });
+        return this.reject(id, new GrapevineError(CODES.NOT_PAIRED, 'Not paired', { reason: 'pair-again', keyHeldBy: 'connector' }));
+      }
+      key = stored.key;
+    }
+    const serverNonce = hs.nonce();
+    this.pending = { key, serverNonce, pairing: !!params.auth.pair };
+    this.peer = params.app;
+    this.peerId = peerId;
+    this.protocol = protocol;
+    this.agreed = hs.agree(this.host.mine, params.capabilities);
+    this.state = 'auth';
+    const agreed = {};
+    for (const [cap, v] of [...this.agreed.incoming, ...this.agreed.outgoing]) agreed[cap] = String(v.major);
+    this.rpc.reply(id, {
+      protocol,
+      app: this.host.self,
+      capabilities: hs.helloCapabilities(this.host.mine.provides, this.host.mine.uses),
+      agreed,
+      auth: { proof: hs.proof(key, 'server', params.auth.nonce), nonce: serverNonce, ...(this.pending.pairing ? { key } : {}) },
+    });
+  }
+
+  handleAuth(id, params) {
+    const { key, serverNonce, pairing } = this.pending;
+    if (!hs.proofOk(key, 'client', serverNonce, params.proof)) {
+      this.emit('status', { status: 'pair-again', peer: this.peer, keyHeldBy: 'them' });
+      return this.reject(id, new GrapevineError(CODES.NOT_PAIRED, 'Wrong proof', { reason: 'pair-again', keyHeldBy: 'connector' }));
+    }
+    if (pairing) this.host.keys.set(this.peerId, key);
+    this.pending = null;
+    this.rpc.reply(id, {});
+    this.ready();
+  }
+
+  /** Refuses a request, then closes. */
+  reject(id, err) {
+    this.rpc.fail(id, err);
+    this.close(err.message);
+  }
+
+  // ------------------------------------------------------------------ ready
+
+  ready() {
+    clearTimeout(this.handshakeTimer);
+    this.state = 'ready';
+    this.host.log('info', `Connected to ${this.peer.name} ${this.peer.version}`);
+    if (this.initiator) {
+      this.pingTimer = setInterval(() => {
+        this.rpc.request('link.ping', {}, { timeout: this.host.timing.pongMs }).catch((err) => {
+          if (err.code === CODES.TIMEOUT) this.close('The other app stopped answering');
+        });
+      }, this.host.timing.pingMs);
+    } else {
+      // The listening app hears a ping at least every pingMs; three missed means it's hung.
+      this.pingTimer = setInterval(() => {
+        if (Date.now() - this.lastHeard > this.host.timing.pingMs * 3) this.close('The other app stopped answering');
+      }, this.host.timing.pingMs);
+    }
+    this.pingTimer.unref?.();
+    this.emit('ready');
+    // Every event of every capability this app uses from the other one.
+    const events = [];
+    for (const [cap, { major }] of this.agreed.incoming) events.push(...Object.keys(this.host.schemas.get(cap, major)?.events ?? {}));
+    if (events.length) {
+      this.rpc.request('link.subscribe', { events }).catch((err) => this.host.log('warn', `Couldn't subscribe to ${this.peer?.name}: ${err.message}`));
+    }
+  }
+
+  // ------------------------------------------------------------------ incoming
+
+  onMessage(m) {
+    this.lastHeard = Date.now();
+    if (this.state === 'authing' && !('result' in m || 'error' in m)) return void this.queue.push(m);
+    if (!this.withinRate(m)) return;
+    this.rpc.handle(m);
+  }
+
+  /** At most rateMax messages a second; going over it three times in a minute closes the connection. */
+  withinRate(m) {
+    const now = Date.now();
+    const r = this.rate;
+    if (now - r.windowStart >= 1000) {
+      r.windowStart = now;
+      r.count = 0;
+    }
+    r.count += 1;
+    if (r.count <= this.host.timing.rateMax) return true;
+    if (r.count === this.host.timing.rateMax + 1) {
+      r.strikes = r.strikes.filter((t) => now - t < 60_000).concat(now);
+      if (r.strikes.length >= this.host.timing.strikes) {
+        this.close('Too many messages');
+        return false;
+      }
+    }
+    if ('id' in m && typeof m.method === 'string') this.rpc.fail(m.id, new GrapevineError(CODES.TOO_MANY, 'Too many messages: slow down'));
+    return false;
+  }
+
+  async onRequest({ id, method, params }) {
+    if (this.state === 'hello' && !this.initiator && method === 'link.hello') return this.handleHello(id, params);
+    if (this.state === 'auth' && method === 'link.auth') return this.handleAuth(id, params);
+    if (this.state !== 'ready') return this.rpc.fail(id, new GrapevineError(CODES.NOT_PAIRED, 'Say hello and prove the pairing first'));
+    if (method === 'link.ping') return this.rpc.reply(id, {});
+    if (method === 'link.subscribe') {
+      const subscribed = this.host.subscribe(this, Array.isArray(params.events) ? params.events.filter((e) => typeof e === 'string') : []);
+      this.rpc.reply(id, { subscribed });
+      return this.host.afterSubscribe?.(this);
+    }
+    if (method === 'link.unpair') {
+      this.host.keys.delete(this.peerId);
+      this.rpc.reply(id, {});
+      this.emit('unpaired');
+      return this.close('Disconnected in the other app');
+    }
+    try {
+      this.rpc.reply(id, await this.host.call(this, method, params));
+    } catch (err) {
+      this.rpc.fail(id, err instanceof GrapevineError ? err : new GrapevineError(CODES.INTERNAL_ERROR, 'The app failed to answer'));
+      if (!(err instanceof GrapevineError)) this.host.log('error', `${method} failed: ${err?.message ?? err}`);
+    }
+  }
+
+  onNotification({ method, params }) {
+    if (method === 'link.bye') return this.close(`The other app said goodbye${params.reason ? ` (${params.reason})` : ''}`);
+    if (this.state !== 'ready') return;
+    const cap = this.host.schemas.capabilityOf(method);
+    const agreed = cap && this.agreed.incoming.get(cap);
+    if (!agreed) return this.host.log('warn', `Ignored ${method}: not agreed with ${this.peer.name}`);
+    const problems = this.host.schemas.validate(cap, agreed.major, 'event', method, params);
+    if (problems.length) return this.host.log('warn', `Dropped an invalid ${method} from ${this.peer.name}: ${problems.join('; ')}`);
+    this.emit('event', method, params);
+  }
+
+  // ------------------------------------------------------------------ the end
+
+  /** Says goodbye (a reason the other app can show) and closes. */
+  bye(reason) {
+    this.rpc.notify('link.bye', { reason });
+    this.close(reason);
+  }
+
+  close(reason) {
+    if (this.state === 'closed') return;
+    const wasReady = this.state === 'ready';
+    this.state = 'closed';
+    this.closeReason = reason;
+    clearTimeout(this.handshakeTimer);
+    clearInterval(this.pingTimer);
+    this.rpc.close();
+    // end() lets a last reply (why it was refused) reach the other app; destroy() if it doesn't finish.
+    this.socket.end();
+    setTimeout(() => this.socket.destroy(), 500).unref?.();
+    if (wasReady) this.host.log('info', `Disconnected from ${this.peer?.name}: ${reason}`);
+    this.emit('close', reason, wasReady);
+  }
+}
+
+module.exports = { Connection, TIMING };

package/src/errors.js

@@ -0,0 +1,39 @@
+// JSON-RPC 2.0's error codes, and the ones Grapevine adds (PROTOCOL.md, "Errors").
+'use strict';
+
+const CODES = Object.freeze({
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  NOT_PAIRED: -32001, // not paired yet, or the proof was wrong
+  NOT_AGREED: -32002, // the capability wasn't agreed on this connection
+  UNSUPPORTED: -32003, // no version both apps support
+  TOO_MANY: -32004, // too many messages
+  SWITCHED_OFF: -32005, // the app's switch for the other app is off
+  CLOSED: -32099, // the connection closed before the reply came (local only, never sent)
+  TIMEOUT: -32098, // no reply in time (local only, never sent)
+});
+
+/** An error with a JSON-RPC code, thrown by request() and by handlers that want a specific code. */
+class GrapevineError extends Error {
+  /**
+   * @param {number} code
+   * @param {string} message
+   * @param {unknown} [data]
+   */
+  constructor(code, message, data) {
+    super(message);
+    this.name = 'GrapevineError';
+    this.code = code;
+    this.data = data;
+  }
+
+  /** The `error` member of a JSON-RPC reply. */
+  toJSON() {
+    return this.data === undefined ? { code: this.code, message: this.message } : { code: this.code, message: this.message, data: this.data };
+  }
+}
+
+module.exports = { CODES, GrapevineError };

package/src/framing.js

@@ -0,0 +1,65 @@
+// A socket carries bytes, not messages: each message is one line of JSON ending in "\n".
+'use strict';
+
+const { StringDecoder } = require('string_decoder');
+
+const MAX_LINE = 1024 * 1024; // bytes; a longer line closes the connection
+
+/** Turns a message into its line. */
+function encode(message) {
+  return `${JSON.stringify(message)}\n`;
+}
+
+/**
+ * Collects bytes into lines and parses each one. `onMessage(object)` gets every JSON object,
+ * `onBad(reason)` anything else: 'parse' (not JSON), 'not-object' (an array, number, …) or
+ * 'too-long' (over the limit, after which the reader stops).
+ */
+class LineReader {
+  /**
+   * @param {(message: Record<string, unknown>) => void} onMessage
+   * @param {(reason: 'parse' | 'not-object' | 'too-long') => void} onBad
+   * @param {number} [max]
+   */
+  constructor(onMessage, onBad, max = MAX_LINE) {
+    this.onMessage = onMessage;
+    this.onBad = onBad;
+    this.max = max;
+    this.buffer = '';
+    this.done = false;
+    this.decoder = new StringDecoder('utf8'); // a character split across two chunks stays whole
+  }
+
+  /** @param {Buffer | string} chunk */
+  push(chunk) {
+    if (this.done) return;
+    this.buffer += typeof chunk === 'string' ? chunk : this.decoder.write(chunk);
+    for (let at = this.buffer.indexOf('\n'); at !== -1; at = this.buffer.indexOf('\n')) {
+      const line = this.buffer.slice(0, at);
+      this.buffer = this.buffer.slice(at + 1);
+      if (Buffer.byteLength(line) > this.max) return this.stop();
+      if (line.trim()) this.parse(line);
+      if (this.done) return;
+    }
+    if (Buffer.byteLength(this.buffer) > this.max) this.stop();
+  }
+
+  parse(line) {
+    let value;
+    try {
+      value = JSON.parse(line);
+    } catch {
+      return this.onBad('parse');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return this.onBad('not-object');
+    this.onMessage(value);
+  }
+
+  stop() {
+    this.done = true;
+    this.buffer = '';
+    this.onBad('too-long');
+  }
+}
+
+module.exports = { MAX_LINE, encode, LineReader };