CyberTrainРуководстваИсходящий HTTP, потоки WebSocket и электронная почта

Исходящий HTTP, потоки WebSocket и электронная почта

Исходящий HTTP

Приложение, которое обращается к другому серверу (вебхук, входящий вебхук Slack, сторонний API), использует Cybertrain::HttpClient. require "cybertrain" загружает его и слой TLS через отправитель Sentry; приложение на cybertrain/core подключает его там, где он используется, а также слой TLS, если какой-либо URL — https:

ruby
require "json"
require "cybertrain/http_client"
require "cybertrain/net/tls"   # только для https://; компонуется с системной libssl

client = Cybertrain::HttpClient.new(timeout: 5, deadline: 15, max_body: 1 << 20)
begin
  res = client.post(ENV["SLACK_WEBHOOK_URL"], JSON.generate({ "text" => "Deployed" }),
                    content_type: "application/json")
  Cybertrain.logger.warn("slack answered #{res.status}") unless res.success?
rescue Cybertrain::HttpClient::Error => e
  Cybertrain.logger.warn("slack: #{e.message}")   # называет host:port, но никогда путь
end

res = client.get("https://api.example.com/v1/status", headers: { "Authorization" => "Bearer #{token}" })
res.status              # 200
res.header("ETag")      # имена в любом регистре; в res.headers они в нижнем регистре
res.body                # байты, с удалённым chunked-кодированием

Зачем он нужен: Net::HTTP из Spinel выполняет рукопожатие TLS и каждое чтение после первого байта блокирующими вызовами C, и каждый из них удерживает рабочий поток ОС — а при SPINEL_WORKERS=1 по умолчанию это весь веб-сервер — столько, сколько захочет зависший эндпоинт. HttpClient никогда не блокирует рабочий поток на сети:

  • Каждое ожидание ограничено. Подключение (неблокирующий connect; TCPSocket.new из Spinel игнорирует connect_timeout:), каждый шаг рукопожатия TLS, каждое чтение и каждая запись ждут не более timeout секунд (по умолчанию 5), а весь запрос — не более deadline секунд (по умолчанию 15). При превышении любого из них — HttpClient::TimeoutError. Чтение идёт через байтовый буфер, наполняемый read_nonblock, поэтому уже полученные байты никогда не ожидаются.
  • Разрешение имён блокирует. У getaddrinfo в среде выполнения нет неблокирующей формы: поток, выполняющий запрос, ждёт DNS (обычно миллисекунды, но неработающий резолвер может занять системный тайм-аут, около 5 с на попытку). Крайний срок учитывает это время, но не может его прервать.
  • Непубличные адреса назначения отвергаются до того, как что-либо отправлено: loopback (127.0.0.0/8, ::1), частные (10/8, 172.16/12, 192.168/16, fc00::/7), link-local (169.254/16, куда входят облачные сервисы метаданных, fe80::/10), неопределённые (0.0.0.0/8, ::), multicast, broadcast, CGNAT (100.64/10), диапазоны для документации и бенчмарков, а также их формы IPv4-mapped, NAT64 и 6to4 (Cybertrain::Net::Address.blocked_reason). Имя хоста разрешается один раз, и проверяются и набираются именно те адреса, в которые оно разрешилось (повторно ничего не ищется), поэтому имя, разрешающееся в частный адрес (запись в /etc/hosts, DNS rebinding), отвергается так же, как литерал; сертификат TLS всё равно проверяется по имени. Проверка идёт по каждому адресу: отвергнутый адрес пропускается, и запрос завершается сбоем, только когда отвергнуты все адреса. HttpClient::BlockedAddressError сообщает причину. Чтобы обратиться к сервису в собственной сети или к локальному серверу в тесте, задайте c.http_allow_private = true в config/app.rb (или CYBERTRAIN_HTTP_ALLOW_PRIVATE=1) либо передайте allow_private: true в HttpClient.new; оставляйте это выключенным всякий раз, когда URL может прийти от пользователя.
  • Перебираются все разрешённые адреса в порядке, который даёт резолвер, IPv6 и IPv4 одинаково: когда один отказывает, недоступен, сбрасывает соединение или не отвечает в пределах timeout, набирается следующий, все — в пределах deadline, а когда не удаётся ни один, возбуждается ошибка последнего. Именно благодаря этому localhost работает на macOS, где он разрешается сначала в ::1, а сервер, слушающий на 127.0.0.1, такое соединение отвергает. Cybertrain::Mailer подключается так же.
  • TLS берётся из пакета openssl: VERIFY_PEER по хранилищу доверенных сертификатов операционной системы (SSL_CERT_FILE / SSL_CERT_DIR указывают на другое; у пакета нет X509::Store для собственного), проверка имени хоста, SNI, TLS 1.2 или новее. URL https нужно имя хоста: IP-адрес не совпадает с именем в сертификате. Без require "cybertrain/net/tls" запрос https возбуждает HttpClient::TLSError, который говорит об этом; один cybertrain/http_client никогда не компонуется с libssl.
  • Клиент для уведомлений и API, а не браузер: HTTP/1.1 с Connection: close, одно соединение на запрос, без keep-alive, редиректы только по просьбе (ниже), без прокси, без cookie. Ответы могут быть с Content-Length, chunked или читаться до закрытия; заголовки ограничены 64 КиБ и 100 строками, тело — max_body (по умолчанию 1 МиБ), сверх которого — HttpClient::TooLargeError. Ответ, который не является HTTP/1.x или обрывается раньше времени, — это HttpClient::BadResponseError; отвергнутое или сброшенное соединение либо имя, которое не разрешается, — HttpClient::RefusedError. Соединение, которое сбрасывается или закрывается во время рукопожатия TLS (сервер, не говорящий на TLS), — это HttpClient::TLSError («TLS handshake failed») на любой платформе, как и рукопожатие, которое отвергает OpenSSL. Все они — HttpClient::Error.
  • Ошибки никогда не содержат путь или строку запроса, в которых URL вебхука несёт свой секрет: сообщения называют только хост и порт. Некорректный URL или заголовок с CR/LF — это ArgumentError, который тоже его не повторяет. Host, Connection, Content-Length и Transfer-Encoding принадлежат клиенту; User-Agent по умолчанию — cybertrain/<version>.

