@daugasauron/dolly-host-save 0.0.0-stage → 0.1.4-rc.2

package/README.md

@@ -1,3 +1,4 @@
-# Temporary Holding Version
+# @daugasauron/dolly-host-save
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Dolly's `download@0` host module: offer a file to save; the user clicks. Give the URL of its
+`module.json` to `boot()`'s `modules`; @daugasauron/dolly's README says how.

package/abi.mjs

@@ -0,0 +1,10 @@
+// Generated from host/download/dolly-download-0.wat, host/download/download.h, include/dolly/process.h.
+export const DOLLY_DOWNLOAD_OPEN = 1;
+export const DOLLY_DOWNLOAD_WRITE = 2;
+export const DOLLY_DOWNLOAD_CLOSE = 3;
+export const DOLLY_DOWNLOAD_ABORT = 4;
+export const DOLLY_DOWNLOAD_CHUNK_CAPACITY = 1048576;
+export const DOLLY_DOWNLOAD_MAX_SIZE = 1073741824;
+export const DOLLY_DOWNLOAD_FILE = 51;
+export const DOLLY_ERRNO = Object.freeze({ E2BIG: 1, EACCES: 2, EADDRINUSE: 3, EADDRNOTAVAIL: 4, EAFNOSUPPORT: 5, EAGAIN: 6, EALREADY: 7, EBADF: 8, EBADMSG: 9, EBUSY: 10, ECANCELED: 11, ECHILD: 12, ECONNABORTED: 13, ECONNREFUSED: 14, ECONNRESET: 15, EDEADLK: 16, EDESTADDRREQ: 17, EDOM: 18, EDQUOT: 19, EEXIST: 20, EFAULT: 21, EFBIG: 22, EHOSTUNREACH: 23, EIDRM: 24, EILSEQ: 25, EINPROGRESS: 26, EINTR: 27, EINVAL: 28, EIO: 29, EISCONN: 30, EISDIR: 31, ELOOP: 32, EMFILE: 33, EMLINK: 34, EMSGSIZE: 35, EMULTIHOP: 36, ENAMETOOLONG: 37, ENETDOWN: 38, ENETRESET: 39, ENETUNREACH: 40, ENFILE: 41, ENOBUFS: 42, ENODEV: 43, ENOENT: 44, ENOEXEC: 45, ENOLCK: 46, ENOLINK: 47, ENOMEM: 48, ENOMSG: 49, ENOPROTOOPT: 50, ENOSPC: 51, ENOSYS: 52, ENOTCONN: 53, ENOTDIR: 54, ENOTEMPTY: 55, ENOTRECOVERABLE: 56, ENOTSOCK: 57, ENOTTY: 59, ENXIO: 60, EOVERFLOW: 61, EOWNERDEAD: 62, EPERM: 63, EPIPE: 64, EPROTO: 65, EPROTONOSUPPORT: 66, EPROTOTYPE: 67, ERANGE: 68, EROFS: 69, ESPIPE: 70, ESRCH: 71, ESTALE: 72, ETIMEDOUT: 73, ETXTBSY: 74, EXDEV: 75, ENODATA: 116, ENOTSUP: 138 });
+export const DOLLY_DOWNLOAD_ABI_DIGEST = "f5c6e4ad11e3859791578d73cce40946eb3528da93dc6971c17951faac642b4f";

package/download.mjs

