@tinvar/react 0.0.0-stage → 0.4.1

package/src/transfer.js

@@ -0,0 +1,135 @@
+// Starting the application's exports and imports, by name, from the maps
+// codegen writes (ADR 0070).
+//
+// `transfer.export('orders', { format: 'csv' })` POSTs to /_export/orders;
+// `transfer.import('stock', file)` POSTs the file, as multipart, to
+// /_import/stock. Each answers with the record's id once the server has
+// queued it -- the work itself is a job, and its progress is a page's to
+// show, from the loader that reads the user's transfers. Both carry the
+// session's CSRF token, read from the cookie as the request is sent, as
+// every action does; the URL is a path on this origin and nothing else, so
+// the token never goes anywhere else.
+//
+// No React and nothing from Node.
+
+import { CSRF_HEADER, csrfToken } from './csrf.js';
+
+/** A start the server refused: its status, its error code, and a 422's field errors. */
+export class TransferError extends Error {
+  /**
+   * @param {string} name
+   * @param {number} status
+   * @param {unknown} body
+   */
+  constructor(name, status, body) {
+    const error =
+      body !== null &&
+      typeof body === 'object' &&
+      'error' in body &&
+      body.error !== null &&
+      typeof body.error === 'object'
+        ? /** @type {{ code?: unknown, message?: unknown }} */ (body.error)
+        : {};
+    super(
+      typeof error.message === 'string'
+        ? error.message
+        : `[tinvar] '${name}' could not be started (${status}).`,
+    );
+    this.name = 'TransferError';
+    this.transfer = name;
+    this.status = status;
+    /** @type {string | null} */
+    this.code = typeof error.code === 'string' ? error.code : null;
+    /** @type {Record<string, string[]>} */
+    this.errors =
+      status === 422 && body !== null && typeof body === 'object' && 'errors' in body
+        ? /** @type {Record<string, string[]>} */ (body.errors)
+        : {};
+  }
+}
+
+const NAME = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/;
+
+/**
+ * @param {string} prefix
+ * @param {string} name
+ */
+function pathOf(prefix, name) {
+  if (!NAME.test(name)) throw new Error(`[tinvar] '${name}' is not an export or import name.`);
+  return `${prefix}${name}`;
+}
+
+/**
+ * @param {string} name
+ * @param {Response} response
+ * @returns {Promise<{ transfer: string, status: string }>}
+ */
+async function answer(name, response) {
+  const text = await response.text();
+  let body = /** @type {unknown} */ (null);
+  try {
+    body = text === '' ? null : JSON.parse(text);
+  } catch {
+    body = text;
+  }
+  if (!response.ok) throw new TransferError(name, response.status, body);
+
+  return /** @type {{ transfer: string, status: string }} */ (body);
+}
+
+/** @param {Record<string, string>} headers */
+function withToken(headers) {
+  const token = csrfToken();
+  if (token !== null) headers[CSRF_HEADER] = token;
+  return headers;
+}
+
+export function transfers() {
+  return {
+    /**
+     * @param {string} name
+     * @param {{ args?: Record<string, unknown>, format?: string, signal?: AbortSignal, fetch?: typeof fetch }} [options]
+     */
+    async export(name, options = {}) {
+      const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+      const response = await doFetch(pathOf('/_export/', name), {
+        method: 'POST',
+        headers: withToken({ accept: 'application/json', 'content-type': 'application/json' }),
+        body: JSON.stringify({
+          args: options.args ?? {},
+          ...(options.format === undefined ? {} : { format: options.format }),
+        }),
+        signal: options.signal,
+        credentials: 'same-origin',
+        redirect: 'manual',
+      });
+
+      return answer(name, response);
+    },
+
+    /**
+     * @param {string} name
+     * @param {Blob} file
+     * @param {{ args?: Record<string, string | number | boolean | null>, signal?: AbortSignal, fetch?: typeof fetch }} [options]
+     */
+    async import(name, file, options = {}) {
+      const form = new FormData();
+      for (const [key, value] of Object.entries(options.args ?? {})) {
+        if (value !== null && value !== undefined) form.append(`args[${key}]`, String(value));
+      }
+      form.append('file', file, file instanceof File ? file.name : 'import.csv');
+
+      const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+      const response = await doFetch(pathOf('/_import/', name), {
+        method: 'POST',
+        headers: withToken({ accept: 'application/json' }),
+        body: form,
+        signal: options.signal,
+        credentials: 'same-origin',
+        redirect: 'manual',
+      });
+
+      return answer(name, response);
+    },
+  };
+}

package/src/transport.js

