express-sessionのざっくり翻訳1 - プログラミングまわりのメモ(初心者)

express-sessionのざっくり翻訳1
express-sessionのざっくり翻訳2

node.jsでexpressを使いつつ色々実装しようと思っていて、express-passportで認証をしようとしていましたが、express-sessionが登場してしまったので、先にexpress-sessionについて公式をざっくりと斜め読みしました。
そのときのざっくり翻訳です。正確さは低めです。また、別のサイト等で自分で調べたことやコメントは(⇒ )としています。

参考：公式(2017/1/26)

(⇒express-sessionはセッションをうまいことやってくれるAPIです。)
前提 ☆今回
インストール ☆今回
API ☆今回途中まで
Session Store Implementation

0. 前提

2017/1/26現在のexpress-sessionのバージョンは1.15.0

1. インストール

$npm install express-session

2. API

$var session = require('express-session');

session(options)

指定されたオプションを使ってセッションのmiddlewareを作ります。
- セッションデータはcookie自体には保存されずサーバに保存されます。cookieにはセッションIDだけが保存されます。
- セッションデータはデフォルトでサーバのMemoryStoreに保存されますが、実用向きではないのでうまくやる必要があります。
- 1.5.0から cookie-parserが不要になりました。(⇒特に2014/6以前のネット上の解説を読む際には注意です。)

Options

cookie: session ID cookieのオブジェクトの設定。デフォルトは
{path: '/', httpOnly: true, secure: false, maxAge: null}
cookie.domain: cookieのDomain属性の設定ができます。
(⇒「どこのドメインに対して有効なcookieにしますか」的なやつみたいです。)
デフォルトではドメインは設定されておらず、だいたいのクライアントではそのドメインだけにcookieを対応させます。
cookie.expires: Dataオブジェクトを指定して、cookieのExpires属性を指定します。
デフォルトでは期限が設定されておらず、だいたいのクライアントでは"non-persistent cookie"(⇒セッション切れたら無効)として扱われます。
・expiresとmaxAgeがどちらも設定されていたら、遅く設定された方が適応されます。
・expireを直接設定するべきではありません。代わりにmaxAgeのみを設定しましょう。
cookie.httpOnly: true/falseでcookieのHttpOnly属性を設定します。デフォルトではtrueでHttpOnlyが設定されます。
cookie.maxAge: ミリ秒指定でcookieのExpires属性を計算します。
その時点のサーバー時間にmaxAgeをミリ秒で加えてExpires属性にします。
デフォルトでは未設定です。
・expiresとmaxAgeがどちらも設定されていたら、遅く設定された方が適応されます。
cookie.path: cookieのPath属性を設定します。デフォルトではドメインルートの'/'が設定されます。
cookie.sameSite: true/falseでcookieのSameSite属性を指定します。
・true : SameSite属性にStrictが設定されます。
・false : SameSite属性は設定されません。
・'lax' : SameSite属性にLaxが設定されます。
・'strict' : SameSite属性にStrictが設定されます。

- まだ標準化されていない部分のため、今後変わる可能性があり、多くのクライアントで無視される可能性があります。
cookie.secure: true/falseでcookieのSecure属性を指定します。trueでSecureが設定されます。
デフォルトではSecureは設定されません。
- trueにするときは気をつけましょう。HTTPS接続していないブラウザはサーバにcookieを返しません。

secure: true とするのが推奨されますが、httpsに対応したサイトが必要です。
HTTPを介してサイトへ接続するとcookieはセットされません。
node.jsをproxyの背後で動かしていて secure: true とする場合は、"trust proxy"をexpress上で設定する必要があります。(コード例省略)
cookie.secureには他にも auto という特別な値を設定することができます。(⇒いい感じに設定してくれます。)
この設定をHTTP, HTTPS両方に対応するサイトで指定する場合には注意する必要があります。(省略)
genid: 新しいセッションIDを生成し返す関数です。
req を第一引数とすることで、セッションID生成時にreq内のいくつかの値を使用できます。
デフォルトでは uid-safe ライブラリを生成に使用する関数です。
name: response、またrequestからの読み取り時にセッションIDのクッキーに設定される名前です。
- 同じホスト名で複数のアプリケーションを実行する場合、それぞれのセッションcookieを分ける必要があります。一番簡単なのは、name に対してアプリケーションごとに違う値を設定することです。
proxy: secure cookiesを設定した時、リバースプロキシを信用します。("X-Forwarded-Proto"ヘッダを使用)
デフォルトは undefinedです。
・true : "X-Forwarded-Proto"ヘッダが使用されます。
・false: 全てのヘッダが無視され、TSL/SSL接続が直接行われている場合にのみ secureと処理します。
・undefined : expressの"trust proxy"設定を使用します。
resave: セッションに変更が加えられていないとしても、session storeにセッションを強制的に保存します。
使用するstoreにより必要になるかもしれませんが、クライアントが並列で複数のリクエストをサーバに投げた場合など、変更した内容を変更前の内容で上書きしてしまう恐れもあります。(振る舞いは使っているstoreにもよりけりです。)
デフォルトはtrueですが、デフォルトでの使用は非推奨です。デフォルトの値は将来的に変更される可能性があります。
一般的には false となると思いますが、どちらが必要かケースごとに考える必要があります。

チェックする一番簡単な方法は、使用するstoreが touch methodを持っているかどうかです。
touch methodが実装されていれば、resave : false を安心して設定できます。
touch methodが実装されておらず、保存されているセッションに期限が設定されている場合には resave : trueが必要なのかもしれません。
rolling: 毎回の応答で、セッションの識別用cookieを強制的に設定します。cookieの期限はmaxAgeの値をもとに再設定され、期限はリセットされます。
デフォルトはfalseです。
- このオプションがtrueで、かつ saveUninitialized オプションも falseの時、初期化されていないセッションの応答に対してcookieがセットされません。
saveUninitialized: "uninitialized"なセッションをstoreに強制的に保存します。セッションが新しいが編集されていない場合に "uninitialized"となります。
false はloginセッションを実装するのに適しており、サーバー要領の削減、cookieの設定の前に認証を行うという法律?にも対応します。並列に投げられるrequestについても、falseとすることで競合をさけることにつながります。

デフォルトは true ですが、trueは非推奨です。デフォルトの値は将来的に変更される可能性があります。
ケースごとにどちらがよいか考えてください。

- passportjs0.3.0以前を使用している場合は別途注意
secret: Required option
session ID cookieに署名するときに使われる鍵です。
文字列、もしくは文字列からなる配列を設定できます。配列を設定した場合、最初の文字列だけがsession ID cookieの署名に使用され、requestの署名を認証する際に全ての要素が考慮されます。(⇒要するにどういうこと?)
store: セッション保存のインスタンスで、デフォルトでは new MemoryStoreのインスタンスです。
unset: 未設定の req.sessionに対する処理を決めます。デフォルトは'keep'です。
・'destroy' : 応答が完了したとき、セッションは破棄されます。
・'keep' : セッションは保存されますが、request中に行われた編集は無視され、保存されません。