v0.21

ジョブとキュー

はじめに

dframeworkは分離されたワーカースレッドでジョブを実行するネイティブのバックグラウンドジョブキューを備過しています。ジョブはアプリケーションコードからディスパッチされメインhttpプロセスをブロックすることなく非同期に実行されます。これはメール送信、画像処理、外部api同期などユーザーへの応答を遅延させるべきでないタスクに最適です。

NOTE

キューシステムはredisや個別のキューサーバーのような外部依存関係を一切必要としません。組み込みの`worker_threads`モジュールを使用してnode.jsランタイム内で完全に動作します。

ジョブの作成

ジョブクラス

ジョブはプロジェクト直下のjobsディレクトリに保存されるクラスです。すべてのジョブはhandle(payload)メソッドを持つクラスをデフォルトエクスポートする必要があります。handleメソッドはジョブディスパッチ時に渡されたペイロードを受け取り実際に実行する処理を含みます。

1export default class SendWelcomeEmailJob {
2 async handle(payload) {
3 const user = await User.find(payload.userId);
4 await Mailer.send(user.email, 'welcome', { name: user.name });
5 }
6}

handleメソッドは非同期にできます。ワーカーは返されたpromiseが解決されるのを待ってから完了を報告します。

ジョブ設定

ジョブはクラスの静的プロパティとしてデフォルトの実行オプションを直接定義できます。これらは呼び出し元で上書きされない限りジョブのディスパッチ時に自動的に適用されます。

1export default class ProcessVideoJob {
2 static timeout = 30000;
3 static tries = 3;
4 static backoff = 1000;
5
6 async handle(payload) {
7 await this.transcode(payload.videoId);
8 }
9}
プロパティ 型 デフォルト値 説明
timeout number 60000 ミリ秒単位の実行タイムアウト(このタイムアウトを超過したワーカーは終了します)
tries number 1 ジョブが失敗としてマークされるまでの最大試行回数
backoff number 1000 再試行間のミリ秒単位の指数バックオフ基本遅延

ジョブの生成

cliを使用して新しいジョブファイルをスキャフォールディングできます。

1dstrn make:job SendWelcomeEmailJob

これにより適切な定型構造を持つjobs/SendWelcomeEmailJob.jsファイルが作成されます。

ジョブのディスパッチ

コントローラーから

ジョブをディスパッチする最も一般的な方法はユーザーリクエストを処理した後にコントローラーから行うことです。

1export default class RegistrationController {
2 async register(req, res) {
3 const user = await User.create(req.body);
4 Job.dispatch('SendWelcomeEmailJob', { userId: user.id });
5 return redirect('/dashboard');
6 }
7}

Job.dispatch()はノンブロッキングです。ジョブがバックグラウンドワーカースレッドで実行される間即座にコントローラーに制御を返します。

どこからでも

Jobファサードはグローバルに利用可能です。コントローラー、ミドルウェア、ソケットイベントハンドラー、他のジョブ、スケジュールされたコマンドからジョブをディスパッチすることもフレームワークルートから直接インポートすることもできます。

1import { Job } from 'dframework';
2
3Job.dispatch('SyncInventoryJob', { warehouseId: 3 });

またはすべてのランタイムコンテキストで自動的に利用可能なグローバルJobファサードを使用します。

1Job.dispatch('GenerateReportJob', { month: 'june', year: 2026 });

コマンドラインから

dstrn dispatchコマンドを使用してコマンドラインからジョブをディスパッチすることもできます。これは開発中のジョブテストや手動での単発タスク実行に役立ちます。

1dstrn dispatch SendWelcomeEmailJob --payload '{"userId": 1}'

--payloadフラグはパースされてジョブのhandleメソッドに渡されるjson文字列を受け取ります。省略された場合ジョブは空のオブジェクトを受け取ります。このコマンドはワーカースレッドと同様にデータベース接続やすべてのフレームワークグローバルを含む完全なアプリケーションコンテキストをブートストラップします。完了時に実行時間が報告されます。

1dstrn dispatch CleanupExpiredSessionsJob

