path: root/packages/meshbay-hub/src/meshbay_hub/static/downloads.js

/**
 * Where downloads go.
 *
 * A web page cannot be told a path. It cannot read "~/Downloads", cannot write
 * to it, and cannot be configured with "C:\Users\…" either — which is also why
 * none of this needs to change when someone runs it on Windows. What a browser
 * grants is a *handle* to a directory the user picked, once, in a dialog. That
 * handle is what this module keeps.
 *
 * Two modes, and the default matters:
 *
 *   auto (default) — write into the granted folder without asking. Downloading
 *     twelve files puts twelve files there. Without a granted folder, the file
 *     goes wherever the browser puts downloads, which on most machines is the
 *     same folder anyway.
 *   ask — a Save As dialog for every file, which is the right answer for one
 *     file and the wrong one for twelve.
 *
 * Firefox and Safari have no File System Access API at all: no folder can be
 * granted there, and both modes fall back to the browser's own download folder.
 * The setting says so rather than offering a choice that does nothing.
 */

const PREF_KEY = 'mb_dl_mode';
const IDB_NAME = 'meshbay-downloads';
const IDB_STORE = 'handles';
const HANDLE_KEY = 'target-dir';

export const SUPPORTED = typeof window !== 'undefined'
  && typeof window.showDirectoryPicker === 'function';

export function getMode() {
  const v = localStorage.getItem(PREF_KEY);
  return v === 'ask' ? 'ask' : 'auto';
}

export function setMode(mode) {
  localStorage.setItem(PREF_KEY, mode === 'ask' ? 'ask' : 'auto');
}

// ── The granted directory ────────────────────────────────────────────────────

function idb() {
  return new Promise((resolve, reject) => {
    const req = indexedDB.open(IDB_NAME, 1);
    req.onupgradeneeded = () => {
      if (!req.result.objectStoreNames.contains(IDB_STORE)) {
        req.result.createObjectStore(IDB_STORE);
      }
    };
    req.onsuccess = () => resolve(req.result);
    req.onerror = () => reject(req.error);
  });
}

async function idbGet(key) {
  try {
    const db = await idb();
    const tx = db.transaction(IDB_STORE, 'readonly');
    const req = tx.objectStore(IDB_STORE).get(key);
    const out = await new Promise((r, j) => {
      req.onsuccess = () => r(req.result); req.onerror = () => j(req.error);
    });
    db.close();
    return out || null;
  } catch { return null; }
}

async function idbPut(key, value) {
  try {
    const db = await idb();
    const tx = db.transaction(IDB_STORE, 'readwrite');
    if (value === null) tx.objectStore(IDB_STORE).delete(key);
    else tx.objectStore(IDB_STORE).put(value, key);
    await new Promise((r, j) => { tx.oncomplete = r; tx.onerror = j; });
    db.close();
  } catch { /* best effort: the setting simply will not stick */ }
}

/** The folder handle, if one was ever granted. Says nothing about permission. */
export async function savedDirectory() {
  return SUPPORTED ? idbGet(HANDLE_KEY) : null;
}

/** Ask for a folder. Must be called from a click — browsers require a gesture. */
export async function chooseDirectory() {
  const handle = await window.showDirectoryPicker({ mode: 'readwrite' });
  await idbPut(HANDLE_KEY, handle);
  return handle;
}

export async function forgetDirectory() {
  await idbPut(HANDLE_KEY, null);
}

/**
 * Permission survives a reload as a *claim*, not as a grant: the handle comes
 * back from IndexedDB in state "prompt" and has to be re-authorized once per
 * session. Doing that quietly during a download click is why this takes no
 * arguments and returns a boolean instead of throwing.
 */
export async function ensurePermission(handle, { prompt = true } = {}) {
  if (!handle) return false;
  try {
    const opts = { mode: 'readwrite' };
    if (await handle.queryPermission(opts) === 'granted') return true;
    if (!prompt) return false;
    return await handle.requestPermission(opts) === 'granted';
  } catch {
    return false;
  }
}

// ── Names ────────────────────────────────────────────────────────────────────

/**
 * A name not already taken, as "clip (2).mp4".
 *
 * Writing into a folder repeatedly is the whole point of the automatic mode, so
 * the second copy of a file must not silently replace the first. `exists` is
 * passed in so this can be tested without a filesystem.
 */
