mikser-io 11.6.0 → 11.8.0

package/docs/diagnostics.md

@@ -1044,6 +1044,7 @@ distinction is the whole of [Faults](#faults) above.
 | Code | Severity | Means |
 | --- | --- | --- |
 | `config-coverage-partial` | warn | This Node build has no module loader hooks, so the config stamp covers the entry file alone. Editing an imported module will not invalidate the cache. |
+| `config-stale-in-process` | warn | A config file changed on disk while `--watch` is running. Node has the module cached and config is only read at startup, so this rebuild and every one after it uses the logic the process booted with. Restart to pick it up. |
 | `durable-open` | error | The durable store could not be opened. Auth grants and the change-set log are unavailable. |
 | `durable-migration` | error | A registered migration failed. |
 | `durable-gitignore` | error | The durable store could not be added to `.gitignore` — it holds credentials and the working folder is usually a repo. |
@@ -1063,6 +1064,7 @@ distinction is the whole of [Faults](#faults) above.
 
 | Code | Severity | Means |
 | --- | --- | --- |
+| `source-content-not-text` | warn | A `sources()` collection with `content: true` loaded a file whose bytes are not text. They are decoded as UTF-8 and stored mangled, and every consumer inherits that. Set `content: false` to catalogue the files by path instead — `entity.uri` still points at them. Once per collection. |
 | `observer-bad-uri` | warn | An observer's `uri` is not an absolute URL, so no webhook can be routed to it. |
 | `untracked-file-read` | warn | A template read a file outside every folder mikser takes entities from, so it has no entity and changing it invalidates nothing. |
 | `progress` | info | A long phase reporting where it has got to. See [Progress](#progress). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "11.6.0",
+  "version": "11.8.0",
   "files": [
     "app.js",
     "index.js",

package/src/instance.js

@@ -288,7 +288,7 @@ function configMismatch(theirs) {
 // configCoverage lists every local module the config graph pulled in, so a
 // stat over that list catches an edit to an imported module — which a
 // client-side checksum of the entry file would miss entirely.
-async function configStale() {
+export async function configStale() {
     const covered = runtime.options.configCoverage?.files ?? []
     if (!covered.length) return null
     const { stat } = await import('node:fs/promises')

package/src/manager.js

@@ -4,6 +4,7 @@ import cron from 'node-cron'
 import { onProcess, onFinalized } from './lifecycle.js'
 import { resetReport } from './report.js'
 import { useLogger } from './engine/index.js'
+import { configStale } from './instance.js'
 import { ACTION } from './constants.js'
 import { junkFilter } from './utils/index.js'
 
@@ -22,12 +23,52 @@ const tasks = []
 // would wipe it out of a one-shot build's report.
 function scheduleProcess() {
     clearTimeout(runtime.engine.processTimeout)
-    runtime.engine.processTimeout = setTimeout(() => {
+    runtime.engine.processTimeout = setTimeout(async () => {
+        await warnConfigStale()
         resetReport()
         runtime.process()
     }, 1000)
 }
 
+// Editing config/*.js while watching changes nothing, and says nothing.
+//
+// Node has the module cached, and the config stamp is only compared at
+// startup — that is where "Config changed since the last run. Wiping the
+// cache…" comes from. So a watch process keeps running the logic it booted
+// with, rebuilds happily, and reports green. Reported after it cost a
+// consumer several rounds: a derivation plugin they had already fixed kept
+// producing the old output, every symptom pointed at the data rather than at
+// the process, and they reported it as broken twice before finding it.
+//
+// The check already exists — instance.js compares mtimes across
+// configCoverage.files to refuse a forwarded command against drifted config.
+// It just never ran on this path, where no client is asking.
+//
+// A warning, not a reload: re-importing a config module does not re-run the
+// plugin registration that happened at boot, so a "reload" that only
+// refreshed the module would be a more convincing version of the same lie.
+// Restarting is the honest fix, and mikser_ping already reports `stale` for
+// packages installed since boot on exactly this reasoning.
+async function warnConfigStale() {
+    if (runtime.options.watch !== true) return
+    let changed = null
+    try {
+        changed = await configStale()
+    } catch { return }          // never let a diagnostic break the rebuild
+    if (!changed || changed === configStaleReported) return
+    configStaleReported = changed
+    useLogger().warn(
+        { code: 'config-stale-in-process', file: changed },
+        'Config changed on disk (%s) but this process is still running the version it started with — '
+        + 'Node has the module cached and config is only re-read at startup. This rebuild, and every one '
+        + 'after it, uses the OLD logic. Restart to pick it up.',
+        changed)
+}
+
+// One warning per file, so a watch session editing the same module in a loop
+// does not print it on every save — and a DIFFERENT file still speaks up.
+let configStaleReported = null
+
 export async function createdHook(name, context) {
     if (!runtime.started) return
 

package/src/routes.js

@@ -50,7 +50,12 @@ const DEFAULT_AUTH_LABEL = {
 // an origin is known — public --url / config.url wins (clickable,
 // shareable), localhost:port is the dev fallback — bare path when the
 // engine doesn't own a listener (external-app embedding, no url set).
-export function routeLocation(displayPath) {
+export function routeLocation(displayPath, host) {
+    // A host-scoped route HAS an origin, and it is not this server's. Printing
+    // `http://localhost:3001//drive.example.com/` names a place nothing
+    // answers. Protocol-relative because the scheme belongs to whatever
+    // terminates TLS in front, which this process does not know.
+    if (host) return `//${host}${displayPath === '/' ? '/' : displayPath}`
     const origin = runtime.options.url
         ?? (runtime.options.port ? `http://localhost:${runtime.options.port}` : null)
     return origin ? `${origin}${displayPath}` : displayPath
@@ -62,12 +67,21 @@ export function routeLocation(displayPath) {
 // '/drive') answers for its own requests rather than its parent's. Exported
 // because the CORS middleware needs the same answer Express will reach, and a
 // second implementation of "which mount is this" would drift from this one.
-export function routeFor(requestPath) {
+export function routeFor(requestPath, host) {
     if (!requestPath) return null
     let best = null
     for (const route of runtime.routes ?? []) {
+        // A host-scoped route answers for its own domain and no other.
+        if (route.host && route.host !== host) continue
         const base = route.path
-        if (requestPath !== base && !requestPath.startsWith(`${base}/`)) continue
+        // A host-scoped route mounted at `/` owns every path on that host —
+        // it IS the server there. Prefix matching cannot express that, since
+        // nothing starts with `//`. An unscoped route at `/` is left alone:
+        // it would otherwise swallow the whole site.
+        const owns = base === '/' && route.host
+            ? true
+            : requestPath === base || requestPath.startsWith(`${base}/`)
+        if (!owns) continue
         if (!best || base.length > best.path.length) best = route
     }
     return best
@@ -87,6 +101,10 @@ export function routeFor(requestPath) {
 //                 facade must disable buffering for it (Caddy
 //                 flush_interval -1, nginx proxy_buffering off).
 //                 Default false.
+//   host          when set, the mount answers only for this Host. Used
+//                 by a route that takes a domain of its own — a WebDAV
+//                 share at `/` on `drive.example.com`, say, which would
+//                 otherwise shadow every page on the site.
 //   cors          `false` to emit no CORS headers for this mount. The
 //                 same word as the global `--no-cors` /
 //                 `config.server.cors: false`, meaning the same thing,
@@ -138,6 +156,7 @@ export function registerRoute({
     streaming = false,
     methods = null,
     cors,
+    host,
     label,
     detail,
     displayPath,
@@ -162,6 +181,7 @@ export function registerRoute({
     const descriptor = { path, plugin, reachability, streaming }
     if (methods) descriptor.methods = methods.map(m => m.toUpperCase())
     if (cors === false) descriptor.cors = false
+    if (host) descriptor.host = host
 
     // Dedup by path — a re-register (same path) replaces rather than
     // duplicates. Mounts happen once per process, but this keeps the
@@ -172,7 +192,7 @@ export function registerRoute({
 
     const logger = useLogger()
     if (logger) {
-        const location = routeLocation(displayPath ?? path)
+        const location = routeLocation(displayPath ?? path, host)
         const bracket  = authLabel ?? DEFAULT_AUTH_LABEL[reachability]
         logger.info('%s mounted: %s [%s]%s',
             label ?? plugin, location, bracket, detail ? ` ${detail}` : '')

package/src/server.js

@@ -223,7 +223,7 @@ export function setupServer() {
             // because routes are registered at onLoaded and this middleware
             // at onLoad — it is mounted before any of them exist, and every
             // request arrives long after they all do.
-            const route = routeFor(req.path ?? req.url)
+            const route = routeFor(req.path ?? req.url, req.hostname)
 
             // Does that mount answer OPTIONS itself?
             //
@@ -249,6 +249,36 @@ export function setupServer() {
             // PROPFIND, LOCK and the rest.
             const ownsPreflight = Boolean(route?.methods?.includes('OPTIONS'))
 
+            // A bare OPTIONS is not a preflight, and must not be answered as
+            // one.
+            //
+            // A CORS preflight is defined by its headers: the browser sends
+            // `Access-Control-Request-Method`, and without it the request is
+            // something else entirely. This middleware used to answer ALL of
+            // them — so every path on the site, routed or not, replied 204 to
+            // any OPTIONS with a list of five REST verbs and no `DAV:` header.
+            //
+            // That is a manufactured "I exist and I am not WebDAV", and it is
+            // a stronger negative than the 404 a static path would otherwise
+            // give. The Microsoft WebDAV redirector establishes a session by
+            // walking up from the path it was given, and on a mikser site
+            // every level of that walk answered no — including `/` and
+            // `/drive`, neither of which is anything. Deployments that DO map
+            // on Windows (Nextcloud at /remote.php/dav, SharePoint) sit behind
+            // hosts that simply have nothing to say at those paths.
+            //
+            // Falling through costs nothing a browser wanted: a real preflight
+            // still carries the header and is still answered below, and a
+            // non-preflight OPTIONS now reaches whatever owns the path — the
+            // mount's own discovery response, or the static handler's 404.
+            //
+            // `origin: false` is how the package steps aside: with a falsy
+            // origin it never builds an originCallback, so it calls next()
+            // without touching the response (cors/lib/index.js:210-228).
+            if (req.method === 'OPTIONS' && !req.headers['access-control-request-method']) {
+                return callback(null, { origin: false })
+            }
+
             // A route that wants no CORS headers at all.
             //
             // `origin: false` is the cors package's way of emitting none — the

package/src/source.js

@@ -44,7 +44,7 @@ import pMap from 'p-map'
 import runtime from './runtime.js'
 import { useLogger } from './engine/index.js'
 import { ACTION } from './constants.js'
-import { checksum as fileChecksum, checksumOf, junkIgnore } from './utils/index.js'
+import { checksum as fileChecksum, checksumOf, junkIgnore, looksTextual } from './utils/index.js'
 import { reportGated, reportChanged } from './report.js'
 import { findById, findEntities, checksumsByCollection } from './catalog.js'
 import { bypassReason } from './invalidation.js'
@@ -293,6 +293,39 @@ export function scanSummary({ cap, loaded, emitted = 0, skipped = 0, deleted = 0
  *     called per file; returned object is merged onto the base entity.
  *     Return null to skip a file.
  */
+// Collections already warned about a `content: true` binary. Module-level so
+// the warning survives across cycles — a watch rebuild re-reads the same
+// files, and repeating it every cycle is how a warning gets filtered out.
+const binaryWarned = new Set()
+
+// `content: true` is right for the CSS and template parts useSource was built
+// for, and wrong in silence for a binary. `toString('utf8')` never fails: it
+// substitutes U+FFFD and returns a string, so a 4 MB PDF becomes 4 MB of
+// mangled text and every consumer downstream inherits it.
+//
+// Reported by mikser-io-ocr, which sent one as a prompt and got back "Your
+// input exceeds the context window of this model" — an error that names the
+// document, so the reader goes and looks at the PDF rather than at the
+// collection's config.
+//
+// Returns whether it warned, so the decision is testable without reading logs.
+export function warnIfNotText(collection, name, bytes, logger) {
+    if (binaryWarned.has(collection)) return false
+    if (looksTextual(bytes.subarray(0, SNIFF_BYTES))) return false
+    binaryWarned.add(collection)
+    logger?.warn(
+        { code: 'source-content-not-text', collection, sample: name },
+        'Source %j has `content: true` but %j is not text — its bytes are being decoded as UTF-8 and stored ' +
+        'mangled. Set `content: false` on the collection to catalogue these files by path instead ' +
+        '(entity.uri still points at them).',
+        collection, name)
+    return true
+}
+
+// Same prefix the filesystem provider sniffs (src/utils/entity.js). Enough
+// to see a file header without decoding a whole document twice.
+const SNIFF_BYTES = 8 * 1024
+
 export function useSource(core, options) {
     const {
         runtime,
@@ -559,6 +592,20 @@ export function useSource(core, options) {
             // Decoded from the bytes the checksum was taken over — not
             // re-read. See the gate above.
             base.content = bytes.toString('utf8')
+
+            // `content: true` is right for the CSS and template parts this
+            // was built for, and wrong in silence for a binary. toString
+            // never fails: it substitutes U+FFFD and hands back a string, so
+            // a 4 MB PDF becomes 4 MB of mangled text and every consumer
+            // downstream inherits it. Reported by mikser-io-ocr, which sent
+            // one as a prompt and got back "Your input exceeds the context
+            // window of this model" — an error that names the document and
+            // sends the reader to the PDF rather than to this line.
+            //
+            // Once per collection, not per file: a media folder catalogued
+            // this way is all binaries, and the fix is one setting either
+            // way.
+            warnIfNotText(collection, name, bytes, logger)
         }
         try {
             const extra = await load({ file, name, relativePath, entity: base })