@@ -0,0 +1,390 @@
+// One POST to an action or query endpoint, and what came back, classified.
+//
+// tinvar-spec.md, "Forms and mutations": "Keep three error channels: 422 ->
+// errors, other statuses -> onHttpException, connectivity -> onNetworkError."
+// Everything that sends to /_action or /_query -- <Form>, useForm, useHttp,
+// Precognition, a generated action called directly -- comes through here, so
+// the three channels are told apart in one place and mean the same thing to
+// each of them.
+//
+// Never throws for an outcome. A 500 and a dropped connection are answers the
+// caller has to route somewhere, not exceptions to be caught at a distance.
+
+import { CSRF_HEADER, csrfToken } from './csrf.js';
+import { hasFiles, toFormData } from './form-data.js';
+
+/**
+ * @typedef {{ loaded: number, total: number | undefined, percentage: number | undefined }} Progress
+ *
+ * @typedef {(
+ *   | { type: 'success', status: number, body: any, headers: Headers }
+ *   | { type: 'redirect', location: string, headers: Headers }
+ *   | { type: 'location', location: string, headers: Headers }
+ *   | { type: 'validation', status: 422, errors: Record<string, string[]>, body: any, headers: Headers }
+ *   | { type: 'http', status: number, body: any, headers: Headers, code: string | null, reference: string | null, retryAfter: number | null }
+ *   | { type: 'expired', headers: Headers }
+ *   | { type: 'network', error: unknown }
+ *   | { type: 'cancelled' }
+ * )} Outcome
+ *
+ * @typedef {{
+ *   url: string,
+ *   data?: Record<string, unknown>,
+ *   body?: Blob,
+ *   headers?: Record<string, string>,
+ *   signal?: AbortSignal,
+ *   onUploadProgress?: (progress: Progress) => void,
+ *   stallTimeout?: number,
+ *   fetch?: typeof fetch,
+ * }} SendOptions
+ */
+
+/**
+ * Sends one request.
+ *
+ * JSON unless the data holds a file, then multipart -- "payloads with files
+ * become multipart automatically, with upload progress" -- which goes by
+ * XMLHttpRequest, since fetch reports nothing of an upload.
+ *
+ * Or `body`, a Blob sent as it is -- a chunk of a resumable upload, under
+ * the headers given -- by XMLHttpRequest too, for its progress.
+ *
+ * `stallTimeout`, for a request sent by XMLHttpRequest, gives it up as a
+ * network failure once it has sent nothing for that many milliseconds: a
+ * connection that hangs without ever failing would otherwise wait forever.
+ * Only while the body goes; the answer is waited for as long as it takes.
+ *
+ * `RSC: 1` says it is the client router asking. A redirect is then answered
+ * 409 + X-Redirect, as a navigation's is, rather than a 303 whose Location
+ * the fetch below -- redirect: 'manual', so that nothing is followed off-site
+ * with the CSRF header -- could never read.
+ *
+ * @param {SendOptions} options
+ * @returns {Promise<Outcome>}
+ */
+export async function send({
+  url,
+  data = {},
+  body: blob,
+  headers = {},
+  signal,
+  onUploadProgress,
+  stallTimeout,
+  fetch: doFetch,
+}) {
+  const multipart = blob === undefined && hasFiles(data);
+
+  /** @param {string | null} token */
+  const attempt = (token) => {
+    const all = {
+      accept: 'application/json',
+      RSC: '1',
+      ...(token === null ? {} : { [CSRF_HEADER]: token }),
+      ...headers,
+      ...(multipart || blob !== undefined ? {} : { 'content-type': 'application/json' }),
+    };
+    if (blob !== undefined) return viaXhr(url, blob, all, signal, onUploadProgress, stallTimeout);
+    // Built for each attempt: a FormData or a string, either can be sent
+    // only once.
+    const body = multipart ? toFormData(data) : JSON.stringify(data);
+    return multipart
+      ? viaXhr(url, /** @type {FormData} */ (body), all, signal, onUploadProgress, stallTimeout)
+      : viaFetch(doFetch ?? globalThis.fetch.bind(globalThis), url, body, all, signal);
+  };
+
+  if (signal?.aborted) return { type: 'cancelled' };
+
+  // The token is the session's, and goes only where the session is: a URL
+  // an application passes that names another origin is sent the request
+  // without it, so nothing off-site is handed a token it could replay here.
+  const ours = sameOrigin(url);
+
+  /** @type {{ status: number, headers: Headers, text: string }} */
+  let raw;
+  try {
+    // Read from the cookie now, never kept: a sign-in rotates it.
+    const sent = ours ? csrfToken() : null;
+    raw = await attempt(sent);
+
+    // A 419 is a token the session no longer has: it expired, or rotated
+    // in another tab. The refusal sets the session's token as a cookie on
+    // its way back, so the cookie is read again and the request sent once
+    // more with what it holds now. Only when it holds something new: the
+    // same token again would be refused the same way.
+    if (raw.status === 419 && ours) {
+      const fresh = csrfToken();
+      if (fresh !== null && fresh !== sent) raw = await attempt(fresh);
+    }
+  } catch (error) {
+    if (signal?.aborted || /** @type {any} */ (error)?.name === 'AbortError') return { type: 'cancelled' };
+    return { type: 'network', error };
+  }
+
+  // Still refused. "A 419 becomes a same-origin redirect back with a 'page
+  // expired' flash, not an error screen" -- which the caller arranges,
+  // since only it knows what page it is on.
+  if (raw.status === 419) return { type: 'expired', headers: raw.headers };
+
+  return classify(raw);
+}
+
+/**
+ * Whether $url resolves to this page's own origin. A relative URL always
+ * does; with no page to resolve against, only a relative one does.
+ *
+ * @param {string} url
+ */
+function sameOrigin(url) {
+  const here = globalThis.location?.href;
+  if (here === undefined) return !/^[a-z][a-z0-9+.-]*:|^\/\//i.test(url);
+  try {
+    return new URL(url, here).origin === new URL(here).origin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {typeof fetch} doFetch
+ * @param {string} url
+ * @param {BodyInit} body
+ * @param {Record<string, string>} headers
+ * @param {AbortSignal | undefined} signal
+ */
+async function viaFetch(doFetch, url, body, headers, signal) {
+  const response = await doFetch(url, {
+    method: 'POST',
+    headers,
+    body,
+    credentials: 'same-origin',
+    redirect: 'manual',
+    signal,
+  });
+
+  // An unreadable body is still an answer; its status says what happened.
+  const text = await response.text().catch(() => '');
+  return {
+    status: response.status,
+    headers: response.headers,
+    text,
+    opaque: response.type === 'opaqueredirect',
+  };
+}
+
+/**
+ * @param {string} url
+ * @param {FormData | Blob} body
+ * @param {Record<string, string>} headers
+ * @param {AbortSignal | undefined} signal
+ * @param {((progress: Progress) => void) | undefined} onUploadProgress
+ * @param {number | undefined} stallTimeout
+ * @returns {Promise<{ status: number, headers: Headers, text: string, opaque?: boolean }>}
+ */
+function viaXhr(url, body, headers, signal, onUploadProgress, stallTimeout) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open('POST', url);
+    xhr.withCredentials = true;
+    for (const [name, value] of Object.entries(headers)) xhr.setRequestHeader(name, value);
+    const stall = watchStall(xhr, stallTimeout);
+
+    if (onUploadProgress && xhr.upload) {
+      xhr.upload.addEventListener('progress', (event) => {
+        const total = event.lengthComputable ? event.total : undefined;
+        onUploadProgress({
+          loaded: event.loaded,
+          total,
+          percentage: total ? Math.round((event.loaded / total) * 100) : undefined,
+        });
+      });
+    }
+
+    const abort = () => xhr.abort();
+    signal?.addEventListener('abort', abort, { once: true });
+
+    xhr.addEventListener('load', () => {
+      stall.stop();
+      signal?.removeEventListener('abort', abort);
+      // XHR follows a redirect itself, where the fetch above is told not
+      // to: a 303 from something in front of the endpoint ended at the page
+      // it pointed to -- a sign-in page's 200, say -- and was taken for the
+      // action's success when the action had never run. Told by where the
+      // answer came from, and answered as the fetch path answers a redirect
+      // it could not read.
+      if (redirected(xhr.responseURL, url)) {
+        resolve({ status: 0, headers: new Headers(), text: '', opaque: true });
+        return;
+      }
+      resolve({
+        status: xhr.status,
+        headers: parseHeaders(xhr.getAllResponseHeaders()),
+        text: xhr.responseText,
+      });
+    });
+    xhr.addEventListener('error', () => {
+      stall.stop();
+      signal?.removeEventListener('abort', abort);
+      reject(new TypeError('The request could not be sent.'));
+    });
+    xhr.addEventListener('abort', () => {
+      stall.stop();
+      signal?.removeEventListener('abort', abort);
+      reject(
+        stall.stalled()
+          ? new TypeError('The request sent nothing for too long.')
+          : Object.assign(new Error('The request was cancelled.'), { name: 'AbortError' }),
+      );
+    });
+
+    xhr.send(body);
+  });
+}
+
+/**
+ * Watches an XMLHttpRequest's upload, and aborts it once it has sent
+ * nothing for $ms: from the start, and from each progress event, until the
+ * body has gone. `stalled()` then tells that abort from a cancel, for the
+ * caller to answer it as a network failure. Nothing is watched without $ms.
+ *
+ * @param {XMLHttpRequest} xhr
+ * @param {number | undefined} ms
+ * @returns {{ stop: () => void, stalled: () => boolean }}
+ */
+export function watchStall(xhr, ms) {
+  if (typeof ms !== 'number' || !(ms > 0)) return { stop: () => {}, stalled: () => false };
+  let stalled = false;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null;
+  const stop = () => {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  };
+  const arm = () => {
+    stop();
+    timer = setTimeout(() => {
+      timer = null;
+      stalled = true;
+      xhr.abort();
+    }, ms);
+  };
+  xhr.upload?.addEventListener('progress', () => {
+    if (!stalled) arm();
+  });
+  // The body has gone: the answer -- a last chunk's scan, say -- takes as long as it takes.
+  xhr.upload?.addEventListener('load', stop);
+  arm();
+  return { stop, stalled: () => stalled };
+}
+
+/**
+ * Whether an XHR's answer came from somewhere other than where it was
+ * sent: a redirect it followed. An empty responseURL says nothing either
+ * way, and is taken as the answer of the URL asked.
+ *
+ * @param {string} responseUrl
+ * @param {string} url
+ */
+function redirected(responseUrl, url) {
+  if (!responseUrl) return false;
+  try {
+    return new URL(responseUrl).href !== new URL(url, globalThis.location?.href).href;
+  } catch {
+    return true;
+  }
+}
+
+/** @param {string} block */
+function parseHeaders(block) {
+  const headers = new Headers();
+  for (const line of block.trim().split(/[\r\n]+/)) {
+    const at = line.indexOf(':');
+    if (at > 0) {
+      try {
+        headers.append(line.slice(0, at).trim(), line.slice(at + 1).trim());
+      } catch {
+        // A header Headers refuses is one nothing here reads.
+      }
+    }
+  }
+  return headers;
+}
+
+/**
+ * @param {{ status: number, headers: Headers, text: string, opaque?: boolean }} raw
+ * @returns {Outcome}
+ */
+function classify({ status, headers, text, opaque }) {
+  let body = null;
+  if (text !== '') {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = null;
+    }
+  }
+
+  if (status === 409) {
+    const redirect = headers.get('x-redirect');
+    if (redirect) return { type: 'redirect', location: redirect, headers };
+    const location = headers.get('x-location');
+    if (location) return { type: 'location', location, headers };
+  }
+
+  // A raw redirect the fetch did not follow. The server answers 409 to an
+  // `RSC: 1` caller instead; a 303 here came from something in between, and
+  // where it pointed cannot be read. Nothing was shown as succeeding.
+  if (opaque || status === 0) {
+    return {
+      type: 'http',
+      status: 0,
+      body: null,
+      headers,
+      code: 'opaque_redirect',
+      reference: null,
+      retryAfter: null,
+    };
+  }
+
+  if (status >= 200 && status < 300) return { type: 'success', status, body, headers };
+
+  // "422 -> errors", every 422: a query refusing its arguments answers with
+  // a code and no field to put it on, and is still the input's fault rather
+  // than the server's -- the errors channel, with no fields in it.
+  if (status === 422) {
+    return { type: 'validation', status: 422, errors: normalizeErrors(body?.errors), body, headers };
+  }
+
+  const retryAfter = Number(headers.get('retry-after'));
+  return {
+    type: 'http',
+    status,
+    body,
+    headers,
+    code: typeof body?.error?.code === 'string' ? body.error.code : null,
+    reference: typeof body?.error?.digest === 'string' ? body.error.digest : null,
+    retryAfter: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : null,
+  };
+}
+
+/**
+ * Field errors as the server sends them, a list of messages per field, made
+ * safe to index: a PHP empty array arrives as a JSON list, and a field whose
+ * messages are a single string is read as a list of one.
+ *
+ * @param {unknown} errors
+ * @returns {Record<string, string[]>}
+ */
+export function normalizeErrors(errors) {
+  /** @type {Record<string, string[]>} */
+  const out = {};
+  if (errors === null || typeof errors !== 'object' || Array.isArray(errors)) return out;
+  for (const [field, messages] of Object.entries(errors)) {
+    if (Array.isArray(messages)) {
+      const list = messages.filter((m) => typeof m === 'string');
+      if (list.length > 0) out[field] = list;
+    } else if (typeof messages === 'string') {
+      out[field] = [messages];
+    }
+  }
+  return out;
+}