mikser-io-drive 11.3.0 → 11.3.1

package/README.md

@@ -353,6 +353,45 @@ class of problem from Nephele's four known gaps, and it carries 65 open issues
 against Nephele's zero. Nephele is also Apache-2.0 and load-bearing for its
 author's own product, which is the maintenance signal that matters most.
 
+**Writing it here was considered and is not close.** RFC 4918 is about 4,650
+lines in Nephele — 2,994 of method handlers and 1,662 of machinery — and the
+weight is not where it looks:
+
+| | lines | |
+| --- | --- | --- |
+| `Method.js` | 930 | the base class every method inherits |
+| — `checkIfHeader` | 234 | the `If:` header alone |
+| — `checkConditionalHeaders` | 77 | |
+| `LOCK` + `UNLOCK` | 442 | plus 81 lock references threaded through `Method.js` |
+| `MOVE` + `COPY` | 438 | `Depth` and `Overwrite` semantics |
+| `PROPFIND` | 276 | |
+| `GET`/`HEAD` | 286 | ranges, etags |
+
+Listing files is the cheap part. `If:` is a grammar rather than a value —
+tagged and untagged lists, `Not`, lock tokens and etags mixed, evaluated
+against resources other than the request target — and getting it wrong means
+Finder's Save As either walks over somebody's lock or refuses forever. Locking
+is not isolated in `LOCK.js` either: provisional locks, timeouts, per-user lock
+permission and token extraction run on every write method.
+
+And the litmus column above is what would be given up: 95 of 104 on
+`meta-files`, with four known gaps named and pinned. A hand-written server
+starts at zero and earns each point by a client breaking in someone's hands.
+
+The read-only case is genuinely different — `OPTIONS` + `PROPFIND` + `GET` with
+no locking and no conditionals is a few hundred lines, and the drive root in
+`lib/root-listing.js` is already that shape. It is not the case anyone is
+asking for.
+
+**The sharper version of the question is the ADAPTER, not the engine.** Three
+things have been worked around here, and all three are in
+`@nephele/adapter-file-system` rather than in the protocol: `displayname`
+commented out of its live-property list with a TODO, a flat `max-age=604800` on
+the OPTIONS response, and a read-only mount advertising `PUT` in `Allow`. The
+adapter answers "what is at this path and what are its properties", which is
+the thin half. If it keeps costing, replace it and keep the 4,650 lines that
+matter.
+
 Staying on Nephele. If its gaps ever become the binding constraint, the
 serious alternative is not another npm package — it is **Apache `mod_dav`**,
 the implementation litmus was written to test, which reads `htpasswd` and

package/index.js

@@ -47,9 +47,12 @@ export const writeCapability = (name) => `drive:${name}:write`
  *             data:    { folder: 'data', readOnly: true },
  *             Reports: { folder: 'reports' },            // shows as "Reports"
  *             q3:      { folder: 'q3', displayName: 'Q3 reports' },
- *             share:   { folder: 'share', host: 'drive.example.com' },
  *         },
  *         auth: identity,
+ *         // A domain of its own, where `/` lists the endpoints the caller
+ *         // may read. Belongs to the DRIVE, not to one endpoint: the whole
+ *         // point is that several endpoints share it.
+ *         host: 'drive.example.com',
  *     })
  *
  * One Nephele server per endpoint, mounted at `<base>/<name>` — the same
@@ -145,6 +148,18 @@ export function drive(options = {}) {
                 if (!ep.folder) {
                     throw new Error(`drive: endpoint ${JSON.stringify(name)} declares no folder`)
                 }
+                // `host` belongs to the drive, not to an endpoint — several
+                // endpoints share one domain, and `/` on it lists them. Said
+                // out loud because the alternative is a config that reads as
+                // though it works and does nothing: this option was
+                // per-endpoint while it was being designed, and the example in
+                // this file's own JSDoc showed it that way after it moved.
+                if (ep.host) {
+                    logger.warn(
+                        'drive: endpoint %j sets `host`, which is a plugin-level option and is ignored here. '
+                        + 'Move it beside `endpoints`: drive({ host: %j, endpoints: { … } }).',
+                        name, ep.host)
+                }
                 const root = resolve(ep.folder)
                 const mountPath = `${base}/${name}`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-drive",
-  "version": "11.3.0",
+  "version": "11.3.1",
   "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/root-listing.test.js

@@ -113,6 +113,32 @@ after(async () => {
     await rm(dir, { recursive: true, force: true })
 })
 
+describe('host in the wrong place', () => {
+    // It was per-endpoint while this was being designed, and moved to the
+    // plugin when the root listing arrived — several endpoints share one
+    // domain, and `/` on it lists them. This file's own JSDoc went on showing
+    // the old shape, which is a config that reads as though it works and does
+    // nothing at all. So it says so.
+    it('warns instead of silently ignoring it', async () => {
+        const said = []
+        const core = {
+            runtime,
+            onLoad:    () => {},
+            onLoaded:  (cb) => said.push(cb),
+            useLogger: () => ({
+                info(){}, error(){}, debug(){}, trace(){},
+                warn: (...args) => said.push(args.join(' ')),
+            }),
+        }
+        drive({ endpoints: { Share: { folder: 'documents', host: 'drive.example.test' } } })(core)
+        for (const entry of [...said]) if (typeof entry === 'function') await entry()
+
+        const warning = said.find(entry =>
+            typeof entry === 'string' && entry.includes('plugin-level option'))
+        assert.ok(warning, `no warning about a misplaced host:\n${said.filter(e => typeof e === 'string').join('\n')}`)
+    })
+})
+
 describe('the drive root on its own host', () => {
     it('announces itself as WebDAV, which is what the redirector asks first', async () => {
         // Answered without credentials on purpose: this is discovery, and it