interlocking 0.0.1__py3-none-any.whl

interlocking/dispatcher.py

@@ -0,0 +1,471 @@
+"""
+interlocking.dispatcher
+==================
+TrainDispatcher と Train の実装。
+
+TrainDispatcher が列車編成・Middleware 呼び出し・信号解除を統括する。
+"""
+from __future__ import annotations
+
+import getpass
+import importlib
+import inspect
+import json
+import logging
+import time
+import uuid
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Optional,
+    Set,
+    Tuple,
+)
+
+from .models import (
+    Coupler,
+    SignalBlockedError,
+    SignalStatus,
+    StaleLockError,
+    TrainRecord,
+    TrainResult,
+)
+from .station import Station
+
+logger = logging.getLogger(__name__)
+
+
+def _default_run_by() -> str:
+    """実行ユーザー名の既定値。Lambda など passwd に UID がない環境では "unknown"。"""
+    try:
+        return getpass.getuser()
+    except (KeyError, OSError, ImportError):
+        return "unknown"
+
+
+def _task_signature(func: Callable) -> Tuple[Optional[str], list[str], Set[str]]:
+    """タスク関数のシグネチャを解析する。
+
+    Returns:
+        (Coupler 引数名 or None, Coupler を除く引数名のリスト, そのうち必須の引数名)。
+    """
+    argspec = inspect.getfullargspec(func)
+    coupler_arg_name = None
+    # inspect.get_annotations() を使用して "from __future__ import annotations" にも対応
+    try:
+        type_hints = inspect.get_annotations(func, eval_str=True)
+        for arg_name in argspec.args:
+            if type_hints.get(arg_name) is Coupler:
+                coupler_arg_name = arg_name
+                break
+    except Exception:
+        # 型ヒントの解決に失敗した場合は無視
+        pass
+
+    names = [a for a in argspec.args if a != coupler_arg_name]
+    n_defaults = len(argspec.defaults or ())
+    optional = set(argspec.args[len(argspec.args) - n_defaults:])
+    required = {a for a in names if a not in optional}
+    return coupler_arg_name, names, required
+
+
+class TrainMiddleware:
+    """interlocking のライフサイクル Middleware。デフォルト実装は logging モジュールへの出力。
+
+    dispatch(train) をオーバーライドして任意の処理を差し込む。
+    train.prepare() + train.run() を必ず呼ぶこと。呼ばなかった場合タスクは実行されない。
+
+    LoggerAdapter により extra={"run_id": ..., "run_by": ...} の指定が不要::
+
+        class SailsTaskMiddleware(TrainMiddleware):
+            def dispatch(self, train: Train) -> None:
+                token = context.run_id_var.set(train.current.run_id)
+                try:
+                    super().dispatch(train)  # ログ・prepare・run・記録保存を委譲
+                finally:
+                    context.run_id_var.reset(token)  # スコープ保証
+
+    シグナルブロック・メンテナンスウィンドウなどで実行をスキップする場合::
+
+        class SailsTaskMiddleware(TrainMiddleware):
+            def dispatch(self, train: Train) -> None:
+                if is_maintenance_mode():
+                    return  # 意図的にスキップ
+                super().dispatch(train)
+    """
+
+    def dispatch(self, train: Train) -> None:
+        """タスクのライフサイクル全体を実行する。
+
+        Args:
+            train: Train インスタンス。train.current で実行情報にアクセスできる。
+
+        Note:
+            train.prepare() / train.run() を呼ばない場合タスクは実行されない（意図的スキップ）。
+        """
+        log = logging.LoggerAdapter(
+            logger,
+            {
+                "track_id": train.current.track_id,
+                "run_id": train.current.run_id,
+                "run_by": train.current.run_by
+            },
+        )
+
+        try:
+            train.prepare()
+        except StaleLockError:
+            log.warning(
+                "Signal RED (stale): %s has a leftover lock. "
+                "Recover with abort, or run with allow_stale_takeover.",
+                train.current.track_id,
+            )
+            return
+        except SignalBlockedError:
+            log.warning("Signal RED: %s is already in operation.", train.current.track_id)
+            return
+
+        if train.coupler.stale_lock:
+            log.warning(
+                "Stale lock inherited: %s (prev run_id=%s run_by=%s)",
+                train.current.track_id,
+                train.coupler.last_stop.run_id,
+                train.coupler.last_stop.run_by,
+            )
+
+        log.info("Departure: %s", train.current.track_id)
+        try:
+            train.run()
+        except Exception:
+            log.exception("Failed: %s", train.current.track_id)
+
+        log.info("Arrived: %s elapsed=%.1f sec", train.current.track_id, train.current.elapsed)
+
+
+# registry の値の型: (func, help)
+_TrackEntry = Tuple[Callable, str]
+
+
+class Train:
+    """列車。signal check からユーザー関数実行・記録保存までを封じ込める。
+
+    Middleware は train.current で run_id / run_by / track_id に常にアクセスできる。
+    train.prepare() 呼び出し後、train.coupler が設定される。
+
+    Args:
+        track_id:       タスク識別子（"line_name:track_name" 形式）。
+        current:          今回の実行情報（run_id, run_by など）。prepare() 前から参照可能。
+        func:             ユーザー関数。
+        filtered:         ユーザー関数に渡す CLI 引数 dict（Coupler 引数は除外済み）。
+        coupler_arg_name: Coupler 型の引数名。None の場合は Coupler 不要。
+        station:          ストレージバックエンド。
+        stale_after:      この秒数が経過したロックを stale（前回ロックの残骸）とみなす。
+        force:            True のとき信号確認をスキップする。
+        allow_stale_takeover: True のとき、stale なロックだけを引き継いで実行する。
+    """
+
+    def __init__(
+        self,
+        track_id: str,
+        current: TrainRecord,
+        func: Callable,
+        filtered: dict,
+        coupler_arg_name: str | None,
+        station: Station,
+        stale_after: int,
+        force: bool,
+        allow_stale_takeover: bool = False,
+    ) -> None:
+        self.track_id = track_id
+        self.current = current
+        self.coupler: Optional[Coupler] = None  # prepare() 後に設定される
+        self._func = func
+        self._filtered = filtered
+        self._coupler_arg_name = coupler_arg_name
+        self._station = station
+        self._stale_after = stale_after
+        self._force = force
+        self._allow_stale_takeover = allow_stale_takeover
+        # depart() が結果判定・信号解除に使う実行状態
+        self.signal_acquired = False  # 自分がロックを取得した場合のみ True
+        self.blocked = False
+        self.stale = False  # blocked のうち、stale（前回ロックの残骸）が原因の場合 True
+        self.started = False
+        self.error: Optional[BaseException] = None
+
+    def prepare(self) -> None:
+        """シグナルチェック・記録ロード・Coupler 構築を行う。
+
+        Station が報告したロック状態に基づいて、例外の送出と引き継ぎの判断を行う。
+        CLEAR 以外はすべて赤信号として扱う（判断できないときは止める）。
+
+        Raises:
+            StaleLockError:     stale なロックがあり、allow_stale_takeover=False の場合。
+            SignalBlockedError: force=False かつ信号が赤（多重起動）の場合。
+        """
+        stale = False
+        if not self._force:
+            try:
+                status = self._station.check_signal(self.track_id, self._stale_after)
+            except SignalBlockedError:
+                self.blocked = True
+                raise
+            if status is SignalStatus.STALE:
+                if not self._allow_stale_takeover:
+                    self.blocked = True
+                    self.stale = True
+                    raise StaleLockError(self.track_id)
+                if not self._station.takeover_signal(self.track_id, self._stale_after):
+                    self.blocked = True  # 引き継ぎの競合に負けた
+                    raise SignalBlockedError(self.track_id)
+                stale = True
+            elif status is not SignalStatus.CLEAR:
+                self.blocked = True
+                raise SignalBlockedError(self.track_id)
+            self.signal_acquired = True
+        last_stop = self._station.load_record(self.track_id)
+        self.coupler = Coupler(current=self.current, last_stop=last_stop, stale_lock=stale)
+
+    @property
+    def params(self) -> dict:
+        """タスク関数に渡す引数（Coupler を除く）のコピー。Middleware から実行引数を観測できる。"""
+        return dict(self._filtered)
+
+    def result(self) -> TrainResult:
+        """現時点の実行状態から TrainResult を組み立てる。"""
+        if self.blocked:
+            status = "blocked"
+        elif not self.started:
+            status = "skipped"
+        else:
+            status = self.current.status
+        return TrainResult(
+            track_id=self.track_id,
+            run_id=self.current.run_id,
+            status=status,
+            data=self.current.data if status == "success" else None,
+            elapsed=self.current.elapsed,
+            error=self.error,
+            is_stale=self.stale,
+        )
+
+    def _linkable_data(self, result: Any) -> Optional[dict]:
+        """戻り値を次回実行へ連携できる data に変換する。連携できなければ WARNING を出して None を返す。"""
+        if result is None:
+            return None
+        if not isinstance(result, dict):
+            logger.warning(
+                "Return value not linked: %s returned %s (only dict can be linked to the next run).",
+                self.track_id,
+                type(result).__name__,
+            )
+            return None
+        try:
+            json.dumps(result)
+        except (TypeError, ValueError) as e:
+            logger.warning(
+                "Return value not linked: %s returned a dict that is not JSON serializable (%s).",
+                self.track_id,
+                e,
+            )
+            return None
+        return result
+
+    def run(self) -> None:
+        """ユーザー関数を実行し、結果を記録する。"""
+        self.started = True
+        self.current.started_at = time.time()
+        try:
+            if self._coupler_arg_name:
+                result = self._func(**{self._coupler_arg_name: self.coupler}, **self._filtered)
+            else:
+                result = self._func(**self._filtered)
+            self.current.data = self._linkable_data(result)
+            self.current.status = "success"
+            self.current.arrived_at = time.time()
+            self._station.save_record(self.track_id, self.current)
+        except Exception as e:
+            self.error = e
+            self.current.status = "failed"
+            self.current.error_type = type(e).__name__
+            self.current.error_message = str(e)
+            self.current.arrived_at = time.time()
+            self._station.save_record(self.track_id, self.current)
+            raise
+
+
+class TrainDispatcher:
+    """全路線の運行を統括する司令塔。
+
+    タスクの登録（registry）、列車編成、Middleware 呼び出し、信号解除を行う。
+
+    ライフサイクルをカスタマイズしたい場合は TrainMiddleware のサブクラスを作り
+    TrainDispatcher のコンストラクタに渡す。TrainDispatcher 自体はサブクラス化しない。
+
+    Args:
+        station: ストレージバックエンド。
+        lines:   路線名 -> "module.path:attr" のマッピング。
+                 depart() 呼び出し時に該当する路線だけを lazy import し登録する。
+    """
+
+    def __init__(
+        self,
+        station: Station,
+        lines: Optional[Dict[str, str]] = None,
+        middleware: Optional[TrainMiddleware] = None,
+        run_id_generator: Optional[Callable[[], str]] = None,
+    ) -> None:
+        self.master = station
+        self._lines = lines or {}
+        self._loaded_lines: set = set()  # ロード済み路線名
+        self.middleware = middleware or TrainMiddleware()
+        self.run_id_generator = run_id_generator or (lambda: uuid.uuid4().hex)
+        self.registry: Dict[str, _TrackEntry] = {}
+
+    @property
+    def lines(self) -> Dict[str, str]:
+        """路線名 -> "module.path:attr" のマッピング（コピー）。"""
+        return dict(self._lines)
+
+    def abort(self, track_id: str, run_by: Optional[str] = None) -> None:
+        """実行中フラグを強制解除し、操作の事実を TrainRecord に記録する。
+
+        status を "aborted" に更新し、aborted_at / aborted_by を記録する。
+        data / run_id などは保持する（次回実行の Coupler.last_data を失わない）。
+        error_type / error_message は前回の失敗の情報なのでクリアする。
+
+        Args:
+            track_id: タスク識別子。
+            run_by:   操作したユーザー名。省略時は getpass.getuser()。
+        """
+        self.master.abort(track_id)
+        record = self.master.load_record(track_id)
+        record.status = "aborted"
+        record.error_type = None
+        record.error_message = None
+        record.aborted_at = time.time()
+        record.aborted_by = run_by or _default_run_by()
+        self.master.save_record(track_id, record)
+
+    def load_line(self, line_name: str) -> None:
+        """指定路線を lazy import して registry に登録する。
+
+        既にロード済みの場合や lines に存在しない路線名の場合は何もしない。
+        """
+        if line_name in self._loaded_lines or line_name not in self._lines:
+            return
+        self._loaded_lines.add(line_name)
+        module_path, attr = self._lines[line_name].rsplit(":", 1)
+        module = importlib.import_module(module_path)
+        line_obj = getattr(module, attr)
+        line_obj.register_to(self, line_name)
+
+    def _ensure_line_for(self, track_id: str) -> None:
+        """タスク識別子から路線名 prefix を抽出して対応する路線をロードする。"""
+        self.load_line(track_id.split(":")[0])
+
+    def register(self, track_id: str, func: Callable, help: str) -> None:
+        """タスクを registry に登録する。通常は Line.register_to() から呼ばれる。"""
+        self.registry[track_id] = (func, help)
+
+    def task_params(self, track_id: str) -> Tuple[Set[str], Set[str]]:
+        """タスクが受け取れる引数名と、そのうち必須の引数名を返す（Coupler 引数は含まない）。
+
+        Raises:
+            KeyError: 未登録のタスクの場合。
+        """
+        self._ensure_line_for(track_id)
+        _, names, required = _task_signature(self.registry[track_id][0])
+        return set(names), required
+
+    def depart(
+        self,
+        track_id: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        force: bool = False,
+        allow_stale_takeover: bool = False,
+        stale_after: int = 600,
+        run_id: Optional[str] = None,
+        run_by: Optional[str] = None,
+        raise_on_failure: bool = False,
+        raise_on_blocked: bool = False,
+    ) -> TrainResult:
+        """列車を出発させる。
+
+        Args:
+            track_id: タスク識別子（"line_name:track_name" 形式）。
+            params:     タスク関数に渡す引数の dict。関数シグネチャにないキーがあると ValueError。
+            force:      True のとき信号確認をスキップする。
+            allow_stale_takeover: True のとき、stale（前回ロックの残骸）なロックだけを引き継いで実行する。
+                        False のときは stale も赤信号（blocked）とし、自動では引き継がない。
+            stale_after: この秒数が経過したロックを stale とみなす。
+            run_id:     実行ID。省略時は run_id_generator() で生成。
+            run_by:     実行ユーザー名。省略時は getpass.getuser()（取得できなければ "unknown"）。
+            raise_on_failure: True のときタスクの例外を信号解除後に再送出する。
+            raise_on_blocked: True のとき赤信号（多重起動）を SignalBlockedError（stale の場合は StaleLockError）として送出する。
+
+        Returns:
+            実行結果。既定では失敗・赤信号でも例外を送出せず status に反映する。
+
+        Raises:
+            ValueError:         params にタスク関数が受け取れないキーが含まれる場合（ロックは取得しない）。
+            Exception:          raise_on_failure=True かつタスクが失敗した場合、その例外。
+            SignalBlockedError: raise_on_blocked=True かつ赤信号の場合（stale ならサブクラスの StaleLockError）。
+        """
+        _run_id = run_id or self.run_id_generator()
+        _run_by = run_by or _default_run_by()
+        _params = params or {}
+
+        self._ensure_line_for(track_id)
+
+        current = TrainRecord(
+            track_id=track_id,
+            run_id=_run_id,
+            run_by=_run_by,
+            track_help=self.registry[track_id][1],  # help テキスト
+            status="running",
+            force=force,
+            allow_stale_takeover=allow_stale_takeover,
+        )
+
+        func, _ = self.registry[track_id]
+
+        # Coupler 引数は変数名ではなく型ヒントで判定する。
+        coupler_arg_name, arg_names, _ = _task_signature(func)
+
+        if unknown := _params.keys() - set(arg_names):
+            raise ValueError(
+                f"{track_id} に存在しない引数です: {sorted(unknown)} (使用可能: {sorted(arg_names)})"
+            )
+        filtered = dict(_params)
+
+        train = Train(
+            track_id=track_id,
+            current=current,
+            func=func,
+            filtered=filtered,
+            coupler_arg_name=coupler_arg_name,
+            station=self.master,
+            stale_after=stale_after,
+            force=force,
+            allow_stale_takeover=allow_stale_takeover,
+        )
+
+        try:
+            self.middleware.dispatch(train)
+        finally:
+            # 自分が取得したロックだけを解除する。赤信号で弾かれた起動が
+            # 実行中の他プロセスのロックを消さないようにする（S3Station は無条件に削除するため）。
+            if train.signal_acquired:
+                self.master.clear_signal(track_id)
+
+        result = train.result()
+        if raise_on_blocked and result.status == "blocked":
+            if result.is_stale:
+                raise StaleLockError(track_id)
+            raise SignalBlockedError(track_id)
+        if raise_on_failure and train.error is not None:
+            raise train.error
+        return result

