@valbuild/server 0.130.0 → 0.131.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @valbuild/server
 
+## 0.131.0
+
+### Minor Changes
+
+- [#686](https://github.com/valbuild/val/pull/686) [`0d5857b`](https://github.com/valbuild/val/commit/0d5857b731e11f7e6a011f79297df6485908c31f) Thanks [@freekh](https://github.com/freekh)! - Say `VAL_MODE=memory` where there is no disk, and get a sentence instead of an `EPERM`
+
+  Memory mode — the one for a host that holds the project's source itself — is
+  selected by passing `sourceFiles`, and it has to be: nothing in an environment
+  can supply a project's source, so a mode that an env var could switch on would
+  be a server with no content in it.
+
+  The cost was the failure when a host forgot. Val inferred `fs` mode, `fs` mode
+  went looking for a working tree, and in a Worker isolate the first thing to
+  touch the disk failed:
+
+  ```
+  patch-error /bundle/.val/patches.lock: EPERM
+  ```
+
+  That names a path two layers below the decision that caused it, and nobody
+  reading it would guess "your server was configured for the wrong mode".
+
+  So an environment can now DECLARE that it has no disk:
+
+  ```
+  VAL_MODE=memory
+  ```
+
+  It does not turn memory mode on. It says the host is supposed to be supplying
+  `sourceFiles`, so if none arrive, Val refuses at configuration time and says
+  where to pass them. `VAL_MODE=` counts as unset, the way a shell means it; any
+  other value is refused rather than ignored, since leaving you in `fs` mode is
+  the exact failure this is meant to catch.
+
+  **`initValContent` takes the same options, and this is the release that
+  noticed.** It builds a Val server of its own — these readers resolve content by
+  asking it, not by calling the API over HTTP — so configuring `initValServer`
+  alone left them inferring `fs` mode. On a host with no filesystem that is a
+  reader looking for a working tree that is not there; it went unnoticed because
+  published reads still worked.
+
+  ```ts
+  const patchStore = new InMemoryPatchStore(); // now exported from this package
+
+  const { valApiHandler, draftMode } = initValServer(valModules, config, {
+    sourceFiles: FILES,
+    patchStore,
+    unsafelyAllowUnauthenticated: true,
+  });
+
+  const { fetchValStega } = initValContent(config, valModules, {
+    draftMode,
+    // The same three. Two patch stores are two sets of pending edits, and a
+    // reader that checks a session the host never issues answers itself 401 and
+    // falls back to published content — a draft render showing the live site.
+    sourceFiles: FILES,
+    patchStore,
+    unsafelyAllowUnauthenticated: true,
+  });
+  ```
+
+  All three are optional. Left out, this reader gets its own store and its own
+  answer about authentication, which is right for published content.
+
+  `@valbuild/next` has no memory mode: its `initValServer` takes neither option,
+  so for a Next app `VAL_MODE=memory` names an environment Val cannot serve from,
+  and the error says so.
+
+  Nothing changes for an app that sets none of this: `http` when `VAL_API_KEY`
+  and `VAL_SECRET` are both present, `fs` otherwise, as before.
+
 ## 0.130.0
 
 ### Minor Changes

package/dist/declarations/src/ValRouter.d.ts

@@ -61,6 +61,11 @@ type ValServerOverrides = Partial<{
      * and "proxy" this one cannot be inferred from the environment -- there is
      * nothing to infer it FROM, and a mode that can be turned on without
      * supplying the source would be a server with no content in it.
+     *
+     * An environment that has no disk can still say it EXPECTS this, by setting
+     * `VAL_MODE=memory`. That does not select the mode; it makes forgetting to
+     * pass the source an error here rather than an `EPERM` from `fs` mode two
+     * layers down.
      */
     sourceFiles: Record<string, string>;
     /**

package/dist/valbuild-server.cjs.dev.js

@@ -10103,6 +10103,31 @@ async function initHandlerOptions(route, opts, config) {
       config
     };
   }
+  /*
+   * `VAL_MODE=memory` says the host MEANT to hold the source, and did not.
+   *
+   * It cannot SELECT memory mode -- nothing in the environment can supply
+   * `sourceFiles`, and a mode turned on without them is a server with no
+   * content in it. What it does is turn the fall-through into an error.
+   *
+   * Without it, a host that forgot to pass its source got `fs` mode, and `fs`
+   * mode in a Worker isolate reaches for a working tree that is not there: the
+   * failure is an `EPERM` on `.val/patches.lock`, several layers below the
+   * mistake, naming a path rather than the decision that led to it. Every
+   * environment that runs Val without a disk can set this once and get a
+   * sentence instead.
+   */
+  const declaredMode = process.env.VAL_MODE;
+  if (declaredMode === "memory") {
+    throw new Error("VAL_MODE is 'memory', but no `sourceFiles` were given here, so there " + "is no source to serve. Memory mode cannot be turned on by the " + "environment: it needs the project's own source, and only the host " + "that holds it can hand it over. On TanStack Start that is the " + "`sourceFiles` option, passed to `initValServer` AND to " + "`initValContent`, which has a Val server of its own and is " + "configured separately. @valbuild/next has no memory mode yet, so " + "for a Next app this variable is set on an environment Val cannot " + "serve from. Unset " + "VAL_MODE to go back to the inferred mode instead ('http' when " + "VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise).");
+  }
+  // An empty value counts as unset, which is what `VAL_MODE=` in a shell or a
+  // CI settings page means. Every other value is refused rather than ignored:
+  // ignoring `VAL_MODE=memry` would leave the app in `fs` mode, which is the
+  // exact failure this variable exists to catch.
+  if (declaredMode !== undefined && declaredMode !== "") {
+    throw new Error(`VAL_MODE is '${declaredMode}', which is not a mode Val knows. The only ` + "value it accepts is 'memory', which asserts that the host supplies " + "`sourceFiles`. 'fs' and 'http' are inferred rather than named: " + "'http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise.");
+  }
   const maybeApiKey = opts.apiKey || process.env.VAL_API_KEY;
   const maybeValSecret = opts.valSecret || process.env.VAL_SECRET;
   const isProxyMode = opts.mode === "proxy" || opts.mode === undefined && (maybeApiKey || maybeValSecret);

package/dist/valbuild-server.cjs.prod.js

@@ -10103,6 +10103,31 @@ async function initHandlerOptions(route, opts, config) {
       config
     };
   }
+  /*
+   * `VAL_MODE=memory` says the host MEANT to hold the source, and did not.
+   *
+   * It cannot SELECT memory mode -- nothing in the environment can supply
+   * `sourceFiles`, and a mode turned on without them is a server with no
+   * content in it. What it does is turn the fall-through into an error.
+   *
+   * Without it, a host that forgot to pass its source got `fs` mode, and `fs`
+   * mode in a Worker isolate reaches for a working tree that is not there: the
+   * failure is an `EPERM` on `.val/patches.lock`, several layers below the
+   * mistake, naming a path rather than the decision that led to it. Every
+   * environment that runs Val without a disk can set this once and get a
+   * sentence instead.
+   */
+  const declaredMode = process.env.VAL_MODE;
+  if (declaredMode === "memory") {
+    throw new Error("VAL_MODE is 'memory', but no `sourceFiles` were given here, so there " + "is no source to serve. Memory mode cannot be turned on by the " + "environment: it needs the project's own source, and only the host " + "that holds it can hand it over. On TanStack Start that is the " + "`sourceFiles` option, passed to `initValServer` AND to " + "`initValContent`, which has a Val server of its own and is " + "configured separately. @valbuild/next has no memory mode yet, so " + "for a Next app this variable is set on an environment Val cannot " + "serve from. Unset " + "VAL_MODE to go back to the inferred mode instead ('http' when " + "VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise).");
+  }
+  // An empty value counts as unset, which is what `VAL_MODE=` in a shell or a
+  // CI settings page means. Every other value is refused rather than ignored:
+  // ignoring `VAL_MODE=memry` would leave the app in `fs` mode, which is the
+  // exact failure this variable exists to catch.
+  if (declaredMode !== undefined && declaredMode !== "") {
+    throw new Error(`VAL_MODE is '${declaredMode}', which is not a mode Val knows. The only ` + "value it accepts is 'memory', which asserts that the host supplies " + "`sourceFiles`. 'fs' and 'http' are inferred rather than named: " + "'http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise.");
+  }
   const maybeApiKey = opts.apiKey || process.env.VAL_API_KEY;
   const maybeValSecret = opts.valSecret || process.env.VAL_SECRET;
   const isProxyMode = opts.mode === "proxy" || opts.mode === undefined && (maybeApiKey || maybeValSecret);

package/dist/valbuild-server.esm.js

@@ -10069,6 +10069,31 @@ async function initHandlerOptions(route, opts, config) {
       config
     };
   }
