@agoric/swing-store 0.9.2-dev-bf1e645.0 → 0.9.2-dev-07f6885.0

package/src/transcriptStore.js

@@ -15,10 +15,10 @@ import { createSHA256 } from './hasher.js';
  *
  * @typedef {{
  *   initTranscript: (vatID: string) => void,
- *   rolloverSpan: (vatID: string) => number,
- *   rolloverIncarnation: (vatID: string) => number,
+ *   rolloverSpan: (vatID: string) => Promise<number>,
+ *   rolloverIncarnation: (vatID: string) => Promise<number>,
  *   getCurrentSpanBounds: (vatID: string) => { startPos: number, endPos: number, hash: string, incarnation: number },
- *   stopUsingTranscript: (vatID: string) => void,
+ *   stopUsingTranscript: (vatID: string) => Promise<void>,
  *   deleteVatTranscripts: (vatID: string, budget?: number) => { done: boolean, cleanups: number },
  *   addItem: (vatID: string, item: string) => void,
  *   readSpan: (vatID: string, startPos?: number) => IterableIterator<string>,
@@ -61,14 +61,15 @@ function insistTranscriptPosition(position) {
  * @param {() => void} ensureTxn
  * @param {(key: string, value: string | undefined ) => void} noteExport
  * @param {object} [options]
- * @param {boolean | undefined} [options.keepTranscripts]
+ * @param {boolean} [options.keepTranscripts]
+ * @param {(spanName: string, entries: ReturnType<exportSpan>) => Promise<void>} [options.archiveTranscript]
  * @returns { TranscriptStore & TranscriptStoreInternal & TranscriptStoreDebug }
  */
 export function makeTranscriptStore(
   db,
   ensureTxn,
   noteExport = () => {},
-  { keepTranscripts = true } = {},
+  { keepTranscripts = true, archiveTranscript } = {},
 ) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS transcriptItems (
@@ -219,10 +220,12 @@ export function makeTranscriptStore(
    */
   function initTranscript(vatID) {
     ensureTxn();
-    const initialIncarnation = 0;
-    sqlWriteSpan.run(vatID, 0, 0, initialHash, 1, initialIncarnation);
-    const newRec = spanRec(vatID, 0, 0, initialHash, true, 0);
-    noteExport(spanMetadataKey(newRec), JSON.stringify(newRec));
+    const pos = 0;
+    const isCurrent = 1;
+    const incarnation = 0;
+    sqlWriteSpan.run(vatID, pos, pos, initialHash, isCurrent, incarnation);
+    const rec = spanRec(vatID, pos, pos, initialHash, isCurrent, incarnation);
+    noteExport(spanMetadataKey(rec), JSON.stringify(rec));
   }
 
   const sqlGetCurrentSpanBounds = db.prepare(`
@@ -244,6 +247,102 @@ export function makeTranscriptStore(
     return bounds;
   }
 
+  const sqlGetSpanEndPos = db.prepare(`
+    SELECT endPos
+    FROM transcriptSpans
+    WHERE vatID = ? AND startPos = ?
+  `);
+  sqlGetSpanEndPos.pluck(true);
+
+  const sqlReadSpanItems = db.prepare(`
+    SELECT item
+    FROM transcriptItems
+    WHERE vatID = ? AND ? <= position AND position < ?
+    ORDER BY position
+  `);
+
+  /**
+   * Read the items in a transcript span
+   *
+   * @param {string} vatID  The vat whose transcript is being read
+   * @param {number} [startPos] A start position identifying the span to be
+   *    read; defaults to the current span, whatever it is
+   *
+   * @returns {IterableIterator<string>}  An iterator over the items in the indicated span
+   */
+  function readSpan(vatID, startPos) {
+    /** @type {number | undefined} */
+    let endPos;
+    if (startPos === undefined) {
+      ({ startPos, endPos } = getCurrentSpanBounds(vatID));
+    } else {
+      insistTranscriptPosition(startPos);
+      endPos = sqlGetSpanEndPos.get(vatID, startPos);
+      if (typeof endPos !== 'number') {
+        throw Fail`no transcript span for ${q(vatID)} at ${q(startPos)}`;
+      }
+    }
+    startPos <= endPos || Fail`${q(startPos)} <= ${q(endPos)}}`;
+    const expectedCount = endPos - startPos;
+
+    function* reader() {
+      let count = 0;
+      for (const { item } of sqlReadSpanItems.iterate(
+        vatID,
+        startPos,
+        endPos,
+      )) {
+        yield item;
+        count += 1;
+      }
+      count === expectedCount ||
+        Fail`read ${q(count)} transcript entries (expected ${q(
+          expectedCount,
+        )})`;
+    }
+    harden(reader);
+
+    if (startPos === endPos) {
+      return empty();
+    }
+
+    return reader();
+  }
+
+  const sqlGetSpanIsCurrent = db.prepare(`
+    SELECT isCurrent
+    FROM transcriptSpans
+    WHERE vatID = ? AND startPos = ?
+  `);
+  sqlGetSpanIsCurrent.pluck(true);
+
+  /**
+   * Read a transcript span and return it as a stream of data suitable for
+   * export to another store.  Transcript items are terminated by newlines.
+   *
+   * Transcript span artifact names should be strings of the form:
+   *   `transcript.${vatID}.${startPos}.${endPos}`
+   *
+   * @param {string} name  The name of the transcript artifact to be read
+   * @returns {AsyncIterableIterator<Uint8Array>}
+   * @yields {Uint8Array}
+   */
+  async function* exportSpan(name) {
+    typeof name === 'string' || Fail`artifact name must be a string`;
+    const parts = name.split('.');
+    const [type, vatID, pos] = parts;
+    // prettier-ignore
+    (parts.length === 4 && type === 'transcript') ||
+      Fail`expected artifact name of the form 'transcript.{vatID}.{startPos}.{endPos}', saw ${q(name)}`;
+    const isCurrent = sqlGetSpanIsCurrent.get(vatID, pos);
+    isCurrent !== undefined || Fail`transcript span ${q(name)} not available`;
+    const startPos = Number(pos);
+    for (const entry of readSpan(vatID, startPos)) {
+      yield Buffer.from(`${entry}\n`);
+    }
+  }
+  harden(exportSpan);
+
   const sqlEndCurrentSpan = db.prepare(`
     UPDATE transcriptSpans
     SET isCurrent = null
@@ -255,32 +354,33 @@ export function makeTranscriptStore(
     WHERE vatID = ? AND position >= ? AND position < ?
   `);
 
-  function doSpanRollover(vatID, isNewIncarnation) {
+  /**
+   * Finalize a span, setting isCurrent to null, marking the resulting record
+   * for export, and effecting disk archival and database cleanup as
+   * configured.
+   * Note that creation of a new DB row and removal/replacement of the
+   * transcript.${vatID}.current export record are responsibility of the caller.
+   *
+   * @param {string} vatID
+   * @param {ReturnType<getCurrentSpanBounds>} bounds
+   */
+  async function closeSpan(vatID, bounds) {
     ensureTxn();
-    const { hash, startPos, endPos, incarnation } = getCurrentSpanBounds(vatID);
+    const { startPos, endPos, hash, incarnation } = bounds;
     const rec = spanRec(vatID, startPos, endPos, hash, false, incarnation);
 
-    // add a new record for the now-old span
+    // add a new export record for the now-old span
     noteExport(spanMetadataKey(rec), JSON.stringify(rec));
 
-    // and change its DB row to isCurrent=0
+    // and change its DB row to isCurrent=null
     sqlEndCurrentSpan.run(vatID);
 
-    // create a new (empty) row, with isCurrent=1
-    const incarnationToUse = isNewIncarnation ? incarnation + 1 : incarnation;
-    sqlWriteSpan.run(vatID, endPos, endPos, initialHash, 1, incarnationToUse);
-
-    // overwrite the transcript.${vatID}.current record with new span
-    const newRec = spanRec(
-      vatID,
-      endPos,
-      endPos,
-      initialHash,
-      true,
-      incarnationToUse,
-    );
-    noteExport(spanMetadataKey(newRec), JSON.stringify(newRec));
-
+    await null;
+    if (archiveTranscript) {
+      const spanName = spanArtifactName(rec);
+      const entries = exportSpan(spanName);
+      await archiveTranscript(spanName, entries);
+    }
     if (!keepTranscripts) {
       // Delete items of the previously-current span.
       // There may still be items associated with even older spans, but we leave
@@ -290,7 +390,32 @@ export function makeTranscriptStore(
       // that doesn't include them.
       sqlDeleteOldItems.run(vatID, startPos, endPos);
     }
-    return incarnationToUse;
+  }
+
+  async function doSpanRollover(vatID, isNewIncarnation) {
+    ensureTxn();
+    const bounds = getCurrentSpanBounds(vatID);
+    const { endPos, incarnation } = bounds;
+
+    // deal with the now-old span
+    await closeSpan(vatID, bounds);
+
+    // create a new (empty) DB row, with isCurrent=1
+    const newSpanIncarnation = isNewIncarnation ? incarnation + 1 : incarnation;
+    sqlWriteSpan.run(vatID, endPos, endPos, initialHash, 1, newSpanIncarnation);
+
+    // overwrite the transcript.${vatID}.current record with new span
+    const rec = spanRec(
+      vatID,
+      endPos,
+      endPos,
+      initialHash,
+      true,
+      newSpanIncarnation,
+    );
+    noteExport(spanMetadataKey(rec), JSON.stringify(rec));
+
+    return newSpanIncarnation;
   }
 
   /**
@@ -300,9 +425,9 @@ export function makeTranscriptStore(
    * @param {string} vatID  The vat whose transcript is to rollover to a new
    *    span.
    *
-   * @returns {number} the new incarnation number
+   * @returns {Promise<number>} the new incarnation number
    */
-  function rolloverIncarnation(vatID) {
+  async function rolloverIncarnation(vatID) {
     return doSpanRollover(vatID, true);
   }
 
@@ -313,9 +438,9 @@ export function makeTranscriptStore(
    * @param {string} vatID  The vat whose transcript is to rollover to a new
    *    span.
    *
-   * @returns {number} the incarnation number
+   * @returns {Promise<number>} the incarnation number
    */
-  function rolloverSpan(vatID) {
+  async function rolloverSpan(vatID) {
     return doSpanRollover(vatID, false);
   }
 
@@ -360,28 +485,21 @@ export function makeTranscriptStore(
   `);
 
   /**
-   * Prepare for vat deletion by marking the isCurrent span as not
-   * current. Idempotent.
+   * Prepare for vat deletion by marking the isCurrent=1 span as not current.
+   * Idempotent.
    *
    * @param {string} vatID  The vat being terminated/deleted.
    */
-  function stopUsingTranscript(vatID) {
+  async function stopUsingTranscript(vatID) {
     ensureTxn();
-    // this transforms the current span into a (short) historical one
-    // (basically doSpanRollover without adding replacement data)
     const bounds = sqlGetCurrentSpanBounds.get(vatID);
-    if (bounds) {
-      // add a new record for the now-old span
-      const { startPos, endPos, hash, incarnation } = bounds;
-      const rec = spanRec(vatID, startPos, endPos, hash, false, incarnation);
-      noteExport(spanMetadataKey(rec), JSON.stringify(rec));
+    if (!bounds) return;
 
-      // and change its DB row to isCurrent=0
-      sqlEndCurrentSpan.run(vatID);
+    // deal with the now-old span
+    await closeSpan(vatID, bounds);
 
-      // remove the transcript.${vatID}.current record
-      noteExport(spanMetadataKey({ vatID, isCurrent: true }), undefined);
-    }
+    // remove the transcript.${vatID}.current record
+    noteExport(spanMetadataKey({ vatID, isCurrent: true }), undefined);
   }
 
   /**
@@ -542,7 +660,7 @@ export function makeTranscriptStore(
         }
       }
     } else if (artifactMode === 'archival') {
-      // every span for all vatIDs that have an isCurrent span (to
+      // every span for all vatIDs that have an isCurrent=1 span (to
       // ignore terminated/partially-deleted vats)
       const vatIDs = new Set();
       for (const { vatID } of sqlGetCurrentSpanMetadata.iterate()) {
@@ -569,102 +687,6 @@ export function makeTranscriptStore(
   }
   harden(getArtifactNames);
 
-  const sqlGetSpanEndPos = db.prepare(`
-    SELECT endPos
-    FROM transcriptSpans
-    WHERE vatID = ? AND startPos = ?
-  `);
-  sqlGetSpanEndPos.pluck(true);
-
-  const sqlReadSpanItems = db.prepare(`
-    SELECT item
-    FROM transcriptItems
-    WHERE vatID = ? AND ? <= position AND position < ?
-    ORDER BY position
-  `);
-
-  /**
-   * Read the items in a transcript span
-   *
-   * @param {string} vatID  The vat whose transcript is being read
-   * @param {number} [startPos] A start position identifying the span to be
-   *    read; defaults to the current span, whatever it is
-   *
-   * @returns {IterableIterator<string>}  An iterator over the items in the indicated span
-   */
-  function readSpan(vatID, startPos) {
-    /** @type {number | undefined} */
-    let endPos;
-    if (startPos === undefined) {
-      ({ startPos, endPos } = getCurrentSpanBounds(vatID));
-    } else {
-      insistTranscriptPosition(startPos);
-      endPos = sqlGetSpanEndPos.get(vatID, startPos);
-      if (typeof endPos !== 'number') {
-        throw Fail`no transcript span for ${q(vatID)} at ${q(startPos)}`;
-      }
-    }
-    startPos <= endPos || Fail`${q(startPos)} <= ${q(endPos)}}`;
-    const expectedCount = endPos - startPos;
-
-    function* reader() {
-      let count = 0;
-      for (const { item } of sqlReadSpanItems.iterate(
-        vatID,
-        startPos,
-        endPos,
-      )) {
-        yield item;
-        count += 1;
-      }
-      count === expectedCount ||
-        Fail`read ${q(count)} transcript entries (expected ${q(
-          expectedCount,
-        )})`;
-    }
-    harden(reader);
-
-    if (startPos === endPos) {
-      return empty();
-    }
-
-    return reader();
-  }
-
-  const sqlGetSpanIsCurrent = db.prepare(`
-    SELECT isCurrent
-    FROM transcriptSpans
-    WHERE vatID = ? AND startPos = ?
-  `);
-  sqlGetSpanIsCurrent.pluck(true);
-
-  /**
-   * Read a transcript span and return it as a stream of data suitable for
-   * export to another store.  Transcript items are terminated by newlines.
-   *
-   * Transcript span artifact names should be strings of the form:
-   *   `transcript.${vatID}.${startPos}.${endPos}`
-   *
-   * @param {string} name  The name of the transcript artifact to be read
-   * @returns {AsyncIterableIterator<Uint8Array>}
-   * @yields {Uint8Array}
-   */
-  async function* exportSpan(name) {
-    typeof name === 'string' || Fail`artifact name must be a string`;
-    const parts = name.split('.');
-    const [type, vatID, pos] = parts;
-    // prettier-ignore
-    (parts.length === 4 && type === 'transcript') ||
-      Fail`expected artifact name of the form 'transcript.{vatID}.{startPos}.{endPos}', saw ${q(name)}`;
-    const isCurrent = sqlGetSpanIsCurrent.get(vatID, pos);
-    isCurrent !== undefined || Fail`transcript span ${q(name)} not available`;
-    const startPos = Number(pos);
-    for (const entry of readSpan(vatID, startPos)) {
-      yield Buffer.from(`${entry}\n`);
-    }
-  }
-  harden(exportSpan);
-
   const sqlAddItem = db.prepare(`
     INSERT INTO transcriptItems (vatID, item, position, incarnation)
     VALUES (?, ?, ?, ?)