docs: Update the middleware / endpoint documentation (#4442)

packages/docs/codesandbox.sync.ts

@@ -50,7 +50,7 @@ function findCodeSandboxes(
   for (let lineNo = 0; lineNo < lines.length; lineNo++) {
     const line = lines[lineNo];
     newLines.push(line);
-    const match = line.match(/(.*)<(CodeSandbox|CodeFile) src=["']([^"']*)["'][^/]*>$/);
+    const match = line.match(/(.*)<(CodeSandbox|CodeFile) src=["']([^"']*)["'].*>$/);
     if (match) {
       const [, prefix, tag, srcPath] = match;
       const content: string[] = [];

packages/docs/public/docs/qwikcity/README.md

@@ -0,0 +1 @@
+The images in this folder were created: https://docs.google.com/presentation/d/1HjlWpOpnPAmjdxEV7F2uttjvkWf1FOLvXaWMcxGLs38/

packages/docs/src/routes/demo/demo-reset.css

@@ -68,19 +68,17 @@ demo a:active {
 }
 
 demo ul {
-  margin-top: 1em;
-  margin-bottom: 1em;
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
   margin-left: 0;
   margin-right: 0;
-  padding-left: 40px;
-  list-style-type: square;
 }
 
 demo li {
   margin-top: 0.5em;
   margin-bottom: 0.5em;
   padding-left: 0;
-  list-style-type: none;
+  list-style-type: disc;
   margin-left: 1em;
 }
 

packages/docs/src/routes/demo/integration/img/qwik-image/index.tsx

@@ -1,11 +1,14 @@
 import { $, component$ } from '@builder.io/qwik';
-import { Image, useImageProvider } from 'qwik-image';
-import type { ImageTransformerProps } from 'qwik-image';
+import {
+  Image,
+  type ImageTransformerProps,
+  useImageProvider,
+} from 'qwik-image';
 
 export default component$(() => {
   const imageTransformer$ = $(
     ({ src, width, height }: ImageTransformerProps): string => {
-      // Here you can set your favourite image loader CDN
+      // Here you can set your favorite image loaders service
       return `https://cdn.builder.io/api/v1/${src}?height=${height}&width=${width}}&format=webp&fit=fill`;
     }
   );

packages/docs/src/routes/demo/qwikcity/middleware/basePathname/index.tsx

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ basePathname, json }) => {
+  json(200, { basePathname });
+};

packages/docs/src/routes/demo/qwikcity/middleware/cacheControl/index.tsx

@@ -0,0 +1,12 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({
+  cacheControl,
+  headers,
+  json,
+}) => {
+  cacheControl({ maxAge: 42, public: true });
+  const obj: Record<string, string> = {};
+  headers.forEach((value, key) => (obj[key] = value));
+  json(200, obj);
+};

packages/docs/src/routes/demo/qwikcity/middleware/component/index.tsx

@@ -0,0 +1,16 @@
+import { component$ } from '@builder.io/qwik';
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onRequest: RequestHandler = async ({ redirect }) => {
+  if (!isLoggedIn()) {
+    throw redirect(308, '/login');
+  }
+};
+
+export default component$(() => {
+  return <div>You are logged in.</div>;
+});
+
+function isLoggedIn() {
+  return true; // Mock login as true
+}

packages/docs/src/routes/demo/qwikcity/middleware/cookie/index.tsx

@@ -0,0 +1,8 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ cookie, json }) => {
+  let count = cookie.get('Qwik.demo.count')?.number() || 0;
+  count++;
+  cookie.set('Qwik.demo.count', count);
+  json(200, { count });
+};

packages/docs/src/routes/demo/qwikcity/middleware/env/index.tsx

@@ -0,0 +1,10 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ env, json }) => {
+  json(200, {
+    USER: env.get('USER'),
+    MODE_ENV: env.get('MODE_ENV'),
+    PATH: env.get('PATH'),
+    SHELL: env.get('SHELL'),
+  });
+};

packages/docs/src/routes/demo/qwikcity/middleware/error/index.tsx

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ error }) => {
+  throw error(500, 'ERROR: Demonstration of an error response.');
+};

packages/docs/src/routes/demo/qwikcity/middleware/exit/index.tsx

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ exit }) => {
+  throw exit();
+};

