Rewrite pageinfo as /article/meta (#54747)

Author: hectorsector

src/article-api/README-pageinfo.md

@@ -8,3 +8,17 @@ This subject folder contains the code for the Article API endpoints:
 ## What it does
 
 Article API endpoints allow consumers to query GitHub Docs for listings of current articles, and for specific article information.
+
+The `/api/article/meta` endpoint powers hovercards, which provide a preview for internal links on <docs.github.com>.
+
+## How it works
+
+The `/api/article` endpoints return information about a page by `pathname`. 
+
+`api/article/meta` is highly cached, in JSON format.
+
+## How to get help
+
+For internal folks ask in the Docs Engineering slack channel. 
+
+For open source folks, please open a discussion in the public repository.

src/article-api/README.md

@@ -0,0 +1,37 @@
+import type { Response } from 'express'
+
+import { Context } from '#src/types.js'
+import { ExtendedRequestWithPageInfo } from '../types'
+import contextualize from '#src/frame/middleware/context/context.js'
+
+export async function getArticleBody(req: ExtendedRequestWithPageInfo) {
+  // req.pageinfo is set from pageValidationMiddleware and pathValidationMiddleware
+  // and is in the ExtendedRequestWithPageInfo
+  const { page, pathname, archived } = req.pageinfo
+
+  if (archived?.isArchived)
+    throw new Error(`Page ${pathname} is archived and can't be rendered in markdown.`)
+  // for anything that's not an article (like index pages), don't try to render and
+  // tell the user what's going on
+  if (page.documentType !== 'article') {
+    throw new Error(`Page ${pathname} isn't yet available in markdown.`)
+  }
+  // these parts allow us to render the page
+  const mockedContext: Context = {}
+  const renderingReq = {
+    path: pathname,
+    language: page.languageCode,
+    pagePath: pathname,
+    cookies: {},
+    context: mockedContext,
+    headers: {
+      'content-type': 'text/markdown',
+    },
+  }
+
+  // contextualize and render the page
+  await contextualize(renderingReq as ExtendedRequestWithPageInfo, {} as Response, () => {})
+  renderingReq.context.page = page
+  renderingReq.context.markdownRequested = true
+  return await page.render(renderingReq.context)
+}

src/article-api/middleware/article-body.ts

@@ -1,23 +1,11 @@
-import express from 'express'
-import type { RequestHandler, Response } from 'express'
+import type { Response } from 'express'
 import type { ExtendedRequestWithPageInfo } from '../types'
 
 import type { ExtendedRequest, Page, Context, Permalink } from '@/types'
-import statsd from '@/observability/lib/statsd.js'
-import { defaultCacheControl } from '@/frame/middleware/cache-control.js'
-import catchMiddlewareError from '@/observability/middleware/catch-middleware-error.js'
-import {
-  SURROGATE_ENUMS,
-  setFastlySurrogateKey,
-  makeLanguageSurrogateKey,
-} from '@/frame/middleware/set-fastly-surrogate-key.js'
 import shortVersions from '@/versions/middleware/short-versions.js'
 import contextualize from '@/frame/middleware/context/context'
 import features from '@/versions/middleware/features.js'
 import { readCompressedJsonFile } from '@/frame/lib/read-json-file.js'
-import { pathValidationMiddleware, pageValidationMiddleware } from './validation'
-
-const router = express.Router()
 
 // If you have pre-computed page info into a JSON file on disk, this is
 // where it would be expected to be found.
@@ -96,7 +84,7 @@ type CachedPageInfo = {
 }
 
 let _cache: CachedPageInfo | null = null
-async function getPageInfoFromCache(page: Page, pathname: string) {
+export async function getPageInfoFromCache(page: Page, pathname: string) {
   let cacheInfo = ''
   if (_cache === null) {
     try {
@@ -111,12 +99,12 @@ async function getPageInfoFromCache(page: Page, pathname: string) {
     }
   }
 
-  let info = _cache[pathname]
+  let meta = _cache[pathname]
   if (!cacheInfo) {
-    cacheInfo = info ? 'hit' : 'miss'
+    cacheInfo = meta ? 'hit' : 'miss'
   }
-  if (!info) {
-    info = await getPageInfo(page, pathname)
+  if (!meta) {
+    meta = await getPageInfo(page, pathname)
     // You might wonder; why do we not store this compute information
     // into the `_cache` from here?
     // The short answer is; it won't be used again.
@@ -128,74 +116,37 @@ async function getPageInfoFromCache(page: Page, pathname: string) {
     // In CI, we use the caching because the CI runs
     // `npm run precompute-pageinfo` right before it runs vitest tests.
   }
-  info.cacheInfo = cacheInfo
-  return info
+  meta.cacheInfo = cacheInfo
+  return meta
 }
 
-router.get(
-  '/v1',
-  pathValidationMiddleware as RequestHandler,
-  pageValidationMiddleware as RequestHandler,
-  catchMiddlewareError(async function pageInfo(req: ExtendedRequestWithPageInfo, res: Response) {
-    // Remember, the `validationMiddleware` will use redirects if the
-    // `pathname` used is a redirect (e.g. /en/articles/foo or
-    // /articles or '/en/enterprise-server@latest/foo/bar)
-    // So by the time we get here, the pathname should be one of the
-    // page's valid permalinks.
-    const { page, pathname, archived } = req.pageinfo
-
-    if (archived && archived.isArchived) {
-      const { requestedVersion } = archived
-      const title = `GitHub Enterprise Server ${requestedVersion} Help Documentation`
-      const intro = ''
-      const product = 'GitHub Enterprise Server'
-      defaultCacheControl(res)
-      return res.json({ info: { intro, title, product } })
-    }
+export async function getMetadata(req: ExtendedRequestWithPageInfo) {
+  // Remember, the `validationMiddleware` will use redirects if the
+  // `pathname` used is a redirect (e.g. /en/articles/foo or
+  // /articles or '/en/enterprise-server@latest/foo/bar)
+  // So by the time we get here, the pathname should be one of the
+  // page's valid permalinks.
+  const { page, pathname, archived } = req.pageinfo
+
+  if (archived && archived.isArchived) {
+    const { requestedVersion } = archived
+    const title = `GitHub Enterprise Server ${requestedVersion} Help Documentation`
+    const intro = ''
+    const product = 'GitHub Enterprise Server'
+    return { meta: { intro, title, product } }
+  }
 
-    if (!page) {
-      return res.status(400).json({ error: `No page found for '${pathname}'` })
-    }
+  if (!page) {
+    throw new Error(`No page found for '${pathname}'`)
+  }
 
-    const pagePermalinks = page.permalinks.map((p: Permalink) => p.href)
-    if (!pagePermalinks.includes(pathname)) {
-      throw new Error(`pathname '${pathname}' not one of the page's permalinks`)
-    }
+  const pagePermalinks = page.permalinks.map((p: Permalink) => p.href)
+  if (!pagePermalinks.includes(pathname)) {
+    throw new Error(`pathname '${pathname}' not one of the page's permalinks`)
+  }
 
-    const fromCache = await getPageInfoFromCache(page, pathname)
-    const { cacheInfo, ...info } = fromCache
-
-    const tags = [
-      // According to https://docs.datadoghq.com/getting_started/tagging/#define-tags
-      // the max length of a tag is 200 characters. Most of ours are less than
-      // that but we truncate just to be safe.
-      `pathname:${pathname}`.slice(0, 200),
-      `language:${page.languageCode}`,
-      `cache:${cacheInfo}`,
-    ]
-    statsd.increment('pageinfo.lookup', 1, tags)
-
-    defaultCacheControl(res)
-
-    // This is necessary so that the `Surrogate-Key` header is set with
-    // the correct language surrogate key bit. By default, it's set
-    // from the pathname but `/api/**` URLs don't have a language
-    // (other than the default 'en').
-    // We do this so that all of these URLs are cached in Fastly by language
-    // which we need for the staggered purge.
-
-    setFastlySurrogateKey(
-      res,
-      `${SURROGATE_ENUMS.DEFAULT} ${makeLanguageSurrogateKey(page.languageCode)}`,
-      true,
-    )
-    res.status(200).json({ info })
-  }),
-)
-
-// Alias for the latest version
-router.get('/', (req, res) => {
-  res.redirect(307, req.originalUrl.replace('/pageinfo', '/pageinfo/v1'))
-})
-
-export default router
+  const fromCache = await getPageInfoFromCache(page, pathname)
+  const { cacheInfo, ...meta } = fromCache
+
+  return { meta, cacheInfo }
+}