@invisibleloop/pulse 0.1.39 → 0.2.1

package/src/server/index.js

@@ -21,7 +21,7 @@ import { createRequire } from 'module'
 
 const _require = createRequire(import.meta.url)
 export const version = _require('../../package.json').version
-import { renderToString, renderToStream, wrapDocument, resolveServerState } from '../runtime/ssr.js'
+import { renderToString, renderToStream, renderToNavStream, wrapDocument, resolveServerState } from '../runtime/ssr.js'
 import { validateSpec } from '../spec/schema.js'
 import { validateStore, resolveStoreState } from '../store/index.js'
 
@@ -63,6 +63,7 @@ const BASE_CSP = {
   'img-src':        ["'self'", 'data:'],
   'font-src':       ["'self'"],
   'connect-src':    ["'self'"],
+  'object-src':     ["'none'"],
   'frame-ancestors':["'none'"],
   'base-uri':       ["'self'"],
   'form-action':    ["'self'"],
@@ -203,7 +204,10 @@ function parseMultipart(buf, boundary) {
 // ---------------------------------------------------------------------------
 
 class TtlCache {
-  constructor() { this._store = new Map() }
+  constructor() {
+    this._store    = new Map()
+    this._interval = null
+  }
 
   get(key) {
     const entry = this._store.get(key)
@@ -215,11 +219,38 @@ class TtlCache {
   set(key, value, ttlSeconds) {
     this._store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 })
   }
+
+  /** Remove all entries whose TTL has elapsed. */
+  purgeExpired() {
+    const now = Date.now()
+    for (const [key, entry] of this._store) {
+      if (now > entry.expiresAt) this._store.delete(key)
+    }
+  }
+
+  /**
+   * Start a background eviction timer.
+   * The interval is unref()'d so it never prevents the Node.js process from exiting.
+   *
+   * @param {number} intervalMs - how often to purge (default 60 000 ms)
+   */
+  startEviction(intervalMs = 60_000) {
+    if (this._interval) return  // already running
+    this._interval = setInterval(() => this.purgeExpired(), intervalMs).unref()
+  }
+
+  /** Stop the background eviction timer (used for graceful shutdown and tests). */
+  stopEviction() {
+    if (this._interval) { clearInterval(this._interval); this._interval = null }
+  }
 }
 
 const serverDataCache = new TtlCache()
 const pageHtmlCache   = new TtlCache()
 
+serverDataCache.startEviction()
+pageHtmlCache.startEviction()
+
 // ---------------------------------------------------------------------------
 // Cache-Control builder
 // ---------------------------------------------------------------------------
@@ -395,6 +426,7 @@ export function createServer(specs, options = {}) {
 
   // Per-host brand cache — avoids hitting the data store on every request
   const brandCache = new TtlCache()
+  brandCache.startEviction(30_000)  // brand TTL is 60s, scan every 30s
 
   // Load manifest — maps source hydrate paths to production bundle paths
   const hydrateMap     = loadManifest(manifest, staticDir)
@@ -567,16 +599,20 @@ export function createServer(specs, options = {}) {
         return
       }
 
-      // Client-side navigation request — return JSON fragment, not a full document
+      // Client-side navigation request — return JSON fragment (or NDJSON stream), not a full document
       if (req.headers['x-pulse-navigate'] === 'true') {
-        await handleNavResponse(spec, ctx, res, dev)
+        if (stream) {
+          await handleNavStreamResponse(spec, ctx, res)
+        } else {
+          await handleNavResponse(spec, ctx, res, dev)
+        }
         return
       }
 
       if (stream) {
         await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
       } else {
-        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp)
+        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
       }
 
     } catch (err) {
@@ -622,6 +658,11 @@ export function createServer(specs, options = {}) {
 
     console.log('⚡ Pulse shutting down gracefully…')
 
+    // Stop background cache eviction timers
+    serverDataCache.stopEviction()
+    pageHtmlCache.stopEviction()
+    brandCache.stopEviction()
+
     // Stop accepting new connections; exit once all connections are closed
     server.close(() => process.exit(0))
 
@@ -683,11 +724,43 @@ async function handleNavResponse(spec, ctx, res, dev = false) {
   res.end(payload)
 }
 
+/**
+ * Client-side navigation — streaming NDJSON variant.
+ * Sends meta immediately, then streams shell HTML and deferred segments
+ * as their server data resolves. The browser applies chunks progressively,
+ * showing shell content without waiting for slower deferred fetchers.
+ */
+async function handleNavStreamResponse(spec, ctx, res) {
+  const meta = resolveMeta(spec.meta, ctx)
+
+  res.writeHead(200, {
+    'Content-Type':      'application/x-ndjson',
+    'Cache-Control':     'no-store',
+    'X-Accel-Buffering': 'no',
+    ...SECURITY_HEADERS,
+  })
+
+  const navStream = renderToNavStream(spec, ctx, meta)
+  const reader    = navStream.getReader()
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      res.write(value)
+    }
+  } catch {
+    // Headers already sent — cannot change status, just end cleanly
+  } finally {
+    res.end()
+  }
+}
+
 /**
  * Render to a complete string then send — simpler, easier to cache.
  * Checks the in-process page cache before rendering; stores result after.
  */
-async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}) {
+async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null) {
   const cacheKey = spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
   // Pages with server data or store data embed a nonce'd __PULSE_SERVER__ script — don't cache them
   const ttl      = (!spec.server && !spec.store?.length) ? pageCacheTtl(spec, dev, defaultCache) : 0
@@ -773,6 +846,15 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
     ? (canonicalRaw(ctx) || canonicalBase)
     : (canonicalRaw || canonicalBase)
 
+  // 103 Early Hints — browser starts fetching CSS/JS while server resolves data
+  const earlyLinks = [
+    ...(meta.styles || []).map(href => `<${href}>; rel=preload; as=style`),
+    ...(runtimeBundle && spec.hydrate?.startsWith('/dist/') ? [`<${runtimeBundle}>; rel=modulepreload; as=script`] : []),
+  ]
+  if (earlyLinks.length > 0) {
+    try { res.writeEarlyHints({ link: earlyLinks }) } catch {}
+  }
+
   const stylePreloads = (meta.styles || [])
     .map(href => `  <link rel="preload" as="style" href="${escHtml(href)}">`)
     .join('\n')

package/src/server/server.test.js

@@ -397,6 +397,110 @@ await test('normal request still returns full HTML document', async () => {
 
 // ---------------------------------------------------------------------------
 
+const streamNavSpec = {
+  route:   '/stream-nav',
+  hydrate: '/examples/stream-nav.js',
+  state:   {},
+  meta:    { title: 'Stream Nav', styles: ['/app.css'] },
+  server:  { msg: async () => 'streamed hello' },
+  view:    (_s, server) => `<main id="main-content">${server.msg}</main>`
+}
+
+const deferredNavSpec = {
+  route:   '/deferred-nav',
+  hydrate: '/examples/deferred-nav.js',
+  state:   {},
+  meta:    { title: 'Deferred Nav' },
+  server:  {
+    fast: async () => 'shell-data',
+    slow: async () => { await new Promise(r => setTimeout(r, 30)); return 'deferred-data' },
+  },
+  stream: {
+    shell:    ['header'],
+    deferred: ['feed'],
+    scope:    { header: ['fast'], feed: ['slow'] },
+  },
+  view: {
+    header: (_s, srv) => `<header>${srv.fast}</header>`,
+    feed:   (_s, srv) => `<aside>${srv.slow}</aside>`,
+  },
+}
+
+console.log('\nClient-side navigation — streaming (stream: true)\n')
+
+await test('X-Pulse-Navigate with stream:true returns application/x-ndjson', async () => {
+  await withServer([streamNavSpec], {}, async (port) => {
+    const { status, headers } = await request(port, 'GET', '/stream-nav', { 'X-Pulse-Navigate': 'true' })
+    assert(status === 200, `Expected 200, got ${status}`)
+    assert(headers['content-type']?.includes('application/x-ndjson'), `Expected NDJSON: ${headers['content-type']}`)
+  })
+})
+
+await test('streaming nav: first NDJSON line is a meta message with title and hydrate', async () => {
+  await withServer([streamNavSpec], {}, async (port) => {
+    const { body } = await request(port, 'GET', '/stream-nav', { 'X-Pulse-Navigate': 'true' })
+    const lines    = body.trim().split('\n').filter(Boolean)
+    const meta     = JSON.parse(lines[0])
+    assert(meta.type === 'meta',                      `First line should be meta, got ${meta.type}`)
+    assert(meta.title === 'Stream Nav',               `Expected title 'Stream Nav', got ${meta.title}`)
+    assert(meta.hydrate === '/examples/stream-nav.js', `Expected hydrate, got ${meta.hydrate}`)
+    assert(meta.styles[0] === '/app.css',             `Expected styles, got ${JSON.stringify(meta.styles)}`)
+  })
+})
+
+await test('streaming nav: html message contains rendered server data', async () => {
+  await withServer([streamNavSpec], {}, async (port) => {
+    const { body }  = await request(port, 'GET', '/stream-nav', { 'X-Pulse-Navigate': 'true' })
+    const messages  = body.trim().split('\n').filter(Boolean).map(l => JSON.parse(l))
+    const htmlMsg   = messages.find(m => m.type === 'html')
+    assert(htmlMsg,                                    'should have html message')
+    assert(htmlMsg.html.includes('streamed hello'),    `Expected server data in html: ${htmlMsg.html}`)
+    assert(!htmlMsg.html.includes('<!DOCTYPE'),        'html should not be a full document')
+  })
+})
+
+await test('streaming nav: done message contains serverState', async () => {
+  await withServer([streamNavSpec], {}, async (port) => {
+    const { body }   = await request(port, 'GET', '/stream-nav', { 'X-Pulse-Navigate': 'true' })
+    const messages   = body.trim().split('\n').filter(Boolean).map(l => JSON.parse(l))
+    const done       = messages.find(m => m.type === 'done')
+    assert(done,                                          'should have done message')
+    assert(done.serverState?.msg === 'streamed hello',    `Expected serverState.msg, got ${JSON.stringify(done.serverState)}`)
+  })
+})
+
+await test('streaming nav: deferred spec sends shell then deferred then done', async () => {
+  await withServer([deferredNavSpec], {}, async (port) => {
+    const { body }   = await request(port, 'GET', '/deferred-nav', { 'X-Pulse-Navigate': 'true' })
+    const messages   = body.trim().split('\n').filter(Boolean).map(l => JSON.parse(l))
+    const types      = messages.map(m => m.type)
+    assert(types[0] === 'meta',                           `First should be meta, got ${types[0]}`)
+    assert(types.includes('html'),                        'should include html')
+    assert(types.includes('deferred'),                    'should include deferred')
+    assert(types[types.length - 1] === 'done',            'last should be done')
+
+    const deferred = messages.find(m => m.type === 'deferred')
+    assert(deferred?.id === 'feed',                       `Expected deferred id 'feed', got ${deferred?.id}`)
+    assert(deferred?.html.includes('deferred-data'),      `Expected deferred content, got: ${deferred?.html}`)
+
+    // Shell arrives before deferred: html index should precede deferred index
+    const htmlIdx     = types.indexOf('html')
+    const deferredIdx = types.indexOf('deferred')
+    assert(htmlIdx < deferredIdx, `html (${htmlIdx}) should precede deferred (${deferredIdx})`)
+  })
+})
+
+await test('streaming nav: html includes <pulse-deferred> placeholder for deferred segments', async () => {
+  await withServer([deferredNavSpec], {}, async (port) => {
+    const { body }  = await request(port, 'GET', '/deferred-nav', { 'X-Pulse-Navigate': 'true' })
+    const messages  = body.trim().split('\n').filter(Boolean).map(l => JSON.parse(l))
+    const html      = messages.find(m => m.type === 'html')
+    assert(html?.html.includes('pd-feed'), `Shell html should include placeholder, got: ${html?.html}`)
+  })
+})
+
+// ---------------------------------------------------------------------------
+
 console.log('\nError pages\n')
 
 const throwingSpec = {

package/src/spec/schema.js

@@ -18,8 +18,16 @@
  * Shell segments render immediately on first flush.
  * Deferred segments render after their server data resolves.
  *
- * @property {string[]} shell    - Segment keys to render in the first flush
+ * @property {string[]} shell      - Segment keys to render in the first flush
  * @property {string[]} [deferred] - Segment keys to render after async data
+ * @property {Object.<string, string[]>} [scope]
+ *   Optional per-segment fetcher scoping. Maps each segment name to the server
+ *   keys it needs. When declared, the shell only awaits its own fetchers and
+ *   each deferred segment streams as soon as its own fetchers resolve — fetchers
+ *   scoped to deferred segments never block the shell.
+ *
+ *   Example: { header: ['user'], feed: ['posts', 'ads'] }
+ *   Segments not listed in scope receive all server state (safe default).
  */
 
 /**
@@ -190,6 +198,29 @@ export function validateSpec(spec) {
         }
       }
     }
+    // validate scope annotations
+    if (spec.stream.scope !== undefined) {
+      if (typeof spec.stream.scope !== 'object' || Array.isArray(spec.stream.scope)) {
+        errors.push('spec.stream.scope must be a plain object mapping segment names to fetcher key arrays')
+      } else {
+        const allSegments = new Set([...(spec.stream.shell || []), ...(spec.stream.deferred || [])])
+        const serverKeys  = new Set(Object.keys(spec.server || {}))
+        for (const [seg, keys] of Object.entries(spec.stream.scope)) {
+          if (!allSegments.has(seg)) {
+            errors.push(`spec.stream.scope references unknown segment "${seg}"`)
+          }
+          if (!Array.isArray(keys)) {
+            errors.push(`spec.stream.scope["${seg}"] must be an array of server fetcher key strings`)
+          } else {
+            for (const key of keys) {
+              if (!serverKeys.has(key)) {
+                errors.push(`spec.stream.scope["${seg}"] references unknown server key "${key}"`)
+              }
+            }
+          }
+        }
+      }
+    }
   }
 
   // server

package/src/spec/schema.test.js

@@ -103,6 +103,61 @@ test('rejects stream.shell that is not an array', () => {
   )
 })
 
+test('accepts valid stream.scope', () => {
+  const spec = {
+    route: '/s',
+    state: {},
+    server: { user: async () => {}, posts: async () => {} },
+    stream: {
+      shell:    ['header'],
+      deferred: ['feed'],
+      scope:    { header: ['user'], feed: ['posts'] },
+    },
+    view: { header: () => '', feed: () => '' },
+  }
+  const { valid } = validateSpec(spec)
+  assert(valid, 'Expected valid spec with stream.scope')
+})
+
+test('rejects stream.scope referencing unknown segment', () => {
+  assertErrors(
+    {
+      route: '/s',
+      state: {},
+      server: { user: async () => {} },
+      stream: { shell: ['header'], scope: { unknown: ['user'] } },
+      view: { header: () => '' },
+    },
+    'spec.stream.scope references unknown segment "unknown"'
+  )
+})
+
+test('rejects stream.scope referencing unknown server key', () => {
+  assertErrors(
+    {
+      route: '/s',
+      state: {},
+      server: { user: async () => {} },
+      stream: { shell: ['header'], scope: { header: ['missing'] } },
+      view: { header: () => '' },
+    },
+    'spec.stream.scope["header"] references unknown server key "missing"'
+  )
+})
+
+test('rejects stream.scope with non-array value', () => {
+  assertErrors(
+    {
+      route: '/s',
+      state: {},
+      server: { user: async () => {} },
+      stream: { shell: ['header'], scope: { header: 'user' } },
+      view: { header: () => '' },
+    },
+    'spec.stream.scope["header"] must be an array'
+  )
+})
+
 test('rejects mutations with non-function values', () => {
   assertErrors(
     { route: '/x', state: {}, view: () => '', mutations: { inc: 'not a function' } },