@@ -0,0 +1,158 @@
+import { DOLLY_ERRNO as E } from "./abi.mjs";
+import { DOLLY_DOWNLOAD_OPEN, DOLLY_DOWNLOAD_WRITE, DOLLY_DOWNLOAD_CLOSE, DOLLY_DOWNLOAD_ABORT,
+  DOLLY_DOWNLOAD_CHUNK_CAPACITY, DOLLY_DOWNLOAD_MAX_SIZE } from "./abi.mjs";
+export { DOLLY_DOWNLOAD_ABI_DIGEST as digest } from "./abi.mjs";
+
+// Offers awaiting the user's Save/Dismiss click, the open stream included; more fail with EBUSY.
+const maxPending = 4;
+const maxRetainedUrls = 4;
+// No separators, controls or bidi controls that could disguise the saved name.
+function validName(name) {
+  return typeof name === "string" && name.length > 0 && name.length <= 255 &&
+    name !== "." && name !== ".." &&
+    !/[\/\\\u0000-\u001f\u007f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u.test(name);
+}
+const sizeLabel = bytes => bytes < 1024 * 1024 ? `${Math.ceil(bytes / 1024)} KiB`
+  : `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+
+// Wasm can only ask. Each file reaches the browser's download manager through
+// one user click on its Save button, never automatically.
+export function browser({ keyboard, indicators }) {
+  const pending = new Int32Array(new SharedArrayBuffer(4));
+  const panel = document.createElement("ul");
+  panel.id = "downloads";
+  panel.className = "page-indicator";
+  panel.setAttribute("aria-label", "Files Dolly offers to save");
+  panel.hidden = true;
+  document.body.append(panel);
+  const look = document.head.appendChild(Object.assign(document.createElement("style"), { textContent: `
+    #downloads { position: fixed; left: 0.6rem; bottom: 0.6rem; z-index: 7; margin: 0; padding: 0.5rem; list-style: none;
+      max-width: calc(100vw - 1.2rem); color: #e8e3d7; background: #262626; border: 1px solid #f2d45c; font-size: 14px; }
+    #downloads[hidden] { display: none; } #downloads li + li { margin-top: 0.4rem; }
+    #downloads button { margin-right: 0.4rem; color: inherit; background: #333; border: 1px solid #77736c;
+      font: inherit; cursor: pointer; }` }));
+  const urls = [];
+  // The item of the stream the Worker is still receiving.
+  let preparing = null;
+  function revoke(url) {
+    const index = urls.indexOf(url);
+    if (index >= 0) urls.splice(index, 1);
+    URL.revokeObjectURL(url);
+  }
+  function save(name, file) {
+    const url = URL.createObjectURL(file);
+    urls.push(url);
+    if (urls.length > maxRetainedUrls) revoke(urls[0]);
+    setTimeout(() => revoke(url), 60_000);
+    const link = document.createElement("a");
+    link.href = url; link.download = name;
+    link.click();
+  }
+  // An offer waiting for the user's click holds the page's indicators shown.
+  function offer(item) {
+    panel.append(item);
+    panel.hidden = false;
+    indicators.hold("download", true);
+  }
+  function remove(item) {
+    item.remove();
+    panel.hidden = panel.childElementCount === 0;
+    indicators.hold("download", !panel.hidden);
+  }
+  return {
+    configuration: { pending: pending.buffer },
+    messages: {
+      "download-progress"({ name, size }) {
+        if (!validName(name) || !Number.isSafeInteger(size)) throw new Error("Dolly supplied an invalid download");
+        if (!preparing) {
+          preparing = document.createElement("li");
+          preparing.dataset.name = name;
+          offer(preparing);
+        }
+        preparing.textContent = `Preparing ${name} (${sizeLabel(size)})`;
+      },
+      "download-abort"() {
+        if (preparing) remove(preparing);
+        preparing = null;
+      },
+      download({ name, file }) {
+        if (!validName(name) || !(file instanceof Blob) || file.size > DOLLY_DOWNLOAD_MAX_SIZE) {
+          throw new Error("Dolly supplied an invalid download request");
+        }
+        const item = preparing ?? document.createElement("li");
+        preparing = null;
+        item.dataset.name = name;
+        const button = (label, action) => {
+          const element = document.createElement("button");
+          element.type = "button";
+          element.textContent = label;
+          element.addEventListener("click", () => {
+            action();
+            remove(item);
+            Atomics.sub(pending, 0, 1);
+            keyboard?.focus({ preventScroll: true });
+          }, { once: true });
+          return element;
+        };
+        item.replaceChildren(button(`Save ${name} (${sizeLabel(file.size)})`, () => save(name, file)),
+          button("Dismiss", () => {}));
+        offer(item);
+        document.documentElement.dataset.downloadName = name;
+      },
+    },
+    claimsKey: event => panel.contains(event.target),
+    dispose() { panel.remove(); look.remove(); for (const url of [...urls]) revoke(url); },
+  };
+}
+
+// Each chunk becomes a Blob part at once through one staging buffer (a Blob
+// copies its parts), so the Worker allocates nothing per chunk; the browser's
+// Blob storage holds the file until it is saved.
+export function worker({ send, get, configuration }) {
+  const decode = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+  const pending = new Int32Array(configuration.pending);
+  const staging = new Uint8Array(DOLLY_DOWNLOAD_CHUNK_CAPACITY);
+  let stream = null;
+  return { bindings: { "env.dolly_download_dispatch": (operation, address, length) => {
+    const memory = get("runtime").memory.buffer;
+    const [start, size] = [address, length].map(Number);
+    if (![start, size].every(Number.isSafeInteger) || start < 0 || size < 0 ||
+        start > memory.byteLength - size) return -E.EINVAL;
+    const span = new Uint8Array(memory, start, size);
+    if (operation === DOLLY_DOWNLOAD_OPEN) {
+      if (size < 1 || size > 255) return -E.EINVAL;
+      let name;
+      try { name = decode.decode(span.slice()); }
+      catch { return -E.EINVAL; }
+      if (!validName(name)) return -E.EINVAL;
+      if (stream) return -E.EBUSY;
+      if (Atomics.add(pending, 0, 1) >= maxPending) {
+        Atomics.sub(pending, 0, 1);
+        return -E.EBUSY;
+      }
+      stream = { name, parts: [], size: 0 };
+      send({ type: "download-progress", name, size: 0 });
+      return 0;
+    }
+    if (!stream) return -E.EBADF;
+    if (operation === DOLLY_DOWNLOAD_WRITE) {
+      if (size < 1 || size > DOLLY_DOWNLOAD_CHUNK_CAPACITY) return -E.EINVAL;
+      if (size > DOLLY_DOWNLOAD_MAX_SIZE - stream.size) return -E.EFBIG;
+      staging.set(span);
+      stream.parts.push(new Blob([staging.subarray(0, size)]));
+      stream.size += size;
+      send({ type: "download-progress", name: stream.name, size: stream.size });
+      return 0;
+    }
+    if (size !== 0 || ![DOLLY_DOWNLOAD_CLOSE, DOLLY_DOWNLOAD_ABORT].includes(operation)) return -E.EINVAL;
+    if (operation === DOLLY_DOWNLOAD_CLOSE) {
+      send({ type: "download", name: stream.name,
+        file: new Blob(stream.parts, { type: "application/octet-stream" }) });
+    } else {
+      Atomics.sub(pending, 0, 1);
+      send({ type: "download-abort" });
+    }
+    stream = null;
+    return 0;
+  } } };
+}

package/module.json

@@ -0,0 +1,13 @@
+{
+  "name": "download",
+  "version": 0,
+  "gives": "offer a file to save; the user clicks",
+  "dependencies": ["runtime@0"],
+  "imports": ["env.dolly_download_dispatch"],
+  "host": "download.mjs",
+  "contracts": ["dolly-download-0.wat"],
+  "process": [],
+  "headers": ["download.h", "download-abi.h"],
+  "kernel": ["kernel.c"],
+  "client": ["client.c"]
+}

package/package.json

@@ -1,6 +1,14 @@
 {
+  "version": "0.1.4-rc.2",
+  "type": "module",
   "name": "@daugasauron/dolly-host-save",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "license": "MIT",
+  "dependencies": {
+    "@daugasauron/dolly": "0.1.4-rc.2"
+  },
+  "description": "Dolly's download@0 host module: offer a file to save; the user clicks.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daugasauron/dolly.git"
+  }
+}