v0.21

ミドルウェア

はじめに

ミドルウェアはアプリケーションに届くhttpリクエストを検査およびフィルタリングするための便利な仕組みを提供します。例えば認証ミドルウェアはユーザーがログインしているかを検証します。ログインしていない場合ミドルウェアはログイン画面にリダイレクトします。認証されている場合ミドルウェアはリクエストがアプリケーションのより深い処理へ進むことを許可します。

ミドルウェアの定義

すべてのカスタムミドルウェアはmiddlewaresディレクトリに配置します。ミドルウェアは非同期メソッドを持つクラスとして定義します。各メソッドは独立したミドルウェアハンドラーとして機能します。

1// middlewares/AuthMiddleware.js
2export default class AuthMiddleware {
3 async requireAuth(req, next) {
4 if (!Auth.check()) {
5 return redirect('/login', true);
6 }
7 return next();
8 }
9
10 async requireGuest(req, next) {
11 if (Auth.check()) {
12 return redirect('/home', true);
13 }
14 return next();
15 }
16}

cliを使用してミドルウェアのスタブを生成できます。

1dstrn make:middleware AuthMiddleware

next関数

すべてのミドルウェアメソッドはreqオブジェクトとnextクロージャを受け取ります。実行チェーン内の次のミドルウェアに制御を渡すにはnext()を呼び出す必要があります。next()を呼び出さない場合リクエストはそのミドルウェアで停止しフレームワークはレスポンスが処理されたとみなします。

コントローラとビューへのデータ受け渡し

next()にオブジェクトペイロードを渡すか.with()をチェーンすることで後続のコントローラとビューの両方にデータを渡すことができます:

1export default class AuthMiddleware {
2 async requireAuth(req, next) {
3 if (!Auth.check()) {
4 return redirect('/login', true);
5 }
6
7 const devices = await Device.where({ user_id: Auth.user().id, revoked: false });
8
9 // passes data to req.devices and merges it into all view templates
10 return next({ devices });
11 }
12}

チェーン可能な.with()構文を使用することもできます:

1return next().with({ devices, currentDevice });

next(data)またはnext.with(data)経由で渡されたデータはすべて自動的に以下の処理が行われます:

レスポンスオブジェクトへのアクセスが必要なミドルウェアもあります。その場合は第2引数としてresを第3引数としてnextを宣言できます。

1export default class CustomMiddleware {
2 async intercept(req, res, next) {
3 res.set('X-Custom-Header', 'dstrn');
4 return next();
5 }
6}

チェーンの停止

リクエストを停止してコントローラに到達しないようにするにはnext()を呼び出す代わりにredirect()、abort()、json()などのレスポンスヘルパーを返します。

1// middlewares/AdminMiddleware.js
2export default class AdminMiddleware {
3 async requireAdmin(req, next) {
4 if (!Auth.check()) return redirect('/login');
5 if (Auth.user().power < 5) return abort(403, 'unauthorized access');
6
7 return next();
8 }
9}
IMPORTANT

ミドルウェアランナーはレスポンスの状態を厳格に監視します。ミドルウェアがヘッダーを送信したか書き込み可能なストリームを終了した場合誤って`next()`が呼び出されたとしてもチェーンは即座に中断されます。

ミドルウェアの登録

ミドルウェアはグローバルには登録されません。ClassName@methodという文字列構文を使用してルートに直接アタッチします。ルーターはこれらの文字列を自動的に解決します。

単一のルートにミドルウェアを適用できます。

1Route.middleware('AuthMiddleware@requireAuth').get('/profile', 'app.UserProfileController@show');

ルートのグループにミドルウェアを適用できます。

1Route.group({ middleware: ['AuthMiddleware@requireAuth'] }, (auth) => {
2 auth.get('/dashboard', 'app.IndexController@dashboard');
3 auth.get('/library', 'app.IndexController@library');
4});

配列を指定して複数のミドルウェアをチェーンできます。

1Route.group({ middleware: ['AuthMiddleware@requireAuth', 'AdminMiddleware@requireAdmin'] }, (admin) => {
2 admin.get('/users', 'admin.AdminController@list');
3});

最後の項目を除くすべての項目がミドルウェアとして扱われるインライン配列を使用してルートを定義することもできます。

1Route.post('/device/approve', ['AuthMiddleware@requireAuth', 'auth.AuthController@approvePost']);

ミドルウェアパラメータ

dframeworkはミドルウェア文字列構文を介して直接パラメータを渡すことをサポートしていません。ミドルウェアに動的な設定が必要な場合はクラス上に個別のメソッドを定義するかreqオブジェクトを介してデータを渡す必要があります。

1export default class DeviceMiddleware {
2 async verifyDevice(req, next) {
3 const devices = await Device.where({ user_id: Auth.id(), revoked: false });
4
5 // attach data to the request for controllers and views
6 return next({ devices });
7 }
8}

ホットリロード

local環境ではフレームワークはmiddlewaresディレクトリを監視します。ミドルウェアファイルを変更するとランナーはそのキャッシュを自動的に無効化してクラスを再読み込みします。これによりサーバーを再起動することなくミドルウェアのロジックが即座にホットリロードされます。

レート制限

組み込みのRateLimiterはスライディングウィンドウアルゴリズムを使用します。設定可能な時間枠内でキーごとのリクエスト数を追跡し期限切れのエントリを自動的にクリーンアップして標準的なレート制限レスポンスヘッダーを設定します。

1import { RateLimiter } from 'dframework';
2
3const limiter = new RateLimiter({
4 windowMs: 60 * 1000, // 1 minute
5 max: 60, // 60 requests per window
6 message: 'too many requests, please slow down',
7});
8
9Route.middleware(limiter).group({ prefix: '/api' }, (Route) => {
10 Route.post('/messages', 'MessageController@store');
11 Route.post('/uploads', 'UploadController@store');
12});

制限を超過した場合レスポンスには429ステータスとともにRetry-After、X-RateLimit-Limit、X-RateLimit-Remainingヘッダーが含まれます。

オプション デフォルト 説明
windowMs 60000 ミリ秒単位の時間枠
max 60 ウィンドウあたりの最大リクエスト数
message 'too many requests' 制限超過時に返されるメッセージ
keyGenerator クライアントip (req) => string、カスタムグループキー
trustedProxies [] x-forwarded-for解決のための信頼できるプロキシip
maxEntries 100000 lru退去前の最大追跡キー数
headers false 制限未超過のリクエストでもクォータヘッダーを送信

カスタムのkeyGeneratorはユーザー単位での制限に役立ちます:

1const limiter = new RateLimiter({
2 windowMs: 60 * 1000,
3 max: 20,
4 keyGenerator: (req) => Auth.id(),
5});