Merge branch 'main' into patch-1

app/core/components/SponsorPack.js

@@ -7,67 +7,84 @@ import React from "react"
 const sponsors = [
   {
     name: "Flightcontrol",
+    altText: "Flightcontrol",
     href: "https://www.flightcontrol.dev?ref=blitzjs",
     imageUrl: "https://raw.githubusercontent.com/blitz-js/blitz/main/assets/flightcontrol.png",
     tier: 1,
     cost: 800,
   },
   {
     name: "Fauna",
+    altText: "Fauna",
     href: "https://dashboard.fauna.com/accounts/register?utm_source=BlitzJS&utm_medium=sponsorship&utm_campaign=BlitzJS_Sponsorship_2020",
     imageUrl: "https://raw.githubusercontent.com/blitz-js/blitz/canary/assets/Fauna_Logo_Blue.png",
     tier: 2,
     cost: 500,
   },
   {
     name: "RIT",
+    altText: "RIT",
     href: "https://rit-inc.co.jp/?utm_source=BlitzJS&utm_medium=sponsorship&utm_campaign=BlitzJS_Sponsorship_2021",
     imageUrl: "https://raw.githubusercontent.com/blitz-js/blitz/canary/assets/rit_logo.png",
     tier: 3,
     cost: 250,
   },
   {
     name: "Boostry",
+    altText: "Boostry",
     href: "https://boostry.co.jp/?utm_source=BlitzJS&utm_medium=sponsorship&utm_campaign=BlitzJS_Sponsorship_2021",
     imageUrl: "https://raw.githubusercontent.com/blitz-js/blitz/canary/assets/boostry.svg",
     tier: 3,
     cost: 250,
   },
   {
     name: "Byteflow",
+    altText: "Byteflow",
     href: "https://byteflow.app/?ref=blitzjs",
     imageUrl: "https://raw.githubusercontent.com/blitz-js/blitz/main/assets/byteflow.png",
     tier: 3,
     cost: 250,
   },
   {
     name: "Andreas",
+    altText: "Andreas",
     href: "https://andreas.fyi/",
     imageUrl: "https://raw.githubusercontent.com/blitz-js/blitz/canary/assets/andreas.jpg",
     tier: 4,
     cost: 100,
   },
   {
     name: "MeetKai",
+    altText: "MeetKai",
     href: "https://meetkai.com/?ref=blitzjs_web",
     imageUrl: "https://raw.githubusercontent.com/blitz-js/blitz/canary/assets/meetkai.png",
     tier: 4,
     cost: 100,
   },
   {
     name: "JDLT",
+    altText: "JDLT",
     href: "https://jdlt.co.uk/?ref=blitzjs_web",
     imageUrl: "https://raw.githubusercontent.com/blitz-js/blitz/canary/assets/jdlt.png",
     tier: 4,
     cost: 100,
   },
   {
     name: "Simon Lammes",
+    altText: "Simon Lammes",
     href: "https://github.com/simon-lammes",
     imageUrl: "https://avatars.githubusercontent.com/u/46446421?v=4",
     tier: 4,
     cost: 100,
   },
+  {
+    name: "Route4Me",
+    altText: "Route Optimizer and Route Planning Software",
+    href: "https://route4me.com",
+    imageUrl: "https://raw.githubusercontent.com/blitz-js/blitz/main/assets/route4me.png",
+    tier: 4,
+    cost: 100,
+  },
 ]
 
 const pack = {
@@ -150,7 +167,7 @@ export const SponsorPack = () => {
                           >
                             <Image
                               src={circle.data.imageUrl}
-                              alt={circle.data.name}
+                              alt={circle.data.altText}
                               layout="fill"
                               objectFit="contain"
                             />

app/pages/docs/auth-server.mdx

@@ -54,7 +54,103 @@ function PageWithGssp(props: Props) {
 export default PageWithGssp
 ```
 
-## API Routes {#api-routes}
+## App Router API Routes {#app-api-routes}
+
+You can get the session context inside API routes by wrapping it with the
+`withBlitzAuth` function exported from `src/blitz-server`:
+
+```ts
+//app/api/logout/route.ts
+import { withBlitzAuth } from "app/blitz-server"
+
+export const POST = withBlitzAuth(async (_request, _params, ctx) => {
+  const session = ctx.session
+  await session.$revoke()
+  return new Response(
+    JSON.stringify({
+      userId: session.userId,
+    }),
+    { status: 200 }
+  )
+})
+```
+
+#### `withBlitzAuth` API {#with-blitz-auth-api}
+
+The function supports both single handler as an input as well as an object
+of handlers and has the following signature:
+
+```ts
+function withBlitzAuth(handlers: { [method: string]: Handler })
+```
+
+
+##### Arguments
+
+- `handlers: { [method: string]: Handler })` - An object of handlers where
+  the key is the HTTP method and the value is the handler function.
+
+```ts
+type Handler = (
+  request: Request,
+  params: Record<string, string>,
+  ctx: { session: SessionContext }
+) => Promise<Response>
+```
+
+##### Returns
+
+- `{ [method: string]: Handler }` - The wrapper function returns an object
+  of handlers where the key is the HTTP method and the value is the
+  handler function wrapped with the session management of `@blitzjs/auth`.
+
+  ##### Example Usage with single handler
+
+```ts
+//app/api/logout/route.ts
+import { withBlitzAuth } from "app/blitz-server"
+
+export const { POST } = withBlitzAuth({
+  POST: async (_request, _params, { session }) => {
+    // logout the user
+    await session.$revoke()
+    return new Response(
+      JSON.stringify({
+        userId: session.userId,
+      }),
+      { status: 200 }
+    )
+  },
+})
+```
+
+##### Example Usage with multiple handlers
+
+```ts
+//app/api/multiple/route.ts
+import { withBlitzAuth } from "app/blitz-server"
+
+export const { GET, POST } = withBlitzAuth({
+  GET: async (_request, _params, { session }) => {
+    return new Response(
+      JSON.stringify({
+        userId: session.userId,
+      }),
+      { status: 200 }
+    )
+  },
+  POST: async (_request, _params, { session }) => {
+    return new Response(
+      JSON.stringify({
+        userId: session.userId,
+      }),
+      { status: 200 }
+    )
+  },
+})
+```
+
+## Pages Router API Routes {#pages-api-routes}
 
 You can get the session context inside API routes by wrapping it with the
 `api` function exported from `src/blitz-server`:
@@ -216,3 +312,68 @@ export const updateUserRole = async (
   await setPublicDataForUser(userId, { role })
 }
 ```
+
+<Card type="note">
+  The following methods are meant for internal usage or for advanced use
+  cases. They are not needed for general use.
+</Card>
+
+## `getSession` {#get-session}
+
+This function is used internally by Blitz to get the session context from
+the request either from an `IncomingMessage` and `ServerResponse` pair or
+from a `Request` object.
+
+#### Arguments
+
+- `req: IncomingMessage | Request` - The request object from the server.
+- `res: ServerResponse | never` - The response object from the server.
+- `isRsc: boolean` - A boolean that determines if the request is for a
+  resource.
+
+#### Returns
+
+- `SessionContext` - The session context object.
+
+## `SessionContext.setSession` {#session-context-set-session}
+
+This function is used along with [getSession](#get-session) to set the
+session context on the response object after the session has been created
+or updated.
+
+#### Arguments
+
+- `response: Response | ServerResponse` - The response object from the
+  server.
+
+#### Returns
+
+- `void`
+
+#### Example Usage
+
+##### With `Request`
+
+```ts
+async function handler(request: Request, params: Record<string, string>) {
+  const session = await getSession(request)
+  const response = await handler(request, params, { session })
+  session.setSession(response)
+  return response
+}
+```
+
+##### With `IncomingMessage` and `ServerResponse`
+
+```ts
+async function handler(req: IncomingMessage, res: ServerResponse) {
+  const session = await getSession(req, res)
+  await handler(req, res, { session })
+  session.setSession(res)
+}
+```
+
+- `handler` is a function that processes the request and can mutate the
+  session state
+- The `response` | `res` will contain the session state after the handler
+  has been processed

app/pages/docs/middleware.mdx

@@ -33,7 +33,7 @@ Blitz-compatible server plugin.
 
 ```ts
 ...
-import {BlitzServerMiddleware} from "blitz"
+import {BlitzServerMiddleware} from "@blitzjs/next"
 import {BlitzGuardMiddleware} from "@blitz-guard/core/dist/middleware"
 ...