Skip to content

An AI-powered search engine with a generative UI

feat(ops): add a maintenance mode switch (#1097)

Yoshiki Miura35fbbce4398d
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index b1351aea..4da71c91 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -506,6 +506,16 @@ To keep the server from requesting pages itself, send the `regular` fetch type t
FETCH_REGULAR_VIA_API=true
```
+### Maintenance Mode
+
+To take the instance offline while running a long database migration:
+
+```bash
+MAINTENANCE_MODE=true
+```
+
+Every page then returns a static maintenance page and every API route returns `503` JSON. Paths the proxy matcher skips (static assets, image-extension paths and `/api/favicon`) are still served. The value is read at request time, but most hosts (including Vercel) apply an environment change only on the next deployment.
+
### Source Favicons
Favicons for cited sources are fetched by the server and served from your own origin at `/api/favicon`, so a visitor's browser never tells the icon provider which sources a result cites. Responses are cached in memory and at the edge.
diff --git a/lib/__tests__/maintenance.test.ts b/lib/__tests__/maintenance.test.ts
new file mode 100644
index 00000000..41e0e45b
--- /dev/null
+++ b/lib/__tests__/maintenance.test.ts
@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { isMaintenanceMode, maintenanceResponse } from '../maintenance'
+
+describe('maintenance mode', () => {
+ afterEach(() => vi.unstubAllEnvs())
+
+ it('is on only when MAINTENANCE_MODE is "true"', () => {
+ vi.stubEnv('MAINTENANCE_MODE', '')
+ expect(isMaintenanceMode()).toBe(false)
+ vi.stubEnv('MAINTENANCE_MODE', '1')
+ expect(isMaintenanceMode()).toBe(false)
+ vi.stubEnv('MAINTENANCE_MODE', 'true')
+ expect(isMaintenanceMode()).toBe(true)
+ })
+
+ it('serves an HTML page with 503 for pages', async () => {
+ const response = maintenanceResponse('/search/abc')
+ expect(response.status).toBe(503)
+ expect(response.headers.get('Retry-After')).toBe('600')
+ expect(response.headers.get('Content-Type')).toContain('text/html')
+ expect(await response.text()).toContain('maintenance')
+ })
+
+ it('serves JSON with 503 for API routes', async () => {
+ const response = maintenanceResponse('/api/chat')
+ expect(response.status).toBe(503)
+ expect(await response.json()).toEqual({
+ error: 'Service under maintenance'
+ })
+ })
+})
diff --git a/lib/maintenance.ts b/lib/maintenance.ts
new file mode 100644
index 00000000..8ceba60c
--- /dev/null
+++ b/lib/maintenance.ts
@@ -0,0 +1,61 @@
+import { NextResponse } from 'next/server'
+
+const RETRY_AFTER_SECONDS = '600'
+
+const MAINTENANCE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>Under maintenance</title>
+<style>
+ :root { color-scheme: light dark; }
+ body {
+ margin: 0;
+ min-height: 100vh;
+ display: grid;
+ place-items: center;
+ padding: 0 16px;
+ font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+ background: #fff;
+ color: #111;
+ }
+ @media (prefers-color-scheme: dark) {
+ body { background: #0a0a0a; color: #ededed; }
+ p { color: #a1a1a1; }
+ }
+ main { max-width: 28rem; text-align: center; }
+ h1 { font-size: 1.25rem; font-weight: 600; margin: 0 0 0.5rem; }
+ p { margin: 0; line-height: 1.6; color: #555; }
+</style>
+</head>
+<body>
+<main>
+ <h1>We'll be back shortly</h1>
+ <p>Morphic is undergoing scheduled maintenance. Your chats are safe. Please check back in a few minutes.</p>
+</main>
+</body>
+</html>`
+
+export function isMaintenanceMode(): boolean {
+ return process.env.MAINTENANCE_MODE === 'true'
+}
+
+// API callers get JSON so clients can show their own error state
+export function maintenanceResponse(pathname: string): NextResponse {
+ const headers = {
+ 'Retry-After': RETRY_AFTER_SECONDS,
+ 'Cache-Control': 'no-store'
+ }
+ if (pathname.startsWith('/api/')) {
+ return NextResponse.json(
+ { error: 'Service under maintenance' },
+ { status: 503, headers }
+ )
+ }
+ return new NextResponse(MAINTENANCE_HTML, {
+ status: 503,
+ headers: { ...headers, 'Content-Type': 'text/html; charset=utf-8' }
+ })
+}
diff --git a/proxy.ts b/proxy.ts
index 97f6e108..1cbe53ba 100644
--- a/proxy.ts
+++ b/proxy.ts
@@ -7,6 +7,7 @@ import {
relayTarget
} from '@/lib/analytics/relay-target'
import { getAuthProvider, resolveAuthProviderName } from '@/lib/auth/provider'
+import { isMaintenanceMode, maintenanceResponse } from '@/lib/maintenance'
// Better Auth sends /relay through the route handler. Other providers
// proxy straight to PostHog so analytics requests cost no function
@@ -32,6 +33,10 @@ function relayRewrite(request: NextRequest): NextResponse | null {
}
export async function proxy(request: NextRequest) {
+ if (isMaintenanceMode()) {
+ return maintenanceResponse(request.nextUrl.pathname)
+ }
+
const relay = relayRewrite(request)
if (relay) {
return relay