mikser-io-drive 11.0.5 → 11.2.2

package/.github/workflows/publish.yml

@@ -23,6 +23,15 @@ on:
 jobs:
   publish:
     runs-on: ubuntu-latest
+    # A hung test must not cost six hours.
+    #
+    # Without this the job runs to GitHub's own limit, reporting nothing:
+    # a flaky teardown in one suite sat on `npm test` for seventeen
+    # minutes before anyone looked, and would have sat there all day.
+    # The longest suite in the family is a couple of minutes including
+    # install, so fifteen is generous and still fails while someone is
+    # still watching.
+    timeout-minutes: 15
     permissions:
       contents: read
       # The whole mechanism. Without it npm has nothing to verify.

package/README.md

@@ -149,6 +149,37 @@ creates an empty file** (RFC 4918 §9.10.4). A client that locks before writing
 — Finder's Save As does — leaves an empty document behind even if the write
 never arrives.
 
+## What the folder is called
+
+The endpoint key is the name, and the mount reports it as `displayname`:
+
+```js
+drive({
+    endpoints: {
+        SkinCheck:  { folder: 'skincheck' },              // shows as "SkinCheck"
+        reports:    { folder: 'data', displayName: 'Q3 reports' },
+    },
+})
+```
+
+Without it the label is whatever the client derives from the URL, and that is
+not controllable: Express matches routes case-insensitively, so
+`/drive/SkinCheck` and `/drive/skincheck` reach the same mount and the casing
+shown is whichever the client asked for first — an endpoint renamed to
+`SkinCheck` kept reading `skincheck` in Explorer, and remapping did not change
+it. `@nephele/adapter-file-system` does not implement `displayname` (it is
+commented out of its live-property list with a TODO), so a PROPFIND for it
+answered `404 The displayname property was not found` and the client had nothing
+to go on.
+
+The default is the **key**, not `summary`: `displayname` is a name — RFC 4918
+§15.2, "suitable for presentation to a user" — and the key is already the URL
+segment and what the mount log prints. `summary` is a sentence and reads badly
+as a folder label. `displayName` overrides the key where it is not presentable.
+
+Only the mount root is named. Everything below it is a real file or directory
+whose name the client reads from the path.
+
 ## When a client refuses and the server is right
 
 WebDAV clients cache their **discovery** verdict — not the file listing, the
@@ -173,10 +204,15 @@ afternoon was lost to exactly that: `curl` verified the server correct while
 Explorer kept refusing.
 
 The default adapter advertises `max-age=604800` here. Seven days is a strange
-thing to promise about capabilities that are configuration — flipping
-`readOnly` changes both the compliance classes and the `Allow` list — so this
-plugin overrides it. One cheap request per client session buys the ability to
-change a mount and be believed.
+thing to promise about capabilities that are configuration: `locks: 'disallow'`
+drops class 2 and `LOCK` from `Allow`, and a client can keep acting on the old
+answer for a week. So this plugin overrides it. One cheap request per client
+session buys the ability to change a mount and be believed.
+
+`readOnly` is **not** an example of that, though it reads like one: measured, a
+read-only mount reports the same `DAV: 1, 3, 2` and the same `Allow` list as a
+writable one — PUT and DELETE included — and refuses the write when it arrives.
+nephele's read-only plugin gates requests, not the discovery response.
 
 **`OPTIONS /drive` and `OPTIONS /` answer a plain CORS 204 with no `DAV:`
 header, and that is correct.** There is no resource at the base path: one

package/index.js

@@ -4,6 +4,7 @@ import { registerRoute, resolveAuth, reachabilityOf, registerJunk, registerCapab
 import { MikserAuthenticator } from './lib/authenticator.js'
 import { registerFileTools } from './lib/files.js'
 import { withStagedWrites, stageWrites } from './lib/staged-writes.js'
+import { withDisplayName } from './lib/display-name.js'
 
 export { MikserAuthenticator, withStagedWrites, stageWrites }
 
@@ -43,6 +44,8 @@ export const writeCapability = (name) => `drive:${name}:write`
  *             content: { folder: 'documents' },
  *             media:   { folder: 'files/media' },
  *             data:    { folder: 'data', readOnly: true },
+ *             Reports: { folder: 'reports' },            // shows as "Reports"
+ *             q3:      { folder: 'q3', displayName: 'Q3 reports' },
  *         },
  *         auth: identity,
  *     })