Запрос выполняется в вызывающем потоке — зелёном потоке, как и обслуживаемый запрос, — поэтому, пока он ждёт, другие соединения продолжают обслуживаться. Слой сокетов (cybertrain/net/socket.rb: ограниченный connect, буферизованное чтение, ограниченная запись) отделён от слоя HTTP, чтобы им могли пользоваться другие протоколы. Проектное решение: docs/design.md D24 и D55.

Методы, JSON и редиректы

ruby
client = Cybertrain::HttpClient.new(timeout: 5, deadline: 15, redirects: 3)
res = client.request("PATCH", "https://api.example.com/v1/items/7",
                     body: JSON.generate({ "done" => true }), content_type: "application/json")
res = client.request("DELETE", "https://api.example.com/v1/items/7")
item = client.get("https://api.example.com/v1/items/7").json_hash   # {}, если тело не объект JSON
list = client.get("https://api.example.com/v1/items").json_array    # [], если это не массив JSON
  • request(verb, url, body:, content_type:, headers:) отправляет GET, POST, PUT, PATCH, DELETE или HEAD; get и post остаются привычными формами. POST, PUT и PATCH всегда несут своё тело, DELETE — только непустое, GET и HEAD — никакого (тело для них — ArgumentError); у ответа на HEAD нет тела. Response#json_hash и #json_array разбирают тело и для всего остального возвращают {} или [].
  • Редиректы выполняются только по просьбе: redirects: 3 следует не более чем трём 301, 302, 303, 307 или 308 с Location (относительный разрешается от текущего URL), а следующий возбуждает HttpClient::TooManyRedirectsError. По умолчанию, при 0, 3xx возвращается как есть. Каждый переход проверяется как первый (непубличные адреса отвергаются), переход с https на http — это BlockedAddressError, 303 (и 301 или 302 в ответ на POST) превращается в GET без тела, а deadline покрывает все переходы вместе. Заголовки Authorization, Cookie и Proxy-Authorization не отправляются на другой источник (схема, хост или порт), как поступают браузеры и curl. Location, который не является простым ASCII-URL http(s), — это BadResponseError.

