Статические файлы

Статические файлы

Раздача статических файлов из любой файловой системы через http.static. Обработчики статики монтируются напрямую на сервер и могут раздавать SPA, ассеты или пользовательские загрузки с любого пути.

Конфигурация

- name: static
  kind: http.static
  meta:
    server: gateway
  path: /
  fs: app:public
  directory: dist
  static_options:
    spa: true
    index: index.html
    cache: "public, max-age=3600"

Поле	Тип	Описание
meta.server	Registry ID	Родительский HTTP-сервер
path	string	URL-путь монтирования (начинается с /)
fs	Registry ID	Запись файловой системы для раздачи
directory	string	Поддиректория внутри файловой системы
static_options.spa	bool	SPA-режим — отдавать index для несопоставленных путей
static_options.index	string	Index-файл (обязателен при spa=true)
static_options.cache	string	Значение заголовка Cache-Control
middleware	[]string	Цепочка middleware
options	map	Опции middleware (точечная нотация)

Обработчики статики можно монтировать на любой путь сервера. Несколько обработчиков могут сосуществовать — монтируйте ассеты на /static, а SPA на /.

Интеграция с файловой системой

Статические файлы раздаются из записей файловых систем. Подходит любой тип:

entries:
  # Локальная директория
  - name: public
    kind: fs.directory
    directory: ./public

  # Обработчик статики
  - name: static
    kind: http.static
    meta:
      server: gateway
    path: /static
    fs: public

Запрос /static/css/style.css отдаёт ./public/css/style.css.

Поле directory выбирает поддиректорию внутри файловой системы:

- name: docs
  kind: http.static
  meta:
    server: gateway
  path: /docs
  fs: app:content
  directory: documentation/html

SPA-режим

Single Page Applications требуют, чтобы все маршруты отдавали один index-файл для клиентской маршрутизации:

- name: spa
  kind: http.static
  meta:
    server: gateway
  path: /
  fs: app:frontend
  static_options:
    spa: true
    index: index.html

Запрос	Ответ
/app.js	Отдаёт app.js (файл существует)
/users/123	Отдаёт index.html (SPA fallback)
/api/data	Отдаёт index.html (SPA fallback)

При spa: true файл index обязателен. Существующие файлы отдаются напрямую; все остальные пути возвращают index-файл.

Управление кешем

Настройте кеширование для разных типов ассетов:

entries:
  - name: app_fs
    kind: fs.directory
    directory: ./dist

  # Версионированные ассеты — кешировать навсегда
  - name: assets
    kind: http.static
    meta:
      server: gateway
    path: /assets
    fs: app_fs
    directory: assets
    static_options:
      cache: "public, max-age=31536000, immutable"

  # HTML — короткий кеш, обязательная ревалидация
  - name: app
    kind: http.static
    meta:
      server: gateway
    path: /
    fs: app_fs
    static_options:
      spa: true
      index: index.html
      cache: "public, max-age=0, must-revalidate"

Типовые паттерны кеширования:

• Версионированные ассеты: public, max-age=31536000, immutable
• HTML/index: public, max-age=0, must-revalidate
• Пользовательские загрузки: private, max-age=3600

Middleware

Применение middleware для сжатия, CORS и другой обработки:

- name: static
  kind: http.static
  meta:
    server: gateway
  path: /
  fs: app:public
  middleware:
    - compress
    - cors
  options:
    compress.level: "best"
    cors.allow.origins: "*"

Middleware оборачивают обработчик статики по порядку — запросы проходят через каждый middleware до файлового сервера.

Сопоставление путей работает по префиксу. Обработчик на / перехватывает все несопоставленные запросы. Используйте роутеры для API-эндпоинтов, чтобы избежать конфликтов.

См. также

• Сервер — конфигурация HTTP-сервера
• Маршрутизация — роутеры и эндпоинты
• Файловая система — модуль файловой системы
• Middleware — доступные middleware