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

01Конфигурация и переменные окружения

# config/app.rb
Cybertrain.configure do |c|
  c.port = 3000
  c.workers = 1
end

Cybertrain::Config сначала читает переменные окружения; config/app.rb их переопределяет:

Используйте None (вместе с CYBERTRAIN_SESSION_PARTITIONED=1) только для приложения, которое показывается во фрейме другого сайта; браузер должен обращаться к приложению по HTTPS.

Другие атрибуты с фиксированными переопределяемыми значениями по умолчанию: views_root ("app/views"), public_root ("public"), layout ("layouts/application"), log_level (:info), session_cookie_name, session_max_age (2 недели), session_secure (true в production, что помечает cookie сессии как Secure; false в остальных окружениях, хотя SameSite=None и Partitioned всё равно добавляют Secure), pool_size (4), static_files/csrf (true), csrf_exempt_prefixes ([]: префиксы путей, например "/api/", чьи не-GET-запросы пропускают проверку CSRF, — для эндпоинта, который программы вызывают с собственными учётными данными; каждый должен начинаться и заканчиваться на / и не быть просто /, иначе запуск завершается сбоем; префикс сопоставляется с путём в том виде, в каком он отправлен, поэтому percent-кодированное написание всё равно проверяется; ни один другой маршрут не должен совпадать с путём под этим префиксом, а освобождённый контроллер не должен полагаться на сессию для аутентификации, поскольку сессия там всё равно загружается), max_body_bytes (10 МиБ: на более длинное тело запроса, в том виде, в каком оно отправлено, отвечается 413 до его чтения; увеличьте для больших загрузок; распакованный размер тела в gzip ограничивается отдельно через request.decoded_body(limit)), max_render_depth (12 одновременно открытых отрисовок: страница и её партиалы; увеличьте для партиалов, которым обоснованно нужна более глубокая рекурсия; значение должно быть не меньше 1, иначе запуск завершается сбоем). Примечание к обновлению: вложенность отрисовки, прежде неограниченная, теперь по умолчанию ограничена 12 (страница — глубина 1, поэтому партиалы могут вкладываться на 11 уровней; макет отрисовывается после страницы и во вложенность не входит), и приложение с более глубоким деревом (комментарии в виде веток, меню категорий) получает ошибку шаблона, пока не задаст max_render_depth. Загрузка файлов: max_upload_bytes (5 МиБ на загруженный файл; не должен превышать max_body_bytes), max_multipart_parts (128 частей, включая текстовые поля, не более 4096), upload_root ("storage/uploads", куда пишет Cybertrain::BlobStore; создаётся при первой загрузке, а не при запуске).

Заголовки безопасности: каждый ответ, который пишет сервер (действия, middleware статических файлов, страницы ошибок и страница диагностики режима разработки, собственные 400/411/413/500 сервера и HEAD), несёт X-Content-Type-Options: nosniff и X-Frame-Options: SAMEORIGIN, если только ответ уже не задаёт заголовок с таким именем (в любом регистре): Response#to_http добавляет их после собственных заголовков ответа и только при их отсутствии, поэтому response.set_header("X-Frame-Options", "DENY") в действии отправляет ровно ваше значение, один раз. Переключателя в Config, чтобы отключить их для всего приложения, намеренно нет; встраиваемый виджет переопределяет заголовок в собственных ответах (заголовок Content-Security-Policy: frame-ancestors ... в современных браузерах имеет приоритет над X-Frame-Options). Из-за nosniff браузеры понимают Content-Type буквально: middleware статических файлов знает обычные расширения public/ (html, css, js/mjs, изображения, включая webp и avif, шрифты, wasm, pdf, аудио и видео, json, csv, xml), а всё остальное отдаётся как application/octet-stream, то есть на скачивание; добавьте расширение в Cybertrain::Static::EXTENSIONS, если приложению нужно показывать в браузере другое. Обратный прокси, который сам отдаёт public/, обходит эти заголовки (см. docs/deploy.en.md). Cybertrain::Test::Client вызывает приложение внутри процесса и никогда не сериализует ответ, поэтому эти два значения по умолчанию в нём не видны; проверяйте их на response.to_http.

Фильтруемые параметры: строка Started GET "/login?..." в логе запросов и страница ошибок режима разработки (её строка запроса и дамп params и тела JSON) показывают значение каждого параметра, названного в config.filter_parameters, как [FILTERED], как это делает filter_parameters в Rails, поэтому ?token= в URL или пароль, отправленный в форму, которая не прошла проверку, не появляется в логе запросов фреймворка и на странице ошибок режима разработки. Заменяются только значения: остальная часть строки запроса пишется в лог как отправлена (управляющие символы экранируются). Список сопоставляется по подстроке без учёта регистра; расширьте его в config/app.rb (c.filter_parameters = c.filter_parameters + ["otp", "ssn"]) или замените через CYBERTRAIN_FILTER_PARAMETERS. Значения, которые действие пишет в лог само, не фильтруются; там спрашивайте Cybertrain::ParameterFilter.filter?(name) или ParameterFilter.filter_query(text).

