HTTP responseのstatus-line、reason-phraseの内容にどこまでこだわるか？

scalatraのメンテナンスでservletのdeprecatedなメソッドを使っている箇所を直そうと思ったら単純には行かず、延々とHTTP protocolのstatus-lineに入るreason-phraseについて調べることになりました。

せっかくなので、その結果をまとめておきます。

status-lineのreason-phraseとは？

まずはstatus-lineのreason-pheraseについておさらいします。

おなじみHTTP protocolのresponseの1行目はstatus-lineと呼ばれ、「HTTP/1.1 200 OK」や、「HTTP/1.1 404 Not Found」といった内容がサーバサイトの処理結果に応じてクライアントに返されます。

このstatus-lineの内容はRFC 7230で以下のように定義されています。

status-line = HTTP-version SP status-code SP reason-phrase CRLF

status-codeは3桁のコードで、HTTP requestの成否が返されます。その一覧はRFC7231で確認することができます。

続くreason-phraseには人間が理解できるようにstatus-codeの内容を簡潔に示すテキストが入ります。RFC 7230では以下のように定義されていて、あまり現代では必要性無さそうです。

The reason-phrase element exists for the sole purpose of providing a textual description associated with the numeric status code, mostly out of deference to earlier Internet application protocols that were more frequently used with interactive text clients.

更には続けてクライアントソフトは無視すべきであると書かれています。

A client SHOULD ignore the reason-phrase content.

reason-phraseの形式は先ほどのRFC 7230で以下のように定義されています。

reason-phrase  = *( HTAB / SP / VCHAR / obs-text )

先頭がアスタリスクなので、全て省略しても規格上は正しい、つまりreason-phraseは規格上省略可です。

一応RFC7231にstatus-codeごとにreason-phraseの推奨案が記載されていますが、あくまで推奨なので独自に変えたとしてもプロトコルの動作に影響を与えないこととなっています(それで挙動が変わることが有れば実装の方が誤り、という事です)。

サーバアプリケーションでのreason-phraseの設定処理

普段サーバアプリケーションを書いていてreason-phraseのことをいちいち気にすることは無いと思いますが、これは一般的にアプリケーションサーバ側でよしなに処理してくれるからです。

いくつか実装を見てみましょう。

Sinatra + WEBrick(Ruby - Rack)

Sinatra + WEBrickはご存じの通り、Rackというインタフェースを通じて接続されています。Rackのインタフェース上、status-codeしか渡せないので、Sinatraではreason-phraseを設定していませんが、WEBrick側でreason-phraseを設定してくれます。

https://github.com/ruby/webrick/blob/43fc65e0619f033d02e8f4a0d647687f20939240/lib/webrick/httpresponse.rb#L125-L128

ちなみにRackの中でもreason-phraseが定義されていますが、WEBrickでは独自に定義されています。

https://github.com/rack/rack/blob/6b942ff543416e0c82196f0790d4915c7eead4cb/lib/rack/utils.rb#L487-L552

Jetty(Java - Servlet)

JavaのServlet、例えばJetty実装では、以下のように定義されています。

https://github.com/eclipse/jetty.project/blob/6fd3351272ba949dc80d160c18f0e403757a0c0d/jetty-http/src/main/java/org/eclipse/jetty/http/HttpStatus.java#L27-L33

Servletにはエラーレスポンスを即時に返すsendErrorというメソッドが有りますが、以下のようにreason-phraseを取得しています。

https://github.com/eclipse/jetty.project/blob/829fa4fe9bc650e336e7412aae6e6bffa9b37778/jetty-server/src/main/java/org/eclipse/jetty/server/Response.java#L635-L641

なお、Servletのもう一つの実装、Apache Tomcatではver 8.5以降でreason-phraseはデフォルトでは送信されなくなっていて、オプションで送信するように変更可能なものの、その設定自体は非推奨となっています。また、Tomcat 9からはこのオプションすら削除されるそうです。

60362 – Missing reason phrase in response

独自のreason-phraseを設定する

