@tinvar/renderer 0.0.0-stage → 0.4.1

package/src/codec.js

@@ -0,0 +1,297 @@
+// Framing for the PHP-to-renderer socket, mirroring packages/framework/src/Codec.
+//
+// Every message is a 4-byte big-endian length followed by a MessagePack map
+// carrying a `t` (type) key (tinvar-spec.md, "Socket protocol").
+
+import { decode, encode } from '@msgpack/msgpack';
+
+export const DEFAULT_MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+// useBigInt64 keeps integers past 2^53 exact in both directions, which is why
+// the spec picks MessagePack over JSON for this hop.
+const ENCODE_OPTIONS = { useBigInt64: true };
+const DECODE_OPTIONS = { useBigInt64: true };
+
+export class FrameError extends Error {}
+
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+
+const INT32_MIN = -0x80000000;
+const UINT32_MAX = 0xffffffff;
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+
+/** The spec's socket format. */
+export const msgpackCodec = {
+  name: 'msgpack',
+  encode: (value) => encode(widenIntegers(value), ENCODE_OPTIONS),
+  decode: (bytes) => narrowIntegers(decode(bytes, DECODE_OPTIONS)),
+};
+
+const isPlainObject = (value) => {
+  if (value === null || typeof value !== 'object') return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+/**
+ * Safe integers past 32 bits, made BigInt so they leave as int64.
+ *
+ * With useBigInt64 on, @msgpack/msgpack writes every number past 32 bits as
+ * a float64 -- a millisecond timestamp, a file size -- and PHP decodes it as
+ * a float, which an `int` parameter refuses. Only plain objects and arrays
+ * are walked: they are what frames are made of, and anything else is left
+ * for the encoder to take or refuse as it is.
+ */
+function widenIntegers(value) {
+  if (typeof value === 'number') {
+    return Number.isSafeInteger(value) && (value > UINT32_MAX || value < INT32_MIN) ? BigInt(value) : value;
+  }
+  if (Array.isArray(value)) return value.map(widenIntegers);
+  if (isPlainObject(value)) {
+    // Defined, not assigned, for the reason lowerBinary() gives: a
+    // `__proto__` key is data here, and assignment would run the setter.
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      Object.defineProperty(out, key, {
+        value: widenIntegers(item),
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      });
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Every int64 PHP sent comes back as a BigInt, timestamps and file sizes
+ * included. tinvar-spec.md: only integers beyond 2^53 need one -- the rest
+ * are numbers, which arithmetic, Date and JSON.stringify all expect. In
+ * place: the decoder's objects are new and nothing else holds them.
+ */
+function narrowIntegers(value) {
+  if (typeof value === 'bigint') {
+    return value <= MAX_SAFE && value >= MIN_SAFE ? Number(value) : value;
+  }
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) value[i] = narrowIntegers(value[i]);
+    return value;
+  }
+  if (isPlainObject(value)) {
+    // The decoder refuses a `__proto__` key, so assignment is safe here.
+    for (const key of Object.keys(value)) value[key] = narrowIntegers(value[key]);
+  }
+  return value;
+}
+
+/**
+ * The alternative the spec leaves open, kept wire-comparable with
+ * Tinvar\Codec\JsonLinesCodec: same length prefix, same frame maps, binary
+ * carried as {"$b64": "..."} because JSON cannot hold bytes.
+ *
+ * A map key is user data -- a prop, an action's argument -- so a key that is
+ * `$b64` behind any number of `$` travels with one `$` more and comes back
+ * with one fewer, on both sides: user data shaped like the marker is never
+ * read back as bytes.
+ *
+ * Integers past 2^53 cannot survive this codec; that is the cost the spec's
+ * "Why MessagePack" section is pointing at.
+ */
+export const jsonLinesCodec = {
+  name: 'json-lines',
+  encode: (value) => utf8Encoder.encode(JSON.stringify(liftBinary(value))),
+  decode: (bytes) => lowerBinary(JSON.parse(utf8Decoder.decode(bytes))),
+};
+
+export function createCodec(name) {
+  if (name === 'msgpack') return msgpackCodec;
+  if (name === 'json-lines') return jsonLinesCodec;
+  throw new FrameError(`Unknown codec '${name}'. Use 'msgpack' or 'json-lines'.`);
+}
+
+/** `$b64` behind one or more `$`: the binary marker, or a user's key escaped from it. */
+const MARKER_KEY = /^\$+b64$/;
+const ESCAPED_MARKER_KEY = /^\$\$+b64$/;
+
+function liftBinary(value) {
+  if (value instanceof Uint8Array) {
+    return { $b64: Buffer.from(value).toString('base64') };
+  }
+  if (Array.isArray(value)) return value.map(liftBinary);
+  // Plain maps only: anything else (a Date) is JSON.stringify's to write.
+  // Defined, not assigned, for the reason lowerBinary gives.
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      Object.defineProperty(out, MARKER_KEY.test(k) ? `$${k}` : k, {
+        value: liftBinary(v),
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      });
+    }
+    return out;
+  }
+  if (typeof value === 'bigint') {
+    throw new FrameError('json-lines cannot carry an integer past 2^53; use msgpack.');
+  }
+  return value;
+}
+
+function lowerBinary(value) {
+  if (Array.isArray(value)) return value.map(lowerBinary);
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value);
+    if (keys.length === 1 && keys[0] === '$b64' && typeof value.$b64 === 'string') {
+      return new Uint8Array(Buffer.from(value.$b64, 'base64'));
+    }
+    // Defined, not assigned: map keys are user data, and `out[k] =` with a
+    // `__proto__` key runs the prototype setter, so the key disappears and its
+    // value is inherited by every lookup on the map. A null-prototype object
+    // would also keep it, but React refuses to pass one to a client component.
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      Object.defineProperty(out, ESCAPED_MARKER_KEY.test(k) ? k.slice(1) : k, {
+        value: lowerBinary(v),
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      });
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * @param {Record<string, unknown>} frame
+ * @param {number} [maxFrameBytes]
+ * @param {{encode: Function, decode: Function}} [codec]
+ * @returns {Uint8Array}
+ */
+export function encodeFrame(frame, maxFrameBytes = DEFAULT_MAX_FRAME_BYTES, codec = msgpackCodec) {
+  const body = codec.encode(frame);
+  if (body.length > maxFrameBytes) {
+    throw new FrameError(`Frame of ${body.length} bytes exceeds the ${maxFrameBytes}-byte cap.`);
+  }
+  const out = new Uint8Array(4 + body.length);
+  new DataView(out.buffer).setUint32(0, body.length, false);
+  out.set(body, 4);
+  return out;
+}
+
+/**
+ * Accumulates socket reads and yields whole frames. A stream delivers arbitrary
+ * slices, so partial frames have to survive between chunks.
+ *
+ * Reads are kept as they came and joined once, when the frame they make up
+ * is whole. Merging each read into one buffer as it arrived copied all that
+ * had come so far every time: a 15 MB frame in 64 KB reads was seconds of
+ * copying. Here each byte is copied at most once, and a frame that sits in
+ * a single read is not copied at all.
+ */
+export class FrameReader {
+  /** @type {Uint8Array[]} */
+  #chunks = [];
+  #length = 0;
+  #max;
+  #codec;
+
+  constructor(maxFrameBytes = DEFAULT_MAX_FRAME_BYTES, codec = msgpackCodec) {
+    this.#max = maxFrameBytes;
+    this.#codec = codec;
+  }
+
+  /**
+   * @param {Uint8Array} chunk
+   * @returns {Record<string, unknown>[]}
+   */
+  push(chunk) {
+    if (chunk.length > 0) {
+      this.#chunks.push(chunk);
+      this.#length += chunk.length;
+    }
+
+    const frames = [];
+    while (this.#length >= 4) {
+      const header = this.#peek(4);
+      const length = new DataView(header.buffer, header.byteOffset, 4).getUint32(0, false);
+      if (length > this.#max) {
+        throw new FrameError(`Incoming frame of ${length} bytes exceeds the ${this.#max}-byte cap.`);
+      }
+      if (4 + length > this.#length) break;
+
+      const body = this.#take(4 + length).subarray(4);
+      const value = this.#codec.decode(body);
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new FrameError('Frame body must decode to a map.');
+      }
+      frames.push(/** @type {Record<string, unknown>} */ (value));
+    }
+
+    return frames;
+  }
+
+  /**
+   * The first `n` buffered bytes, left in the buffer. Copied only when they
+   * span reads, which for a length prefix is four bytes.
+   *
+   * @param {number} n
+   * @returns {Uint8Array}
+   */
+  #peek(n) {
+    const first = this.#chunks[0];
+    if (first.length >= n) return first.subarray(0, n);
+    const out = new Uint8Array(n);
+    let filled = 0;
+    for (const chunk of this.#chunks) {
+      const part = chunk.subarray(0, n - filled);
+      out.set(part, filled);
+      filled += part.length;
+      if (filled === n) break;
+    }
+    return out;
+  }
+
+  /**
+   * The first `n` buffered bytes, taken out of the buffer: a view of the
+   * first read when they all sit in it, else one allocation filled from
+   * the reads they span.
+   *
+   * @param {number} n
+   * @returns {Uint8Array}
+   */
+  #take(n) {
+    this.#length -= n;
+    const first = this.#chunks[0];
+    if (first.length >= n) {
+      if (first.length === n) this.#chunks.shift();
+      else this.#chunks[0] = first.subarray(n);
+      return first.subarray(0, n);
+    }
+
+    const out = new Uint8Array(n);
+    let filled = 0;
+    while (filled < n) {
+      const chunk = /** @type {Uint8Array} */ (this.#chunks[0]);
+      const wanted = n - filled;
+      if (chunk.length <= wanted) {
+        out.set(chunk, filled);
+        filled += chunk.length;
+        this.#chunks.shift();
+      } else {
+        out.set(chunk.subarray(0, wanted), filled);
+        filled += wanted;
+        this.#chunks[0] = chunk.subarray(wanted);
+      }
+    }
+    return out;
+  }
+
+  get pending() {
+    return this.#length;
+  }
+}

