@agoric/xsnap

xsnap

Xsnap is a utility for taking resumable snapshots of a running JavaScript worker, using Moddable’s XS JavaScript engine.

Xsnap provides a Node.js API for controlling Xsnap workers.

const worker = await xsnap();
await worker.evaluate(`
  // Incrementer, running on XS.
  function handleCommand(message) {
    const number = parseInt(new TextDecoder().decode(message), 10);
    return new TextEncoder().encode(`${number + 1}`).buffer;
  }
`);
await fs.writeFile('bootstrap.xss', worker.makeSnapshotStream());
await worker.close();

Some time later, possibly on a different computer…

const decoder = new TextDecoder();
const worker = await xsnap({
  snapshotStream: fs.createFileStream('bootstrap.xss'),
});
const response = await worker.issueCommand('1');
console.log(decoder.decode(response)); // 2
await worker.close();

The parent and child communicate using "commands".

• The XS child uses the synchronous issueCommand function to send a request and receive as response from the Node.js parent.
• The XS child can implement a synchronous handleCommand function to respond to commands from the Node.js parent.
  • The XS child handleCommand may be asynchronous after a fashion: it may return an object and, before the promise queue becomes empty, set the result property of this object to an ArrayBuffer. See the evaluate and report test for an example.
• The Node.js parent uses an asynchronous issueCommand method to send a request and receive a response from the XS child.
• The Node.js parent can implement an asynchronous handleCommand function to respond to commands from the XS child.