Fix URL-encoded @ symbols in versioned docs URLs (#57594)

Author: heiskr

src/frame/middleware/index.ts

@@ -66,6 +66,7 @@ import { MAX_REQUEST_TIMEOUT } from '@/frame/lib/constants'
 import { initLoggerContext } from '@/observability/logger/lib/logger-context'
 import { getAutomaticRequestLogger } from '@/observability/logger/middleware/get-automatic-request-logger'
 import appRouterGateway from './app-router-gateway'
+import urlDecode from './url-decode'
 
 const { NODE_ENV } = process.env
 const isTest = NODE_ENV === 'test' || process.env.GITHUB_ACTIONS === 'true'
@@ -199,6 +200,7 @@ export default function (app: Express) {
   app.set('etag', false) // We will manage our own ETags if desired
 
   // *** Config and context for redirects ***
+  app.use(urlDecode) // Must come before detectLanguage to decode @ symbols in version segments
   app.use(detectLanguage) // Must come before context, breadcrumbs, find-page, handle-errors, homepages
   app.use(asyncMiddleware(reloadTree)) // Must come before context
   app.use(asyncMiddleware(context)) // Must come before early-access-*, handle-redirects

src/frame/middleware/url-decode.ts

@@ -0,0 +1,28 @@
+import type { NextFunction, Response } from 'express'
+import type { ExtendedRequest } from '@/types'
+
+/**
+ * Middleware to decode URL-encoded @ symbols.
+ *
+ * SharePoint and other systems automatically encode @ symbols to %40,
+ * which breaks our versioned URLs like /en/enterprise-cloud@latest.
+ * This middleware decodes @ symbols anywhere in the URL.
+ */
+export default function urlDecode(req: ExtendedRequest, res: Response, next: NextFunction) {
+  const originalUrl = req.url
+
+  // Only process URLs that contain %40 (encoded @)
+  if (!originalUrl.includes('%40')) {
+    return next()
+  }
+
+  try {
+    // Decode the entire URL, replacing %40 with @
+    const decodedUrl = originalUrl.replace(/%40/g, '@')
+    req.url = decodedUrl
+    return next()
+  } catch {
+    // If decoding fails for any reason, continue with original URL
+    return next()
+  }
+}

src/frame/tests/url-encoding.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'vitest'
+import { get } from '@/tests/helpers/e2etest'
+
+describe('URL encoding for version paths', () => {
+  test('handles URL-encoded @ symbol in enterprise-cloud version', async () => {
+    // SharePoint encodes @ as %40, so /en/enterprise-cloud@latest becomes /en/enterprise-cloud%40latest
+    const encodedUrl = '/en/enterprise-cloud%40latest/copilot/concepts/chat'
+    const res = await get(encodedUrl)
+
+    // Should either:
+    // 1. Work directly (200) - the encoded URL should decode and work
+    // 2. Redirect (301/302) to the proper decoded URL
+    // Should NOT return 404
+    expect([200, 301, 302]).toContain(res.statusCode)
+
+    if (res.statusCode === 301 || res.statusCode === 302) {
+      // If it redirects, it should redirect to the decoded version
+      expect(res.headers.location).toBe('/en/enterprise-cloud@latest/copilot/concepts/chat')
+    }
+  })
+
+  test('handles URL-encoded @ symbol in enterprise-server version', async () => {
+    const encodedUrl =
+      '/en/enterprise-server%403.17/admin/managing-github-actions-for-your-enterprise'
+    const res = await get(encodedUrl)
+
+    expect([200, 301, 302]).toContain(res.statusCode)
+
+    if (res.statusCode === 301 || res.statusCode === 302) {
+      expect(res.headers.location).toBe(
+        '/en/enterprise-server@3.17/admin/managing-github-actions-for-your-enterprise',
+      )
+    }
+  })
+
+  test('handles URL-encoded @ symbol in second path segment', async () => {
+    // When no language prefix is present
+    const encodedUrl = '/enterprise-cloud%40latest/copilot/concepts/chat'
+    const res = await get(encodedUrl)
+
+    // Should redirect to add language prefix and decode
+    expect([301, 302]).toContain(res.statusCode)
+    expect(res.headers.location).toBe('/en/enterprise-cloud@latest/copilot/concepts/chat')
+  })
+
+  test('normal @ symbol paths continue to work', async () => {
+    // Ensure we don't break existing functionality
+    const normalUrl = '/en/enterprise-cloud@latest/copilot/concepts/chat'
+    const res = await get(normalUrl)
+
+    expect(res.statusCode).toBe(200)
+  })
+
+  test('URL encoding in other parts of URL is preserved', async () => {
+    // Only @ symbols in version paths should be decoded, other encoding should be preserved
+    const encodedUrl = '/en/enterprise-cloud@latest/copilot/concepts/some%20page'
+    const res = await get(encodedUrl)
+
+    // This might 404 if the page doesn't exist, but shouldn't break due to encoding
+    expect(res.statusCode).not.toBe(500)
+  })
+
+  test('Express URL properties are correctly updated after decoding', async () => {
+    // Test that req.path, req.query, etc. are properly updated when req.url is modified
+    const encodedUrl = '/en/enterprise-cloud%40latest/copilot/concepts/chat?test=value'
+    const res = await get(encodedUrl)
+
+    // Should work correctly (200 or redirect) - the middleware should properly update
+    // req.path from '/en/enterprise-cloud%40latest/...' to '/en/enterprise-cloud@latest/...'
+    expect([200, 301, 302]).toContain(res.statusCode)
+  })
+})