javascript-solid-server 0.0.225 → 0.0.227

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -15,6 +15,8 @@
15
15
  * static-site exporters — and gives Phase 2 a zero-network fast path.
16
16
  */
17
17
 
18
+ import { readFileSync } from 'node:fs';
19
+
18
20
  /**
19
21
  * Cap on how much JSON-LD we'll inline. A 256 KB resource fits any
20
22
  * realistic profile, type index, or container listing. Above that we
@@ -245,6 +247,137 @@ export function roundTripOptimizationScript() {
245
247
  </script>`;
246
248
  }
247
249
 
250
+ /**
251
+ * Panes loaded at start-up (#652).
252
+ *
253
+ * The server can be given a list of pane module URLs (`--panes`). Each is
254
+ * an ES module whose default export is a SolidOS pane. The data browser
255
+ * page loads and registers them before it starts SolidOS, so they are in
256
+ * the registry at first render and mashlib itself is unchanged.
257
+ *
258
+ * The loader is pane-loader (https://github.com/melvincarvalho/pane-loader),
259
+ * shipped beside this file and served at PANE_LOADER_PATH.
260
+ */
261
+ export const PANE_LOADER_PATH = '/.well-known/jss/pane-loader.js';
262
+
263
+ /** How long the page waits for panes before starting SolidOS anyway. */
264
+ export const PANE_LOAD_TIMEOUT_MS = 5000;
265
+
266
+ // The loader URL carries the package version, so a browser or proxy cache
267
+ // never pairs a new page with an old loader after an upgrade.
268
+ let loaderVersion = '0';
269
+ try {
270
+ loaderVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version || '0';
271
+ } catch { /* unversioned URL: still correct, only less cache-friendly */ }
272
+ const PANE_LOADER_URL = `${PANE_LOADER_PATH}?v=${encodeURIComponent(loaderVersion)}`;
273
+
274
+ /**
275
+ * Turn the `panes` option into a clean list of URLs. Accepts an array or
276
+ * a comma-separated string (CLI flag, env var). Keeps http(s) URLs and
277
+ * absolute paths on this server; anything else is dropped, so a typo
278
+ * cannot become a relative import from whatever page is on show.
279
+ *
280
+ * The string form splits on every comma. A pane URL that contains a comma
281
+ * has to be given in the array form (config file).
282
+ * @param {string[]|string|undefined|null|false} value
283
+ * @returns {string[]}
284
+ */
285
+ export function normalizePanes(value) {
286
+ return sortPanes(value).urls;
287
+ }
288
+
289
+ /**
290
+ * As normalizePanes, and also says which entries were dropped, so the CLI
291
+ * can tell the operator instead of ignoring them silently.
292
+ * @param {string[]|string|undefined|null|false} value
293
+ * @returns {{urls: string[], dropped: string[]}}
294
+ */
295
+ export function sortPanes(value) {
296
+ const urls = [];
297
+ const dropped = [];
298
+ if (!value) return { urls, dropped };
299
+ const list = Array.isArray(value) ? value : String(value).split(',');
300
+ for (const item of list) {
301
+ const url = typeof item === 'string' ? item.trim() : item;
302
+ if (url === '') continue;
303
+ const ok = typeof url === 'string' &&
304
+ (/^https?:\/\/[^\s]+$/i.test(url) || /^\/(?!\/)[^\s]*$/.test(url));
305
+ if (!ok) { dropped.push(String(url)); continue; }
306
+ if (!urls.includes(url)) urls.push(url);
307
+ }
308
+ return { urls, dropped };
309
+ }
310
+
311
+ /** JSON for use inside an inline script: no `<`, so no early `</script>`. */
312
+ function scriptJson(value) {
313
+ return JSON.stringify(value)
314
+ .replace(/</g, '\\u003c')
315
+ .replace(/\u2028/g, '\\u2028')
316
+ .replace(/\u2029/g, '\\u2029');
317
+ }
318
+
319
+ /**
320
+ * Load the configured panes, then start SolidOS. This function is written
321
+ * into the page as source (`toString()`), so it uses nothing from this
322
+ * module and is exported only so that it can be tested.
323
+ *
324
+ * - It always starts SolidOS, once: when every pane has been dealt with or
325
+ * after `timeoutMs`, whichever comes first. A loader that cannot be
326
+ * imported is logged and SolidOS starts without panes.
327
+ * - All pane modules are fetched at once, so a slow or dead host delays
328
+ * only its own pane, never the ones listed after it.
329
+ * - Panes are registered in the order configured. One that is still
330
+ * loading at `timeoutMs` is registered when it arrives; the registry is
331
+ * read at render time, so it is offered from the next view drawn, and
332
+ * the view already on show is not redrawn under the person using it.
333
+ *
334
+ * @param {string[]} urls pane module URLs
335
+ * @param {string} loaderUrl URL of pane-loader.js
336
+ * @param {number} timeoutMs longest wait before SolidOS starts
337
+ * @param {(url: string) => Promise<object>} [load] import function (tests)
338
+ * @returns {Promise<void>} settles when SolidOS has been started
339
+ */
340
+ export function jssStartDataBrowser(urls, loaderUrl, timeoutMs, load) {
341
+ load = load || function (url) { return import(url); };
342
+ var started = false;
343
+ function start() { if (!started) { started = true; panes.runDataBrowser(); } }
344
+ var gate = new Promise(function (resolve) { setTimeout(resolve, timeoutMs); });
345
+ gate.then(start);
346
+ return load(loaderUrl).then(function (loader) {
347
+ function add(url) {
348
+ return loader.loadPane(url).then(function (r) {
349
+ if (r.ok) console.info('[jss] pane "' + r.name + '" loaded from ' + url + (started ? ' (after start-up)' : ''));
350
+ else console.warn('[jss] pane skipped: ' + url + ': ' + r.reason);
351
+ });
352
+ }
353
+ var arrived = urls.map(function () { return false; });
354
+ var fetched = urls.map(function (url, i) {
355
+ // Warm the module cache; loadPane imports the same URL again from it.
356
+ return load(url).then(function () {}, function () {}).then(function () { arrived[i] = true; });
357
+ });
358
+ var chain = Promise.resolve();
359
+ urls.forEach(function (url, i) {
360
+ chain = chain
361
+ .then(function () { return Promise.race([fetched[i], gate]); })
362
+ .then(function () {
363
+ if (arrived[i]) return add(url);
364
+ fetched[i].then(function () { return add(url); });
365
+ });
366
+ });
367
+ return chain;
368
+ }).catch(function (e) {
369
+ console.warn('[jss] panes not loaded: ' + (e && e.message ? e.message : e));
370
+ }).then(start);
371
+ }
372
+
373
+ /** The inline source for the page: the function above, and its call. */
374
+ function paneStartScript(paneUrls) {
375
+ return {
376
+ fn: `\n${jssStartDataBrowser.toString()}\n`,
377
+ call: `jssStartDataBrowser(${scriptJson(paneUrls)}, ${scriptJson(PANE_LOADER_URL)}, ${PANE_LOAD_TIMEOUT_MS})`
378
+ };
379
+ }
380
+
248
381
  /**
249
382
  * Generate Mashlib databrowser HTML
250
383
  *
@@ -255,6 +388,10 @@ export function roundTripOptimizationScript() {
255
388
  * as a `<script type="application/ld+json">` data island. Accepts a
256
389
  * UTF-8 string or a Buffer (coerced via `String()`). Honors a 256 KB
257
390
  * size cap; oversize payloads are silently dropped. Phase 1 of #7.
391
+ * @param {string[]|string} [opts.panes] - Pane module URLs to load and
392
+ * register before SolidOS starts (#652). Empty or absent: the page is
393
+ * unchanged. Not applied by `generateModuleDatabrowserHtml`: a module
394
+ * entry point starts itself, so that mode needs its own design.
258
395
  * @param {boolean} [opts.roundTripOptimization=true] - Inline a small
259
396
  * reader script that lets rdflib-based clients (mashlib and friends)
260
397
  * resolve `fetcher.load(uri)` from the data island instead of issuing
@@ -265,6 +402,11 @@ export function roundTripOptimizationScript() {
265
402
  export function generateDatabrowserHtml(resourceUrl, cdnVersion = null, opts = {}) {
266
403
  const island = dataIsland(resourceUrl, opts.embedJsonLd);
267
404
  const reader = opts.roundTripOptimization === false ? '' : roundTripOptimizationScript();
405
+ const paneUrls = normalizePanes(opts.panes);
406
+ // With no panes configured the page is exactly what it was before #652.
407
+ const paneStart = paneUrls.length ? paneStartScript(paneUrls) : null;
408
+ const start = paneStart ? paneStart.call : 'panes.runDataBrowser()';
409
+ const startFn = paneStart ? paneStart.fn : '';
268
410
  if (cdnVersion) {
269
411
  // CDN mode - use script.onload to ensure mashlib is fully loaded before init
270
412
  // This avoids race conditions with defer + DOMContentLoaded
@@ -274,11 +416,11 @@ export function generateDatabrowserHtml(resourceUrl, cdnVersion = null, opts = {
274
416
  <body id="PageBody">${island}${reader}<header id="PageHeader"></header>
275
417
  <div class="TabulatorOutline" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div>
276
418
  <footer id="PageFooter"></footer>
277
- <script>
419
+ <script>${startFn}
278
420
  (function() {
279
421
  var s = document.createElement('script');
280
422
  s.src = '${cdnBase}/mashlib.min.js';
281
- s.onload = function() { panes.runDataBrowser(); };
423
+ s.onload = function() { ${start}; };
282
424
  s.onerror = function() { document.body.innerHTML = '<p>Failed to load Mashlib from CDN</p>'; };
283
425
  document.head.appendChild(s);
284
426
  })();
@@ -286,8 +428,8 @@ export function generateDatabrowserHtml(resourceUrl, cdnVersion = null, opts = {
286
428
  }
287
429
 
288
430
  // Local mode - use defer (reliable when served locally)
289
- return `<!doctype html><html><head><meta charset="utf-8"/><title>SolidOS Web App</title><script>document.addEventListener('DOMContentLoaded', function() {
290
- panes.runDataBrowser()
431
+ return `<!doctype html><html><head><meta charset="utf-8"/><title>SolidOS Web App</title><script>${startFn}document.addEventListener('DOMContentLoaded', function() {
432
+ ${start}
291
433
  })</script><script defer="defer" src="/mashlib.min.js"></script><link href="/mash.css" rel="stylesheet"></head><body id="PageBody">${island}${reader}<header id="PageHeader"></header><div class="TabulatorOutline" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div><footer id="PageFooter"></footer></body></html>`;
292
434
  }
293
435
 
@@ -0,0 +1,95 @@
1
+ // pane-loader.js — load SolidOS panes at run time, from URLs. No dependencies, no build.
2
+ //
3
+ // This is the copy shipped with JSS, from https://github.com/melvincarvalho/pane-loader
4
+ // with one difference: the upstream file ends with a convenience that loads whatever panes
5
+ // are named in its own URL (`pane-loader.js?pane=URL`). That is left out here, so the only
6
+ // panes this server loads are the ones in its `--panes` list.
7
+ //
8
+ // A dynamically loaded pane is an ES module at a URL whose default export is a SolidOS pane:
9
+ // { name, label(subject, context), render(subject, context), icon?, ... }. Nothing about the pane
10
+ // changes; only how it reaches the registry. See https://melvincarvalho.github.io/solidos-panes/#dynamic
11
+ //
12
+ // Works with released SolidOS as it is: mashlib puts the solid-panes module on the page as
13
+ // `window.panes`, and `panes.register` is all this needs.
14
+ //
15
+ // import { loadPanes } from './pane-loader.js'
16
+ // await loadPanes(['https://alice.example/public/panes/hello-pane.js'])
17
+
18
+ /** Is this object usable as a SolidOS pane? The same test `register` applies, plus render. */
19
+ export function isPane (p) {
20
+ return !!p && typeof p.name === 'string' && p.name !== '' &&
21
+ typeof p.label === 'function' && typeof p.render === 'function'
22
+ }
23
+
24
+ /**
25
+ * Load one pane module and register it. Never throws: a pane that cannot be loaded is skipped.
26
+ * @param {string} url URL of an ES module whose default export is a pane
27
+ * @param {object} [options]
28
+ * @param {object} [options.panes] the solid-panes module (default: the page's `panes`)
29
+ * @returns {Promise<{url: string, ok: boolean, name?: string, already?: boolean, reason?: string}>}
30
+ */
31
+ export async function loadPane (url, options = {}) {
32
+ const panes = options.panes || globalThis.panes
33
+ if (!panes || typeof panes.register !== 'function') {
34
+ return { url, ok: false, reason: 'no SolidOS pane registry on this page (window.panes.register)' }
35
+ }
36
+ let pane
37
+ try {
38
+ pane = (await import(url)).default
39
+ } catch (err) {
40
+ return { url, ok: false, reason: 'import failed: ' + (err && err.message ? err.message : err) }
41
+ }
42
+ if (!isPane(pane)) {
43
+ return { url, ok: false, reason: 'default export is not a pane (needs name, label, render)' }
44
+ }
45
+ const existing = (panes.list || []).find(p => p.name === pane.name)
46
+ if (existing === pane) return { url, ok: true, name: pane.name, already: true } // same module, loaded before
47
+ if (existing) return { url, ok: false, name: pane.name, reason: 'a different pane with this name is already registered' }
48
+ panes.register(pane)
49
+ return { url, ok: true, name: pane.name }
50
+ }
51
+
52
+ /**
53
+ * Load several panes, in order, then redraw the current subject so that new panes are offered.
54
+ * @param {string[]} urls
55
+ * @param {object} [options]
56
+ * @param {object} [options.panes] the solid-panes module (default: the page's `panes`)
57
+ * @param {boolean} [options.refresh] redraw the current subject afterwards (default true)
58
+ * @param {boolean} [options.show] open the last loaded pane that applies to the current subject
59
+ * @param {string} [options.subject] URL of the thing on show, when it is not the page's own URL
60
+ * @returns {Promise<Array>} one result per URL, see loadPane
61
+ */
62
+ export async function loadPanes (urls, options = {}) {
63
+ const results = []
64
+ for (const url of urls) {
65
+ const r = await loadPane(url, options)
66
+ results.push(r)
67
+ if (r.ok) console.info('[pane-loader] ' + (r.already ? 'already have' : 'registered') + ' "' + r.name + '" from ' + url)
68
+ else console.warn('[pane-loader] skipped ' + url + ': ' + r.reason)
69
+ }
70
+ if (options.refresh !== false && results.some(r => r.ok)) refresh(results, options)
71
+ return results
72
+ }
73
+
74
+ // Redraw the subject the data browser is showing. If `show` is set, open the newest loaded pane
75
+ // whose label accepts the subject; otherwise let SolidOS choose as usual (the new pane is a tab).
76
+ function refresh (results, options) {
77
+ const panes = options.panes || globalThis.panes
78
+ const $rdf = globalThis.$rdf
79
+ if (!panes || !$rdf || typeof panes.getOutliner !== 'function' || typeof document === 'undefined') return
80
+ try {
81
+ const outliner = panes.getOutliner(document)
82
+ const subject = $rdf.sym(options.subject || location.href.split('#')[0])
83
+ let pane
84
+ if (options.show) {
85
+ const context = outliner.context || {}
86
+ for (const r of results.filter(r => r.ok).reverse()) {
87
+ const p = panes.byName(r.name)
88
+ try { if (p && p.label(subject, context)) { pane = p; break } } catch (e) { /* a label that throws is a no */ }
89
+ }
90
+ }
91
+ outliner.GotoSubject(subject, true, pane, true, undefined)
92
+ } catch (err) {
93
+ console.warn('[pane-loader] could not redraw the page: ' + (err && err.message ? err.message : err))
94
+ }
95
+ }
package/src/server.js CHANGED
@@ -4,6 +4,7 @@ import rateLimit from '@fastify/rate-limit';
4
4
  import websocket from '@fastify/websocket';