Развёртывание: cybertrain build создаёт dist/: бинарный файл dist/NAME со встроенными представлениями, dist/public/ (статические ресурсы; или пусть их отдаёт обратный прокси), а также dist/storage/ (по умолчанию файл SQLite) и dist/tmp/. Запускайте его из dist/ с заданной CYBERTRAIN_SECRET_KEY_BASE; это production, если CYBERTRAIN_ENV не говорит иного, а ./NAME migrate применяет вкомпилированные в него миграции. Бинарный файл говорит только на обычном HTTP/1.1; для TLS и HTTP/2 поставьте перед ним nginx/Caddy (в production cookie сессии имеет флаг Secure, поэтому отдавайте приложение по HTTPS). В production исключение даёт ответ 500, а голый ответ с ошибкой (текстовый 404 маршрутизатора, head :not_found, render plain:) заменяется на public/<status>.html, если такой файл существует; ошибки, которые действие отрисовывает как HTML или JSON, проходят без изменений. SIGTERM прекращает приём соединений, даёт уже выполняющимся запросам завершиться (с ответом Connection: close; простаивающие keep-alive-соединения закрываются сразу) и выходит, когда они закончатся, или по истечении drain_timeout сервера (10 с). Цикл слежения и пересборки никогда не работает в production. docs/deploy.en.md (на японском: docs/deploy.md) проводит через весь процесс: cybertrain new, сервер Ubuntu, systemd, Caddy с HTTPS, повторные развёртывания, откаты и резервные копии.

Kamal: cybertrain new также записывает то, что нужно Kamal 2: Dockerfile, который выполняет cybertrain setup и cybertrain build на этапе сборки в Ubuntu и копирует dist/ в облегчённый этап того же выпуска (миграции при запуске, затем обслуживание на 0.0.0.0:3000), .dockerignore, config/deploy.yml (kamal-proxy с Let's Encrypt перед приложением, проверка работоспособности по public/up.html, файл SQLite на томе в /app/storage) и .kamal/secrets (KAMAL_REGISTRY_PASSWORD и CYBERTRAIN_SECRET_KEY_BASE из окружения). Заполните значения, помеченные CHANGE ME, сделайте коммит и выполните kamal setup; подробности — в docs/deploy-kamal.md (часть 8 учебника по развёртыванию). examples/blog содержит ту же конфигурацию, собранную с фреймворком из этой рабочей копии.

Настройки приложения

Собственные настройки приложения (публичный базовый URL, переключатель функции, интервал, SMTP-хост) объявляются в том же Config с типом, переменной окружения и значением по умолчанию:

# config/app.rb
Cybertrain.configure do |c|
  c.setting_string :base_url, env: "MYAPP_BASE_URL", default: ""
  c.setting_string :smtp_password, env: "MYAPP_SMTP_PASSWORD", default: "", secret: true
  c.setting_bool :worker, env: "MYAPP_WORKER", default: true
  c.setting_int :prune_interval, env: "MYAPP_PRUNE_INTERVAL", default: 3600, min: 1, max: 9_999_999
end

Cybertrain.config.string_setting(:base_url)
Cybertrain.config.bool_setting(:worker)
Cybertrain.config.int_setting(:prune_interval)

Каждое значение читается один раз, когда config/app.rb выполняется при запуске. Пустая или незаданная переменная означает значение по умолчанию. Булево значение принимает 1/true или 0/false; целое — десятичные цифры (с необязательным ведущим -) в пределах min..max (обе границы необязательны). Любое другое значение заменяется значением по умолчанию, и в лог пишется строка [WARN] об этом. Чтение необъявленного имени или имени, объявленного с другим типом, возбуждает ArgumentError, как и повторное объявление имени. Тесты меняют значение через set_string_setting, set_int_setting и set_bool_setting. ./NAME help перечисляет все объявленные настройки с их переменными и значениями по умолчанию, а стартовый баннер выводит текущие значения (=> Settings: base_url="" worker=true ...); настройка с secret: true в обоих местах показывается только по имени, как [FILTERED]. Аксессора Cybertrain.config.base_url нет: в Spinel нет define_method, поэтому читатели — это типизированные методы, принимающие имя.