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

Раздача статических файлов из любой файловой системы через 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-эндпоинтов, чтобы избежать конфликтов.

См. также