packages/docs/src/routes/demo/qwikcity/middleware/getWritableStream/index.tsx

@@ -0,0 +1,18 @@
+import type { RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async (requestEvent) => {
+  const writableStream = requestEvent.getWritableStream();
+  const writer = writableStream.getWriter();
+  const encoder = new TextEncoder();
+
+  writer.write(encoder.encode('Hello World'));
+  await wait(100);
+  writer.write(encoder.encode('After 100ms'));
+  await wait(100);
+  writer.write(encoder.encode('After 200ms'));
+  await wait(100);
+  writer.write(encoder.encode('END'));
+  writer.close();
+};
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

packages/docs/src/routes/demo/qwikcity/middleware/headerSent/index.tsx

@@ -0,0 +1,11 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ headersSent, json }) => {
+  if (!headersSent) {
+    json(200, { response: 'default response' });
+  }
+};
+
+export const onRequest: RequestHandler = async ({ status }) => {
+  status(200);
+};

packages/docs/src/routes/demo/qwikcity/middleware/headers/index.tsx

@@ -0,0 +1,8 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ headers, json }) => {
+  headers.set('X-SRF-TOKEN', Math.random().toString(36).replace('0.', ''));
+  const obj: Record<string, string> = {};
+  headers.forEach((value, key) => (obj[key] = value));
+  json(200, obj);
+};

packages/docs/src/routes/demo/qwikcity/middleware/html/index.tsx

@@ -0,0 +1,13 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ html }) => {
+  html(
+    200,
+    ` 
+      <html>
+        <body>
+          <h1>HTML response</h1>
+        </body>
+      </html>`
+  );
+};

packages/docs/src/routes/demo/qwikcity/middleware/json/index.tsx

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ json }) => {
+  json(200, { hello: 'world' });
+};

packages/docs/src/routes/demo/qwikcity/middleware/locale/index.tsx

@@ -0,0 +1,12 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onRequest: RequestHandler = async ({ locale, request }) => {
+  const acceptLanguage = request.headers.get('accept-language');
+  const [languages] = acceptLanguage?.split(';') || ['?', '?'];
+  const [preferredLanguage] = languages.split(',');
+  locale(preferredLanguage);
+};
+
+export const onGet: RequestHandler = async ({ locale, json }) => {
+  json(200, { locale: locale() });
+};

packages/docs/src/routes/demo/qwikcity/middleware/method/index.tsx

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onRequest: RequestHandler = async ({ method, json }) => {
+  json(200, { method });
+};

packages/docs/src/routes/demo/qwikcity/middleware/next/index.tsx

@@ -0,0 +1,24 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+// Generic function `onRequest` is executed first
+export const onRequest: RequestHandler = async ({ next, sharedMap, json }) => {
+  const log: string[] = [];
+  sharedMap.set('log', log);
+
+  log.push('onRequest start');
+  await next(); // Execute next middleware function (onGet)
+  log.push('onRequest end');
+
+  json(200, log);
+};
+
+// Specific functions such as `onGet` are executed next
+export const onGet: RequestHandler = async ({ next, sharedMap }) => {
+  const log = sharedMap.get('log') as string[];
+
+  log.push('onGET start');
+  // execute next middleware function
+  // (in our case, there are no more middleware functions nor components.)
+  await next();
+  log.push('onGET end');
+};

packages/docs/src/routes/demo/qwikcity/middleware/params/[myId]/index.tsx

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ params, json }) => {
+  json(200, { params });
+};

packages/docs/src/routes/demo/qwikcity/middleware/parseBody/index.tsx

@@ -0,0 +1,17 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ html }) => {
+  html(
+    200,
+    `
+      <form id="myForm" method="POST">
+        <input type="text" name="project" value="Qwik"/>
+        <input type="text" name="url" value="http://qwik.builder.io"/>
+      </form>
+      <script>myForm.submit()</script>`
+  );
+};
+
+export const onPost: RequestHandler = async ({ parseBody, json }) => {
+  json(200, { body: await parseBody() });
+};

packages/docs/src/routes/demo/qwikcity/middleware/platform/index.tsx

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ platform, json }) => {
+  json(200, Object.keys(platform));
+};

