Rest redirect endpoint (github#27027)

Author: rachmari

components/article/ClientsideRedirectExceptions.tsx

@@ -1,35 +1,67 @@
 import { useEffect } from 'react'
 import { useRouter } from 'next/router'
 
-import restApiOverrides from '../../lib/redirects/static/client-side-rest-api-redirects.json'
-import productOverrides from '../../lib/redirects/static/client-side-product-redirects.json'
-const overrideRedirects: Record<string, string> = { ...restApiOverrides, ...productOverrides }
-
+// We recently moved several rest api operations around
+// in the docs. That means that we are out of sync with
+// the urls defined in the OpenAPI. We will eventually
+// update those urls but for now we want to ensure that
+// we have client-side redirects in place for any urls
+// in the product that link to the rest docs (e.g., error
+// code urls from the apis).
+// The client-side redirects can consist of operation urls
+// being redirected to the new operation url or headings
+// on a page that need to be redirected to the new page (e.g.,
+// /rest/reference/repos#statuses to
+// /rest/reference/commits#commit-statuses)
 export default function ClientSideRedirectExceptions() {
   const router = useRouter()
   useEffect(() => {
-    // We have some one-off redirects for rest api docs
-    // currently those are limited to the repos page, but
-    // that will grow soon as we restructure the rest api docs.
-    // This is a workaround to updating the hardcoded links
-    // directly in the REST API code in a separate repo, which
-    // requires many file changes and teams to sign off.
-    // While the organization is turbulent, we can do this.
-    // Once it's more settled, we can refactor the rest api code
-    // to leverage the OpenAPI urls rather than hardcoded urls.
-    const { hash, pathname } = window.location
+    // Because we have an async call to fetch, it's possible that this
+    // component unmounts before we perform the redirect, however, React
+    // will still try to perform the redirect even after the component
+    // is unmounted. To prevent this, we can use the AbortController signal
+    // to abort the Web request when the component unmounts.
+    const controller = new AbortController()
+    const signal = controller.signal
 
-    // The `hash` will start with a `#` but all the keys in
-    // `overrideRedirects` do not. Hence, this slice.
-    const combined = pathname + hash
-    const overrideKey = combined
+    const { hash, pathname } = window.location
+    // path without a version or language
+    const barePath = pathname
       .replace(`/${router.locale}`, '')
       .replace(`/${router.query.versionId || ''}`, '')
-    const redirectToName = overrideRedirects[overrideKey]
-    if (redirectToName) {
-      const newPathname = combined.replace(overrideKey, redirectToName)
-      router.replace(newPathname)
+
+    async function getRedirect() {
+      try {
+        const sp = new URLSearchParams()
+        sp.set('path', barePath)
+        sp.set('hash', hash.replace(/^#/, ''))
+
+        // call the anchor-redirect endpoint to get the redirect url
+        const response = await fetch(`/anchor-redirect?${sp.toString()}`, {
+          signal,
+        })
+
+        // the response status will always be 200 unless there
+        // was a problem with the fetch request. When the
+        // redirect doesn't exist the json response will be empty
+        if (response.ok) {
+          const { to } = await response.json()
+          if (to) {
+            // we want to redirect with the language and version in tact
+            // so we'll replace the full url's path and hash
+            const fromUrl = pathname + hash
+            const bareUrl = barePath + hash
+            const toUrl = fromUrl.replace(bareUrl, to)
+            router.replace(toUrl)
+          }
+        }
+      } catch (error) {
+        console.warn('Unable to fetch client-side redirect:', error)
+      }
     }
+    getRedirect()
+
+    return () => controller.abort()
   }, [])
 
   return null

lib/redirects/static/client-side-product-redirects.json

@@ -155,6 +155,7 @@
   "/rest/orgs#list-custom-repository-roles-in-an-organization": "/rest/orgs/custom-roles#list-custom-repository-roles-in-an-organization",
   "/rest/repos#deploy-keys": "/rest/deploy-keys",
   "/rest/deployments#deploy-keys": "/rest/deploy-keys",
+  "/rest/repos#statuses": "/rest/commits/statuses",
   "/rest/apps#get-the-authenticated-app": "/rest/apps/apps#get-the-authenticated-app",
   "/rest/apps#create-a-github-app-from-a-manifest": "/rest/apps/apps#create-a-github-app-from-a-manifest",
   "/rest/apps#get-a-webhook-configuration-for-an-app": "/rest/apps/webhooks#get-a-webhook-configuration-for-an-app",

lib/redirects/static/client-side-rest-api-redirects.json

@@ -0,0 +1,23 @@
+import express from 'express'
+import { readCompressedJsonFileFallbackLazily } from '../lib/read-json-file.js'
+
+const clientSideRestAPIRedirects = readCompressedJsonFileFallbackLazily(
+  './lib/redirects/static/client-side-rest-api-redirects.json'
+)
+console.log(clientSideRestAPIRedirects)
+
+const router = express.Router()
+
+// Returns a client side redirect if one exists for the given path.
+router.get('/', function redirects(req, res, next) {
+  if (!req.query.path) {
+    return res.status(400).send("Missing 'path' query string")
+  }
+  if (!req.query.hash) {
+    return res.status(400).send("Missing 'hash' query string")
+  }
+  const redirectFrom = `${req.query.path}#${req.query.hash}`
+  res.status(200).send({ to: clientSideRestAPIRedirects()[redirectFrom] } || null)
+})
+
+export default router

middleware/anchor-redirect.js

@@ -35,6 +35,7 @@ import archivedEnterpriseVersionsAssets from './archived-enterprise-versions-ass
 import events from './events.js'
 import search from './search.js'
 import healthz from './healthz.js'
+import anchorRedirect from './anchor-redirect.js'
 import remoteIP from './remote-ip.js'
 import archivedEnterpriseVersions from './archived-enterprise-versions.js'
 import robots from './robots.js'
@@ -263,6 +264,7 @@ export default function (app) {
   app.use('/events', asyncMiddleware(instrument(events, './events')))
   app.use('/search', asyncMiddleware(instrument(search, './search')))
   app.use('/healthz', asyncMiddleware(instrument(healthz, './healthz')))
+  app.use('/anchor-redirect', asyncMiddleware(instrument(anchorRedirect, './anchor-redirect')))
   app.get('/_ip', asyncMiddleware(instrument(remoteIP, './remoteIP')))
 
   // Check for a dropped connection before proceeding (again)

middleware/index.js

@@ -778,6 +778,7 @@
   },
   "sectionUrls": {
     "/rest/repos#deploy-keys": "/rest/deploy-keys",
-    "/rest/deployments#deploy-keys": "/rest/deploy-keys"
+    "/rest/deployments#deploy-keys": "/rest/deploy-keys",
+    "/rest/repos#statuses": "/rest/commits/statuses"
   }
 }

script/rest/utils/rest-api-overrides.json

@@ -0,0 +1,44 @@
+import { describe, expect } from '@jest/globals'
+import { get } from '../helpers/e2etest.js'
+import clientSideRedirects from '../../lib/redirects/static/client-side-rest-api-redirects.json'
+
+describe('anchor-redirect middleware', () => {
+  test('returns correct redirect to url', async () => {
+    // test the first entry
+    const [key, value] = Object.entries(clientSideRedirects)[0]
+    const [path, hash] = key.split('#')
+    const sp = new URLSearchParams()
+    sp.set('path', path)
+    sp.set('hash', hash)
+    const res = await get('/anchor-redirect?' + sp)
+    expect(res.statusCode).toBe(200)
+    const { to } = JSON.parse(res.text)
+    expect(to).toBe(value)
+  })
+  test('errors when path is not passed', async () => {
+    // test the first entry
+    const key = Object.keys(clientSideRedirects)[0]
+    const hash = key.split('#')[1]
+    const sp = new URLSearchParams()
+    sp.set('hash', hash)
+    const res = await get('/anchor-redirect?' + sp)
+    expect(res.statusCode).toBe(400)
+  })
+  test('errors when path is not passed', async () => {
+    // test the first entry
+    const key = Object.keys(clientSideRedirects)[0]
+    const path = key.split('#')[0]
+    const sp = new URLSearchParams()
+    sp.set('path', path)
+    const res = await get('/anchor-redirect?' + sp)
+    expect(res.statusCode).toBe(400)
+  })
+  test('unfound redirect returns undefined', async () => {
+    const sp = new URLSearchParams()
+    sp.set('path', 'foo')
+    sp.set('hash', 'bar')
+    const res = await get('/anchor-redirect?' + sp)
+    const { to } = JSON.parse(res.text)
+    expect(to).toBe(undefined)
+  })
+})