5
5
  import { readFile } from 'fs/promises';
6
6
  import { readFileSync } from 'fs';
7
+ import { normalizePanes, PANE_LOADER_PATH } from './mashlib/index.js';
7
8
  import { STATUS_CODES } from 'node:http';
8
9
  import { join, dirname } from 'path';
9
10
  import { fileURLToPath } from 'url';
@@ -87,6 +88,8 @@ export function createServer(options = {}) {
87
88
  const mashlibCdn = options.mashlibCdn ?? false;
88
89
  const mashlibEnabled = mashlibCdn || !!mashlibModule;
89
90
  const mashlibVersion = options.mashlibVersion ?? '2.0.0';
91
+ // Panes loaded by the data browser page at start-up (#652). OFF by default.
92
+ const panes = normalizePanes(options.panes);
90
93
  // Git HTTP backend is OFF by default - enables clone/push via git protocol
91
94
  const gitEnabled = options.git ?? false;
92
95
  // CORS proxy (#378) — OFF by default. Numeric settings get the
@@ -334,6 +337,8 @@ export function createServer(options = {}) {
334
337
  fastify.decorateRequest('connegEnabled', null);
335
338
  fastify.decorateRequest('notificationsEnabled', null);
336
339
  fastify.decorateRequest('idpEnabled', null);
340
+ // read by the NIP-98 verifier: the lenient git rules apply only while git is on (#643)
341
+ fastify.decorate('gitEnabled', gitEnabled);
337
342
  fastify.decorateRequest('subdomainsEnabled', null);
338
343
  fastify.decorateRequest('baseDomain', null);
339
344
  fastify.decorateRequest('podName', null);
@@ -341,6 +346,7 @@ export function createServer(options = {}) {
341
346
  fastify.decorateRequest('mashlibCdn', null);
342
347
  fastify.decorateRequest('mashlibVersion', null);
343
348
  fastify.decorateRequest('mashlibModule', null);
349
+ fastify.decorateRequest('panes', null);
344
350
  fastify.decorateRequest('defaultQuota', null);
345
351
  fastify.decorateRequest('provisionKeys', null);
346
352
  fastify.decorateRequest('config', null);
@@ -357,6 +363,7 @@ export function createServer(options = {}) {
357
363
  request.mashlibCdn = mashlibCdn;
358
364
  request.mashlibVersion = mashlibVersion;
359
365
  request.mashlibModule = mashlibModule;
366
+ request.panes = panes;
360
367
  request.defaultQuota = defaultQuota;
361
368
  request.provisionKeys = provisionKeysEnabled;
362
369
  request.config = { public: options.public, readOnly: options.readOnly };
@@ -955,6 +962,9 @@ export function createServer(options = {}) {
955
962
  // identity. GET/HEAD reach the LDP layer normally and serve the
956
963
  // file written by --provision-keys.
957
964
  '/.well-known/nostr.json',
965
+ // The pane loader (#652) is served from the package, never from
966
+ // storage; writes to its path are refused for the same reason.
967
+ PANE_LOADER_PATH,
958
968
  ]) {
959
969
  fastify.put(pat, methodNotAllowed);
960
970
  fastify.post(pat, methodNotAllowed);
@@ -978,6 +988,18 @@ export function createServer(options = {}) {
978
988
  });
979
989
  }
980
990
 
991
+ // The pane loader (#652): one static file from the package, served only
992
+ // when a data browser page can ask for it. Registered as a literal route
993
+ // so it wins over the LDP wildcard below; Fastify derives HEAD from GET.
994
+ // The page asks for it with ?v=<package version>, so it can be cached.
995
+ if (mashlibEnabled && panes.length) {
996
+ const paneLoaderSource = readFileSync(join(__dirname, 'mashlib', 'pane-loader.js'), 'utf8');
997
+ fastify.get(PANE_LOADER_PATH, async (request, reply) => reply
998
+ .header('Content-Type', 'text/javascript; charset=utf-8')
999
+ .header('Cache-Control', 'public, max-age=3600')
1000
+ .send(paneLoaderSource));
1001
+ }
1002
+
981
1003
  // LDP routes - using wildcard routing
982
1004
  // Read operations - no rate limit (handled by bodyLimit)
983
1005
  // The LDP wildcards never serve an app-owned subtree (#611): a request
@@ -0,0 +1,89 @@
1
+ /**
2
+ * Read a fetch Response body under a byte cap AND an abort signal.
3
+ *
4
+ * Pass the same AbortSignal that was handed to `fetch()` and keep its
5
+ * timer alive until this resolves. That is what bounds a server that
6
+ * sends headers promptly and then trickles the body (#641): a timeout
7
+ * that is cleared as soon as `fetch()` resolves only covers the
8
+ * connection and headers, and the body read would otherwise wait for
9
+ * as long as the remote chooses to keep sending.
10
+ *
11
+ * On abort the reader is cancelled (which releases the upstream
12
+ * socket) and the read rejects with a timeout error, never with a
13
+ * partial body.
14
+ *
15
+ * @param {Response} res
16
+ * @param {object} opts
17
+ * @param {number} opts.maxBytes - reject once more than this many bytes arrive
18
+ * @param {AbortSignal} [opts.signal] - the fetch's signal; abort ends the read
19
+ * @param {string} [opts.label='response'] - noun used in error messages
20
+ * @returns {Promise<string>} body as UTF-8 text
21
+ */
22
+ export async function readBodyWithCap(res, { maxBytes, signal, label = 'response' }) {
23
+ const tooLarge = () => new Error(`${label} too large (>${maxBytes} bytes)`);
24
+ const timedOut = () => new Error(`${label} body read timed out`);
25
+
26
+ if (signal?.aborted) throw timedOut();
27
+
28
+ const reader = res.body?.getReader?.();
29
+ if (!reader) {
30
+ // Non-streaming Response (polyfills, hand-built stubs): race the
31
+ // text read against the signal so an abort still ends the wait.
32
+ const text = await raceAbort(res.text(), signal, timedOut);
33
+ if (Buffer.byteLength(text, 'utf8') > maxBytes) throw tooLarge();
34
+ return text;
35
+ }
36
+
37
+ // A real fetch body errors on abort by itself; cancelling here also
38
+ // covers stream implementations that do not watch the signal.
39
+ const onAbort = () => { reader.cancel().catch(() => { /* noop */ }); };
40
+ signal?.addEventListener('abort', onAbort, { once: true });
41
+ try {
42
+ const chunks = [];
43
+ let total = 0;
44
+ for (;;) {
45
+ let result;
46
+ try {
47
+ result = await reader.read();
48
+ } catch (err) {
49
+ if (signal?.aborted) throw timedOut();
50
+ throw err;
51
+ }
52
+ // Check abort before honouring `done`: a cancelled reader resolves
53
+ // `{ done: true }`, which must not pass off a partial body as complete.
54
+ if (signal?.aborted) throw timedOut();
55
+ const { value, done } = result;
56
+ if (done) break;
57
+ total += value.byteLength;
58
+ if (total > maxBytes) {
59
+ try { await reader.cancel(); } catch { /* noop */ }
60
+ throw tooLarge();
61
+ }
62
+ chunks.push(value);
63
+ }
64
+ return Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength))).toString('utf8');
65
+ } finally {
66
+ signal?.removeEventListener('abort', onAbort);
67
+ }
68
+ }
69
+
70
+ function raceAbort(promise, signal, makeError) {
71
+ if (!signal) return promise;
72
+ return new Promise((resolve, reject) => {
73
+ const onAbort = () => reject(makeError());
74
+ signal.addEventListener('abort', onAbort, { once: true });
75
+ promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
76
+ });
77
+ }
78
+
79
+ /**
80
+ * Release a Response whose body will not be read (redirect hop, error
81
+ * status, unexpected content-type, oversize, abort). Without this the
82
+ * upstream socket stays busy until the Response is garbage-collected,
83
+ * which on a trickling host means well past the deadline. Fire and
84
+ * forget: cancel() on undici tears the connection down at once.
85
+ */
86
+ export function discardBody(res) {
87
+ if (!res?.body || res.bodyUsed) return;
88
+ try { res.body.cancel().catch(() => { /* locked or already closed */ }); } catch { /* noop */ }
89
+ }