シェルのタブ補完を容易にするため.jsで終わるファイル名も受け付けます。

1dstrn dispatch CleanupExpiredSessionsJob.js

ペイロードデータ

Job.dispatch()の第2引数はjsonにシリアライズされてジョブのhandleメソッドに渡されるプレーンなjavascriptオブジェクトです。ペイロードは小さくシリアライズ可能な状態を維持してください。完全なオブジェクトではなく識別子を渡すようにします。

1Job.dispatch('ProcessImageJob', {
2 imageId: upload.id,
3 operations: ['resize', 'compress'],
4 quality: 85
5});

Jobファサード

グローバルのJobはアプリケーションのQueueインスタンスに処理を委譲するプロキシファサードです。アプリケーションの起動時に自動的に登録されグローバルスコープで利用可能です。

1Job.dispatch('JobName', { key: 'value' });

Job.dispatch()は実行オプションを指定するオプションの第3引数を受け付けます(ジョブクラスで定義された静的プロパティを上書きします)。

1Job.dispatch('ProcessVideoJob', { videoId: 42 }, {
2 timeout: 30000,
3 tries: 3,
4 backoff: 1000
5});
オプション 型 デフォルト値 説明
timeout number 60000 ミリ秒単位の実行タイムアウト(このタイムアウトを超過したワーカーは終了します)
tries number 1 ジョブが失敗としてマークされるまでの最大試行回数
backoff number 1000 再試行間のミリ秒単位の指数バックオフ基本遅延

アプリケーションが初期化される前にJobファサードを使用しようとすると詳細なエラーがスローされます。

ワーカープールの仕組み

ワーカーの分離

ディスパッチされた各ジョブはnode worker_threadsを使用した専用のWorkerスレッドで実行されます。ワーカースレッドはhttpサーバーを起動することなくデータベース接続、設定の読み込み、すべてのフレームワークグローバルを含む最小限のアプリケーションインスタンスを初期化します。これによりジョブコードはDBファサード、Config、モデルクラス、すべてのヘルパー関数を含むコントローラーとまったく同じapiを使用できます。

同時実行制限

キューは同時実行ワーカーの最大数を強制します。デフォルトでは最大4つのジョブを同時に実行できます。新しいジョブがディスパッチされたときにすべてのワーカースロットが占有されている場合ジョブはメモリ内キューに配置されワーカーが利用可能になり次第実行されます。

最大ワーカー数はqueue.maxWorkers設定キーによって設定可能です。

自動キューイングと永続ワーカープール

ワーカープールが上限に達した場合追加でディスパッチされたジョブは内部キューに自動的にバッファリングされます。dframeworkのワーカーは永続的なワーカースレッドプール内で動作します。

  1. オンデマンド実行: ワーカースレッドはJob.dispatch()によってジョブがディスパッチされたときに遅延生成されます。バックグラウンドジョブをディスパッチしないアプリケーションではワーカーオーバーヘッドが一切発生しません。
  2. 永続実行: ジョブが存在する場合ワーカースレッドはアプリケーション環境とデータベースプールを一度ブートしアイドルプールで生存し続けます。後続のジョブはスレッド生成やアイソレートの起動遅延なしにウォームワーカーによって即座に処理されます。
  3. 自動デキュー: 各ワーカーはジョブを終了すると内部キューから次のバッファリングされたジョブを取得するか今後のディスパッチに備えてアイドルプールに戻ります。
  4. 障害回復: ワーカースレッド内で処理されない致命的なエラーやプロセスクラッシュが発生した場合ワーカーはクリーンアップを行って終了し保留中のタスクの処理を継続するために代替ワーカーが生成されます。

ジョブのライフサイクル

ブートストラップ