interlocking/lambda_.py

@@ -0,0 +1,186 @@
+"""
+interlocking.lambda_
+===============
+AWS Lambda から TrainDispatcher を呼び出すためのハンドラーファクトリ。
+
+dispatcher はモジュールレベルで 1 度だけ生成し、ウォーム起動で再利用すること。
+Station には S3Station を使うこと（LocalStation の /tmp は実行環境ごとに分離されるため排他にならない）。
+
+使用例::
+
+    # handler.py
+    from interlocking import S3Station, TrainDispatcher
+    from interlocking.lambda_ import make_lambda_handler
+
+    dispatcher = TrainDispatcher(
+        station=S3Station(bucket="my-bucket", prefix="interlocking/prod"),
+        lines={"batch": "myapp.tasks:line"},
+    )
+    handler = make_lambda_handler(dispatcher)
+
+既定のイベント形式（EventBridge の Input Transformer や直接 invoke で指定する）::
+
+    {"track_id": "batch:daily", "params": {"target_date": "2026-04-01"}}
+
+任意キー: ``force`` (bool) / ``allow_stale_takeover`` (bool) / ``stale_after`` (int, 秒) / ``run_by`` (str)
+
+未知のキー・型の誤り・未登録のタスク・タスクにない引数・必須引数の不足は、
+タスクを実行せず :class:`InvalidRequestError` (``ValueError``) を送出する。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional
+
+from .dispatcher import TrainDispatcher
+
+# 残り実行時間に加える余裕（秒）。強制終了された Lambda のロックを確実に stale と判定できるようにする。
+_STALE_AFTER_MARGIN_SEC = 60
+_DEFAULT_STALE_AFTER_SEC = 600
+_EVENT_KEYS = frozenset({"track_id", "params", "force", "allow_stale_takeover", "stale_after", "run_by"})
+
+
+class InvalidRequestError(ValueError):
+    """イベントの形式不正、または dispatcher に対して実行できないリクエスト。再試行しても直らない。"""
+
+
+@dataclass
+class LambdaRequest:
+    """Lambda イベントから取り出した depart() の呼び出し内容。
+
+    Attributes:
+        track_id: タスク識別子（"line_name:track_name" 形式）。
+        params:   タスク関数に渡す引数。
+        force:    True のとき信号確認をスキップする。
+        allow_stale_takeover: True のとき、stale なロックだけを引き継いで実行する。
+        stale_after: stale とみなす秒数。None のときは Lambda の残り実行時間から算出する。
+        run_by:   実行ユーザー名。None のとき ``lambda:<関数名>``。
+    """
+    track_id: str
+    params: Dict[str, Any] = field(default_factory=dict)
+    force: bool = False
+    allow_stale_takeover: bool = False
+    stale_after: Optional[int] = None
+    run_by: Optional[str] = None
+
+
+def default_event_mapper(event: Dict[str, Any]) -> LambdaRequest:
+    """既定のイベント形式を検証して LambdaRequest に変換する。
+
+    Raises:
+        InvalidRequestError: 未知のキー・型の誤り・track_id の欠落。
+    """
+    if not isinstance(event, dict):
+        raise InvalidRequestError(f"イベントは dict で指定してください: {type(event).__name__}")
+    if unknown := event.keys() - _EVENT_KEYS:
+        raise InvalidRequestError(f"未知のキーです: {sorted(unknown)} (使用可能: {sorted(_EVENT_KEYS)})")
+
+    track_id = event.get("track_id")
+    if not isinstance(track_id, str) or ":" not in track_id:
+        raise InvalidRequestError(f"track_id は '路線名:タスク名' 形式の文字列で指定してください: {track_id!r}")
+
+    params = event.get("params") or {}
+    if not isinstance(params, dict):
+        raise InvalidRequestError(f"params は dict で指定してください: {type(params).__name__}")
+
+    force = event.get("force", False)
+    if not isinstance(force, bool):
+        raise InvalidRequestError(f"force は真偽値で指定してください: {force!r}")
+
+    allow_stale_takeover = event.get("allow_stale_takeover", False)
+    if not isinstance(allow_stale_takeover, bool):
+        raise InvalidRequestError(f"allow_stale_takeover は真偽値で指定してください: {allow_stale_takeover!r}")
+
+    stale_after = event.get("stale_after")
+    if stale_after is not None and (isinstance(stale_after, bool) or not isinstance(stale_after, int) or stale_after <= 0):
+        raise InvalidRequestError(f"stale_after は正の整数（秒）で指定してください: {stale_after!r}")
+
+    run_by = event.get("run_by")
+    if run_by is not None and not isinstance(run_by, str):
+        raise InvalidRequestError(f"run_by は文字列で指定してください: {run_by!r}")
+
+    return LambdaRequest(
+        track_id=track_id,
+        params=params,
+        force=force,
+        allow_stale_takeover=allow_stale_takeover,
+        stale_after=stale_after,
+        run_by=run_by,
+    )
+
+
+def validate_request(dispatcher: TrainDispatcher, request: LambdaRequest) -> None:
+    """タスクの存在と引数の過不足を検証する。
+
+    ``TrainDispatcher.depart()`` はシグネチャにない引数を黙って無視するため、
+    引数名の誤り（例: ``dry_run`` の綴り間違い）で意図せず既定値のまま実行されることを防ぐ。
+
+    Raises:
+        InvalidRequestError: 未登録のタスク・存在しない引数・必須引数の不足。
+    """
+    dispatcher.load_line(request.track_id.split(":", 1)[0])
+    if request.track_id not in dispatcher.registry:
+        raise InvalidRequestError(f"未登録のタスクです: {request.track_id}")
+
+    names, required = dispatcher.task_params(request.track_id)
+    if unknown := request.params.keys() - names:
+        raise InvalidRequestError(
+            f"{request.track_id} に存在しない引数です: {sorted(unknown)} (使用可能: {sorted(names)})"
+        )
+    if missing := required - request.params.keys():
+        raise InvalidRequestError(f"{request.track_id} の必須引数が不足しています: {sorted(missing)}")
+
+
+def _resolve_stale_after(request: LambdaRequest, context: Any) -> int:
+    """stale_after を決める。Lambda の残り実行時間より長くして、強制終了後のロックを stale と判定できるようにする。
+
+    stale は自動では引き継がれない。復旧は abort か allow_stale_takeover で行う。
+    """
+    if request.stale_after is not None:
+        return int(request.stale_after)
+    get_remaining = getattr(context, "get_remaining_time_in_millis", None)
+    if get_remaining is None:
+        return _DEFAULT_STALE_AFTER_SEC
+    return int(get_remaining()) // 1000 + _STALE_AFTER_MARGIN_SEC
+
+
+def make_lambda_handler(
+    dispatcher: TrainDispatcher,
+    *,
+    event_mapper: Callable[[Dict[str, Any]], LambdaRequest] = default_event_mapper,
+    raise_on_failure: bool = True,
+    raise_on_blocked: bool = False,
+) -> Callable[[Dict[str, Any], Any], Dict[str, Any]]:
+    """Lambda ハンドラー ``handler(event, context)`` を生成する。
+
+    run_id には ``context.aws_request_id`` を使うため、CloudWatch Logs と突き合わせられる。
+    戻り値は :meth:`interlocking.models.TrainResult.to_dict` の JSON 互換 dict。
+
+    Args:
+        dispatcher:       タスクを登録済みの TrainDispatcher。
+        event_mapper:     イベントを LambdaRequest に変換する関数。
+        raise_on_failure: True のときタスク失敗を例外として送出する。
+                          非同期 invoke のリトライや DLQ を機能させるため既定は True。
+        raise_on_blocked: True のとき多重起動（赤信号）を SignalBlockedError として送出する。
+                          既定は False（戻り値の status="blocked" で返す）。
+    """
+
+    def handler(event: Dict[str, Any], context: Any) -> Dict[str, Any]:
+        request = event_mapper(event)
+        validate_request(dispatcher, request)
+        function_name = getattr(context, "function_name", None)
+        run_by = request.run_by or (f"lambda:{function_name}" if function_name else "lambda")
+        result = dispatcher.depart(
+            request.track_id,
+            request.params,
+            force=request.force,
+            allow_stale_takeover=request.allow_stale_takeover,
+            stale_after=_resolve_stale_after(request, context),
+            run_id=getattr(context, "aws_request_id", None),
+            run_by=run_by,
+            raise_on_failure=raise_on_failure,
+            raise_on_blocked=raise_on_blocked,
+        )
+        return result.to_dict()
+
+    return handler