Потоковые и большие ответы

С блоком тело не сохраняется: каждый кусок передаётся блоку по мере поступления (chunked-фрейм, до 1 МиБ за раз, или то, что принесло одно чтение), и Response возвращается с пустым телом. max_body тогда не действует; timeout и deadline действуют, так что давайте длинному потоку длинный deadline:. get_to_file пишет поток в файл:

ruby
client = Cybertrain::HttpClient.new(deadline: 600, redirects: 3)
client.get("https://example.com/export.ndjson") { |chunk| Importer.feed(chunk) }

res = client.get_to_file("https://example.com/dump.csv", "tmp/dump.csv")
Cybertrain.logger.info("#{res.bytes_written} bytes") if res.success?
  • Тело 2xx пишется в path.part по мере поступления и переименовывается в path, когда оно получено целиком, так что загрузка в 78 МБ никогда не лежит в памяти, а читатель никогда не видит половину файла. Любой другой итоговый статус (страница 404, 503) на диск не попадает: проверьте res.success?, path остаётся как был. При ошибке .part удаляется. Пустое тело 2xx (204) действительно заменяет файл пустым.
  • Исключение, возбуждённое блоком, доходит до вызывающего без изменений.

gzip

Клиент запрашивает и распаковывает тела gzip, когда загружена поддержка gzip: require "cybertrain" её загружает, так что в приложении каждый запрос отправляет Accept-Encoding: gzip (если только вы не отправляете свой заголовок Accept-Encoding), а тело с Content-Encoding: gzip приходит распакованным. Программа, которая подключает только cybertrain/http_client, добавляет require "cybertrain/http/gzip_ffi" (он линкует zlib); без него ответ gzip — это BadResponseError, называющий этот файл. Сохраняемое тело ограничено max_body и на проводе, и после распаковки (сверх него — TooLargeError); потоковое распаковывается кусками, не больше 64 КиБ каждый, без общего ограничения, как и несжатое потоковое тело. Заголовки Response — полученные: Content-Encoding: gzip и Content-Length с провода остаются, а body — распакованный текст. Любой другой Content-Encoding (br, deflate) — это BadResponseError; обрезанное или испорченное тело gzip — тоже.

Server-Sent Events

Cybertrain::Sse::Parser превращает куски потокового ответа text/event-stream в события (он не входит в require "cybertrain"):

ruby
require "cybertrain/sse"

parser = Cybertrain::Sse::Parser.new
client = Cybertrain::HttpClient.new(deadline: 180)   # весь поток должен уложиться в deadline
client.request("POST", "https://api.example.com/v1/chat", body: payload, content_type: "application/json") do |chunk|
  parser.feed(chunk) { |event| Answer.append(event.event_data) unless event.event_data == "[DONE]" }
end
parser.finish { |event| Answer.append(event.event_data) }   # последнее событие, которое поток не завершил пустой строкой
  • У каждого Sse::Event есть event_name ("message", если поток его не прислал), event_data (строки data:, соединённые переводом строки), event_id (последний id:, присланный потоком; он переходит и на следующие события) и event_retry_ms (retry:, заданный после предыдущего события, иначе 0).
  • Парсер следует правилам WHATWG: строки заканчиваются на CR, LF или CRLF и могут быть разрезаны где угодно между двумя кусками; строка, начинающаяся с :, — комментарий; пустая строка отправляет событие, если у него были данные. finish передаёт событие, оставшееся незавершённым в конце потока.
  • Он не ограничивает ни строку, ни событие: deadline запроса ограничивает поток по времени, а не по памяти. Двоичные куски дают двоичный event_data; кодировку задавайте сами.

