@johnhenry/wsh 0.7.0 → 0.14.0

package/src/session.mjs

@@ -44,6 +44,23 @@ export class WshSession {
   /** @type {string[]} Advertised session capabilities. */
   #capabilities = [];
 
+  /**
+   * The server-assigned session_id this channel belongs to, from OPEN_OK
+   * (clawser #48). `undefined` for channel kinds with no Attach/Resume-able
+   * session (e.g. file channels).
+   * @type {string|undefined}
+   */
+  #sessionId;
+
+  /**
+   * The session-scoped HMAC token minted by the server at Open time
+   * (clawser #48), also from OPEN_OK. Pass it to `WshClient.resumeSession`
+   * (or optionally `attachSession`) from a later connection to reclaim
+   * this exact session. `undefined` alongside `#sessionId`.
+   * @type {Uint8Array|undefined}
+   */
+  #resumeToken;
+
   /**
    * Stream IDs returned by the server in OPEN_OK.
    * Typically { stdin: number, stdout: number } or a single bidirectional ID.
@@ -131,6 +148,16 @@ export class WshSession {
   /** @type {object|null} */
   #lastTermDiff = null;
 
+  /**
+   * Queue of received FileChunk payloads not yet consumed by
+   * _readFileChunk(). 'file'-kind sessions only.
+   * @type {Array<object>}
+   */
+  #fileChunkQueue = [];
+
+  /** @type {{resolve: function, reject: function}|null} */
+  #fileChunkWaiter = null;
+
   // ── Constructor ─────────────────────────────────────────────────────
 
   /**
@@ -141,8 +168,13 @@ export class WshSession {
    * @param {object} [opts]
    * @param {'stream'|'virtual'} [opts.dataMode='stream']
    * @param {string[]} [opts.capabilities=[]]
+   * @param {string} [opts.sessionId] - Server session_id from OPEN_OK (clawser #48; pty/exec only)
+   * @param {Uint8Array} [opts.resumeToken] - Session-scoped resume token from OPEN_OK (clawser #48)
    */
-  constructor(transport, channelId, streamIds, kind, { dataMode = 'stream', capabilities = [] } = {}) {
+  constructor(
+    transport, channelId, streamIds, kind,
+    { dataMode = 'stream', capabilities = [], sessionId, resumeToken } = {}
+  ) {
     this.#transport = transport;
     this.channelId = channelId;
     this.#streamIds = streamIds;
@@ -150,6 +182,28 @@ export class WshSession {
     this.id = String(channelId);
     this.#dataMode = dataMode === 'virtual' ? 'virtual' : 'stream';
     this.#capabilities = Array.isArray(capabilities) ? [...capabilities] : [];
+    this.#sessionId = sessionId;
+    this.#resumeToken = resumeToken;
+  }
+
+  /**
+   * The server-assigned session_id this channel belongs to, if any
+   * (clawser #48; `undefined` for channel kinds with no Attach/Resume-able
+   * session, e.g. file channels). Pass to `WshClient.attachSession`/
+   * `resumeSession` from another connection.
+   */
+  get sessionId() {
+    return this.#sessionId;
+  }
+
+  /**
+   * The session-scoped resume token minted at Open time, if any (clawser
+   * #48). Pass it to `WshClient.resumeSession` from a later connection to
+   * reclaim this exact session, proving you're the same credentialed
+   * opener rather than merely an authorized principal.
+   */
+  get resumeToken() {
+    return this.#resumeToken;
   }
 
   /** Current session state. */
@@ -358,6 +412,7 @@ export class WshSession {
 
     this.#stdinWriter = null;
     this.#stdoutReadable = null;
+    this.#resolvePendingFileChunk(null);
     this.#emitClose();
   }
 
@@ -382,6 +437,17 @@ export class WshSession {
         break;
       }
 
+      case MSG.FILE_CHUNK: {
+        if (this.#fileChunkWaiter) {
+          const { resolve } = this.#fileChunkWaiter;
+          this.#fileChunkWaiter = null;
+          resolve(msg);
+        } else {
+          this.#fileChunkQueue.push(msg);
+        }
+        break;
+      }
+
       case MSG.EXIT: {
         this.#exitCode = msg.code ?? -1;
         try {
@@ -399,6 +465,7 @@ export class WshSession {
           this.#abort.abort();
           this.#virtualBackend?.close();
           this.#releaseStreams();
+          this.#resolvePendingFileChunk(null);
           this.#emitClose();
         }
         break;
@@ -469,6 +536,45 @@ export class WshSession {
     }
   }
 
+  // ── File transfer ────────────────────────────────────────────────────
+
+  /**
+   * Wait for the next FileChunk control message on this channel.
+   * Used by WshClient.upload/download for 'file'-kind sessions — file
+   * transfer moves bytes as ordinary FileChunk control messages rather
+   * than through write()/read(), so it works the same whether the
+   * channel's data plane is stream- or virtual-backed.
+   *
+   * Returns `null` if the session closes before another chunk arrives
+   * (a truncated transfer, distinct from a chunk with is_final=true).
+   *
+   * @returns {Promise<object|null>}
+   * @internal
+   */
+  async _readFileChunk() {
+    if (this.#fileChunkQueue.length > 0) {
+      return this.#fileChunkQueue.shift();
+    }
+    if (this.#state === STATE_CLOSED) {
+      return null;
+    }
+    return new Promise((resolve, reject) => {
+      this.#fileChunkWaiter = { resolve, reject };
+    });
+  }
+
+  /**
+   * Resolve (or clear) any pending _readFileChunk() waiter.
+   * @private
+   */
+  #resolvePendingFileChunk(value) {
+    if (this.#fileChunkWaiter) {
+      const { resolve } = this.#fileChunkWaiter;
+      this.#fileChunkWaiter = null;
+      resolve(value);
+    }
+  }
+
   // ── Data stream pump ────────────────────────────────────────────────
 
   /**