export async function freeName(name, exists) {
  if (!await exists(name)) return name;
  const dot = name.lastIndexOf('.');
  const stem = dot > 0 ? name.slice(0, dot) : name;
  const ext = dot > 0 ? name.slice(dot) : '';
  for (let n = 2; n < 1000; n++) {
    const candidate = `${stem} (${n})${ext}`;
    if (!await exists(candidate)) return candidate;
  }
  return `${stem} (${Date.now()})${ext}`;
}

/**
 * Where this download should be written, if a folder has been granted.
 *
 * Returns `{writable, name, open}` or null. Null does not mean failure: it
 * means there is no granted folder, and the caller decides between handing the
 * browser a blob and asking for a Save As.
 */
export async function openTarget(filename) {
  if (!SUPPORTED || getMode() === 'ask') return null;

  const dir = await savedDirectory();
  if (!dir || !await ensurePermission(dir)) return null;

  const exists = async (name) => {
    try {
      await dir.getFileHandle(name);
      return true;
    } catch {
      return false;
    }
  };
  const name = await freeName(filename, exists);
  const handle = await dir.getFileHandle(name, { create: true });
  const writable = await handle.createWritable();
  return {
    // `abort()` on a FileSystemWritableFileStream discards the swap file and
    // leaves the target as it was — which here is the empty file
    // `getFileHandle({create: true})` just made, before a single byte arrived.
    // So every cancelled or failed download left a 0-byte file behind, and
    // because `freeName` avoids collisions, three cancels left `film.mkv`,
    // `film (2).mkv` and `film (3).mkv`, all empty, in the person's folder.
    //
    // Removing it is safe *here and only here*: `freeName` guarantees this name
    // was not taken, so the file being deleted is one we created moments ago
    // and nothing else. The `showSaveFilePicker` path in file-utils.js must not
    // do the same — there the person may have picked an existing file, whose
    // contents `abort()` correctly preserves.
    writable: {
      write: (bytes) => writable.write(bytes),
      close: () => writable.close(),
      abort: async (reason) => {
        try { await writable.abort(reason); } catch { /* already gone */ }
        try { await dir.removeEntry(name); } catch { /* already gone */ }
      },
    },
    name,
    // Reading it back is the only way a page can "open" a file it wrote: hand
    // the bytes to a tab and let the browser decide what to do with them. No
    // web page can start a desktop application, or show a file manager.
    open: async () => {
      const file = await handle.getFile();
      const url = URL.createObjectURL(file);
      window.open(url, '_blank', 'noopener');
      setTimeout(() => URL.revokeObjectURL(url), 60000);
    },
  };
}

/**
 * Below this, a download with no granted folder and no service worker is
 * collected in memory and handed to the browser. Above it that would mean
 * holding gigabytes in a tab, so it is worth one Save As dialog instead.
 */
export const BLOB_LIMIT = 512 * 1024 * 1024;

// ── Streaming to disk without the File System Access API ────────────────────

const SW_PATH = '/sw.js';

// On Firefox and Safari this worker is not a nicety, it is the only unbounded
// way to write a download to disk: the File System Access API does not exist
// there, and OPFS is capped at 10% of the volume's size (measured on Firefox
// 154: 389,233,459 bytes on a 3,892,334,592-byte volume, refused to the byte),
// which a film can exceed. Everything below exists to make sure this path is
// available when it is needed, because there is nothing underneath it.
//
// How long to wait for this page to become *controlled*. Generous on purpose:
// the cost of waiting is a spinner, and the cost of giving up is a download
// this browser then cannot do at all.
const SW_CONTROL_BUDGET_MS = 15000;
// How long to wait for the worker to confirm it answered the iframe.
const SW_SERVED_BUDGET_MS = 15000;
// A transient miss gets a second go with a fresh id and a fresh iframe.
const SW_ATTEMPTS = 2;
// How often the page pokes the worker while a download is being written.
// Firefox terminates a service worker that has had no event for roughly thirty
// seconds, and a streaming response does not count as activity — so a download
// that takes longer than that lost its reader half way through. Ten seconds
// leaves a wide margin and costs one empty message.
const SW_KEEPALIVE_MS = 10000;
// And the ping stops on its own once nothing has been written for this long.
// Well past any real gap between chunks, and short enough that an abandoned
// target does not ping for ever. Bounded because the alternative is a timer
// whose lifetime depends on every caller remembering to close its sink.
const SW_KEEPALIVE_IDLE_MS = 120000;