永続ワーカースレッドが起動すると以下の手順が実行されます。

  1. プロジェクトから環境変数と設定ファイルを読み込みます
  2. データベース接続とグローバルファサードを持つアプリケーションインスタンスを初期化します
  3. メインプロセスに準備完了を通知しディスパッチされたジョブを待機します
  4. ジョブを受け取るとjobsディレクトリからジョブクラスをインポートします
  5. ジョブクラスをインスタンス化しhandleメソッドを検証します
  6. シリアライズされたペイロードを渡してhandle(payload)を呼び出します
  7. 実行時間を添えて成功または失敗をメインスレッドに報告します
  8. 後続のジョブを即座に受け付けるためにアイドルワーカープールに戻ります

データベースアクセス

ジョブはコントローラーで利用可能なものと同じDBファサードとモデルクラスを通じてデータベースへの完全なアクセス権を持ちます。各ワーカースレッドは初期化中にデータベース接続プールを確立します。プールはワーカーの生存期間中ジョブの実行をまたいでオープンな状態を維持しワーカーが終了するかキューが空になったときに安全に破棄されます。

1export default class CleanupExpiredSessionsJob {
2 async handle(payload) {
3 const cutoff = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
4 await DB.table('sessions').where('updated_at', '<', cutoff).delete();
5 }
6}

ジョブからのブロードキャスト

ジョブはグローバルなSocketファサードを使用してリアルタイムwebsocketイベントをディスパッチし接続されているクライアントのコンポーネント状態を更新できます。ジョブは専用のワーカースレッド内で実行されるためSocket.broadcast()およびSocket.setState()は内部ワーカーチャネル経由でメインプロセスにメッセージを自動的にリレーしメインプロセスが接続されているブラウザにブロードキャストします。

1export default class GenerateReportJob {
2 async handle(payload) {
3 Socket.broadcast('report:progress', { percent: 25 });
4
5 const report = await this.generate(payload.reportId);
6 Socket.broadcast('report:progress', { percent: 100 });
7
8 Socket.broadcast('report:ready', {
9 reportId: report.id,
10 downloadUrl: `/reports/${report.id}/download`
11 });
12
13 Socket.setState('#report-banner', {
14 status: 'complete',
15 reportId: report.id
16 });
17 }
18}

外部メッセージブローカー(redisなど)は不要です。ワーカースレッドはプライマリサーバーインスタンスと直接通信します。

エラーハンドリング

ジョブのhandleメソッドがエラーをスローした場合エラー名、メッセージ、スタックトレース、実行時間を含む構造化エラーメッセージがメインスレッドに送り返されアプリケーションロガーによって記録されます。ワーカースレッドは終了する前にデータベース接続を閉じるためのクリーンアップ関数を実行します。

1[JOB] [SendWelcomeEmailJob] failed after 1847ms:
2Error: SMTP connection refused
3 at Mailer.send (mailer/Mailer.js:42)
4 at SendWelcomeEmailJob.handle (jobs/SendWelcomeEmailJob.js:12)

ワーカースレッド自体がクラッシュした場合(例えばメモリ不足状態によるものなど)メインスレッドはerrorイベントを受け取りクラッシュをログに記録します。ワーカースロットが解放されキュー内の次のジョブが通常どおり処理されます。ワーカープロセスが終了するとデータベース接続は自動的に解放されます。

設定

キューシステムはapp.queue設定名前空間から設定を読み込みます。

設定キー 型 デフォルト値 説明
app.queue.maxWorkers number 4 同時実行ワーカースレッドの最大数
app.queue.timeout number 60000 ミリ秒単位のデフォルトジョブ実行タイムアウト
app.queue.bootstrapTimeout number 30000 新規起動したワーカーのブートストラップ完了を待機する最大ミリ秒数
app.queue.shutdownTimeout number 30000 グレースフルシャットダウン時に実行中ジョブの完了を待機する最大ミリ秒数
1// config/app.js
2export default {
3 queue: {
4 maxWorkers: Env.value('QUEUE_MAX_WORKERS', 4),
5 timeout: Env.value('QUEUE_TIMEOUT', 60000),
6 bootstrapTimeout: Env.value('QUEUE_BOOTSTRAP_TIMEOUT', 30000),
7 shutdownTimeout: Env.value('QUEUE_SHUTDOWN_TIMEOUT', 30000),
8 },
9};