Потребление потоков WebSocket

Приложение, которое слушает внешний поток (биржевые тики, телеметрию устройств, поток событий), пока работает сервер, подписывается на него через Cybertrain::WebSocket.subscribe. Как и HTTP-клиент, он не входит в require "cybertrain"; подключайте его там, где пишется подписка, а для wss:// — также слой TLS. Он загружает подсистему фидов (роль feeds, проверку здоровья фидов), так что приложению на cybertrain/core другая строка не нужна:

ruby
# config/app.rb (или файл, который bin/<app>.rb подключает до Cybertrain::Main.run)
require "json"
require "cybertrain/websocket"
require "cybertrain/net/tls"   # только для wss://; компонуется с системной libssl

Cybertrain::WebSocket.subscribe("trades", ENV["FEED_URL"],
    headers: { "Authorization" => "Bearer #{ENV["FEED_TOKEN"]}" },
    stale_after: 30)
  .on_open    { |conn| conn.send_text(JSON.generate({ "op" => "subscribe", "channel" => "trades" })) }
  .on_message { |conn, text| Cybertrain::DB.with { |c| c.execute("INSERT INTO trades(raw) VALUES (?)", [text]) } }

Подключение cybertrain/websocket регистрирует потоки в Cybertrain::Background, который Application#serve запускает после планировщика и останавливает при завершении работы, так что вызывать ничего не нужно. Каждая подписка получает один поток выполнения. Он подключается, выполняет on_open (отправляйте там своё сообщение о подписке: оно выполняется снова после каждого переподключения), а затем передаёт каждое сообщение в on_message вместе с Connection (send_text, send_binary, close и last_opcode — :text или :binary). Блоки получают свои аргументы и не могут использовать self (в Spinel нет instance_eval).

  • Когда это выполняется. Потоки запускаются, когда бинарный файл обслуживает запросы, как и планировщик (Фоновая работа); команды migrate, db ..., Main.command и Cybertrain::Test::Client никогда их не запускают. ./<app> feeds [NAME...] запускает их в отдельном процессе, все или названные (Роли процессов). С CYBERTRAIN_WORKER=0 (config.worker = false) они не работают в этом процессе (они просто не запускаются; единственное уведомление — строка планировщика «run elsewhere», а WebSocket.start!, вызванный напрямую, пишет в лог свою): когда запросы обслуживают несколько процессов, отключите это во всех, кроме одного, иначе каждый получит весь поток. subscribe нужно вызвать до запуска сервера; добавлять или удалять поток во время работы нельзя. Имя уникально (ArgumentError), а поток без on_message срывает запуск до того, как занят порт (error: WebSocket subscription "trades" has no on_message, код выхода 1).
  • Параметры. headers: (дополнительные заголовки рукопожатия), timeout: (5 секунд на каждое ожидание при подключении и на каждую запись), max_message: (1 МиБ; более крупное сообщение закрывает соединение с кодом 1009), ping_interval: (15) и stale_after: (45), а также allow_private: (как у HttpClient, ниже).
  • Ожидание и переподключение. После любого сбоя поток ждёт min(60, 2 ** (attempt - 1)) секунд с разбросом 20 % в обе стороны: 1, 2, 4, ... 60. Соединение, продержавшееся 60 секунд, начинает снова с 1. Каждое ожидание ограничено. WebSocket.stop! возвращается примерно через 2 секунды, что бы ни делали серверы: он ждёт не более 2 секунд все потоки вместе, подключённый поток отправляет close (1000) и ждёт ответа сервера не более 1 секунды, и после возврата connected? каждого потока ложно (поток, который всё ещё закрывается, завершается сам).
  • Тишина. Поток может замолчать, так и не закрыв соединение, поэтому поток выполнения отправляет пинг после ping_interval секунд без единого фрейма (и затем раз в интервал), а когда за stale_after секунд не пришло ни одного фрейма, включая pong, закрывает соединение и переподключается. stale_after должен быть больше ping_interval, который должен быть не меньше 1 (ArgumentError от subscribe).
  • Ошибки в ваших блоках. Исключение в on_message пишется в лог, и соединение остаётся. Исключение в on_open пишется в лог, соединение закрывается и повторяется, поскольку от потока, который не подписался, нет пользы.
  • Таймеры. .on_tick(seconds) { |conn| ... } выполняет блок каждые seconds (Integer, не меньше 1) в собственном потоке фида, между его ожиданиями по одной секунде, независимо от того, подключён ли фид: conn — это Connection, пока он подключён, и nil, пока нет, так что проверяйте его. Первый вызов происходит через seconds после запуска фида; исключение пишется в лог, и фид продолжает работу. Работа, которая принадлежит фиду (раз в секунду записать то, что on_message накопил в памяти, закрыть минутную свечу), делается здесь, без блокировки и без задачи по расписанию. Один on_tick на подписку.

    ruby
    BUFFER = Array.new(0) { "" }   # константа: блоки не видят локальных переменных
    
    Cybertrain::WebSocket.subscribe("trades", ENV["FEED_URL"])
      .on_message { |conn, text| BUFFER << text }
      .on_tick(1) { |conn| Trades.flush(BUFFER) }   # код приложения: один INSERT пачки, затем BUFFER.clear
  • Перезапуски. Поток-супервизор каждую секунду проверяет, жив ли поток каждого фида. Поток, который всё-таки завершился (исключение, не являющееся StandardError, или поток, убитый средой выполнения), пишется в лог (ERROR [feed:trades] WebSocket "trades" thread ended: ...) и запускается снова через min(30, 2 ** restarts) секунд со строкой WARN; его открытое соединение сначала закрывается. Счётчик перезапусков никогда не сбрасывается, так что после пяти перезапусков ожидание остаётся 30 секунд. В процессе feeds фид, который снова умирает после feed_restart_limit перезапусков (10, CYBERTRAIN_FEED_RESTART_LIMIT) за feed_restart_window секунд (600, CYBERTRAIN_FEED_RESTART_WINDOW), завершает процесс: FATAL feed trades restarted 10 times in 600 s; exiting, затем все фиды останавливаются, и процесс завершается со статусом 1, чтобы restart: unless-stopped в Docker или Restart=always в systemd запустили новый. server, который выполняет фиды, никогда не завершается из-за них: он продолжает их перезапускать, а /up сообщает feed stale. Ошибка в самом супервизоре (база данных пропала, пока он писал строки состояния) пишется в лог, и надзор продолжается.
  • Что пишется в лог.

    Когда Уровень Строка
    запуск INFO WebSocket started: trades (wss://feed.example.com:443)
    подключение INFO WebSocket "trades" connected to feed.example.com:443
    отключение WARN WebSocket "trades" disconnected: Cybertrain::WebSocket::ClosedError: feed.example.com:443: closed by the server (1001) (retry in 2s)
    тишина WARN WebSocket "trades" silent for 45s; reconnecting
    блок возбудил исключение ERROR WebSocket "trades" on_message failed: KeyError: ... (или on_open)

    Путь и строка запроса никогда не пишутся в лог и не попадают в сообщения об ошибках: в них часто содержится токен. Все строки, кроме первой, пишутся в потоке фида и несут тег [feed:trades]; блок, который бросил исключение, завершение потока и отказ процесса feeds также попадают в отчёты об ошибках.

  • Ошибки. Все они — Cybertrain::WebSocket::Error, и в сообщении только хост и порт. После рукопожатия потерянное соединение или закрытие сервером — это ClosedError (close_code, close_reason; сброс или конец без close-фрейма — 1006); запись, которая превышает тайм-аут или не удаётся в TLS, — по-прежнему TimeoutError или TLSError. Во время подключения это RefusedError, TimeoutError, TLSError, BlockedAddressError (непубличный адрес, по умолчанию отвергаемый ровно так же, как в Исходящий HTTP, с тем же allow_private: и настройкой http_allow_private) или HandshakeError (не 101, неверный Sec-WebSocket-Accept или сервер, ответивший с расширением или подпротоколом). ProtocolError (сервер нарушил формат фреймов; клиент отправляет 1002) и TooLargeError могут возникнуть в любой момент.
  • Состояние. Cybertrain::WebSocket.feed_status("trades") возвращает Status: connected?, last_message_at (секунды эпохи, 0 до первого сообщения), reconnects, restarts (сделанные супервизором) и thread_alive?, прочитанные одно за другим, а не как единый снимок; connected? становится истинным, когда соединение установлено, до того как выполнился on_open. Супервизор также пишет состояние каждого фида в базу данных каждые feed_status_interval секунд (10), и его читают GET /up и ./<app> feeds status в этом или любом другом процессе: Состояние фидов.
  • Делайте on_message коротким. Поток выполнения ждёт через wait_readable или sleep, поэтому зависший поток данных не удерживает рабочий поток ОС, пока ждёт. Удерживают его две вещи: каждая попытка подключения разрешает имя хоста блокирующим getaddrinfo (см. «Разрешение имён блокирует» в Исходящий HTTP; при SPINEL_WORKERS=1 неработающий резолвер задерживает каждый запрос на тайм-аут резолвера, по разу на попытку на поток, а IP-адрес в URL позволяет обойтись без поиска) и вызов SQLite внутри on_message до своего возврата, как в задаче по расписанию (Фоновая работа): при SPINEL_WORKERS=1 долгая запись задерживает каждый запрос. Для нагруженного потока вставляйте одну небольшую строку или собирайте сообщения в памяти и записывайте их пакетами из задачи Scheduler.every.
  • Не реализовано. Расширения (permessage-deflate) и подпротоколы не согласовываются. Нет поддержки прокси, редиректов и cookie, нет автоматического сохранения сообщений (у браузеров есть своя точка входа: Реальное время). Текстовые фреймы не проверяются на допустимый UTF-8 (отступление от RFC 6455, раздел 8.1): байты передаются дальше в том виде, в каком пришли. Connection действителен только во время колбэка; отправка из запроса или задачи не поддерживается.

Для одного соединения без цикла переподключения (скрипт, однократное чтение) используйте синхронный клиент:

ruby
require "cybertrain/websocket"
require "cybertrain/net/tls"   # только для wss://

client = Cybertrain::WebSocket::Client.connect("wss://feed.example.com/v1", timeout: 5)
client.send_text("hello")
msg = client.receive(10)      # ждёт не более 10 с; nil, если ничего не пришло
msg.ws_opcode                 # :text или :binary
msg.ws_data                   # байты
client.close

Проектное решение: docs/design.md D33 и D56.

Отправка электронной почты

Cybertrain::Mailer отправляет электронные письма, простым текстом или с HTML-частью, через SMTP-сервер (сервер отправки вашего провайдера или локальный ретранслятор) — сразу (deliver) или из задачи (deliver_later, ниже). require "cybertrain" его загружает; приложение на cybertrain/core или программа без фреймворка подключает cybertrain/mailer (которому не нужна база данных: deliver_later находится в cybertrain/mailer/later, который загружает и задачи). TLS подключается отдельным require:

ruby
require "cybertrain/mailer"
require "cybertrain/net/tls"   # для starttls (по умолчанию) и tls; компонуется с системной libssl

# Настройки из CYBERTRAIN_SMTP_HOST, _PORT, _USER, _PASSWORD, _FROM, _TLS:
begin
  Cybertrain::Mailer.deliver(to: user.email, subject: "Welcome", body: "Hello #{user.name},\n...")
rescue Cybertrain::Mailer::Error => e
  Cybertrain.logger.warn("mail: #{e.message}")   # никогда не содержит пароль
end

# Или явные настройки, в обход Config:
mailer = Cybertrain::Mailer.new(host: "smtp.example.com", port: 587, tls: "starttls",
                                user: "app", password: ENV["SMTP_PASSWORD"].to_s,
                                from: "noreply@example.com", timeout: 10, deadline: 60)
mailer.deliver(to: "a@example.com, b@example.com", subject: "Report", body: report)
Переменная Атрибут По умолчанию
CYBERTRAIN_SMTP_HOST smtp_host "" (Mailer.new возбуждает ArgumentError, пока она не задана)
CYBERTRAIN_SMTP_PORT smtp_port 0: 587 для starttls, 465 для tls, 25 для none
CYBERTRAIN_SMTP_USER smtp_user "": без AUTH
CYBERTRAIN_SMTP_PASSWORD smtp_password "" (секрет)
CYBERTRAIN_SMTP_FROM smtp_from ""
CYBERTRAIN_SMTP_TLS smtp_tls "starttls"; tls или none
  • Режимы TLS. starttls подключается открытым текстом, требует, чтобы сервер предлагал STARTTLS (иначе Mailer::TLSError), и переходит на TLS прежде, чем сказано что-либо ещё; байты, которые сервер отправляет после своего ответа на STARTTLS, отвергаются. tls говорит на TLS с первого байта (порт 465). Оба проверяют сертификат по host, как HTTP-клиент (указывайте имя хоста, а не IP-адрес), и обоим нужен require "cybertrain/net/tls" (его загружает require "cybertrain"): без него deliver ещё до подключения возбуждает Mailer::TLSError, который говорит об этом. none — открытый текст, для ретранслятора на той же машине или тестового сервера: при настроенном пользователе он отказывается (Mailer::InsecureError, до подключения), если только хост не разрешается в адрес loopback, и тогда набирает только его адреса loopback.
  • Пароль никогда не пишется в лог и не показывается. Его нет в стартовом баннере, в help, в логе и в сообщениях об ошибках; он отправляется только внутри команды AUTH PLAIN, поверх TLS (или на loopback). Не делайте p или inspect для Mailer или Config, которые его хранят.
  • Каждое ожидание ограничено, как в Исходящий HTTP: подключение, каждый шаг TLS и каждый ответ ждут не более timeout секунд (по умолчанию 10), вся доставка — не более deadline секунд (по умолчанию 60), иначе Mailer::TimeoutError. Разрешение имён блокирует вызывающий поток.
  • Диалог: приветствие 220, EHLO (имя — helo:, по умолчанию localhost), STARTTLS и снова EHLO, AUTH PLAIN, когда задан пользователь (сервер должен предлагать PLAIN), MAIL FROM, по одному RCPT TO на получателя, DATA, QUIT. Ответ с другим кодом — это Mailer::RejectedError, чей smtp_code — код сервера (421, 535, 550, ...), а сообщение содержит шаг и текст сервера. Возвращаемое значение — ответ сервера на сообщение ("250 2.0.0 Ok: queued as ...").
  • Сообщение: Date, From, To, Subject, MIME-Version: 1.0, Content-Type: text/plain; charset=UTF-8 (про HTML-письмо — ниже). Тема не в ASCII кодируется по RFC 2047 (=?UTF-8?B?...?=, с разбиением между символами). Концы строк тела становятся CRLF, а строки, начинающиеся с ., дополняются точкой (dot-stuffing). Его Content-Transfer-Encoding — 7bit для ASCII, 8bit (с MAIL FROM ... BODY=8BITMIME) для UTF-8, когда сервер объявляет 8BITMIME, и base64 в остальных случаях или когда строка длиннее 998 байт. Message-ID не добавляется (серверы отправки добавляют его сами).
  • Что отвергается с ArgumentError до подключения: адрес, который не является голым ASCII local@domain (без отображаемого имени, без <>, пробелов, запятых, кавычек, CR и LF; не более 254 байт), тема с CR, LF или NUL (внедрение заголовков) или длиннее 998 байт, тело, которое не является допустимым UTF-8 или содержит NUL, больше 100 получателей. to: принимает один адрес или несколько, разделённых запятыми.
  • Мейлеры: модуль в app/mailers (gen их загружает), метод которого возвращает Cybertrain::MailMessage.new(to:, subject:, body:, html:, from:), читается как в Rails: PasswordsMailer.reset(user, url).deliver_later ставит письмо в очередь, deliver_now отправляет сразу. cybertrain/mailer загружает MailMessage с deliver_now; deliver_later приходит с cybertrain/mailer/later. cybertrain generate authentication пишет два таких (Сброс пароля) и добавляет обе строки.
  • Пока нет: вложений и встроенных изображений, классов мейлеров с default from: и представлениями, найденными по имени, отображаемых имён, заголовков Cc/Bcc (вместо этого отправляйте нескольким получателям), AUTH LOGIN/CRAM-MD5, адресов SMTPUTF8, конвейеризации. deliver выполняется в вызывающем потоке — зелёном потоке, как запрос.

HTML-письма

ruby
html = Cybertrain::Views.render_mail("mail/welcome", user: user)   # app/views/mail/_welcome.html.erb
Cybertrain::Mailer.deliver(to: user.email, subject: "Welcome", body: "Welcome, #{user.name}!\n", html: html)
  • С html: сообщение имеет тип multipart/alternative: сначала текстовая часть (body:), затем HTML-часть, каждая в charset=UTF-8 и base64 (так что никакие правила длины строки и dot-stuffing не действуют), между случайными разделителями. Почтовые программы показывают HTML и откатываются к тексту. Без html: сообщение — это простой текст, описанный выше, без изменений.
  • Views.render_mail(name, locals) отрисовывает частичный шаблон (app/views/mail/_welcome.html.erb) вне запроса — внутри app/views/layouts/mail.html.erb, если такой макет есть, и сам по себе иначе; Views.render_partial отрисовывает его без макета. Значения экранируются для HTML, как на странице. Текстовая часть тоже может прийти из частичного шаблона: отрисуйте его сами и передайте как body: (он выводит свои значения через <%== %>, поскольку <%= %> экранирует).

Отправка позже

ruby
Cybertrain::Mailer.deliver_later(to: user.email, subject: "Welcome", body: text, html: html)

deliver_later требует require "cybertrain/mailer/later" (или require "cybertrain") в bin/<app>.rb и bin/db.rb. Он принимает аргументы deliver, сразу их проверяет (отвергнутый адрес или тема возбуждает исключение здесь, и в очередь ничего не попадает) и ставит в очередь встроенную задачу "cybertrain mail" с готовым сообщением; поток задач (Фоновая работа) отправляет его с настройками SMTP, действующими в тот момент. Отрисуйте тела до вызова: у задачи нет контекста представления. Возвращается id задачи.

  • Повторы. Тайм-аут, отказ в соединении или ответ 4xx (грейлистинг, 421, 452) повторяется через 60 секунд, до 5 попыток, после чего строка становится failed. Ответ 5xx (несуществующий адрес, отвергнутый вход) сразу отбрасывает строку: повтор не изменил бы ответа.
  • Ошибки тоже отбрасываются. ArgumentError при выполнении задачи отбрасывается, и ничего не отправляется: это касается и ошибки конфигурации (нет CYBERTRAIN_SMTP_HOST, нет отправителя), и полезной нагрузки, изменённой в базе. Такое письмо потеряно, пока кто-нибудь не заглянет на страницу задач или в ./<app> jobs list discarded; исправьте конфигурацию, затем ./<app> jobs retry ID снова ставит его в очередь (то же касается отброшенной неудачи входа 535).
  • Одно сообщение — все получатели. Сообщение нескольким получателям — это одна транзакция SMTP: когда сервер отвергает одного из них с 5xx, вся задача отбрасывается, и остальные тоже его не получают. Ставьте в очередь по сообщению на получателя, когда они не должны зависеть друг от друга.
  • Сообщение лежит в базе данных (полезная нагрузка строки задачи, показанная на странице задач), пока задача не выполнится, и столько, сколько хранится завершённая строка.
  • Регистрация этой задачи означает, что каждый процесс, выполняющий задачи, запускает свои потоки задач, даже в приложении без собственного класса задачи.

Проектное решение: docs/design.md D27 и D57.