@celilo/cli 0.14.4 → 0.16.1

package/src/services/alerting/inbound-poller.ts

@@ -20,17 +20,48 @@ import { loadCapabilityFunctions } from '../../hooks/capability-loader';
 import { createCapturingLogger } from '../../hooks/logger';
 import { type AckResult, acknowledgeAlert } from './ack';
 import { interpretInbound } from './inbound';
-import { parseInterviewAnswer } from './interview-responder';
 import type { NotificationTransport } from './notifier';
 import { composeAckBroadcastBody } from './notifier';
 import { consumeDelivery } from './tokens';
 
+/**
+ * What one attempt to read a transport produced.
+ *
+ * `unidirectional` and `failed` used to collapse into a bare null, and that
+ * cost a week: a transport whose read call was being REFUSED reported the same
+ * "0 message(s)" as a transport nobody had replied on. An operator could not
+ * tell "my reply never arrived" from "celilo cannot read this transport at
+ * all", and neither could anyone debugging it.
+ */
+export type TransportReceive =
+  | { status: 'received'; messages: InboundMessage[]; cursor: string | null }
+  | { status: 'unidirectional' }
+  | { status: 'failed'; error: string };
+
+/** A transport that could not be read, and why. */
+export interface TransportFailure {
+  transportModuleId: string;
+  error: string;
+}
+
+/** A message that was read but not acted on, and why. */
+export interface UnheardMessage {
+  senderAddress: string;
+  reason:
+    | 'unknown_sender'
+    | 'unknown_token'
+    | 'wrong_sender'
+    | 'ambiguous'
+    | 'unrecognised'
+    /** A deploy question was named, but with no value to answer it with. */
+    | 'needs_value'
+    /** The token was valid, but the alert it names no longer exists. */
+    | 'stale_target';
+}
+
 export interface InboundPollDeps {
-  /** Receive from one transport module, or null when it cannot be reached. */
-  receiveFrom(
-    transportModuleId: string,
-    cursor: string | null,
-  ): Promise<{ messages: InboundMessage[]; cursor: string | null } | null>;
+  /** Receive from one transport module. */
+  receiveFrom(transportModuleId: string, cursor: string | null): Promise<TransportReceive>;
   /** Persisted receive cursor per transport. */
   readCursor(transportModuleId: string): string | null;
   writeCursor(transportModuleId: string, cursor: string | null): void;
@@ -53,12 +84,14 @@ export interface InboundPollReport {
   transportsPolled: number;
   messagesRead: number;
   acked: number;
-  ignored: number;
-  rejected: number;
   /** Routes told that someone else took the alert. */
   broadcast: number;
   /** Deploy questions answered from a phone. */
   answered: number;
+  /** Transports that could not be read at all. Never silent — see above. */
+  failures: TransportFailure[];
+  /** Messages read and then discarded, with the reason each was discarded. */
+  unheard: UnheardMessage[];
 }
 
 /** Transports that have at least one route pointing at them. */
@@ -89,19 +122,24 @@ export async function pollInbound(db: DbClient, deps: InboundPollDeps): Promise<
     transportsPolled: 0,
     messagesRead: 0,
     acked: 0,
-    ignored: 0,
-    rejected: 0,
     broadcast: 0,
     answered: 0,
+    failures: [],
+    unheard: [],
   };
 
   for (const transportId of transportsWithRoutes(db)) {
     const received = await deps.receiveFrom(transportId, deps.readCursor(transportId));
     report.transportsPolled++;
-    // A transport that cannot be reached is not an error here — its own
-    // health check is what reports that, and one dead transport must not stop
-    // the others from being read.
-    if (!received) continue;
+    // One dead transport must not stop the others being read — but it is
+    // RECORDED rather than skipped in silence, because "cannot read" and
+    // "nothing to read" are the two things an operator most needs to tell
+    // apart at 3am.
+    if (received.status === 'failed') {
+      report.failures.push({ transportModuleId: transportId, error: received.error });
+      continue;
+    }
+    if (received.status === 'unidirectional') continue;
 
     for (const message of received.messages) {
       report.messagesRead++;
@@ -113,25 +151,26 @@ export async function pollInbound(db: DbClient, deps: InboundPollDeps): Promise<
         outstandingForRoute: (routeId) => outstandingAlertDeliveries(db, routeId, deps.now()),
       });
 
