@streamorchard/grapevine 0.6.0 → 0.7.0

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)`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamorchard/grapevine",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "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/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. */