packages/docs/src/routes/demo/qwikcity/middleware/proxy/index.tsx

@@ -0,0 +1,8 @@
+import type { RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ send, url }) => {
+  const response = await fetch(
+    new URL('/demo/qwikcity/middleware/json/', url)
+  );
+  send(response);
+};

packages/docs/src/routes/demo/qwikcity/middleware/query/index.tsx

@@ -0,0 +1,7 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ query, json }) => {
+  const obj: Record<string, string> = {};
+  query.forEach((v, k) => (obj[k] = v));
+  json(200, obj);
+};

packages/docs/src/routes/demo/qwikcity/middleware/redirect/index.tsx

@@ -0,0 +1,8 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ redirect, url }) => {
+  throw redirect(
+    308,
+    new URL('/demo/qwikcity/middleware/status/', url).toString()
+  );
+};

packages/docs/src/routes/demo/qwikcity/middleware/request/index.tsx

@@ -0,0 +1,7 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ json, request }) => {
+  const obj: Record<string, string> = {};
+  request.headers.forEach((v, k) => (obj[k] = v));
+  json(200, { headers: obj });
+};

packages/docs/src/routes/demo/qwikcity/middleware/send/index.tsx

@@ -0,0 +1,11 @@
+import type { RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async (requestEvent) => {
+  const response = new Response('Hello World', {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/plain',
+    },
+  });
+  requestEvent.send(response);
+};

packages/docs/src/routes/demo/qwikcity/middleware/sharedMap/index.tsx

@@ -0,0 +1,50 @@
+import { component$ } from '@builder.io/qwik';
+import {
+  routeLoader$,
+  type RequestHandler,
+  type Cookie,
+} from '@builder.io/qwik-city';
+
+interface User {
+  username: string;
+  email: string;
+}
+
+export const onRequest: RequestHandler = async ({
+  sharedMap,
+  cookie,
+  send,
+}) => {
+  const user = loadUserFromCookie(cookie);
+  if (user) {
+    sharedMap.set('user', user);
+  } else {
+    throw send(401, 'NOT_AUTHORIZED');
+  }
+};
+
+function loadUserFromCookie(cookie: Cookie): User | null {
+  // this is where you would check cookie for user.
+  if (cookie) {
+    // just return mock user for this demo.
+    return {
+      username: `Mock User`,
+      email: `mock@users.com`,
+    };
+  } else {
+    return null;
+  }
+}
+
+export const useUser = routeLoader$(({ sharedMap }) => {
+  return sharedMap.get('user') as User;
+});
+
+export default component$(() => {
+  const log = useUser();
+  return (
+    <div>
+      {log.value.username} ({log.value.email})
+    </div>
+  );
+});

packages/docs/src/routes/demo/qwikcity/middleware/status/index.tsx

@@ -0,0 +1,9 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ status, getWritableStream }) => {
+  status(200);
+  const stream = getWritableStream();
+  const writer = stream.getWriter();
+  writer.write(new TextEncoder().encode('Hello World!'));
+  writer.close();
+};

packages/docs/src/routes/demo/qwikcity/middleware/text/index.tsx

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ text }) => {
+  text(200, 'Text based response.');
+};

packages/docs/src/routes/demo/qwikcity/middleware/throw/index.tsx

@@ -0,0 +1,24 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onRequest: RequestHandler = async ({ next, sharedMap, json }) => {
+  const log: string[] = [];
+  sharedMap.set('log', log);
+
+  log.push('onRequest');
+  if (isLoggedIn()) {
+    // normal behavior call next middleware
+    await next();
+  } else {
+    // If not logged in throw to prevent implicit call to the next middleware.
+    throw json(404, log);
+  }
+};
+
+export const onGet: RequestHandler = async ({ sharedMap }) => {
+  const log = sharedMap.get('log') as string[];
+  log.push('onGET');
+};
+
+function isLoggedIn() {
+  return false; // always return false as mock example
+}

packages/docs/src/routes/demo/qwikcity/middleware/url/index.tsx

@@ -0,0 +1,5 @@
+import { type RequestHandler } from '@builder.io/qwik-city';
+
+export const onGet: RequestHandler = async ({ url, json }) => {
+  json(200, { url: url.toString() });
+};