+  /*
+   * `VAL_MODE=memory` says the host MEANT to hold the source, and did not.
+   *
+   * It cannot SELECT memory mode -- nothing in the environment can supply
+   * `sourceFiles`, and a mode turned on without them is a server with no
+   * content in it. What it does is turn the fall-through into an error.
+   *
+   * Without it, a host that forgot to pass its source got `fs` mode, and `fs`
+   * mode in a Worker isolate reaches for a working tree that is not there: the
+   * failure is an `EPERM` on `.val/patches.lock`, several layers below the
+   * mistake, naming a path rather than the decision that led to it. Every
+   * environment that runs Val without a disk can set this once and get a
+   * sentence instead.
+   */
+  const declaredMode = process.env.VAL_MODE;
+  if (declaredMode === "memory") {
+    throw new Error("VAL_MODE is 'memory', but no `sourceFiles` were given here, so there " + "is no source to serve. Memory mode cannot be turned on by the " + "environment: it needs the project's own source, and only the host " + "that holds it can hand it over. On TanStack Start that is the " + "`sourceFiles` option, passed to `initValServer` AND to " + "`initValContent`, which has a Val server of its own and is " + "configured separately. @valbuild/next has no memory mode yet, so " + "for a Next app this variable is set on an environment Val cannot " + "serve from. Unset " + "VAL_MODE to go back to the inferred mode instead ('http' when " + "VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise).");
+  }
+  // An empty value counts as unset, which is what `VAL_MODE=` in a shell or a
+  // CI settings page means. Every other value is refused rather than ignored:
+  // ignoring `VAL_MODE=memry` would leave the app in `fs` mode, which is the
+  // exact failure this variable exists to catch.
+  if (declaredMode !== undefined && declaredMode !== "") {
+    throw new Error(`VAL_MODE is '${declaredMode}', which is not a mode Val knows. The only ` + "value it accepts is 'memory', which asserts that the host supplies " + "`sourceFiles`. 'fs' and 'http' are inferred rather than named: " + "'http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise.");
+  }
   const maybeApiKey = opts.apiKey || process.env.VAL_API_KEY;
   const maybeValSecret = opts.valSecret || process.env.VAL_SECRET;
   const isProxyMode = opts.mode === "proxy" || opts.mode === undefined && (maybeApiKey || maybeValSecret);

package/package.json

@@ -16,7 +16,7 @@
     "./package.json": "./package.json"
   },
   "types": "dist/valbuild-server.cjs.d.ts",
-  "version": "0.130.0",
+  "version": "0.131.0",
   "devDependencies": {
     "@prettier/sync": "^0.6.1",
     "@types/jest": "^30.0.0"