@streamorchard/grapevine 0.6.0 → 0.7.1

package/PROTOCOL.md

@@ -32,7 +32,7 @@ Every app has a **slug** (`a-z`, `0-9` and `-`, up to 40 characters, starting wi
 - A socket left by a crash answers nothing (`ECONNREFUSED`): its app deletes it and listens again when it starts. If something does answer, another copy of the app is running, and the new copy doesn't start its link.
 - An app only listens, and only looks for others, while at least one of its Connected apps switches is on.
 
-**Who connects.** Of two apps, the one whose slug sorts first (plain string order) connects; the other waits for it. So a pair never opens two connections. If they ever do, both keep the connection opened by the app whose slug sorts first and close the other with `link.bye { reason: "duplicate" }`. It's the slug, not the id, because an app's id can change (see [Renaming an app](#renaming-an-app)) and its socket's name doesn't.
+**Who connects.** Of two apps, the one whose slug sorts first (plain string order) connects; the other waits for it, so a pair normally opens one connection. An app may still connect the other way to check the link on its user's request (a Test button). If they ever do have two, both keep the connection opened by the app whose slug sorts first and close the other with `link.bye { reason: "duplicate" }`. It's the slug, not the id, because an app's id can change (see [Renaming an app](#renaming-an-app)) and its socket's name doesn't.
 
 ## Messages
 

package/README.md

@@ -131,8 +131,15 @@ Editors suggest every event's fields and underline mistakes, in plain JavaScript
 | `formerIds`                           | Ids the app had before a rename                                                                              |
 | `shares`                              | What the two apps share: `{ out, in }`, capabilities this app provides that it uses, and the other way round |
 
-Two calls go with buttons on the card:
-
+Three calls go with buttons on the card:
+
+- **Test:** `await link.test(appId)`. Connected, it's a round trip, `{ ok: true, ms, version, text }`, with `text` like "Stream Multiview 0.4.0 answered in 3 ms". Otherwise it tries straight away, from this side too, and says why it couldn't: `{ ok: false, reason, text }`. `reason` is one of:
+  - `not-running`: "Stream Multiview isn't open"
+  - `switched-off`: its Connect switch is off
+  - `off`: this app's is
+  - `pair-again`: with where to press it
+  - `incompatible`: which app to update
+  - `no-answer`, `not-started`, `unknown`
 - **Disconnect:** `link.disconnect(appId)`. Turn your own switch for that app off too.
 - **Pair again:** `link.pairAgain(appId)`.
 
@@ -190,12 +197,20 @@ When it ships a release that uses Grapevine, record it (next section).
 
 Once an app ships a capability version, Grapevine records it. From then on that version can't change in place, and other apps can say which release to update to.
 
-In the app's repo, at the start of every change:
+Give the app a script for it, in its `package.json`:
+
+```json
+"scripts": { "grapevine:check": "grapevine-check" }
+```
+
+Then, in the app's repo, at the start of every change:
 
 ```sh
-npx grapevine-check
+npm run grapevine:check
 ```
 
+Use the script, not `npx grapevine-check`: in a checkout where Grapevine isn't installed yet, `npx` would fetch and run whatever package on npm has that name. `npm run` only uses what's installed.
+
 - **It reads** the `grapevine` field from each of the app's release tags (`v*`), and Grapevine's record from GitHub (the installed copy if it's offline, or with `--offline`).
 - **It lists** any capability version a release shipped that isn't recorded yet, with the command to record it, e.g. `npm run released -- com.streamorchard.peardrops 0.1.6 drops.farming@1.0 players@1.0`.
 - **That command runs in a Grapevine checkout** (its `app-shipped` skill), followed by a pull request and a patch release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamorchard/grapevine",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Lets desktop apps on the same computer find each other and talk, privately: local sockets, JSON-RPC, pairing and versioned capabilities.",
   "license": "GPL-3.0-only",
   "author": "StreamOrchard",

package/scripts/check-shipped.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-// Run in an app's repo (npx grapevine-check): lists the capability versions the app's releases
+// Run in an app's repo, through a script ("grapevine:check": "grapevine-check"; never npx, which
+// would fetch a package of that name when Grapevine isn't installed): lists the capability versions the app's releases
 // have shipped that Grapevine hasn't recorded yet, with the command that records them (Grapevine's
 // app-shipped skill). Until they're recorded, those versions can still be changed in place, and
 // other apps can't say which release to update to.
@@ -7,9 +8,9 @@
 // The app says what it speaks in its package.json, so every release tag has it:
 //   "grapevine": { "app": "com.streamorchard.peardrops", "provides": { "drops.farming": "1.0" }, "uses": { "players": "1.0" } }
 //
-//   npx grapevine-check            prints what needs recording (exit 0)
-//   npx grapevine-check --strict   exits 1 when something does
-//   npx grapevine-check --offline  uses the record in the installed package, not GitHub's
+//   npm run grapevine:check                prints what needs recording (exit 0)
+//   npm run grapevine:check -- --strict    exits 1 when something does
+//   npm run grapevine:check -- --offline   uses the record in the installed package, not GitHub's
 'use strict';
 
 const fs = require('fs');

package/src/index.js

@@ -418,6 +418,59 @@ class Link extends EventEmitter {
     this.changed();
   }
 
+  /**
+   * Test on a card: checks the link to that app now, and says how it went in words. Connected, a
+   * round trip and back; otherwise it tries straight away (from this side too, whichever app
+   * normally connects) and says why it couldn't.
+   * @returns {Promise<{ok: true, ms: number, version: string, text: string} | {ok: false, reason: string, text: string}>}
+   *   reason: 'unknown' | 'off' | 'not-started' | 'not-running' | 'switched-off' | 'pair-again' | 'incompatible' | 'no-answer'
+   */
+  async test(appId, { timeout = 4000 } = {}) {
+    const id = this.currentId(appId);
+    const app = this.knownApps.find((a) => a.id === id);
+    if (!app) return { ok: false, reason: 'unknown', text: `${appId} isn't an app Grapevine knows` };
+    if (!this.allowedAny(this.idsOf(id))) return { ok: false, reason: 'off', text: `Switched off here: switch on Connect with ${app.name} first` };
+    if (!this.running) return { ok: false, reason: 'not-started', text: `${this.self.name} isn't listening for other apps yet` };
+    if (!this.conns.has(id)) {
+      if (!paths.listSlugs(this.place).includes(app.slug)) return { ok: false, reason: 'not-running', text: `${app.name} isn't open` };
+      this.retry.delete(id);
+      this.why.delete(id);
+      const trying = () => [...this.opening].some((c) => (c.expectedId ?? c.peerId) === id);
+      if (!trying()) this.connect(app);
+      await new Promise((resolve) => {
+        const done = () => {
+          clearTimeout(timer);
+          this.off('change', check);
+          resolve();
+        };
+        const check = () => (this.conns.has(id) || this.why.has(id) || !trying()) && done();
+        const timer = setTimeout(done, timeout);
+        this.on('change', check);
+        check();
+      });
+    }
+    const conn = this.conns.get(id);
+    if (!conn) {
+      const why = this.why.get(id);
+      if (why?.status === 'pair-again') {
+        return { ok: false, reason: 'pair-again', text: `The pairing doesn't match: press Pair again ${why.keyHeldBy === 'them' ? `in ${app.name}` : 'here'}` };
+      }
+      if (why?.status === 'incompatible') {
+        return { ok: false, reason: 'incompatible', text: incompatible(this.self, why.theirApp ?? app, hs.PROTOCOL, why.theirProtocol ?? hs.PROTOCOL).text };
+      }
+      if (why?.reason === 'switched-off') return { ok: false, reason: 'switched-off', text: `${app.name} is open, but its Connect switch is off` };
+      return { ok: false, reason: 'no-answer', text: `${app.name} is open, but didn't answer` };
+    }
+    const started = performance.now();
+    try {
+      await conn.rpc.request('link.ping', {}, { timeout });
+    } catch {
+      return { ok: false, reason: 'no-answer', text: `${app.name} didn't answer` };
+    }
+    const ms = Math.max(1, Math.round(performance.now() - started));
+    return { ok: true, ms, version: conn.peer.version, text: `${app.name} ${conn.peer.version} answered in ${ms} ms` };
+  }
+
   isConnected(appId) {
     return this.conns.has(this.currentId(appId));
   }

package/types/index.d.ts

@@ -128,6 +128,15 @@ export interface Peer {
   keysEncrypted: boolean;
 }
 
+export type TestResult =
+  | { ok: true; ms: number; version: string; text: string }
+  | {
+      ok: false;
+      reason: 'unknown' | 'off' | 'not-started' | 'not-running' | 'switched-off' | 'pair-again' | 'incompatible' | 'no-answer';
+      /** In words, for the card: "Stream Multiview isn't open" */
+      text: string;
+    };
+
 export interface CallContext {
   appId: string;
   app: AppInfo;
@@ -156,6 +165,8 @@ export declare class Link extends EventEmitter {
   /** Pair again on a card: forgets this app's old key. */
   pairAgain(appId: string): void;
   isConnected(appId: string): boolean;
+  /** Test on a card: checks the link now, and says how it went. Tries straight away when not connected. */
+  test(appId: string, opts?: { timeout?: number }): Promise<TestResult>;
   /** Its current id, given any id it has had: for moving your own settings across after another app is renamed. */
   currentId(appId: string): string;
   /** Every known app, for the Connected apps page. */