package/src/dev-app.js

@@ -0,0 +1,45 @@
+// The app entry the renderer imports in dev: four functions that render
+// with whatever the Vite dev server currently has for the app's rsc entry.
+//
+// createRenderer() imports an entry module once and calls it for every
+// render. In dev that module must not be fixed at start: the point is that
+// an edit shows up on the next render. So the renderer is handed this module
+// instead, and each call asks the dev server's module runner for the entry
+// -- the cached module until a file under it changes, then the new one.
+
+/** @type {(() => Promise<Record<string, Function>>) | null} */
+let load = null;
+
+/** Sets where the entry comes from: dev-server.js, once Vite is up. */
+export function useDevEntry(loader) {
+  load = loader;
+}
+
+async function entry() {
+  if (load === null) throw new Error('The dev entry was imported before the dev server started.');
+  return load();
+}
+
+export async function renderHtml(...args) {
+  return (await entry()).renderHtml(...args);
+}
+
+export async function renderRsc(...args) {
+  return (await entry()).renderRsc(...args);
+}
+
+export async function renderFragment(...args) {
+  const app = await entry();
+  if (typeof app.renderFragment !== 'function') {
+    throw new Error('This app has no renderFragment entry; it cannot serve deferred components.');
+  }
+  return app.renderFragment(...args);
+}
+
+export async function renderMail(...args) {
+  const app = await entry();
+  if (typeof app.renderMail !== 'function') {
+    throw new Error('This app has no renderMail entry; it cannot render email.');
+  }
+  return app.renderMail(...args);
+}

