外向きの HTTP
別のサーバー(Webhook、Slack の Incoming Webhook、サードパーティの API)を呼び出すアプリケーションは Cybertrain::HttpClient を使います。require "cybertrain" は、Sentry の送信側を通じて、これと TLS の層を読み込みます。cybertrain/core のアプリケーションは、使う場所で require し、https の URL があれば TLS の層も require してください:
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 # バイト列。チャンク形式は取り除かれている
これがある理由:Spinel の Net::HTTP は、TLS ハンドシェイクと最初のバイト以降のすべての読み取りを、ブロッキングする C の呼び出しとして行います。そのそれぞれが、止まったエンドポイントが望むだけ長く OS のワーカーを占有し、デフォルトの SPINEL_WORKERS=1 ではそれが Web サーバー全体です。HttpClient がネットワークでワーカーをブロックすることは決してありません:
- すべての待ちに上限がある。 接続(ノンブロッキングの connect。Spinel の
TCPSocket.newはconnect_timeout:を無視します)、TLS ハンドシェイクの各手順、各読み取り、各書き込みは最大timeout秒(デフォルトは 5)待ち、リクエスト全体では最大deadline秒(デフォルトは 15)待ちます。どちらかを過ぎるとHttpClient::TimeoutErrorです。読み取りはread_nonblockで満たされるバイトバッファーを通るので、すでに受け取ったバイトを待つことはありません。 - 名前解決はブロックする。 ランタイムには
getaddrinfoのノンブロッキング版がありません:リクエストを行うスレッドは DNS を待ちます(通常は数ミリ秒ですが、リゾルバーが死んでいるとシステムのタイムアウト、1 回の試行につき約 5 秒かかることがあります)。デッドラインはその時間も数えますが、中断はできません。 - 公開されていない宛先は拒否される。 何かを送る前に:ループバック(
127.0.0.0/8、::1)、プライベート(10/8、172.16/12、192.168/16、fc00::/7)、リンクローカル(クラウドのメタデータサービスを含む169.254/16、fe80::/10)、未指定(0.0.0.0/8、::)、マルチキャスト、ブロードキャスト、CGNAT(100.64/10)、ドキュメント用とベンチマーク用の範囲、そしてそれらの IPv4 射影、NAT64、6to4 の形式です(Cybertrain::Net::Address.blocked_reason)。ホスト名は一度だけ解決され、解決されたアドレスがそのまま検査され、接続先になります(再び問い合わせることはありません)。そのため、プライベートなアドレスに解決される名前(/etc/hostsのエントリー、DNS リバインディング)も、リテラルと同じように拒否されます。TLS 証明書は引き続き名前に対して検証されます。検査はアドレスごとです:拒否されたアドレスはスキップされ、すべてのアドレスが拒否されたときにだけリクエストが失敗します。HttpClient::BlockedAddressErrorがその理由を伝えます。自分のネットワーク上のサービスや、テストでローカルのサーバーを呼び出すには、config/app.rbでc.http_allow_private = trueを設定する(またはCYBERTRAIN_HTTP_ALLOW_PRIVATE=1)か、HttpClient.newにallow_private: trueを渡します。URL がユーザーから来る可能性があるときは、常に無効のままにしてください。 - 解決されたすべてのアドレスを試す。 リゾルバーが返した順に、IPv6 も IPv4 も同じように試します:あるアドレスが拒否する、到達できない、リセットする、
timeout以内に応答しない場合は次のアドレスに接続し、そのすべてをdeadline以内に行います。すべてが失敗すると、最後のアドレスのエラーを出します。これによって macOS のlocalhostが動きます。macOS ではlocalhostはまず::1に解決され、127.0.0.1で待ち受けているサーバーはそれを拒否するからです。Cybertrain::Mailerも同じ方法で接続します。 - TLS は openssl パッケージのものです:オペレーティングシステムの信頼ストアに対する
VERIFY_PEER(SSL_CERT_FILE/SSL_CERT_DIRで別の場所を指せます。パッケージにはカスタムのストアのためのX509::Storeがありません)、ホスト名の検査、SNI、TLS 1.2 以降。https の URL にはホスト名が必要です:IP アドレスは証明書の名前に一致しません。require "cybertrain/net/tls"がないと、https のリクエストはその旨を伝えるHttpClient::TLSErrorを出します。cybertrain/http_clientだけでは libssl をリンクすることはありません。 - ブラウザーではなく、通知と API のためのクライアント:
Connection: close付きの HTTP/1.1 で、リクエストごとに接続は 1 つ、keep-alive なし、リダイレクトは求められたときだけ(下記)、プロキシなし、cookie なしです。レスポンスはContent-Length、チャンク形式、または接続が閉じるまでの読み取りのいずれでもかまいません。ヘッダーは 64 KiB かつ 100 行、ボディはmax_body(デフォルトは 1 MiB)が上限で、それを超えるとHttpClient::TooLargeErrorです。HTTP/1.x でない、または途中で終わるレスポンスはHttpClient::BadResponseError、拒否された・リセットされた接続や、解決できない名前はHttpClient::RefusedErrorです。TLS ハンドシェイク中にリセットされた・閉じられた接続(TLS を話さないサーバー)は、OpenSSL が拒否したハンドシェイクと同じく、どのプラットフォームでもHttpClient::TLSError(「TLS handshake failed」)です。これらはすべてHttpClient::Errorです。 - エラーにパスやクエリが含まれることはない。 Webhook の 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、リダイレクト
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はLocation付きの301、302、303、307、308を 3 回までたどり(相対のLocationは今の URL を基準に解決します)、その次はHttpClient::TooManyRedirectsErrorを出します。デフォルトの0では、3xx をそのまま返します。どのホップも最初と同じく確かめられ(公開されていないアドレスは拒否)、https から http へのホップはBlockedAddressErrorになり、303(と POST への301・302)は本文のない GET に変わり、deadlineはすべてのホップをまとめて数えます。ブラウザや curl と同じく、Authorization、Cookie、Proxy-Authorizationヘッダーは別のオリジン(スキーム、ホスト、ポート)には送りません。プレーンな ASCII の http(s) URL でないLocationはBadResponseErrorです。
ストリーミングと大きなレスポンス
ブロックを渡すと本文は保持されません。各部分は届いたときにブロックに渡され(チャンクのフレーム 1 つ、一度に最大 1 MiB、または 1 回の読み取りで届いたもの)、Response は空の本文で返ります。このとき max_body は効きませんが、timeout と deadline は効くので、長いストリームには長い deadline: を与えてください。get_to_file はファイルにストリーミングします:
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 MB のダウンロードがメモリに載ることはなく、読む側が半分のファイルを見ることもありません。それ以外の最終ステータス(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 するプログラムは require "cybertrain/http/gzip_ffi" を足します(zlib をリンクします)。それがなければ、gzip のレスポンスはそのファイルを挙げる BadResponseError になります。保持する本文は、通信路の上でも展開後も max_body で制限されます(超えれば TooLargeError)。ストリーミングの本文は 1 回に最大 64 KiB ずつ展開され、圧縮していないストリーミングの本文と同じく全体の上限はありません。Response のヘッダーは受け取ったままです。body は展開したテキストでも、Content-Encoding: gzip と通信路の Content-Length は残ります。ほかの Content-Encoding(br、deflate)は BadResponseError で、途中で切れた gzip や壊れた gzip の本文もそうです。
Server-Sent Events
Cybertrain::Sse::Parser は、ストリーミングされる text/event-stream のレスポンスの各部分をイベントに変えます(require "cybertrain" には含まれません):
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 で終わり、2 つの部分の間のどこで切れていても構いません。
:で始まる行はコメントです。空行は、データがあればイベントを送り出します。finishは、ストリームの終わりで閉じられずに残ったイベントを渡します。 - 行やイベントの大きさに上限はありません。リクエストの
deadlineはストリームを時間で区切りますが、メモリでは区切りません。バイナリの部分からはバイナリのevent_dataができます。エンコーディングは自分で設定してください。
WebSocket フィードを購読する
サーバーの動作中に外部のフィード(市場のティック、デバイスのテレメトリー、イベントストリーム)を受信するアプリケーションは、Cybertrain::WebSocket.subscribe でそれを購読します。HTTP クライアントと同じく require "cybertrain" には含まれていません。購読を書く場所で require し、wss:// には TLS の層も require してください。これはフィードのサブシステム(feeds ロール、フィードのヘルスチェック)を読み込むので、cybertrain/core のアプリケーションにほかの行は要りません:
# config/app.rb(または bin/<app>.rb が Cybertrain::Main.run の前に require するファイル)
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 を require すると、フィードが Cybertrain::Background に登録されます。Application#serve がスケジューラーの後にこれを開始し、シャットダウン時に停止するので、呼び出すものは何もありません。購読ごとに 1 本のスレッドが付きます。スレッドは接続し、on_open を実行し(購読のメッセージはここで送ってください:再接続のたびに再び実行されます)、その後、各メッセージを Connection(send_text、send_binary、close、そして :text か :binary の last_opcode)とともに on_message に渡します。ブロックは引数を受け取り、self は使えません(Spinel には instance_eval がありません)。
- いつ実行されるか。 フィードは、スケジューラーと同じく、バイナリが配信を行うときに始まります(バックグラウンド処理)。
migrate、db ...、Main.commandのコマンドとCybertrain::Test::Clientでは決して始まりません。./<app> feeds [NAME...]は、それらのすべて、または名前を挙げたものを専用のプロセスで動かします(プロセスの役割)。CYBERTRAIN_WORKER=0(config.worker = false)では、そのプロセスでは動きません(単に始まらないだけです。唯一の知らせはスケジューラーの「run elsewhere」の行で、WebSocket.start!を直接呼んだ場合は自分でログを出します):複数のプロセスが配信する場合は、1 つを除いてすべてで無効にしてください。そうしないと、それぞれがフィード全体を受信します。subscribeはサーバーが始まる前に呼ぶ必要があります。動作中にフィードを追加したり削除したりすることはできません。名前は一意で(ArgumentError)、on_messageのないフィードは、ポートをバインドする前に起動を失敗させます(error: WebSocket subscription "trades" has no on_message、終了コード 1)。 - オプション。
headers:(ハンドシェイクに追加するヘッダー)、timeout:(接続中の各待ちと各書き込みに 5 秒)、max_message:(1 MiB。それより大きいメッセージは 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 秒待ち、接続中のフィードはクローズ(1000)を送ってサーバーの応答を最大 1 秒待ち、戻った時点ですべてのフィードのconnected?は false です(まだ閉じている途中のスレッドは自分で終わります)。 - 無音。 フィードは接続を閉じないまま静かになることがあるので、スレッドはフレームが何もないまま
ping_interval秒たつと ping を送り(その後は間隔ごとに 1 回)、pong も含めてフレームがstale_after秒まったく届かなければ、接続を閉じて再接続します。stale_afterはping_intervalより大きくなければならず、ping_intervalは 1 以上でなければなりません(subscribeからのArgumentError)。 - ブロック内のエラー。
on_messageでの例外はログに記録され、接続はそのままです。on_openでの例外はログに記録され、接続は閉じられて再試行されます。購読していないフィードは役に立たないためです。 -
タイマー。
.on_tick(seconds) { |conn| ... }は、フィードが接続していてもいなくても、フィード自身のスレッドで 1 秒ごとの待ちの合間に、seconds(Integer、1 以上)ごとにブロックを実行します。connは接続中はConnection、そうでなければnilなので、確かめてください。最初の呼び出しはフィードの開始からseconds後です。例外はログに出て、フィードは続きます。フィードに属する作業(on_messageがメモリにためたものを 1 秒ごとに書く、1 分足を閉じる)はここに書きます。ロックもスケジューラーのタスクも要りません。on_tickは購読ごとに 1 つです。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) } # アプリのコード:まとめて 1 回 INSERT し、BUFFER.clear - 再起動。 監視スレッドが、各フィードのスレッドが生きているかを毎秒確かめます。それでも終わってしまったスレッド(
StandardErrorでない例外、またはランタイムが殺したもの)はログに出され(ERROR [feed:trades] WebSocket "trades" thread ended: ...)、min(30, 2 ** restarts)秒後にWARNの行とともに再起動されます。開いていた接続は先に閉じられます。再起動の回数は決してリセットされないので、5 回再起動した後は待ちが 30 秒のままです。feedsのプロセスでは、feed_restart_window秒(600、CYBERTRAIN_FEED_RESTART_WINDOW)のうちにfeed_restart_limit回(10、CYBERTRAIN_FEED_RESTART_LIMIT)再起動した後でまた死んだフィードは、プロセスを終わらせます。FATAL feed trades restarted 10 times in 600 s; exitingを出し、すべてのフィードを止めてから、終了ステータス 1 で終わります。Docker のrestart: unless-stoppedや systemd のRestart=alwaysが新しいプロセスを起動するためです。フィードを動かす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。リセットやクローズフレームなしの終了は 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?。これらは 1 つのスナップショットとしてではなく順に読まれ、connected?は接続ができた時点、on_openの実行前に true になります。監視スレッドは各フィードの状態をfeed_status_interval秒(10)ごとにデータベースにも書き、それをこのプロセスやほかのプロセスのGET /upと./<app> feeds statusが読みます:フィードのヘルス。 on_messageは短く保つ。 スレッドはwait_readableかsleepで待つので、止まったフィードが待っている間 OS のワーカーを占有することはありません。占有するものは 2 つあります:各接続の試行はブロッキングするgetaddrinfoでホスト名を解決します(外向きの HTTP の「名前解決はブロックする」を参照。SPINEL_WORKERS=1では、死んだリゾルバーがフィードごと・試行ごとに 1 回、リゾルバーのタイムアウトの間すべてのリクエストを止めます。URL に IP アドレスを書けば問い合わせを避けられます)。そしてon_messageの中の SQLite の呼び出しは、定期タスクと同じく戻るまで占有します(バックグラウンド処理):SPINEL_WORKERS=1では、長い書き込みがすべてのリクエストを止めます。忙しいフィードでは小さな行を 1 つ挿入するか、メッセージをメモリーに集めてScheduler.everyのタスクからまとめて書き込んでください。- 作られていないもの。 拡張(
permessage-deflate)とサブプロトコルはネゴシエートされません。プロキシ、リダイレクト、cookie のサポートも、メッセージの自動保存もありません(ブラウザーには専用のエンドポイントがあります:リアルタイム)。テキストフレームが有効な UTF-8 かは検査されません(RFC 6455 の 8.1 節からの逸脱):バイト列は届いたまま渡されます。Connectionが有効なのはコールバックの間だけです。リクエストやタスクから送信することはサポートされていません。
再接続のループなしの 1 本の接続(スクリプト、1 回だけの読み取り)には、同期的なクライアントを使います:
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 は、SMTP サーバー(プロバイダーのサブミッションサーバー、またはローカルのリレー)を通じて、プレーンテキストか HTML の部分を持つメールを、すぐに(deliver)またはジョブから(deliver_later、下記)送ります。require "cybertrain" がこれを読み込みます。cybertrain/core のアプリケーションや、フレームワークを使わないプログラムは cybertrain/mailer を require します(データベースは要りません。deliver_later は cybertrain/mailer/later にあり、こちらはジョブも読み込みます)。TLS は別に require します:
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:starttls なら 587、tls なら 465、none なら 25 |
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)、他に何かを話す前にアップグレードします。サーバーが STARTTLS の応答の後に送ってきたバイトは拒否されます。tlsは最初のバイトから TLS を話します(ポート 465)。どちらも HTTP クライアントと同じく証明書をhostに対して検証し(IP アドレスではなくホスト名を指定してください)、どちらにもrequire "cybertrain/net/tls"(require "cybertrain"が読み込みます)が必要です:それがないと、deliverは接続する前に、その旨を伝えるMailer::TLSErrorを出します。noneは平文で、同じマシン上のリレーやテストサーバー向けです:ユーザーが設定されている場合、ホストがループバックアドレスに解決されない限り拒否し(接続する前にMailer::InsecureError)、解決される場合はそのループバックアドレスにだけ接続します。 - パスワードがログに出たり表示されたりすることはない。 起動バナー、
help、ログ、どのエラーメッセージにも含まれず、送られるのは TLS 越しに(またはループバックへ)AUTH PLAIN コマンドの中だけです。パスワードを保持しているMailerやConfigをpやinspectしないでください。 - すべての待ちに上限がある。 外向きの HTTP と同じく:接続、TLS の各手順、各応答は最大
timeout秒(デフォルトは 10)待ち、配信全体では最大deadline秒(デフォルトは 60)待ちます。それを超えるとMailer::TimeoutErrorです。名前解決は呼び出したスレッドをブロックします。 - やり取り: 220 の挨拶、
EHLO(名前はhelo:。デフォルトはlocalhost)、STARTTLSと再度のEHLO、ユーザーが設定されていればAUTH PLAIN(サーバーが PLAIN を提供する必要があります)、MAIL FROM、受信者ごとに 1 つの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 になり、.で始まる行はドットスタッフィングされます。Content-Transfer-Encodingは、ASCII なら7bit、UTF-8 でサーバーが 8BITMIME を広告していれば8bit(MAIL FROM ... BODY=8BITMIME付き)、それ以外や 998 バイトより長い行がある場合はbase64です。Message-IDは追加しません(サブミッションサーバーが追加します)。 - 拒否されるもの。 接続する前に
ArgumentErrorで:素の ASCII のlocal@domainでないアドレス(表示名、<>、空白、カンマ、引用符、CR、LF は不可。最大 254 バイト)、CR、LF、NUL を含む(ヘッダーインジェクション)または 998 バイトを超える件名、有効な UTF-8 でない、または NUL を含む本文、100 を超える受信者。to:は 1 つのアドレス、またはカンマで区切った複数のアドレスを受け取ります。 - メーラー:
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は 2 つ書き出し(パスワードリセット)、両方の行を追加します。 - まだないもの: 添付ファイルとインライン画像、
default from:と名前で見つかるビューを持つメーラークラス、表示名、Cc/Bccヘッダー(代わりに複数の受信者に送ってください)、AUTH LOGIN/CRAM-MD5、SMTPUTF8 のアドレス、パイプライン。deliverは呼び出したスレッドで実行されます。これはリクエストと同じくグリーンスレッドです。
HTML メール
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(なので行の長さやドットスタッフィングの規則は関係ありません)、間にはランダムな区切りが入ります。メールソフトは HTML を表示し、表示できなければテキストに戻ります。html:がなければ、メッセージはこれまでどおり上のプレーンテキストです。Views.render_mail(name, locals)は、リクエストの外でパーシャル(app/views/mail/_welcome.html.erb)をレンダーします。app/views/layouts/mail.html.erbがあればそのレイアウトの中で、なければパーシャルだけです。Views.render_partialはレイアウトなしでレンダーします。値はページと同じく HTML エスケープされます。プレーンテキストの部分もパーシャルから作れます。自分でレンダーしてbody:に渡してください(<%= %>はエスケープするので、値は<%== %>で出力します)。
後で送る
Cybertrain::Mailer.deliver_later(to: user.email, subject: "Welcome", body: text, html: html)
deliver_later には bin/<app>.rb と bin/db.rb に require "cybertrain/mailer/later"(または require "cybertrain")が必要です。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のログイン失敗も同じです)。 - 1 つのメッセージ、すべての受信者。 複数の受信者へのメッセージは 1 つの SMTP のトランザクションです。サーバーがそのうち 1 人を
5xxで拒否すると、ジョブ全体が破棄され、ほかの受信者にも届きません。受信者どうしが互いに左右されてはならないときは、受信者ごとに 1 つのメッセージをキューに入れてください。 - メッセージはデータベースに残ります(ジョブの行のペイロード。ジョブページに表示されます)。ジョブが実行されるまで、そして終わった行を残している間ずっとです。
- このジョブが登録されるので、ジョブを実行するプロセスはどれも、自分のジョブクラスがないアプリケーションでもジョブスレッドを起動します。
設計:docs/design.md D27 と D57。