-      if (outcome.action === 'ignored') {
-        report.ignored++;
-        continue;
-      }
-      if (outcome.action === 'rejected') {
-        report.rejected++;
+      if (outcome.action === 'ignored' || outcome.action === 'rejected') {
+        report.unheard.push({ senderAddress: message.senderAddress, reason: outcome.reason });
         continue;
       }
 
       // An interview reply IS the answer rather than an acknowledgement —
       // same token table, same sender check, different meaning for the body.
-      if (outcome.delivery.kind === 'interview') {
-        const value = parseInterviewAnswer(message.body, outcome.delivery.token);
-        if (!value || !deps.answerInterview) {
-          report.rejected++;
+      // The value was extracted by `interpretInbound`, which is the only place
+      // that knows the delivery's kind; re-parsing it here is what left the
+      // real grammar unreachable for months (#533).
+      if (outcome.action === 'answer') {
+        if (!deps.answerInterview) {
+          // Nothing is attached to publish the answer against, so the question
+          // is still unanswered. Say so rather than consuming the token: the
+          // operator's next attempt has to be able to work.
+          report.unheard.push({ senderAddress: message.senderAddress, reason: 'unrecognised' });
           continue;
         }
         consumeDelivery(db, outcome.delivery.id, deps.now());
-        deps.answerInterview(outcome.delivery.targetId, value);
+        deps.answerInterview(outcome.delivery.targetId, outcome.value);
         report.answered++;
         continue;
       }
@@ -145,12 +184,23 @@ export async function pollInbound(db: DbClient, deps: InboundPollDeps): Promise<
         outcome.route.personId,
         deps.now(),
       );
+
+      // A live token can outlive the alert it names. When the row is gone
+      // there is nothing to acknowledge, and saying "1 acked" anyway is a lie
+      // the operator has no way to catch — observed live: a reply reported
+      // `1 acked` while every alert still read `ackedBy: null`. Count what
+      // HAPPENED, never what was attempted.
+      if (!ack) {
+        report.unheard.push({ senderAddress: message.senderAddress, reason: 'stale_target' });
+        continue;
+      }
+
       report.acked++;
 
       // Everyone else who was paged is still expecting to act. Telling them is
       // the entire point of a per-delivery token — it is what makes the reply
       // identify a PERSON rather than just an alert.
-      if (ack) report.broadcast += await broadcastAck(db, ack, deps);
+      report.broadcast += await broadcastAck(db, ack, deps);
     }
 
     deps.writeCursor(transportId, received.cursor);
@@ -213,12 +263,23 @@ function outstandingAlertDeliveries(db: DbClient, routeId: string, now: Date) {
  *
  * A transport with no `receive` is unidirectional — that is not an error, it
  * just means replies cannot arrive, which the route's `can_ack` already
- * records.
+ * records. Anything else going wrong IS an error and is returned as one.
+ *
+ * This used to be a bare `catch {}` returning null, on the reasoning that the
+ * transport's own health check would report an unreachable daemon. That was
+ * wrong twice over: a health check that only proves the daemon answers cannot
+ * see a read call being REFUSED by a daemon that is otherwise perfectly
+ * healthy, and the swallowed error was the only place the reason existed. The
+ * live signal-cli case was exactly that shape — `receive` refused with
+ * "Receive command cannot be used if messages are already being received."
+ * while every health check passed and every poll reported zero messages.
  */
 export function makeReceiver(db: DbClient) {
-  return async (transportModuleId: string, cursor: string | null) => {
+  return async (transportModuleId: string, cursor: string | null): Promise<TransportReceive> => {
     const module = db.select().from(modules).where(eq(modules.id, transportModuleId)).get();
-    if (!module) return null;
+    if (!module) {
+      return { status: 'failed', error: `no module '${transportModuleId}' is installed` };
+    }
 
     try {
       const { logger } = createCapturingLogger();
@@ -226,11 +287,11 @@ export function makeReceiver(db: DbClient) {
       const notification = (capabilities as Record<string, unknown>).notification as
         | NotificationCapability
         | undefined;
-      if (!notification?.receive) return null;
-      return await notification.receive(cursor);
-    } catch {
-      // Unreachable transport: the transport's own health check reports it.
-      return null;
+      if (!notification?.receive) return { status: 'unidirectional' };
+      const result = await notification.receive(cursor);
+      return { status: 'received', messages: result.messages, cursor: result.cursor };
+    } catch (error) {
+      return { status: 'failed', error: error instanceof Error ? error.message : String(error) };
     }
   };
 }

package/src/services/alerting/inbound.test.ts

@@ -33,8 +33,37 @@ describe('parseInbound', () => {
     expect(parseInbound('K7QM2X ack')).toEqual({ kind: 'ack', token: 'K7QM2X' });
   });
 
-  test.each(['', '   ', 'what is going on', 'K7QM', 'K7QM2XY'])('%p is unrecognised', (body) => {
-    expect(parseInbound(body)).toEqual({ kind: 'unrecognised' });
+  test.each(['', '   ', 'what is going on', 'K7QM2XY', 'ack now please'])(
+    '%p is unrecognised',
+    (body) => {
+      expect(parseInbound(body)).toEqual({ kind: 'unrecognised' });
+    },
+  );
+
+  // The bug that started this: the page says "reply BPRJEH", and a human types
+  // "ack BPRJEH". The old grammar read the VERB as the token, failed the length
+  // check, and rejected a real acknowledgement over word order.
+  test.each([
+    ['ack K7QM2X', 'K7QM2X'],
+    ['ACK K7QM2X', 'K7QM2X'],
+    ['ok k7qm2x', 'K7QM2X'],
+    ['K7QM2X ack', 'K7QM2X'],
+    ['k7qm2x OK', 'K7QM2X'],
+    ['👍 K7QM2X', 'K7QM2X'],
+    ['  ack   k7qm2x  ', 'K7QM2X'],
+  ])('%p yields token %p — the verb may lead, trail, or be absent', (body, token) => {
+    expect(parseInbound(body)).toEqual({ kind: 'ack', token });
+  });
+
+  // A prefix is legal INPUT; whether it identifies anything is the delivery
+  // table's question, not the parser's.
+  test.each([
+    ['bp', 'BP'],
+    ['ack bp', 'BP'],
+    ['BP ack', 'BP'],
+    ['b', 'B'],
+  ])('%p parses as the prefix %p', (body, token) => {
+    expect(parseInbound(body)).toEqual({ kind: 'ack', token });
   });
 });
 
@@ -128,6 +157,69 @@ describe('interpretInbound', () => {
     expect(interpretInbound(db, late)).toEqual({ action: 'rejected', reason: 'unknown_token' });
   });
 
+  describe('an abbreviated token', () => {
+    // How much an operator must type depends on what is actually outstanding.
+    test('resolves when the prefix is unique among live deliveries', () => {
+      const delivery = mintFor('r-peter');
+      const prefix = delivery.token.slice(0, 2);
+      const outcome = interpretInbound(db, context(PETER, `ack ${prefix.toLowerCase()}`));
+      expect(outcome).toMatchObject({ action: 'ack' });
+      expect(outcome.action === 'ack' && outcome.delivery.id).toBe(delivery.id);
+    });
+
+    test('a single character is enough when only one alert is live', () => {
+      const delivery = mintFor('r-peter');
+      // One character in 32 is `K`, which is ALSO an ack synonym — so that
+      // token parses as a bare ack rather than as a prefix. Either reading
+      // must land on the single live delivery, so the harness reflects it as
+      // outstanding as well; without this the test failed ~3% of runs with
+      // `unknown_token`, because the bare-ack path saw nothing outstanding.
+      outstanding.push(delivery);
+      const outcome = interpretInbound(db, context(PETER, delivery.token.slice(0, 1)));
+      expect(outcome).toMatchObject({ action: 'ack' });
+    });
+
+    // Never a guess: acknowledging the wrong alert is worse than asking again.
+    test('is refused as ambiguous when two live deliveries share the prefix', () => {
+      const a = mintFor('r-peter', 'alert-a');
+      let b = mintFor('r-peter', 'alert-b');
+      // Force a shared prefix rather than hoping two random tokens collide.
+      for (let i = 0; i < 40 && b.token[0] !== a.token[0]; i++) {
+        b = mintFor('r-peter', `alert-b-${i}`);
+      }
+      if (b.token[0] !== a.token[0]) return; // vanishingly unlikely; do not flake
+      // As above: a shared first character of `K` parses as a bare ack, and
+      // that path reads `outstandingForRoute` rather than the prefix search.
+      // Both readings must answer `ambiguous` here, so both are given two
+      // candidates to be ambiguous between.
+      outstanding.push(a, b);
+      expect(interpretInbound(db, context(PETER, a.token[0]))).toEqual({
+        action: 'rejected',
+        reason: 'ambiguous',
+      });
+    });
+
+    // Uniqueness is scoped to what is LIVE, so yesterday's tokens cannot make
+    // today's prefix ambiguous.
+    test('an expired delivery does not make a prefix ambiguous', () => {
+      const delivery = mintFor('r-peter');
+      const late = {
+        ...context(PETER, delivery.token.slice(0, 2)),
+        now: new Date(NOW.getTime() + TTL_MS + 1),
+      };
+      expect(interpretInbound(db, late)).toEqual({ action: 'rejected', reason: 'unknown_token' });
+    });
+
+    // The second factor still holds for a prefix.
+    test('a prefix from the WRONG sender is still refused', () => {
+      const delivery = mintFor('r-peter');
+      expect(interpretInbound(db, context(WIFE, delivery.token.slice(0, 3)))).toEqual({
+        action: 'rejected',
+        reason: 'wrong_sender',
+      });
+    });
+  });
+
   test('gibberish from a known sender is rejected as unrecognised', () => {
     expect(interpretInbound(db, context(PETER, 'what is going on'))).toEqual({
       action: 'rejected',
@@ -168,6 +260,125 @@ describe('interpretInbound', () => {
       });
     });
   });
+
+  /**
+   * Answering a deploy question.
+   *
+   * These ran against `parseInterviewAnswer` in isolation and all passed while
+   * the feature was dead in production (#533) — the alert grammar rejected
+   * every one of these bodies before the answer path was ever reached. They
+   * live here now, against `interpretInbound`, because the wiring is the part
+   * that was broken and the part worth guarding.
+   */
+  describe('a deploy question', () => {
+    const askFor = (routeId: string, targetId = 'evt-1') =>
+      mintDelivery(db, { kind: 'interview', targetId, routeId, now: NOW, ttlMs: TTL_MS });
+
+    test('takes everything after the token as the answer', () => {
+      const q = askFor('r-peter');
+      expect(interpretInbound(db, context(PETER, `${q.token} www.example.com`))).toMatchObject({
+        action: 'answer',
+        value: 'www.example.com',
+      });
+    });
+
+    test('is case-insensitive on the token', () => {
+      const q = askFor('r-peter');
+      expect(
+        interpretInbound(db, context(PETER, `${q.token.toLowerCase()} www.example.com`)),
+      ).toMatchObject({ action: 'answer', value: 'www.example.com' });
+    });
+
+    // An answer may legitimately contain spaces and punctuation. Second-guessing
+    // it would corrupt exactly the values that are painful to retype. This is
+    // the shape that was refused as `unrecognised` for months.
+    test('preserves an answer containing spaces and punctuation verbatim', () => {
+      const q = askFor('r-peter');
+      expect(
+        interpretInbound(db, context(PETER, `${q.token} my value: with, punctuation`)),
+      ).toMatchObject({ action: 'answer', value: 'my value: with, punctuation' });
+    });
+
+    // The word that must NOT acknowledge an alert is a perfectly good answer to
+    // a question. That the same text means different things is the whole reason
+    // the token is resolved before the grammar is chosen.
+    test('an answer that looks like a terminal verb is still an answer', () => {
+      const q = askFor('r-peter');
+      expect(interpretInbound(db, context(PETER, `${q.token} resolve`))).toMatchObject({
+        action: 'answer',
+        value: 'resolve',
+      });
+    });
+
+    test('a token with no value says so, rather than being unrecognised', () => {
+      const q = askFor('r-peter');
+      for (const body of [q.token, `${q.token}   `]) {
+        expect(interpretInbound(db, context(PETER, body))).toEqual({
+          action: 'rejected',
+          reason: 'needs_value',
+        });
+      }
+    });
+
+    // A verb-led message names no value, so it is not an answer.
+    test('a leading ack verb is not an answer', () => {
+      const q = askFor('r-peter');
+      expect(interpretInbound(db, context(PETER, `ack ${q.token}`))).toEqual({
+        action: 'rejected',
+        reason: 'unrecognised',
+      });
+    });
+
+    // Both factors still apply — a question is no less sensitive than a page.
+    test('an answer from the wrong number is refused', () => {
+      const q = askFor('r-peter');
+      expect(interpretInbound(db, context(WIFE, `${q.token} www.example.com`))).toEqual({
+        action: 'rejected',
+        reason: 'wrong_sender',
+      });
+    });
+
+    // Reported as `unrecognised` rather than `unknown_token`, and that is
+    // deliberate: `ZZZZZZ value` and `what is going on` are the same shape to
+    // celilo — a token-shaped word followed by text — because the token
+    // alphabet is most of the Latin one. Nothing corroborates that the leading
+    // word was meant as a token, so claiming the operator got a TOKEN wrong
+    // would send them hunting for a typo they may not have made.
+    test('an unknown leading token is not answerable', () => {
+      askFor('r-peter');
+      expect(interpretInbound(db, context(PETER, 'ZZZZZZ value'))).toEqual({
+        action: 'rejected',
+        reason: 'unrecognised',
+      });
+    });
+  });
+
+  /**
+   * The two grammars share a table, so the same body must mean different
+   * things depending on what the token names. Asserting both readings side by
+   * side is the guard against one of them quietly swallowing the other again.
+   */
+  describe('the two grammars do not bleed into each other', () => {
+    test('`<token> resolve` answers a question and REFUSES an alert', () => {
+      const question = mintDelivery(db, {
+        kind: 'interview',
+        targetId: 'evt-1',
+        routeId: 'r-peter',
+        now: NOW,
+        ttlMs: TTL_MS,
+      });
+      const alert = mintFor('r-peter');
+
+      expect(interpretInbound(db, context(PETER, `${question.token} resolve`))).toMatchObject({
+        action: 'answer',
+        value: 'resolve',
+      });
+      expect(interpretInbound(db, context(PETER, `${alert.token} resolve`))).toEqual({
+        action: 'rejected',
+        reason: 'unrecognised',
+      });
+    });
+  });
 });
 
 /**