@webjsdev/cli 0.10.54 → 0.10.56

package/templates/gallery/app/features/rate-limit/ping/middleware.ts

@@ -1,8 +1,40 @@
 // Per-segment middleware. It sits in the ping/ folder, so it applies ONLY to
 // /features/rate-limit/ping (its route.ts), not to the demo page one level up.
-// rateLimit() returns a standard webjs middleware: return a Response to
-// short-circuit (the 429), or call next() to continue. Keyed by client IP by
-// default; pass `key` to key by user id, API key, etc.
+// rateLimit() returns a standard WebJs middleware: return a Response to
+// short-circuit (the 429), or call next() to continue. Pass `key` to bucket by
+// user id, API key, or anything else instead of by IP.
+//
+// `trustProxy: true` is the load-bearing option here, and it is why this demo
+// works on the deployed site. WITHOUT it the bucket key is the socket peer,
+// which is correct only when the visitor's browser is the thing connecting.
+// Behind a CDN or a platform router the peer is that proxy, so every visitor
+// sharing one proxy shares one bucket, and (worse for a limiter) a proxy POOL
+// hands out one bucket per proxy, which multiplies the real limit by the pool
+// size. WITH it the key comes from the forwarded client address instead.
+//
+// `clientIpHeader` then says WHICH forwarded header carries the visitor, and on
+// this deployment it is load-bearing too. Without it the default chain takes the
+// leftmost X-Forwarded-For entry, which behind Cloudflare is Cloudflare's EGRESS
+// address rather than yours. Cloudflare pins an egress IP per connection, so the
+// limiter hands out one bucket per connection: the count descends convincingly
+// while you hold one connection open and resets the moment a new one opens,
+// which is a limiter that limits nobody. Your address is in CF-Connecting-IP, so
+// that is the header this app names.
+//
+// Copying this into your own app? Name the header YOUR proxy sets, and only
+// after checking it cannot be forged past that proxy. Cloudflare overwrites
+// CF-Connecting-IP, which is what makes it safe HERE and unsafe on a deploy that
+// Cloudflare is not in front of. The same precondition applies to the default
+// chain: the proxy MUST strip an inbound X-Forwarded-For before adding its own.
+// Serving with nothing in front? Drop both options, since then the socket peer
+// IS the visitor. WEBJS_NO_TRUST_PROXY=1 outranks all of it.
+// /docs/rate-limiting has the full threat model.
 import { rateLimit } from '@webjsdev/server';
 
-export default rateLimit({ window: '10s', max: 5, message: 'Slow down: five requests per ten seconds.' });
+export default rateLimit({
+  window: '10s',
+  max: 5,
+  trustProxy: true,
+  clientIpHeader: 'cf-connecting-ip',
+  message: 'Slow down: five requests per ten seconds.',
+});

package/templates/gallery/app/features/route-handler/data/route.ts