@@ -189,10 +192,15 @@ export function drive(options = {}) {
                 // log on either side, and `Restart-Service WebClient -Force`
                 // the only way out. That is not a remedy anyone guesses.
                 //
-                // And the capabilities here are CONFIGURATION. Flipping
-                // `readOnly` changes both the compliance classes and the Allow
-                // list, so a week-long cache lets a client keep acting on a
-                // shape the mount no longer has.
+                // And the capabilities here are CONFIGURATION.
+                // `locks: 'disallow'` drops class 2 and LOCK from the Allow
+                // list — see test/protocol.test.js — so a week-long cache lets
+                // a client keep acting on a shape the mount no longer has.
+                //
+                // NOT `readOnly`, which was the example first given here and
+                // is wrong: measured, a read-only mount reports the same
+                // classes and the same Allow list as a writable one, and
+                // refuses the write per request instead.
                 //
                 // `no-cache` costs one cheap request per client session and
                 // buys the ability to change a mount and be believed. Set on
@@ -208,13 +216,33 @@ export function drive(options = {}) {
                     // watcher can import a half-written file, and an
                     // interrupted overwrite leaves the ORIGINAL destroyed.
                     // Both measured; see lib/staged-writes.js.
-                    adapter: (ep.atomicWrites === false)
-                        ? fsAdapter
-                        : withStagedWrites(fsAdapter, {
-                            onFailure: (err, file) => logger.warn(
-                                'drive: upload of %s failed, original left intact — %s',
-                                path.basename(file), err.message),
-                        }),
+                    // The mount answers to its own name.
+                    //
+                    // `displayname` is what a client labels the folder with,
+                    // and the adapter does not implement it — so the label was
+                    // whatever each client derived from the URL, which is not
+                    // controllable: Express matches routes case-insensitively,
+                    // so an endpoint renamed to `SkinCheck` went on reading
+                    // `skincheck` in Explorer, from a casing the client had
+                    // cached.
+                    //
+                    // Defaults to the endpoint KEY rather than `summary`.
+                    // displayname is a NAME — RFC 4918 §15.2, "suitable for
+                    // presentation to a user" — and the key is already the URL
+                    // segment and the mount log label, so nothing new has to
+                    // be written down. `summary` is a sentence, which reads
+                    // badly as a folder label. `displayName` overrides it for
+                    // a key that is not presentable.
+                    adapter: withDisplayName(
+                        (ep.atomicWrites === false)
+                            ? fsAdapter
+                            : withStagedWrites(fsAdapter, {
+                                onFailure: (err, file) => logger.warn(
+                                    'drive: upload of %s failed, original left intact — %s',
+                                    path.basename(file), err.message),
+                            }),
+                        ep.displayName ?? name,
+                    ),
                     authenticator,
                     // `readOnly: true` is a hard cap — "nobody writes here",
                     // which is a different statement from "you may not write
@@ -250,6 +278,24 @@ export function drive(options = {}) {
                     // Allow list including LOCK when class 2 is present. This
                     // list is what CORS advertises to browsers; the response
                     // Windows reads comes from nephele.
+                    // No CORS headers on a DAV mount.
+                    //
+                    // They were inherited from the global default, which
+                    // answers `access-control-allow-origin: *` — a claim about
+                    // who may read this endpoint from a web page, made on an
+                    // AUTHENTICATED mount, by nobody in particular. It is not
+                    // an exposure today: the engine never configures
+                    // `credentials: true`, so no browser attaches the Basic
+                    // credentials cross-origin. It is a claim with no
+                    // beneficiary either — this mount's clients are OS WebDAV
+                    // redirectors, CLI tools and curl, none of which consult
+                    // CORS at all.
+                    //
+                    // So it is stated rather than inherited. A project that
+                    // genuinely wants a browser-side DAV client can put the
+                    // endpoint behind its own app.
+                    cors: false,
+
                     // Only the ENDPOINT path is a share. `OPTIONS /drive`
                     // and `OPTIONS /` answer a plain CORS 204 with no `DAV:`
                     // header, and that is right: there is no resource at the

package/lib/display-name.js

@@ -0,0 +1,95 @@
+// The mount's own name, served as `displayname` on its root collection.
+//
+// A WebDAV client shows a folder label. WebDAV has a property for it —
+// RFC 4918 §15.2, "a name for the resource suitable for presentation to a
+// user" — and @nephele/adapter-file-system does not implement it: the name is
+// commented out of its live-property list with a TODO, so a PROPFIND for it
+// answers 404 and the client falls back to guessing from the URL.
+//
+// Guessing from the URL is not controllable. Express matches routes
+// case-insensitively, so `/drive/SkinCheck`, `/drive/skincheck` and
+// `/drive/SKINCHECK` all reach the same mount, and the casing a client ends up
+// displaying is whichever one it happened to ask for first. An endpoint
+// renamed to `SkinCheck` went on reading `skincheck` in Explorer.
+//
+// The name is already written down — it is the ENDPOINTS key, the URL segment
+// and the mount log label — so the site can just answer the question instead.
+//
+// Applied to the root collection only. Every other resource is a real file or
+// directory whose name the client reads from the path, and which the author
+// did not choose in mikser's config.
+
+// The root of a mount. `Resource.path` is relative to the adapter root with a
+// trailing separator stripped, so the mount's own collection is the empty one.
+const isMountRoot = (resource) => resource?.path === ''
+
+// A Properties facade that answers one more question than the one it wraps.
+//
+// PROPFIND reaches properties through the BY-USER variants — listByUser,
+// getAllByUser, getByUser — and the adapter's versions delegate to the plain
+// ones on `this`. A Proxy binds methods to the TARGET, so wrapping only the
+// plain three would leave PROPFIND reading straight past this. Both sets are
+// wrapped, which is why the property actually appears.
+function withDisplayNameProperty(properties, displayName) {
+    const answer = (name, fallback) =>
+        name === 'displayname' ? Promise.resolve(displayName) : fallback()
+    const including = async (listing) => {
+        const names = await listing()
+        return names.includes('displayname') ? names : ['displayname', ...names]
+    }
+
+    return new Proxy(properties, {
+        get(target, prop, receiver) {
+            switch (prop) {
+                case 'get':         return (name) => answer(name, () => target.get(name))
+                case 'getByUser':   return (name, user) => answer(name, () => target.getByUser(name, user))
+                case 'list':        return () => including(() => target.list())
+                case 'listByUser':  return (user) => including(() => target.listByUser(user))
+                case 'listLive':    return () => including(() => target.listLive())
+                case 'listLiveByUser': return (user) => including(() => target.listLiveByUser(user))
+                case 'getAll':      return async () => ({ ...(await target.getAll()), displayname: displayName })
+                case 'getAllByUser': return async (user) => ({ ...(await target.getAllByUser(user)), displayname: displayName })
+            }
+            const value = Reflect.get(target, prop, receiver)
+            return typeof value === 'function' ? value.bind(target) : value
+        },
+    })
+}
+
+function withDisplayNameResource(resource, displayName) {
+    return new Proxy(resource, {
+        get(target, prop, receiver) {
+            if (prop === 'getProperties') {
+                return async () => withDisplayNameProperty(await target.getProperties(), displayName)
+            }
+            const value = Reflect.get(target, prop, receiver)
+            return typeof value === 'function' ? value.bind(target) : value
+        },
+    })
+}
+
+/**
+ * Decorate an adapter so its root collection reports `displayName`.
+ *
+ * Same shape as withStagedWrites, and composes with it: both wrap the three
+ * methods that hand back a resource, and each passes everything else through.
+ *
+ * @param {object} adapter      a nephele adapter
+ * @param {string} displayName  what a client should call this mount
+ */
+export function withDisplayName(adapter, displayName) {
+    if (!displayName) return adapter
+    const wrap = (method) => async (...args) => {
+        const resource = await adapter[method](...args)
+        return isMountRoot(resource) ? withDisplayNameResource(resource, displayName) : resource
+    }
+    return new Proxy(adapter, {
+        get(target, prop, receiver) {
+            if (prop === 'getResource' || prop === 'newResource' || prop === 'newCollection') {
+                return wrap(prop)
+            }
+            const value = Reflect.get(target, prop, receiver)
+            return typeof value === 'function' ? value.bind(target) : value
+        },
+    })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-drive",
-  "version": "11.0.5",
+  "version": "11.2.2",
   "description": "WebDAV for mikser-io. Exposes working-folder directories as WebDAV endpoints via Nephele, authenticated through mikser-io-auth's htpasswd identity — so content can be edited from Finder, Explorer or any DAV client and the build picks the change up.",
   "main": "index.js",
   "type": "module",

package/test/atomic-writes.test.js

@@ -51,6 +51,19 @@ before(async () => {
 })
 
 after(async () => {
+    // Destroy the sockets before closing, or the close never settles.
+    //
+    // `server.close()` waits for every connection to end, and these suites
+    // leave some that never will: fetch() pools keep-alives, and the
+    // interrupted-upload cases abort a request mid-body on purpose. The file's
+    // tests would all pass and the FILE would hang — "Promise resolution is
+    // still pending but the event loop has already resolved" — which in CI is
+    // a job that stops reporting and, before the 15-minute cap, ran until
+    // GitHub's own. It blocked two of today's releases.
+    //
+    // Reproducible with `--test-concurrency=2` (a CI runner's shape; a 16-core
+    // box hides it), and gone with this.
+    server?.closeAllConnections?.()
     await new Promise(r => server?.close(r))
     await rm(dir, { recursive: true, force: true })
 })

package/test/derived.test.js

@@ -156,7 +156,27 @@ before(async (t) => {
 })
 
 after(async () => {
-    server?.kill()
+    // WAIT for it to die, and escalate. `kill()` only sends the signal; the
+    // child's stdout/stderr are pipes we hold, so until it actually exits
+    // those handles keep THIS process alive and the run never ends. Every
+    // test passes and then node sits there — on CI that was fifteen minutes
+    // of nothing, ended by the job timeout and "Terminate orphan process".
+    //
+    // mikser handles SIGTERM itself (instance.js: close(); process.exit(0)),
+    // so the graceful path is the normal one; SIGKILL is the floor for when
+    // close() does not come back.
+    if (server && server.exitCode === null && server.signalCode === null) {
+        const exited = new Promise(resolve => server.once('exit', resolve))
+        server.kill()
+        const inTime = await Promise.race([
+            exited.then(() => true),
+            new Promise(resolve => setTimeout(() => resolve(false), 5000)),
+        ])
+        if (!inTime) {
+            server.kill('SIGKILL')
+            await exited
+        }
+    }
     if (dir) await rm(dir, { recursive: true, force: true })
 })
 

package/test/drive.test.js

@@ -77,6 +77,19 @@ before(async () => {
 })
 
 after(async () => {
+    // Destroy the sockets before closing, or the close never settles.
+    //
+    // `server.close()` waits for every connection to end, and these suites
+    // leave some that never will: fetch() pools keep-alives, and the
+    // interrupted-upload cases abort a request mid-body on purpose. The file's
+    // tests would all pass and the FILE would hang — "Promise resolution is
+    // still pending but the event loop has already resolved" — which in CI is
+    // a job that stops reporting and, before the 15-minute cap, ran until
+    // GitHub's own. It blocked two of today's releases.
+    //
+    // Reproducible with `--test-concurrency=2` (a CI runner's shape; a 16-core
+    // box hides it), and gone with this.
+    server?.closeAllConnections?.()
     await new Promise(r => server?.close(r))
     await rm(dir, { recursive: true, force: true })
 })

package/test/protocol.test.js

@@ -56,6 +56,19 @@ before(async () => {
 })
 
 after(async () => {
+    // Destroy the sockets before closing, or the close never settles.
+    //
+    // `server.close()` waits for every connection to end, and these suites
+    // leave some that never will: fetch() pools keep-alives, and the
+    // interrupted-upload cases abort a request mid-body on purpose. The file's
+    // tests would all pass and the FILE would hang — "Promise resolution is
+    // still pending but the event loop has already resolved" — which in CI is
+    // a job that stops reporting and, before the 15-minute cap, ran until
+    // GitHub's own. It blocked two of today's releases.
+    //
+    // Reproducible with `--test-concurrency=2` (a CI runner's shape; a 16-core
+    // box hides it), and gone with this.
+    server?.closeAllConnections?.()
     await new Promise(r => server?.close(r))
     await rm(dir, { recursive: true, force: true })
 })
@@ -263,3 +276,58 @@ describe('known nephele non-compliance, pinned', () => {
         assert.equal(res.status, 500, 'if this becomes 400, nephele fixed it')
     })
 })
+
+describe('the mount answers to its own name', () => {
+    // A client labels the folder from `displayname`, and
+    // @nephele/adapter-file-system does not implement it — the name is
+    // commented out of its live-property list with a TODO — so a PROPFIND for
+    // it answered 404 and the client fell back to guessing from the URL.
+    //
+    // Guessing is not controllable: Express matches routes case-insensitively,
+    // so `/drive/SkinCheck` and `/drive/skincheck` reach the same mount and the
+    // casing shown is whichever the client asked for first. An endpoint renamed
+    // to `SkinCheck` went on reading `skincheck` in Explorer.
+    const propfind = (ep, body) => fetch(`http://127.0.0.1:${port}/drive/${ep}/`, {
+        method: 'PROPFIND',
+        headers: { authorization: AUTH, 'content-type': 'text/xml', depth: '0' },
+        body,
+    })
+    const NAMED = '<propfind xmlns="DAV:"><prop><displayname/></prop></propfind>'
+    const ALLPROP = '<propfind xmlns="DAV:"><allprop/></propfind>'
+
+    it('reports the endpoint key as displayname, asked for by name', async () => {
+        const res = await propfind('emulated', NAMED)
+        const xml = await res.text()
+        assert.equal(res.status, 207, xml)
+        assert.match(xml, /<[^>]*displayname[^>]*>emulated</,
+            `displayname must carry the endpoint key — got:\n${xml}`)
+        assert.doesNotMatch(xml, /displayname property was not found/, xml)
+    })
+
+    it('includes it in allprop, which is how a client usually asks', async () => {
+        // PROPFIND reaches properties through the BY-USER variants, and the
+        // adapter's delegate to the plain ones on `this` — so a decorator that
+        // wrapped only the plain three would be read straight past. This is the
+        // case that catches that.
+        const xml = await (await propfind('emulated', ALLPROP)).text()
+        assert.match(xml, /<[^>]*displayname[^>]*>emulated</, `allprop must include it — got:\n${xml}`)
+    })
+
+    it('names each endpoint separately, since each is its own mount', async () => {
+        const xml = await (await propfind('readonly', NAMED)).text()
+        assert.match(xml, /<[^>]*displayname[^>]*>readonly</, xml)
+    })
+
+    it('leaves the files inside it alone', async () => {
+        // Only the mount ROOT is named in config. Everything below is a real
+        // file whose name the client reads from the path.
+        const res = await fetch(`http://127.0.0.1:${port}/drive/emulated/page.md`, {
+            method: 'PROPFIND',
+            headers: { authorization: AUTH, 'content-type': 'text/xml', depth: '0' },
+            body: NAMED,
+        })
+        const xml = await res.text()
+        assert.doesNotMatch(xml, /<[^>]*displayname[^>]*>emulated</,
+            `a file must not inherit the mount's name — got:\n${xml}`)
+    })
+})

package/test/real-client.test.js

@@ -67,6 +67,19 @@ before(async () => {
 })
 
 after(async () => {
+    // Destroy the sockets before closing, or the close never settles.
+    //
+    // `server.close()` waits for every connection to end, and these suites
+    // leave some that never will: fetch() pools keep-alives, and the
+    // interrupted-upload cases abort a request mid-body on purpose. The file's
+    // tests would all pass and the FILE would hang — "Promise resolution is
+    // still pending but the event loop has already resolved" — which in CI is
+    // a job that stops reporting and, before the 15-minute cap, ran until
+    // GitHub's own. It blocked two of today's releases.
+    //
+    // Reproducible with `--test-concurrency=2` (a CI runner's shape; a 16-core
+    // box hides it), and gone with this.
+    server?.closeAllConnections?.()
     await new Promise(r => server?.close(r))
     await rm(dir, { recursive: true, force: true })
 })