What's BlackOps

BlackOpsが解決する分断、Headless Operation Frameworkの意味、設計原則を理解する。

BlackOpsはPHP 8.5向けのHeadless Operation Frameworkです。#[Route]で同期HTTP、#[Deferred]でDeferred Worker、#[ConsoleCommand]でCLIから同じOperationを起動し、Lifecycle Journalで実行事実を追跡します。HeadlessなのでUIを持たず、生成したJavaScript Client CodeをNext.js、NuxtJS、SvelteKitなどのFrontendへ接続できます。

一つのOperation Modelに型付きInput、Outcome、Execution Contextを集約し、InlineとDeferredの実行経路を同じLifecycle境界で扱います。

同期HTTPと非同期Jobを別々のModelで実装すると、同じ業務上の意図でもLifecycle、Retry、Trace、Outcomeの扱いが実行経路ごとに分かれます。障害調査ではController、Queue、Worker、Application Logを横断し、「処理を受理したのか」「何回試したのか」「最終結果は何か」を組み立て直さなければなりません。

BlackOpsは、Applicationが実行したい一つの意図をOperationとして表し、Request内で実行するInlineと、Durable受付後にWorkerが実行するDeferredをExecution Strategyの違いとして扱います。Operation、型付きInput、Outcome、追跡Contextは実行経路を変えても同じです。

Headless Operation Framework

BlackOpsのHeadlessはUIを提供せず、JavaScript Client Codeを生成してFrontendへ接続するRuntimeです。Session Core、Authentication Middleware、Authorization PolicyのFramework境界を提供し、User、Password、Registration、Cookie／CSRF、Role、Tenant、Resource PolicyはApplicationが所有します。Domain OperationはHTTP Controller、BlackOps CLI、Deferred Workerなどの入口から分離できます。

BlackOpsはWeb Application全体を置き換えません。既存のRouter、Authentication、Template、Frontendと組み合わせながら、追跡可能にしたい処理をOperationとして実行できます。

一つのOperation Model

同じOperationをInlineまたはDeferredで実行しても、次の境界は変わりません。

• OperationValueが型付きInputを表します。
• Operationのhandle()が業務処理を実行します。
• 正常完了時は型付きOutcomeを返します。
• ExecutionContextがOperation ID、Correlation、Causation、Attemptを伝播します。
• JournalがLifecycleで起きた事実を追記します。

実行経路ごとの差はCore ConceptsとInline and Deferredで確認できます。

Lifecycle Journalで実行事実を追跡する

FrameworkがOperationとして受理した処理は、Inline／Deferredを問わずLifecycle Journalへ記録します。受理、Attempt開始、完了、業務拒否、失敗、Retryなどの事実をOperation IDから追跡できます。

この原則には明確な境界があります。Route不一致、壊れたJSON、必要Headerの欠落など、Operationとして受理する前のProtocol ErrorはHTTP等の入力Adapterの責務です。受理前のInputにはOperation Lifecycleがまだ存在しないため、Lifecycle Journalの対象にはなりません。入力AdapterのAccess LogやError Responseで観測してください。

Laravel／Symfony経験からの対応

次の表はBlackOpsの概念を理解するためのMental Modelです。

この対応は一対一のAPI移植表ではありません。Controllerを機械的にOperationへRenameしたり、既存Queue MessageをそのままOperationへ置換したりするものではありません。入口から独立させたい業務上の意図、型付きInput／Output、追跡境界を見つけるために使ってください。

次はCore Conceptsで、Operationと周辺概念の関係を一枚の図から確認します。