Commit 7fdc9e48 authored by Max Leiter's avatar Max Leiter

<LowPriority>

parent e2eee896
......@@ -867,5 +867,7 @@
"866": "Both \"%s\" and \"%s\" files are detected. Please use \"%s\" instead.",
"867": "The %s \"%s\" must export a %s or a \\`default\\` function",
"868": "No reference found for param: %s in reference: %s",
"869": "No reference found for segment: %s with reference: %s"
"869": "No reference found for segment: %s with reference: %s",
"870": "LowPriority is a server component and cannot be used on the client.",
"871": "network() can only be called from a Server Component or Server Action."
}
export {
LowPriority,
type LowPriorityProps,
type LowPriorityWhen,
} from 'next/dist/server/components/low-priority'
module.exports = require('next/dist/server/components/low-priority')
......@@ -41,6 +41,8 @@
"link.d.ts",
"form.js",
"form.d.ts",
"low-priority.js",
"low-priority.d.ts",
"router.js",
"router.d.ts",
"jest.js",
......
......@@ -15,3 +15,5 @@ export { ImageResponse } from 'next/dist/server/web/spec-extension/image-respons
export type { ImageResponseOptions } from 'next/dist/compiled/@vercel/og/types'
export { after } from 'next/dist/server/after'
export { connection } from 'next/dist/server/request/connection'
export { network } from 'next/dist/server/request/network'
export type { NetworkProfile } from 'next/dist/server/app-render/network-profile'
......@@ -13,6 +13,7 @@ const serverExports = {
.URLPattern,
after: require('next/dist/server/after').after,
connection: require('next/dist/server/request/connection').connection,
network: require('next/dist/server/request/network').network,
}
// https://nodejs.org/api/esm.html#commonjs-namespaces
......@@ -28,3 +29,4 @@ exports.userAgent = serverExports.userAgent
exports.URLPattern = serverExports.URLPattern
exports.after = serverExports.after
exports.connection = serverExports.connection
exports.network = serverExports.network
......@@ -18,6 +18,7 @@ import type {
PrerenderStoreModernRuntime,
RequestStore,
} from '../app-render/work-unit-async-storage.external'
import { extractNetworkHints, createNetworkProfile } from './network-profile'
import type { NextParsedUrlQuery } from '../request-meta'
import type { LoaderTree } from '../lib/app-dir-module'
import type { AppPageModule } from '../route-modules/app-page/module'
......@@ -2069,6 +2070,55 @@ export const renderToHTMLOrFlight: AppPageRender = (
)
}
// Extract network profile from request headers (Client Hints)
const networkHints = extractNetworkHints(req.headers)
const networkProfile = createNetworkProfile(networkHints)
// Advertise support for Network Information API Client Hints
// This tells browsers to send ECT, RTT, Downlink, and Save-Data headers
if (!res.hasHeader('Accept-CH')) {
res.setHeader('Accept-CH', 'ECT, RTT, Downlink, Save-Data')
} else {
const existingAcceptCH = res.getHeader('Accept-CH')
const hints = ['ECT', 'RTT', 'Downlink', 'Save-Data']
const existingHints = existingAcceptCH
? String(existingAcceptCH)
.split(',')
.map((h) => h.trim())
: []
const newHints = hints.filter((h) => !existingHints.includes(h))
if (newHints.length > 0) {
res.setHeader('Accept-CH', [...existingHints, ...newHints].join(', '))
}
}
// Mark as critical so browsers send hints on first request
if (!res.hasHeader('Critical-CH')) {
res.setHeader('Critical-CH', 'ECT, RTT, Downlink')
}
// Add Vary header to ensure proper caching based on network hints
if (!res.hasHeader('Vary')) {
res.setHeader('Vary', 'ECT, RTT, Downlink, Save-Data')
} else {
const existingVary = res.getHeader('Vary')
const varyHeaders = ['ECT', 'RTT', 'Downlink', 'Save-Data']
const existingVaryHeaders = existingVary
? String(existingVary)
.split(',')
.map((h) => h.trim())
: []
const newVaryHeaders = varyHeaders.filter(
(h) => !existingVaryHeaders.includes(h)
)
if (newVaryHeaders.length > 0) {
res.setHeader(
'Vary',
[...existingVaryHeaders, ...newVaryHeaders].join(', ')
)
}
}
const workStore = createWorkStore({
page: renderOpts.routeModule.definition.page,
renderOpts,
......@@ -2077,6 +2127,7 @@ export const renderToHTMLOrFlight: AppPageRender = (
buildId: sharedContext.buildId,
previouslyRevalidatedTags,
nonce,
networkProfile,
})
return workAsyncStorage.run(
......
import { describe, it, expect } from '@jest/globals'
import {
decideSlow,
extractNetworkHints,
createNetworkProfile,
type NetworkProfileInput,
} from './network-profile'
describe('network-profile', () => {
describe('decideSlow', () => {
it('should return true when saveData is enabled', () => {
const profile: NetworkProfileInput = {
saveData: true,
}
expect(decideSlow(profile)).toBe(true)
})
it('should return true when ect is slow-2g', () => {
const profile: NetworkProfileInput = {
ect: 'slow-2g',
}
expect(decideSlow(profile)).toBe(true)
})
it('should return true when ect is 2g', () => {
const profile: NetworkProfileInput = {
ect: '2g',
}
expect(decideSlow(profile)).toBe(true)
})
it('should return false when ect is 3g', () => {
const profile: NetworkProfileInput = {
ect: '3g',
}
expect(decideSlow(profile)).toBe(false)
})
it('should return false when ect is 4g', () => {
const profile: NetworkProfileInput = {
ect: '4g',
}
expect(decideSlow(profile)).toBe(false)
})
it('should return true when rtt > 800', () => {
const profile: NetworkProfileInput = {
rtt: 900,
}
expect(decideSlow(profile)).toBe(true)
})
it('should return false when rtt <= 800', () => {
const profile: NetworkProfileInput = {
rtt: 800,
}
expect(decideSlow(profile)).toBe(false)
})
it('should return true when downlink < 1.5', () => {
const profile: NetworkProfileInput = {
downlink: 1.0,
}
expect(decideSlow(profile)).toBe(true)
})
it('should return false when downlink >= 1.5', () => {
const profile: NetworkProfileInput = {
downlink: 1.5,
}
expect(decideSlow(profile)).toBe(false)
})
it('should return false when downlink is 0', () => {
const profile: NetworkProfileInput = {
downlink: 0,
}
expect(decideSlow(profile)).toBe(false)
})
it('should return true when backpressure is high', () => {
const profile: NetworkProfileInput = {
backpressure: 'high',
}
expect(decideSlow(profile)).toBe(true)
})
it('should return false when backpressure is low', () => {
const profile: NetworkProfileInput = {
backpressure: 'low',
}
expect(decideSlow(profile)).toBe(false)
})
it('should return false when backpressure is none', () => {
const profile: NetworkProfileInput = {
backpressure: 'none',
}
expect(decideSlow(profile)).toBe(false)
})
it('should return true when multiple slow conditions are met', () => {
const profile: NetworkProfileInput = {
saveData: true,
ect: '2g',
rtt: 1000,
downlink: 0.5,
}
expect(decideSlow(profile)).toBe(true)
})
it('should return false when no slow conditions are met', () => {
const profile: NetworkProfileInput = {
saveData: false,
ect: '4g',
rtt: 50,
downlink: 10,
backpressure: 'none',
}
expect(decideSlow(profile)).toBe(false)
})
it('should return false when profile is empty', () => {
const profile: NetworkProfileInput = {}
expect(decideSlow(profile)).toBe(false)
})
})
describe('extractNetworkHints', () => {
it('should extract hints from Headers object', () => {
const headers = new Headers({
'save-data': 'on',
ect: '3g',
downlink: '5.0',
rtt: '100',
})
const hints = extractNetworkHints(headers)
expect(hints).toEqual({
saveData: true,
ect: '3g',
downlink: 5.0,
rtt: 100,
})
})
it('should extract hints from Map', () => {
const headers = new Map<string, string>([
['save-data', 'on'],
['ect', '4g'],
['downlink', '10.5'],
['rtt', '50'],
])
const hints = extractNetworkHints(headers)
expect(hints).toEqual({
saveData: true,
ect: '4g',
downlink: 10.5,
rtt: 50,
})
})
it('should extract hints from plain object', () => {
const headers = {
'save-data': 'on',
ect: '2g',
downlink: '1.2',
rtt: '900',
}
const hints = extractNetworkHints(headers)
expect(hints).toEqual({
saveData: true,
ect: '2g',
downlink: 1.2,
rtt: 900,
})
})
it('should handle missing headers', () => {
const headers = new Headers()
const hints = extractNetworkHints(headers)
expect(hints).toEqual({
saveData: false,
ect: undefined,
downlink: undefined,
rtt: undefined,
})
})
it('should handle save-data: off', () => {
const headers = new Headers({
'save-data': 'off',
})
const hints = extractNetworkHints(headers)
expect(hints.saveData).toBe(false)
})
it('should handle array values in plain object', () => {
const headers = {
'save-data': ['on', 'extra'],
ect: ['3g'],
}
const hints = extractNetworkHints(headers)
expect(hints.saveData).toBe(true)
expect(hints.ect).toBe('3g')
})
it('should handle case-insensitive header values', () => {
const headers = new Headers({
'save-data': 'ON',
ect: '3G',
})
const hints = extractNetworkHints(headers)
expect(hints.saveData).toBe(true)
expect(hints.ect).toBe('3g')
})
})
describe('createNetworkProfile', () => {
it('should create profile with slow=true for slow conditions', () => {
const input: NetworkProfileInput = {
saveData: true,
}
const profile = createNetworkProfile(input)
expect(profile).toEqual({
saveData: true,
slow: true,
})
})
it('should create profile with slow=false for fast conditions', () => {
const input: NetworkProfileInput = {
ect: '4g',
rtt: 50,
downlink: 10,
}
const profile = createNetworkProfile(input)
expect(profile).toEqual({
ect: '4g',
rtt: 50,
downlink: 10,
slow: false,
})
})
it('should preserve all input fields', () => {
const input: NetworkProfileInput = {
saveData: false,
ect: '3g',
rtt: 200,
downlink: 5,
backpressure: 'low',
}
const profile = createNetworkProfile(input)
expect(profile).toEqual({
saveData: false,
ect: '3g',
rtt: 200,
downlink: 5,
backpressure: 'low',
slow: false,
})
})
})
})
export type NetworkEffectiveConnectionType =
| 'slow-2g'
| '2g'
| '3g'
| '4g'
| undefined
export type NetworkBackpressure = 'none' | 'low' | 'high'
export interface NetworkProfile {
ect?: NetworkEffectiveConnectionType
rtt?: number // milliseconds
downlink?: number // Mbps
saveData?: boolean
backpressure?: NetworkBackpressure
slow: boolean
}
export type NetworkProfileInput = Omit<NetworkProfile, 'slow'>
/**
* Determines if the network should be considered "slow" based on the profile.
* A network is considered slow if any of the following conditions are met:
* - Save-Data header is enabled
* - ECT is slow-2g or 2g
* - RTT is greater than 800ms
* - Downlink is less than 1.5 Mbps (if available)
* - Backpressure is high
*/
export function decideSlow(profile: NetworkProfileInput): boolean {
const ectSlow = profile.ect === 'slow-2g' || profile.ect === '2g'
const rttSlow = (profile.rtt ?? 0) > 800
const dlSlow =
profile.downlink !== undefined &&
profile.downlink > 0 &&
profile.downlink < 1.5
const bpSlow = profile.backpressure === 'high'
return profile.saveData === true || ectSlow || rttSlow || dlSlow || bpSlow
}
/**
* Extract network hints from request headers.
* These headers are sent by browsers that support Network Information API Client Hints.
*/
export function extractNetworkHints(
headers:
| Headers
| Map<string, string | string[] | undefined>
| Record<string, string | string[] | undefined>
): NetworkProfileInput {
const getHeader = (name: string): string | undefined => {
if (headers instanceof Headers) {
return headers.get(name)?.toLowerCase() || undefined
}
if (headers instanceof Map) {
const value = headers.get(name)
if (typeof value === 'string') return value.toLowerCase()
if (Array.isArray(value)) return value[0]?.toLowerCase()
return undefined
}
// Handle plain object (IncomingHttpHeaders)
const value = headers[name]
if (typeof value === 'string') return value.toLowerCase()
if (Array.isArray(value)) return value[0]?.toLowerCase()
return undefined
}
const saveDataValue = getHeader('save-data')
const ectValue = getHeader('ect')
const downlinkValue = getHeader('downlink')
const rttValue = getHeader('rtt')
return {
saveData: saveDataValue === 'on',
ect: ectValue as NetworkEffectiveConnectionType,
downlink: downlinkValue ? Number(downlinkValue) : undefined,
rtt: rttValue ? Number(rttValue) : undefined,
}
}
/**
* Creates a complete network profile with the slow determination.
*/
export function createNetworkProfile(
input: NetworkProfileInput
): NetworkProfile {
return {
...input,
slow: decideSlow(input),
}
}
......@@ -5,6 +5,7 @@ import type { DeepReadonly } from '../../shared/lib/deep-readonly'
import type { AppSegmentConfig } from '../../build/segment-config/app/app-segment-config'
import type { AfterContext } from '../after/after-context'
import type { CacheLife } from '../use-cache/cache-life'
import type { NetworkProfile } from './network-profile'
// Share the instance module in the next-shared layer
import { workAsyncStorageInstance } from './work-async-storage-instance' with { 'turbopack-transition': 'next-shared' }
......@@ -100,6 +101,12 @@ export interface WorkStore {
cacheComponentsEnabled: boolean
dev: boolean
/**
* Network profile information for the current request.
* Contains network quality hints and whether the connection is considered slow.
*/
readonly networkProfile?: NetworkProfile
/**
* Run the given function inside a clean AsyncLocalStorage snapshot. This is
* useful when generating cache entries, to ensure that the cache generation
......
......@@ -5,6 +5,7 @@ import type { FetchMetric } from '../base-http'
import type { RequestLifecycleOpts } from '../base-server'
import type { AppSegmentConfig } from '../../build/segment-config/app/app-segment-config'
import type { CacheLife } from '../use-cache/cache-life'
import type { NetworkProfile } from '../app-render/network-profile'
import { AfterContext } from '../after/after-context'
......@@ -71,6 +72,11 @@ export type WorkStoreContext = {
// Tags that were previously revalidated (e.g. by a redirecting server action)
// and have already been sent to cache handlers.
previouslyRevalidatedTags: string[]
/**
* Network profile information for the current request.
*/
networkProfile?: NetworkProfile
}
export function createWorkStore({
......@@ -80,6 +86,7 @@ export function createWorkStore({
buildId,
previouslyRevalidatedTags,
nonce,
networkProfile,
}: WorkStoreContext): WorkStore {
/**
* Rules of Static & Dynamic HTML:
......@@ -144,6 +151,7 @@ export function createWorkStore({
refreshTagsByCacheKind: createRefreshTagsByCacheKind(),
runInCleanSnapshot: createSnapshot(),
shouldTrackFetchMetrics,
networkProfile,
}
// TODO: remove this when we resolve accessing the store outside the execution context
......
import * as React from 'react'
import { workAsyncStorage } from '../app-render/work-async-storage.external'
export type LowPriorityWhen = 'auto' | 'always' | 'never'
export interface LowPriorityProps {
/**
* When to show the fallback instead of children:
* - 'auto': Show fallback only on slow network connections (default)
* - 'always': Always show fallback
* - 'never': Never show fallback, always show children
*/
when?: LowPriorityWhen
/**
* Content to render when the connection is slow or when="always".
* Defaults to null.
*/
fallback?: React.ReactNode
/**
* Content to render on fast connections or when when="never"
*/
children: React.ReactNode
}
/**
* LowPriority is a server component that conditionally renders children
* based on network quality indicators.
*
* When network is detected as "slow" (based on Client Hints or other signals),
* the fallback is rendered instead of children. This allows you to:
* - Skip expensive components on slow connections
* - Reduce initial payload size for low-bandwidth users
* - Provide a lighter experience on 2G/3G networks
*
* @example
* ```tsx
* import { LowPriority } from 'next/low-priority'
*
* export default function Page() {
* return (
* <>
* <Hero />
* <LowPriority fallback={<SimpleRecommendations />}>
* <RichRecommendations />
* </LowPriority>
* </>
* )
* }
* ```
*/
export function LowPriority({
when = 'auto',
fallback = null,
children,
}: LowPriorityProps): React.ReactElement {
// Force this to be a server component
if (typeof window !== 'undefined') {
throw new Error(
'LowPriority is a server component and cannot be used on the client.'
)
}
// Handle 'never' case - always show children
if (when === 'never') {
return <>{children}</>
}
// Handle 'always' case - always show fallback
if (when === 'always') {
return <>{fallback}</>
}
// Handle 'auto' case - check network profile
const store = workAsyncStorage.getStore()
const networkProfile = store?.networkProfile
// If no network profile is available, show children (fast path default)
const isSlow = networkProfile?.slow ?? false
return <>{isSlow ? fallback : children}</>
}
import { workAsyncStorage } from '../app-render/work-async-storage.external'
import type { NetworkProfile } from '../app-render/network-profile'
/**
* Get the network profile information for the current request.
*
* This function provides access to network quality indicators including:
* - ECT (Effective Connection Type): slow-2g, 2g, 3g, or 4g
* - RTT (Round Trip Time) in milliseconds
* - Downlink bandwidth in Mbps
* - Save-Data preference
* - slow: boolean indicating if the connection is considered slow
*
* The information is derived from Client Hints headers sent by the browser.
* Not all browsers support these headers, so values may be undefined.
*
* @returns The network profile for the current request
* @throws Error if called outside of a request context
*
* @example
* ```tsx
* import { network } from 'next/server'
*
* export default function Page() {
* const net = network()
*
* if (net.slow) {
* return <LightweightVersion />
* }
*
* return <FullExperience />
* }
* ```
*
* @example
* ```tsx
* import { network } from 'next/server'
*
* export default function Page() {
* const { ect, rtt, downlink, saveData } = network()
*
* console.log('Connection type:', ect) // 'slow-2g' | '2g' | '3g' | '4g'
* console.log('Round trip time:', rtt) // milliseconds
* console.log('Downlink speed:', downlink) // Mbps
* console.log('Save data enabled:', saveData) // boolean
* }
* ```
*/
export function network(): NetworkProfile {
const store = workAsyncStorage.getStore()
if (!store) {
throw new Error(
'network() can only be called from a Server Component or Server Action.'
)
}
// Return a default profile if network profile is not available
return (
store.networkProfile ?? {
slow: false,
}
)
}
import { LowPriority } from 'next/low-priority'
export default function AlwaysPage() {
return (
<div>
<h1>Always Fallback</h1>
<LowPriority when="always" fallback={<div>Always Fallback</div>}>
<div>Full Content</div>
</LowPriority>
</div>
)
}
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
import { network } from 'next/server'
export default function NetworkApiPage() {
const net = network()
return (
<div>
<h1>Network API</h1>
<div id="ect">ECT: {net.ect ?? 'unknown'}</div>
<div id="rtt">RTT: {net.rtt ?? 'unknown'}</div>
<div id="downlink">Downlink: {net.downlink ?? 'unknown'}</div>
<div id="save-data">Save Data: {String(net.saveData ?? false)}</div>
<div id="slow">Slow: {String(net.slow)}</div>
</div>
)
}
import { LowPriority } from 'next/low-priority'
export default function NeverPage() {
return (
<div>
<h1>Never Skip</h1>
<LowPriority when="never" fallback={<div>Never Fallback</div>}>
<div>Never Skipped Content</div>
</LowPriority>
</div>
)
}
import { LowPriority } from 'next/low-priority'
export default function Page() {
return (
<div>
<h1>Low Priority Test</h1>
<LowPriority fallback={<div id="content">Fallback Content</div>}>
<div id="content">Full Content</div>
</LowPriority>
</div>
)
}
import { nextTestSetup } from 'e2e-utils'
describe('low-priority', () => {
const { next } = nextTestSetup({
files: __dirname,
})
describe('LowPriority component - server-side rendering', () => {
// Testing the server-side behavior by sending Client Hints headers directly.
// In production, these headers would be sent automatically by browsers that
// support Network Information API Client Hints (based on Accept-CH response headers).
it('should render children by default (no network hints)', async () => {
const $ = await next.render$('/')
expect($('#content').text()).toBe('Full Content')
})
it('should render children with fast network (4g)', async () => {
const res = await next.fetch('/', {
headers: {
ect: '4g',
rtt: '50',
downlink: '10',
},
})
const html = await res.text()
expect(html).toContain('Full Content')
expect(html).not.toContain('Fallback Content')
})
it('should render fallback with slow network (2g)', async () => {
const res = await next.fetch('/', {
headers: {
ect: '2g',
},
})
const html = await res.text()
expect(html).not.toContain('Full Content')
expect(html).toContain('Fallback Content')
})
it('should render fallback with save-data enabled', async () => {
const res = await next.fetch('/', {
headers: {
'save-data': 'on',
},
})
const html = await res.text()
expect(html).not.toContain('Full Content')
expect(html).toContain('Fallback Content')
})
it('should render fallback with high RTT', async () => {
const res = await next.fetch('/', {
headers: {
rtt: '1000',
},
})
const html = await res.text()
expect(html).not.toContain('Full Content')
expect(html).toContain('Fallback Content')
})
it('should render fallback with low downlink', async () => {
const res = await next.fetch('/', {
headers: {
downlink: '0.5',
},
})
const html = await res.text()
expect(html).not.toContain('Full Content')
expect(html).toContain('Fallback Content')
})
})
describe('LowPriority with when="always"', () => {
it('should always render fallback regardless of network', async () => {
const res = await next.fetch('/always', {
headers: {
ect: '4g',
rtt: '50',
downlink: '10',
},
})
const html = await res.text()
expect(html).not.toContain('Full Content')
expect(html).toContain('Always Fallback')
})
})
describe('LowPriority with when="never"', () => {
it('should always render children regardless of network', async () => {
const res = await next.fetch('/never', {
headers: {
ect: '2g',
'save-data': 'on',
},
})
const html = await res.text()
expect(html).toContain('Never Skipped Content')
expect(html).not.toContain('Never Fallback')
})
})
describe('network() API', () => {
it('should expose network profile with fast connection', async () => {
const res = await next.fetch('/network-api', {
headers: {
ect: '4g',
rtt: '50',
downlink: '10',
},
})
const html = await res.text()
expect(html).toContain('ECT: 4g')
expect(html).toContain('RTT: 50')
expect(html).toContain('Downlink: 10')
expect(html).toContain('Slow: false')
})
it('should expose network profile with slow connection', async () => {
const res = await next.fetch('/network-api', {
headers: {
ect: '2g',
rtt: '900',
downlink: '1',
},
})
const html = await res.text()
expect(html).toContain('ECT: 2g')
expect(html).toContain('RTT: 900')
expect(html).toContain('Downlink: 1')
expect(html).toContain('Slow: true')
})
it('should handle missing network hints', async () => {
const $ = await next.render$('/network-api')
expect($('#slow').text()).toBe('Slow: false')
})
})
describe('Client Hints headers', () => {
it('should send Accept-CH header to advertise support', async () => {
const res = await next.fetch('/')
const acceptCH = res.headers.get('Accept-CH')
expect(acceptCH).toBeTruthy()
expect(acceptCH).toContain('ECT')
expect(acceptCH).toContain('RTT')
expect(acceptCH).toContain('Downlink')
expect(acceptCH).toContain('Save-Data')
})
it('should send Critical-CH header for first-request hints', async () => {
const res = await next.fetch('/')
const criticalCH = res.headers.get('Critical-CH')
expect(criticalCH).toBeTruthy()
expect(criticalCH).toContain('ECT')
expect(criticalCH).toContain('RTT')
expect(criticalCH).toContain('Downlink')
})
it('should send Vary header for proper caching', async () => {
const res = await next.fetch('/')
const vary = res.headers.get('Vary')
expect(vary).toBeTruthy()
expect(vary).toContain('ECT')
expect(vary).toContain('RTT')
expect(vary).toContain('Downlink')
expect(vary).toContain('Save-Data')
})
})
})
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment