Профили рендеринга frontend-приложений¶

Требования применяются к разработке и сборке frontend-приложений с client-side rendering (CSR), server-side rendering (SSR), static site generation (SSG) или выполнением на edge. Уровни обязательности определены в корневом README.md.

CSR означает создание пользовательского представления преимущественно в браузере; SSR — создание HTML серверным runtime на запрос; SSG — создание HTML во время сборки; edge — выполнение frontend-кода в ограниченном runtime между клиентом и origin.

FE-PROF-001. Машинно-читаемый профиль рендеринга¶

Уровень: MUST

Применяется к: каждому frontend-приложению

Проект должен зафиксировать применяемые профили csr, ssr, ssg и edge, точки входа каждого профиля и маршруты, которые он обслуживает. Один маршрут может использовать несколько стадий рендеринга только с явно определённой последовательностью и источником окончательного состояния.

Обоснование¶

Профиль определяет доступные API, границу доверия и состав артефакта.

Проверка¶

review машинно-читаемой конфигурации framework и маршрутов;
сборка каждой объявленной точки входа;
тест выбора профиля для каждого маршрута.

Исключения¶

Не допускаются.

FE-PROF-002. Разделение клиентского и доверенного кода¶

Уровень: MUST

Применяется к: проекту с SSR, SSG или edge

Модуль, включаемый в browser bundle, не должен импортировать server-only или edge-only код, secrets, файловую систему либо внутренний backend client. Доверенный модуль не должен передавать в HTML, hydration state или client bundle данные сверх публичного контракта страницы.

Обоснование¶

Общий module graph может незаметно раскрыть серверный код или данные клиенту.

Проверка¶

статическая проверка границ импортов;
анализ состава browser bundle и HTML;
тест с marker-значением server-only конфигурации.

Исключения¶

Изоморфный модуль допустим, если он зависит только от API, доступных во всех целевых runtime, и не получает доверенные данные.

FE-PROF-003. Детерминированная гидратация¶

Уровень: MUST

Применяется к: HTML, который продолжает выполнение в браузере

Серверная или статическая разметка и первый клиентский render должны создавать совместимое состояние. Время, случайность, локаль, timezone и данные запроса должны передаваться явно либо вычисляться после hydration. Ошибка hydration не должна молча заменять защищённое или пользовательское содержимое другим состоянием.

Обоснование¶

Различие первого render вызывает потерю состояния и непредсказуемый интерфейс.

Проверка¶

component- или e2e-тест hydration без mismatch;
тест различающихся locale, timezone и clock;
тест недоступности данных после формирования HTML.

Исключения¶

Изолированный client-only компонент может не иметь серверной разметки, если его граница объявлена и основной сценарий остаётся работоспособным.

FE-PROF-004. Изоляция данных запросов SSR и edge¶

Уровень: MUST

Применяется к: состоянию, создаваемому при обработке запроса SSR или edge

Изменяемое состояние пользователя, запроса, авторизации и персонализации не должно храниться в module-level singleton или переиспользоваться между запросами. Cache key должен включать все входы, влияющие на разграничение доступа и представление; защищённый ответ не должен становиться публично кэшируемым.

Обоснование¶

Повторное использование runtime способно раскрыть данные между запросами.

Проверка¶

параллельный тест запросов разных субъектов;
статическая проверка mutable global state;
contract-тест cache key и заголовков ответа.

Исключения¶

Неизменяемые публичные данные могут совместно использоваться всеми запросами.

FE-PROF-005. Воспроизводимость SSG¶

Уровень: MUST

Применяется к: данным и страницам, создаваемым при SSG

Build должен получать входные данные из зафиксированного snapshot, версии контракта или иного воспроизводимого источника. Недоступность либо неполнота обязательного источника должна завершать сборку ошибкой. Секрет, использованный для чтения данных, не должен попадать в созданные страницы и metadata.

Обоснование¶

Незафиксированный источник делает содержание release зависимым от момента сборки и скрывает неполные страницы.

Проверка¶

повторная сборка с теми же входными данными;
тест недоступного и неполного источника;
поиск marker-секрета в output.

Исключения¶

Явно изменяемая дата сборки допустима как metadata, если она не влияет на пользовательскую семантику.

FE-PROF-007. Безопасная сериализация клиентского состояния¶

Уровень: MUST

Применяется к: данным, встраиваемым в HTML для hydration или client runtime

Данные должны сериализоваться предназначенным для контекста механизмом, который не позволяет закрыть текущий HTML-элемент или создать исполняемый script, attribute либо URL. Конкатенация непроверенного значения в HTML или JavaScript запрещена. После parsing данные должны проходить проверку клиентской схемой.

Обоснование¶

Корректная JSON-сериализация сама по себе не гарантирует безопасность внутри HTML-контекста.

Проверка¶

security-тест закрывающих tags, Unicode separators и HTML entities;
статическая проверка конкатенации;
schema validation восстановленного состояния.

Исключения¶

Статическое значение без внешних данных остаётся в области Content Security Policy и сборочных проверок.