// Holds a *successful* controller, or an in-flight attempt. Never a failure —
// see serviceWorker(). The previous version cached the rejected/null result
// for the life of the page, so one slow first click (a cold worker, a busy
// phone) left the tab unable to stream anything ever again, with no way back
// but a reload nobody knew to do.
let _swPromise = null;
let _lastFailure = '';

/** Why the streamed path last declined, for a message worth reading. */
export function lastStreamFailure() { return _lastFailure; }

export const STREAMS_VIA_SW = typeof window !== 'undefined'
  && 'serviceWorker' in navigator
  && typeof TransformStream === 'function'
  && window.isSecureContext;

/** Resolves with the controller, or null once `budgetMs` is spent. */
function _awaitControl(budgetMs) {
  if (navigator.serviceWorker.controller) {
    return Promise.resolve(navigator.serviceWorker.controller);
  }
  return new Promise((resolve) => {
    let timer = 0;
    const done = () => {
      clearTimeout(timer);
      navigator.serviceWorker.removeEventListener('controllerchange', done);
      resolve(navigator.serviceWorker.controller || null);
    };
    navigator.serviceWorker.addEventListener('controllerchange', done);
    timer = setTimeout(done, budgetMs);
  });
}

async function _claimController(budgetMs) {
  const reg = await navigator.serviceWorker.register(SW_PATH, { scope: '/' });
  // `ready` resolves on an *active* registration; being active is not being in
  // control. An uncontrolled page's requests never reach the fetch handler, so
  // the worker would take our stream and never be asked for it — the download
  // then freezes after exactly one chunk, which is how this was found.
  await navigator.serviceWorker.ready;
  const controller = await _awaitControl(budgetMs);
  if (controller) return controller;
  // Active but not controlling after the whole budget. `sw.js` calls
  // `clients.claim()` on activate, so this is rare; when it happens the page
  // was loaded before any worker existed and the claim was missed. Ask the
  // active worker to claim again rather than declare the path unavailable.
  if (reg.active) {
    try { reg.active.postMessage({ type: 'mbdl-claim' }); } catch { /* gone */ }
    return await _awaitControl(2000);
  }
  return null;
}

/**
 * Register the worker and get this page controlled, now.
 *
 * Called at application start, not at the first download. Registration used to
 * happen inside the first click, so that click paid install, activate and claim
 * while somebody watched a button do nothing — and if the claim did not land
 * inside the budget, the download fell through to a path that cannot hold a
 * film. By the time anyone clicks anything, this has long since finished.
 *
 * Fire-and-forget by design: nothing waits on it, and a failure here is not
 * fatal because `serviceWorker()` will simply try again.
 */
export function primeServiceWorker() {
  if (!STREAMS_VIA_SW) return;
  serviceWorker().catch(() => {});
}

async function serviceWorker(controlMs = SW_CONTROL_BUDGET_MS) {
  if (!STREAMS_VIA_SW) {
    _lastFailure = 'no service worker support in this browser';
    return null;
  }
  if (navigator.serviceWorker.controller) return navigator.serviceWorker.controller;
  if (!_swPromise) {
    _swPromise = _claimController(controlMs).catch((err) => {
      _lastFailure = 'service worker registration failed: ' + err.message;
      console.warn('[MeshBay]', _lastFailure);
      return null;
    });
  }
  const controller = await _swPromise;
  if (!controller) {
    // Not remembered. The next attempt starts from scratch, which is the whole
    // point: these failures are transient far more often than they are final.
    _swPromise = null;
    if (!_lastFailure) _lastFailure = 'the page did not come under the worker’s control';
  }
  return controller;
}

/**
 * A sink the browser writes to disk, for Firefox and anything else without the
 * File System Access API.
 *
 * The page keeps the writable half of a stream and gives the readable half to
 * the service worker, which answers a made-up URL with it. Navigating a hidden
 * iframe there turns it into an ordinary download: written as it arrives, with
 * the browser's own progress, and nothing held in the tab. Backpressure is
 * real — `writer.write()` waits when the browser is behind.
 *
 * Returns {writable, name} shaped like the File System Access one, or null if
 * this browser cannot do it either.
 */