冒頭で説明した通り、reason-phraseは規格上は推奨案は有っても厳格な定義はされていません。例えば先ほどのServletのSendErrorメソッドの第二引数に任意の文字列を渡せば独自のreason-phraseを設定することができ、規格上も問題ありません。

RackやPSGI(Perl)と言った言語でのインタフェースではstatus-codeしか渡さないので、アプリ側から独自のreason-phraseを定義する方法は無さそうです（serverの実装しだい…でも見たことが無い…）。

HTTP/2

最近普及してきたHTTP/2では規格自体にreason-phraseが無いそうです。

github.com

Scalatraのメンテで遭遇した事象

古いServletの規格では2つの引数を取るsetStatusというメソッドが用意されていて、status-codeと独自のreason-phraseを設定し、かつbody部を定義することができました。現在最新のScalatra 2.5.1ではこれが使われています(reason-phraseが設定されていない時は、status-codeのみをセットするsetStatusが使われるが、ユーザーコード側からは見えないように隠蔽されている)。

現在（といってもServlet 2.1以降)では2つの引数を取るsetStatusは非推奨になり、独自のreason-phraseを設定したい場合は、body部無しにただしにエラーを返す(エラー例外を送出し、エラーログに出力される)SendErrorメソッドを使うしか有りません。

現在のServletではエラーが発生した時に、body無しで簡潔にエラー内容を伝えたい時（ログに残したい時）に使う思想のようです。しかし先ほどのTomcatのように、そもそもreason-phraseを一切送信しない実装も有るので、必ずクライアント側に送信される保証は無く、あまり使い道は無さそうです。

この解決はGitHubのissueで！

結論

というわけで、ここまで見てきて…

• 設定内容がそもそも規格上保証されていない(RFC 7231)
• アプリ側で自由に設定できない規格/実装がある(Rackは設定できない、Servletはエラー時のみ設定可)
• 送信されない実装が有る(apache Tomcatなど)
• HTTP/2では規格上存在しない
• そもそも規格でクライアントは無視すべきとまで書かれている(RFC 7230)

現代では「status-lineのreason-phraseにこだわってはいけないこと」がよく分かりました。HTTP responseの死活チェックなどで「200 OK」をチェックしないように気をつけましょう！

SRE サイトリライアビリティエンジニアリングを読んだ

ちょっと前に邦訳が出て話題になっていた「SRE サイトリライアビリティエンジニアリング」をようやく読んだ。

GoogleエンジニアによるSRE(Site Reliability Engineering)の解説記事の集合体。全体のページ数は500ページを超えていてかなりのボリュームだけど、割と短い記事の集合なので拾い読みには丁度良いかも。

日本ではメルカリがSREチームを大々的にアピールしていますね(既に日本、と限定できない組織になっていますが)。

tech.mercari.com

トイル(toil)

色々と読み所の多い本では有りますが、個人的には第5章「トイルの撲滅」が一番興味深く読めました。

トイル(toil)という言葉は今まで知らなかったのですが、辞書を引くと「骨折り(仕事); 苦労」と書かれていて、あまり良い意味では無さそうです。

本書の中では、以下のように定義されています。

プロダクションサービスを動作させることに関係する作業で、手作業で繰り返し行われ、自動化することが可能であり、戦術的で長期的な価値を持たず、作業量がサービスの成長に比例するといった傾向を持つものです。

システムを運用していれば日々色々なアラートメッセージを受け取りますが、必ずしも全てに新規性が有るわけではなく、日々既知のアラートを受け取り、「(改善を図る暇も無いし)既知だから問題ありません」とインシデントをクローズすることが有るかと思います。

しかし、このような作業の割合が増えていくと、本書でも触れられているようにエンジニアとしてのキャリアの停滞につながります。

たいてい一つ一つの作業はすぐに終わるし、システムは安定的に運用されているし…と言った理由でこのような小さな問題はマネージメントサイドから注目されることが少ないのですが、実はこうゆうことを一つ一つクリアにしていくことが大事なんだな、と改めて理解しました。