package/src/dev-guard.js

@@ -0,0 +1,33 @@
+// The one check dev mode makes before anything of it is loaded: that this is
+// not production. Its own module, importing nothing, so the refusal happens
+// before Vite -- or any dependency of the app -- has run a line.
+
+/** The variables any of which, saying `production`, rule the dev server out. Mirrors Tinvar\Support\DevMode. */
+export const PRODUCTION_MARKERS = ['NODE_ENV', 'TINVAR_ENV', 'APP_ENV'];
+
+export class DevServerRefused extends Error {}
+
+/**
+ * Refuses, loudly, anywhere that says production.
+ *
+ * The dev server runs unsandboxed, serves source over HTTP and shows stacks
+ * to whoever loads a failing page. A NODE_ENV or TINVAR_ENV left saying
+ * production is the one signal there is that this is the wrong place, so
+ * any of them saying so stops it.
+ *
+ * @param {Record<string, string | undefined>} env
+ */
+export function assertDevelopment(env = process.env) {
+  for (const name of PRODUCTION_MARKERS) {
+    if (
+      String(env[name] ?? '')
+        .trim()
+        .toLowerCase() === 'production'
+    ) {
+      throw new DevServerRefused(
+        `The dev server is refused: ${name}=production. It runs without the renderer's sandbox and serves ` +
+          'source to the browser, so it never runs in production. Use the built renderer there.',
+      );
+    }
+  }
+}