feat(nuxt): useRequestHeader utility

docs/3.api/2.composables/use-request-header.md

@@ -0,0 +1,34 @@
+---
+title: "useRequestHeader"
+description: "Use useRequestHeader to access a certain incoming request header."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/ssr.ts
+    size: xs
+---
+
+You can use the built-in [`useRequestHeader`](/docs/api/composables/use-request-header) composable to access any incoming request header within your pages, components, and plugins.
+
+```ts
+// Get the cookie request header
+const cookie = useRequestHeader('cookie')
+```
+
+::callout
+In the browser, `useRequestHeader` will return an empty string.
+::
+
+## Example
+
+We can use `useRequestHeader` to easily figure out if a user is authorized or not.
+
+The example below reads the `authorization` request header to find out if a person can access a restricted resource.
+
+```ts [middleware/authorized-only.ts]
+export default defineNuxtRouteMiddleware((to, from) => {
+  if(!useRequestHeader('authorization')){
+    return navigateTo('/not-authorized')
+  }
+})
+```

packages/nuxt/src/app/composables/ssr.ts

@@ -1,5 +1,5 @@
 import type { H3Event } from 'h3'
-import { setResponseStatus as _setResponseStatus, appendHeader, getRequestHeaders } from 'h3'
+import { setResponseStatus as _setResponseStatus, appendHeader, getRequestHeader, getRequestHeaders } from 'h3'
 import type { NuxtApp } from '../nuxt'
 import { useNuxtApp } from '../nuxt'
 
@@ -17,6 +17,13 @@ export function useRequestHeaders (include?: any[]) {
   return Object.fromEntries(include.map(key => key.toLowerCase()).filter(key => headers[key]).map(key => [key, headers[key]]))
 }
 
+export function useRequestHeader(include: string) {
+  if (import.meta.client) { return '' }
+  const event = useRequestEvent()
+  const header = event ? getRequestHeader(event, include) : ''
+  return header
+}
+
 export function useRequestFetch (): typeof global.$fetch {
   if (import.meta.client) {
     return globalThis.$fetch