@@ -16,7 +16,15 @@ export async function GET(req: Request) {
   return json({
     ok: true,
     at: new Date(), // a real Date; richFetch decodes it back to a Date, not a string
+    // Two addresses, because behind a proxy they are NOT the same and the
+    // difference is invisible until something depends on it (a rate limiter
+    // did, and bucketed proxies instead of visitors). `ip` is the socket peer,
+    // which is the visitor only when the browser connects to you directly.
+    // `forwardedIp` is what the visitor's own CDN header says, which is what a
+    // limiter or an audit log wants. Deployed behind Cloudflare and Railway,
+    // `ip` is a rotating 100.64.x.x router address while `forwardedIp` is you.
     ip: clientIp(req),
+    forwardedIp: clientIp(req, { trustProxy: true, header: 'cf-connecting-ip' }),
     requestId: requestId(),
     userAgent: headers().get('user-agent') ?? 'unknown',
     // cookies() reads the REQUEST cookies. Report how many are present (a

package/templates/gallery/modules/client-router/components/router-controls.ts

@@ -1,7 +1,12 @@
 // Programmatic client navigation. `navigate(url)` does the same soft, in-place
 // swap an <a> click does, but from an event handler (after a save, a wizard
 // step, etc.). `revalidate(url?)` evicts the browser snapshot cache so the next
-// visit refetches fresh HTML instead of the cached page. `disableClientRouter()`
+// visit refetches fresh HTML instead of the cached page.
+// `refreshPage(mode?)` re-renders the page you are ALREADY on and swaps the
+// result in place, recording no history entry and never scrolling, so the reader
+// keeps their place. 'page' (the default) morphs the deepest shared boundary, so
+// hydrated component state outside it survives; 'shell' replaces the whole body,
+// which is what a layout change needs. `disableClientRouter()`
 // / `enableClientRouter()` turn soft navigation off / back on at runtime (for a
 // moment where you want a full page load, e.g. handing off to a third-party
 // flow). disableClientRouter() removes the document-level <a>/<form> click
@@ -11,7 +16,7 @@
 // All are client-only (they run in the browser), so a component is the right
 // home; a page/layout never hydrates. With JS off the plain link still works
 // (progressive enhancement), while the buttons are inert.
-import { WebComponent, html, signal, navigate, revalidate, disableClientRouter, enableClientRouter } from '@webjsdev/core';
+import { WebComponent, html, signal, navigate, revalidate, refreshPage, disableClientRouter, enableClientRouter } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
 
 export class RouterControls extends WebComponent {
@@ -35,10 +40,19 @@ export class RouterControls extends WebComponent {
           <button
             @click=${() => revalidate()}
             class=${buttonClass({ variant: 'link', size: 'none' })}>revalidate() the snapshot cache</button>
+          <button
+            @click=${() => refreshPage()}
+            class=${buttonClass({ variant: 'link', size: 'none' })}>refreshPage() this page</button>
           <button
             @click=${() => this.toggleRouter()}
             class=${buttonClass({ variant: 'link', size: 'none' })}>${soft ? 'disableClientRouter()' : 'enableClientRouter()'} (soft nav: ${soft ? 'on' : 'off'})</button>
         </div>
+        <p class="text-sm text-muted-foreground">
+          refreshPage() re-renders THIS url on the server and swaps it in.
+          The server time above updates, and your scroll position does not
+          move. On a page with hydrated components outside the swapped region,
+          their state survives too.
+        </p>
         <p class="text-sm text-muted-foreground">
           Plain link:
           <a href="/features/client-router/second" class="text-primary underline">/features/client-router/second</a>.

package/templates/gallery/modules/gallery/nav.ts

@@ -3,6 +3,15 @@
  * left sidebar (so they can never drift). A browser-safe data module (no server
  * imports, no client globals): the home flattens the groups into its card grid,
  * and <gallery-nav> renders them grouped. gallery:clear removes this module.
+ *
+ * Blurbs are INTENT-shaped, not noun-shaped: each one opens on the job you would
+ * be doing when you want this demo, because the index is the first thing an
+ * agent reads and a card that only names the feature cannot be found by someone
+ * who does not know the feature exists. The skill's cheat sheet
+ * (.agents/skills/webjs/SKILL.md, "Reach For The Right Primitive") carries the
+ * same set keyed the same way, and the repo's
+ * test/repo-health/skill-gallery-intent-parity.test.mjs fails if the two fall
+ * out of step.
  */
 export interface NavItem { href: string; title: string; blurb: string; }
 export interface NavGroup { label: string; items: NavItem[]; }
@@ -11,68 +20,68 @@ export const FEATURE_GROUPS: NavGroup[] = [
   {
     label: 'Routing',
     items: [
-      { href: '/features/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
-      { href: '/features/boundaries', title: 'Boundaries', blurb: 'The control-flow throws (forbidden / unauthorized / notFound) and the nearest boundary file that catches each.' },
-      { href: '/features/metadata', title: 'Metadata', blurb: 'Static metadata plus generateMetadata(ctx), which reads the request to compute the title and Open Graph tags.' },
+      { href: '/features/routing', title: 'Routing', blurb: 'Add a URL to the app, static or with a dynamic [id] segment. The file is the route, so there is no table to register it in.' },
+      { href: '/features/boundaries', title: 'Boundaries', blurb: 'Abandon a render because something is missing or not allowed. Throw notFound / forbidden / unauthorized and the nearest boundary file catches it.' },
+      { href: '/features/metadata', title: 'Metadata', blurb: 'Give a page its own title, description, and social preview without writing head markup yourself.' },
     ],
   },
   {
     label: 'Components',
     items: [
-      { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
-      { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
-      { href: '/features/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
+      { href: '/features/components', title: 'Components', blurb: 'Make one part of the page respond to a click or hold state. A page never hydrates, so interactivity lives in a component.' },
+      { href: '/features/directives', title: 'Directives', blurb: 'Render a keyed list, or swap a single node when state changes, without re-rendering the component around it.' },
+      { href: '/features/async-render', title: 'Async render', blurb: 'Get server data into the first paint. Await it in async render() rather than fetching after mount, which SSR never runs.' },
     ],
   },
   {
     label: 'Data & actions',
     items: [
-      { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, plus the HTTP-verb config exports that make a read a cached GET.' },
-      { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the WebJs equivalent of a Next route handler.' },
-      { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form bound to a server action, with server-side validation errors.' },
-      { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
+      { href: '/features/server-actions', title: 'Server actions', blurb: 'Call server code from the browser by importing the function. No fetch, no endpoint to name, and the types survive the trip.' },
+      { href: '/features/route-handler', title: 'Route handlers', blurb: 'Expose JSON to a caller outside the app. A server-only route.ts, the WebJs equivalent of a Next route handler.' },
+      { href: '/features/forms', title: 'Forms', blurb: 'Write data from a form that still works with JS off. Binding the action to the form is the whole wiring.' },
+      { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'Make a mutation feel instant. optimistic() applies the change immediately and rolls it back if the server refuses.' },
     ],
   },
   {
     label: 'Client & streaming',
     items: [
-      { href: '/features/client-router', title: 'Client router', blurb: 'Automatic soft navigation: fragment-only fetches, hover prefetch, scroll restore, and graceful no-JS fallback.' },
-      { href: '/features/view-transitions', title: 'View transitions', blurb: 'The opt-in view-transition meta cross-fades a soft navigation, with a data-webjs-permanent element persisted across the swap.' },
-      { href: '/features/streaming', title: 'Streaming actions', blurb: 'A use-server action that returns an async generator, streamed to the call site token by token with for await.' },
-      { href: '/features/stream', title: 'Stream updates', blurb: 'The <webjs-stream> element: renderStream() applies surgical append / replace / remove DOM updates by target id, no region redraw.' },
-      { href: '/features/suspense', title: 'Suspense boundary', blurb: 'The <webjs-suspense> element: a first-paint fallback for a SLOW component, with the resolved content streamed in.' },
-      { href: '/features/frames', title: 'Frames', blurb: 'A webjs-frame region that swaps a filtered sub-list in place from a link, shipping zero component JS, with a no-JS full-nav fallback.' },
+      { href: '/features/client-router', title: 'Client router', blurb: 'Navigate without a full page reload. Automatic the moment a page ships a component, with nothing to import or configure.' },
+      { href: '/features/view-transitions', title: 'View transitions', blurb: 'Cross-fade a navigation instead of snapping. One opt-in meta, plus a marker for elements that must survive the swap.' },
+      { href: '/features/streaming', title: 'Streaming actions', blurb: 'Show tokens or progress as the server produces them. An action returning an async generator, consumed with for await.' },
+      { href: '/features/stream', title: 'Stream updates', blurb: 'Change one element after a write, like appending a row or bumping a count, without redrawing the region around it.' },
+      { href: '/features/suspense', title: 'Suspense boundary', blurb: 'Paint the page before a slow region is ready. The fallback flushes on the first byte and the content streams in behind it.' },
+      { href: '/features/frames', title: 'Frames', blurb: 'Refresh one region on its own with no navigation, like a filtered list or a tab panel. Zero component JS, full-nav fallback with JS off.' },
     ],
   },
   {
     label: 'Real-time',
     items: [
-      { href: '/features/websockets', title: 'WebSockets', blurb: 'A WS(ws, req) route endpoint plus the connectWS() client, echoing messages over a live socket.' },
-      { href: '/features/broadcast', title: 'Broadcast', blurb: 'Fan a message out to every connected client on a WebSocket path, so all open tabs stay in sync.' },
+      { href: '/features/websockets', title: 'WebSockets', blurb: 'Hold a live two-way connection instead of polling. A WS(ws, req) route export on the server, connectWS() on the client.' },
+      { href: '/features/broadcast', title: 'Broadcast', blurb: 'Push one update to every client connected on a WebSocket path, so a change made in one of them shows up in the rest. Optionally excluding the sender.' },
     ],
   },
   {
     label: 'Auth & sessions',
     items: [
-      { href: '/features/auth', title: 'Auth', blurb: 'Password login on createAuth, a signed session cookie, and a real protected route that redirects anonymous visitors to login.' },
-      { href: '/features/sessions', title: 'Sessions', blurb: 'A signed-cookie session applied by a segment middleware, read and written per visitor with getSession() in a route.' },
+      { href: '/features/auth', title: 'Auth', blurb: 'Add login and a route only signed-in visitors can open, without rolling password hashing and session cookies yourself.' },
+      { href: '/features/sessions', title: 'Sessions', blurb: 'Remember something per visitor across requests. A signed cookie applied by middleware, read and written with getSession().' },
     ],
   },
   {
     label: 'Built-ins',
     items: [
-      { href: '/features/caching', title: 'Caching', blurb: 'export const revalidate caches the page HTML per URL, with the safety rule for when a shared cache is allowed.' },
-      { href: '/features/env', title: 'Env vars', blurb: 'The server-only vs WEBJS_PUBLIC_ boundary, read during SSR so secrets never reach the browser.' },
-      { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After once the interval resets.' },
-      { href: '/features/file-storage', title: 'File storage', blurb: 'A no-JS multipart upload streamed into the FileStore, then served back through a streaming route.' },
-      { href: '/features/service-worker', title: 'Service worker', blurb: 'The opt-in offline enhancement, registered from a browser-only lifecycle hook (never a page or layout).' },
+      { href: '/features/caching', title: 'Caching', blurb: 'Stop re-rendering a page that is identical for every visitor. export const revalidate, with the rule for when that is safe.' },
+      { href: '/features/env', title: 'Env vars', blurb: 'Read config and secrets at runtime while keeping the secrets server-side. WEBJS_PUBLIC_ is the only prefix the browser sees.' },
+      { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'Stop one caller hammering an endpoint. The rateLimit() middleware returns a 429 with Retry-After until the interval resets.' },
+      { href: '/features/file-storage', title: 'File storage', blurb: 'Accept an upload and serve it back, streamed both ways, with nothing buffered in memory and nothing written into public/.' },
+      { href: '/features/service-worker', title: 'Service worker', blurb: 'Keep the app usable offline. The opt-in service worker, registered from a browser-only lifecycle hook (never a page or layout).' },
     ],
   },
 ];
 
 /** The whole example apps (composed features), shown after the single-feature demos. */
 export const EXAMPLES: NavItem[] = [
-  { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
+  { href: '/examples/todo', title: 'Optimistic todo', blurb: 'See the pieces composed in one real feature: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
 ];
 
 /**

package/templates/gallery/test/rate-limit/rate-limit.test.ts

@@ -0,0 +1,91 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+import { createRequestHandler } from '@webjsdev/server';
+import { testRequest } from '@webjsdev/server/testing';
+
+const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+const PING = '/features/rate-limit/ping';
+
+// The demo's own numbers, so a change to the middleware that these tests do not
+// notice is a change that made them stale rather than one they tolerated.
+const MAX = 5;
+
+// Each test picks its own visitor addresses. The limiter counts into the global
+// in-memory cache store, which outlives a handler instance, so two tests sharing
+// an address would share a bucket and the second would start already exhausted.
+// The demo names CF-Connecting-IP, because that is the header carrying the
+// visitor on the deployment it runs on. Every request here also carries an
+// X-Forwarded-For that DISAGREES, standing in for the CDN egress address the
+// real deploy puts there, so a test that passes only because the two agree
+// cannot exist.
+function ping(handle: (req: Request) => Promise<Response>, visitor: string, cdnEgress = '172.68.1.9') {
+  return testRequest(handle, PING, {
+    headers: { 'cf-connecting-ip': visitor, 'x-forwarded-for': cdnEgress },
+  });
+}
+
+test('the demo limits one visitor to five requests per window', async () => {
+  const app = await createRequestHandler({ appDir, dev: true });
+  const visitor = '203.0.113.10';
+
+  for (let i = 1; i <= MAX; i += 1) {
+    const res = await ping(app.handle, visitor);
+    assert.equal(res.status, 200, `request ${i} is inside the window`);
+    assert.equal(res.headers.get('x-ratelimit-remaining'), String(MAX - i));
+  }
+
+  const limited = await ping(app.handle, visitor);
+  assert.equal(limited.status, 429, 'the sixth request is refused');
+  assert.equal(limited.headers.get('retry-after'), '10');
+});
+
+// This is the assertion the deployed bug would have failed. Both visitors reach
+// the app through the same proxy, so the socket peer is identical for both and a
+// peer-keyed limiter would count them into ONE bucket: exhausting the first
+// would refuse the second. Keying on the forwarded address keeps them apart.
+//
+// Counterfactual, proven at this commit: removing `trustProxy: true` from
+// gallery/app/features/rate-limit/ping/middleware.ts fails this test on the last
+// assertion (the second visitor gets a 429), while the single-visitor test above
+// still passes. That asymmetry is the point, since the single-visitor test is
+// what a peer-keyed limiter satisfies too.
+test('one visitor exhausting the window does not refuse another behind the same proxy', async () => {
+  const app = await createRequestHandler({ appDir, dev: true });
+  const noisy = '203.0.113.20';
+  const bystander = '203.0.113.21';
+
+  for (let i = 0; i < MAX; i += 1) await ping(app.handle, noisy);
+  assert.equal((await ping(app.handle, noisy)).status, 429, 'the noisy visitor is limited');
+
+  const other = await ping(app.handle, bystander);
+  assert.equal(other.status, 200, 'a different visitor keeps their own window');
+  assert.equal(other.headers.get('x-ratelimit-remaining'), String(MAX - 1));
+});
+
+// The half `trustProxy: true` alone did not deliver, and the one the live site
+// disproved (#1389). A CDN gives each connection a different egress address, so
+// one visitor opening several connections arrives with several X-Forwarded-For
+// values and ONE CF-Connecting-IP. Keyed on XFF that visitor gets a fresh bucket
+// per connection and is never refused, which is what shipped and read as working.
+//
+// Counterfactual, proven at this commit: removing `clientIpHeader` from the
+// middleware fails this test at the sixth request AND the two-visitor test
+// above, while the single-visitor test still passes. The one that survives is
+// the one whose requests all carry the same CDN address, which is exactly the
+// blind spot that let the first fix look complete on a real deployment.
+test('one visitor is limited across connections, whatever CDN address they arrive on', async () => {
+  const app = await createRequestHandler({ appDir, dev: true });
+  const visitor = '203.0.113.30';
+
+  for (let i = 1; i <= MAX; i += 1) {
+    const res = await ping(app.handle, visitor, `172.68.9.${i}`);
+    assert.equal(res.status, 200, `request ${i} arrives on its own CDN egress address`);
+  }
+
+  const limited = await ping(app.handle, visitor, '172.68.9.99');
+  assert.equal(limited.status, 429, 'a new CDN egress address does not buy a new window');
+});

package/templates/scripts/clear-gallery.mjs

@@ -53,10 +53,13 @@ if (!existsSync(join(root, 'app/features'))) {
 
 // 1) Gallery route trees + example metadata routes. `app/api/auth` is the auth
 // card's createAuth handler (it lives at the app root, not under app/features/,
-// because createAuth hardcodes /api/auth/*), and `test/auth` is the auth card's
-// request-pipeline test, so both are removed here alongside the card.
+// because createAuth hardcodes /api/auth/*), and `test/auth` + `test/rate-limit`
+// are card-owned request-pipeline tests, so they are removed alongside their
+// cards. A card that ships a test under test/ MUST be listed here: the prune
+// below only removes test/ once it is EMPTY, so a missed entry silently leaves
+// the reset app with a test suite for a card it no longer has.
 const galleryPaths = [
-  'app/features', 'app/examples', 'app/sitemaps', 'app/api/auth', 'test/auth',
+  'app/features', 'app/examples', 'app/sitemaps', 'app/api/auth', 'test/auth', 'test/rate-limit',
   'app/icon.ts', 'app/apple-icon.ts', 'app/manifest.ts', 'app/opengraph-image.ts',
   'app/twitter-image.ts', 'app/robots.ts', 'app/sitemap.ts',
   'app/global-error.ts', 'app/global-not-found.ts',