トイル、減らしていきましょう！

おわりに

SRE サイトリライアビリティエンジニアリング ―Googleの信頼性を支えるエンジニアリングチーム

なお、原著がオンラインで無料公開されているので、まずはそちらを読んでみると良い。

Google - Site Reliability Engineering

sbt 1.0時代のPlugin事情

sbt-scalatraというsbt pluginを1.0対応させるためにやったことをまとめておきます。

sbt 1.0対応作業一覧

sbt 1.0対応のpluginをゼロから作るときの詳しい解説は、公式ドキュメントにきちんと書かれているので、まずはそれを読む。

sbt Reference Manual — Plugins

ここでは既にsbt 0.13系のPluginをアップデートしてsbt 1.0対応したときのことを書く。ざっと以下のような作業を行った。

1. AutoPlugin化
2. project/pluginをアップデートする
3. 複数のsbtのバージョンに対応させる
4. plugin間の依存関係の定義
5. pluginを自動で有効にする
6. settingsの対応
7. deprecatedなメソッドの書き換え

AutoPlugin化

sbt 1.0以降はAutoPluginしかサポートされなくなるので、従来Plugin classを継承していた箇所をAutoPlugin classの継承へ書き換える。

単純に書き換えるだけでOK。

これを…

object ScalatraPlugin extends Plugin {

こう書き換える。

object ScalatraPlugin extends AutoPlugin {

AutoPlugin自体の詳しい解説はAPI Documentや、AutoPlugin登場時の解説記事を読むと分かりやすい。

http://www.scala-sbt.org/1.0.2/api/sbt/AutoPlugin.html

http://eed3si9n.com/ja/sbt-preview-auto-plugins

project/plugin.sbtをアップデートする

project/plugin.sbtに書かれているsbt pluginのバージョンをsbt 1.0対応したものへアップデートする。

sbt 1.0への対応状況はsbtのWikiを参照すると良い。きちんとアップデートされている。

github.com

ここで一つでも使用しているsbt pluginがsbt 1.0対応できていなければ1.0対応のコンパイルが通らないため、先にそちらのpluginをアップデートするか、issue上げて直してもらうか、PR送るか、という3択となる（もしくは使うのを止める）。

plugin間の依存関係の定義

AutoPluginでは、Plugin同士の依存関係を定義できる。

例えばsbt-scalatraのScalatraPluginは、xsbt-web-pluginのJettyPluginに依存していて、ScalatraPluginを有効にすれば自動的にJettyPluginも有効になる(AutoPlugin化される前は明示的に別々に有効にする必要が有った)。

依存するPluginは、project/plugin.sbtではなくbuild.sbtに定義する。その際addSbtPluginではなく、libraryDependenciesを使う。

sbtの複数バージョンに対応させるため、build.sbtに以下のように定義する(xsbt-web-pluginに依存する場合の指定例です)。sbtとScalaのバージョンがターゲットのsbtのバージョンによって自動的に選択される。

libraryDependencies += {
  Defaults.sbtPluginExtra(
    "com.earldouglas" % "xsbt-web-plugin" % "4.0.0",
    (sbtBinaryVersion in pluginCrossBuild).value,
    (scalaBinaryVersion in pluginCrossBuild).value
  )
},

なぜかsbtのドキュメントにはsbtPluginExtraのことが書かれていないが、以下のブログを読むと構造が分かる。

始める sbt - プラグインの使用

実際のplugin間の依存関係は、以下のようにrequiresをオーバーライドすることで定義する。

import sbt._
object ScalatraPlugin extends AutoPlugin {
  override def requires = JettyPlugin

複数のsbtのバージョンに対応させる

当面sbt 0.13も利用され続けると思われるので、0.13系と1.0系の両方に対応させるためには、build.sbtにcrossSbtVersionsを定義し、クロスビルドを有効にする。

例えば以下のように記述すれば、0.13.16と、1.0.2に対応したバイナリを作成する。

crossSbtVersions := Seq("0.13.16", "1.0.2"),

普通にcompileするとproject/build.propertiesのバージョンを参照するので、^comileや^scriptedのように先頭に'^'を付けてコマンドを実行する。

project/build.propertiesに指定するバージョンは、crossSbtVersionsに指定したバージョンのうち、どちらかと必ず合わせた方が良い。そうしないと無駄に色々なバージョンのsbtをダウンロードすることになる。

pluginを自動で有効にする

下記のように定義すると、Pluginは自動的に有効になる。

override def trigger = allRequirements

triggerをオーバライドしない場合、build.sbtの中で明示的にpluginを有効にする。

enablePlugins(ScalatraPlugin)

例えば一つのbuild.sbtに複数のサブプロジェクトが有り、特定のサブプロジェクトでしか有効にする必要が無いPluginであれば明示的に有効させるべきだし、ソースコードフォーマッターのようにプロジェクト横断的に使うものであれば明示的に有効にさせる必要は無いかもしれない。その辺りはユースケース次第だが、どちらにしてもドキュメントには明示した方が良い。

settingsの対応

AutoPluginより前はpluginごとに色々な設定名が使われていたが、AutoPlugin化以降は、MyPlugin.projectSettingsみたいにpluginのclass名に続けてprojectSettings又はbuildSettingsという名称で統一された。

互換性のため、既存のsettingsの名称を変える必要は無いが、以下のようにprojectSettingsに代入しておくことでprojectSettings形式で使えるようにする方が良い。

override lazy val projectSettings = scalatraSettings

またsettingsを使って有効にしたいtaskKeyやsettingKeyはautoImportに定義する。

deprecatedなメソッドの書き換え

sbt 0.13でdeprecatedになっているメソッドはsbt 1.0では削除されている。そのため下記のドキュメントを参考にソースコードを書き換える。

sbt Reference Manual — Migrating from sbt 0.12.x

互換性の関係からどうしても一つのソースコードにまとめられない場合は、それぞれのsbtのバージョンに対応したディレクトリを用意することで、sbtのバージョン別ソースコードを用意することができる(sbtのAPIが変わったものや、Scala 2.10と2.12の非互換など)。

src/main/scala-sbt-0.13/

src/main/scala-sbt-1.0/

具体的なコード例は、sbt-scalatraの例を参考にすると良い。

github.com

おわりに

一つ一つの作業は単純だけど、特にsbt 1.0で内部構造が大きく変わっているものなど、クラスの階層構造が変わっていたり、別リポジトリへ移っていたりと、意外と移動先を探すのが大変だった。

そこはひたすらsbt自体のソースを見るしかない。あとsbt自体のドキュメントがかなりの量あるので、それを読み込むのがけっこう大変だった。

とりあえずsbt 1.0にアップデートしないとJava9で動作しないので、前に進むしかない。ソフトウェアエンジニアに後退する、という選択肢は無いので進もう！

MacBook Pro 2017モデル 13″の電源アダプタを快適に持ち運ぶ

MacBook Pro 2017モデル 13″を購入した。

USB PDになれば純正以外の充電器が選び放題で、外出用のサードパーティー製の充電器とケーブルを買うぞ！と意気込んだものの、MacBook Proで使うとなると結局これ！という物が無いのが実情…

thewirecutter.com

しょうがないので、純正の充電器とケーブルを持ち運んでいるけど、以前の充電器と違ってType-Cの充電器では電源ケーブルを巻き取ることができないし、純正USBケーブルはしなやかさに欠けていて、まとめづらい。

クルッと巻いてケーブルバンドで固定して、コクヨのSHELLBROというペンケースに、ケーブルと充電器を収納して運んでいます。いまのところ、これが一番カバンの中で収まりが良い。

オウルテック 結束マジックテープ OWL-SKSN03

コクヨ ペンケース シェルブロ ブラック×オレンジ F-VBF190-1

クラウドファンディングで良さそうなアクセサリケースを見つけたけど、すぐに入手できないので、様子見。

www.makuake.com

Markdown Night 2017 Summerというイベントを開催しました

やるぞ！という話になって2ヶ月あまり、ついに開催しました。

早速色々とまとめて頂いているので、イベントの様子はそちらをご覧頂ければと思います。

スライドも既にアップされていますので、見逃した方はそちらをご覧下さい。

tech.mercari.com

togetter.com

blog.bitjourney.com

当日は80人近くの方に参加頂き、懇親会含めて、非常に盛況でした。 会場・懇親会を提供頂いたメルカリ様、並びに運営をサポート頂いた社員の方に感謝致します。

少しタイムテーブル的に余裕が無かったかな、という点が反省でしたが、次回に生かしていきたいと思います。

第2回の開催は今回の反響次第ですが、我こそはMarkdownについて話したい！という方がいらっしゃましたらご連絡下さい。

※読み・書き・そろばん・markdownという標語(?)を意外と拾って頂いたのでちょっと嬉しかった…

「現場で役立つシステム設計の原則」を読んだ

細々と書き直したので、最初の公開の時とちょっと変わっています。

---

最近ようやくこの手の「良い設計」をちゃんと解説してくれる書籍が出版されるようになってきて、良い時代になったなぁ。データベースであればドメインを定義したり、正規化といった、ある程度定型的な観点が有る手法が有るので割と以前から良い設計に対するアプローチが明確だった気がするけど、アプリケーションになるとなぜか、あまり見かけなかった。

今までコードを書いたことが無い人が読んでも、今一つ納得感が無いような気がするけど、一度でも他人のコードの改修に苦労したことが有れば、発見が有る本。

全編に渡って素晴らしい知見が多いのだけど、まずはChapter1の「小さくまとめてわかりやすくする」だけでもしっかり読んだ方がいい。特に値オブジェクト重要。

値オブジェクトを使ったリファクタリングと機能追加を体験するだけでも、ソフトウェアの複雑さのコントロールについての一番大事なポイントが理解できるんじゃないかと。ソフトウェアの機能追加を安定的に行っていくためには、影響範囲をどうやって正しく特定するか？ということに尽きるんだけど、それが型レベルで追跡し易くなるだけで格段に楽になるし、想定外の値が混入していないことも保証されるので、安心できる。

複雑なソフトウェアに対するリファクタリングと機能追加をみっちりやる体験講座が有れば良いのに！

Chapter2以降も良い話が満載だけど、まずはChapter1を腹落ちするまでコードを書いた方がいいんじゃないかと。

良い設計を行うために

設計の話ということで、先日のBuildersconでしんぺいさんが発表された「複雑なJavaScriptアプリケーションに立ち向かうためのアーキテクチャ」というトーク本編とQAの中でとても良い言葉が有ったので、その話とリンクするのですが…

techblog.reraku.co.jp

スライドに出てくる「設計に正解は無い」という言葉と、QAの中で出てきた「良い設計か否かは機能追加するまで分からない」という言葉は大事だな、と。○○すればOKなんてことは無くて、未来にどんなことが起きる得るか、それをしっかり考えて（かつ、考えすぎず）その環境においてベストな設計を自らの意思で選択することが大事なんじゃないかと思うわけです。

あと「機能追加するまで良い設計か分からない」ということは裏を返せば、過去の機能追加で苦労した所をしっかり振り返っておけば、自分たちに必要な保守性や、拡張性はおのずと分かるハズです。

現場で役立つシステム設計の原則 〜変更を楽で安全にするオブジェクト指向の実践技法

Markdown Night 2017 Summerというイベントを開催する

Builderscon Tokyo 2017の興奮も覚めやらぬ中、Markdown Night 2017 Summerというイベントを開催することにしました。

connpass.com

普段吉祥寺.pmというイベントを定期的に開催しているけど、そろそろ別の形式のイベントもやってみたい、ということでgfxさんの発案に乗っかり、更にはメルカリ様の会場提供という嬉しい展開も有り、なかなか盛り上がる予感です。