export async function openStreamedDownload(filename, size = 0, {
  controlMs = SW_CONTROL_BUDGET_MS,
  servedMs = SW_SERVED_BUDGET_MS,
  attempts = SW_ATTEMPTS,
} = {}) {
  for (let attempt = 1; attempt <= attempts; attempt++) {
    const target = await _attemptStreamedDownload(
      filename, size, attempt, controlMs, servedMs);
    if (target) return target;
    // A miss is usually the worker having been asleep or the navigation losing
    // a race, not this browser being unable. Falling through on the first miss
    // is what sent large downloads to the in-memory floor.
    if (attempt < attempts) {
      console.warn(`[MeshBay] streamed download attempt ${attempt} missed `
                   + `(${_lastFailure}); retrying`);
    }
  }
  return null;
}

async function _attemptStreamedDownload(filename, size, attempt,
                                        controlMs, servedMs) {
  const worker = await serviceWorker(controlMs);
  if (!worker) return null;

  const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
  const { readable, writable } = new TransformStream();

  // The worker tells us when it actually answers the iframe. Without that
  // confirmation this path fails silently: the write side blocks on
  // backpressure that will never be relieved, which reads as a download frozen
  // after one chunk rather than as an error.
  const chan = new MessageChannel();
  const serving = new Promise((resolve) => {
    chan.port1.onmessage = (e) => {
      if (e.data && e.data.type === 'mbdl-serving') resolve(true);
    };
  });

  try {
    worker.postMessage({ type: 'mbdl', id, filename, size, readable, port: chan.port2 },
                       [readable, chan.port2]);
  } catch (err) {
    // Transferable streams are what makes the backpressure work; without them
    // this would be a memory buffer wearing a stream's clothes. This one is
    // final rather than transient — a browser does not grow the capability
    // between two attempts — so it is reported as such.
    _lastFailure = 'this browser cannot transfer a stream to the worker: ' + err.message;
    console.warn('[MeshBay]', _lastFailure);
    return null;
  }

  const frame = document.createElement('iframe');
  frame.hidden = true;
  frame.src = `/_mbdl/${id}`;
  document.body.appendChild(frame);

  const answered = await Promise.race([
    serving,
    new Promise((r) => setTimeout(() => r(false), servedMs)),
  ]);
  if (!answered) {
    // Some browsers refuse a download started from a hidden iframe, and an
    // uncontrolled page never reaches the worker at all. Tear this attempt
    // down completely — the stream, the port and the frame — so a retry starts
    // clean rather than leaving a half-open sink behind.
    _lastFailure = `the worker did not answer the download within `
      + `${servedMs / 1000}s (attempt ${attempt})`;
    console.warn('[MeshBay]', _lastFailure);
    frame.remove();
    try { chan.port1.close(); } catch { /* already gone */ }
    try { await writable.abort('not served'); } catch { /* already gone */ }
    return null;
  }

  _lastFailure = '';
  // Every few seconds for as long as this download is being written. Well
  // inside the ~30 s Firefox allows an idle worker, and cheap: one postMessage
  // with no payload. Cleared by close() and abort() below, so a finished
  // download leaves no timer behind.
  // Self-limiting, and that is not belt-and-braces: a target can be opened and
  // then never written to — a transfer cancelled while it waits for a slot
  // never runs, so nothing calls close() or abort() — and an interval nobody
  // clears pings for the life of the page. It also kept the Node test process
  // alive for ever, which is the same defect wearing a louder symptom (the
  // MessagePort above did exactly this a few hours earlier).
  let lastWrite = Date.now();
  const keepAlive = setInterval(() => {
    if (Date.now() - lastWrite > SW_KEEPALIVE_IDLE_MS) {
      clearInterval(keepAlive);
      return;
    }
    try { worker.postMessage({ type: 'mbdl-ping' }); } catch { /* gone */ }
  }, SW_KEEPALIVE_MS);
  // The port has delivered the one message it exists for. Closing it matters:
  // an open MessagePort is a live handle, and one was leaked per download for
  // the life of the page. (It is also what hung the Node harness in
  // test_streamed_download_reliability.py — there the leak is a process that
  // never exits, which is the same defect wearing a louder symptom.)
  try { chan.port1.close(); } catch { /* already gone */ }

  const writer = writable.getWriter();
  return {
    name: filename,
    writable: {
      write: (bytes) => { lastWrite = Date.now(); return writer.write(bytes); },
      close: async () => {
        clearInterval(keepAlive);
        await writer.close();
        setTimeout(() => frame.remove(), 2000);
      },
      abort: async (reason) => {
        clearInterval(keepAlive);
        try { await writer.abort(reason); } catch { /* already gone */ }
        frame.remove();
      },
    },
  };
}