interlocking 0.0.1__py3-none-any.whl

interlocking/station.py

@@ -0,0 +1,428 @@
+"""
+interlocking.station
+======================
+Station の抽象基底クラスと LocalStation の実装。
+
+ストレージバックエンドの差し替えは Station を継承して実現する。
+現在提供する実装:
+  - LocalStation: Windows/Linux ローカルファイルロック（単一ホスト専用）
+  - S3Station:    S3 Conditional Write による分散ロック（複数ホスト対応）
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import time
+import uuid
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Dict
+
+from .models import SignalStatus, TrainRecord
+
+logger = logging.getLogger(__name__)
+
+# 確認中にロックが入れ替わった場合のやり直し回数。確定できなければ止める側に倒す。
+_MAX_ATTEMPTS = 5
+
+
+class Station(ABC):
+    """ストレージバックエンドの抽象基底クラス。
+
+    信号（排他ロック）と駅の記録（JSON）の読み書きを担う。
+    サブクラスで Local / S3 などを実装する。
+
+    Station はロック状態の報告だけを責務とする。引き継ぎを許可するか、
+    例外を送出するかといった判断は Train が行う。
+    """
+
+    @abstractmethod
+    def check_signal(self, track_id: str, stale_after: int = 600) -> SignalStatus:
+        """信号の状態を確認し、青信号ならロックを取得する。
+
+        確認と取得は原子的に行う（分散環境で競合しないため）。
+
+        Args:
+            track_id:    タスク識別子（"line_name:track_name" 形式）。
+            stale_after: この秒数が経過したロックを stale（前回ロックの残骸）とみなす。
+                         時間で判定しない実装（OS ロック等）は無視してよい。
+
+        Returns:
+            CLEAR:   ロックを取得した。
+            BLOCKED: 他の列車が運行中。ロックは取得していない。
+            STALE:   前回ロックの残骸。ロックは取得していない（引き継ぎは takeover_signal）。
+        """
+
+    @abstractmethod
+    def takeover_signal(self, track_id: str, stale_after: int = 600) -> bool:
+        """stale なロックを引き継いで取得する。
+
+        複数のプロセスが同時に引き継ごうとしても、取得できるのは 1 つだけ。
+
+        Returns:
+            True:  引き継いでロックを取得した。
+            False: 取得できなかった（他のプロセスが先に取得した、または stale ではなくなった）。
+        """
+
+    @abstractmethod
+    def clear_signal(self, track_id: str) -> None:
+        """信号を解放する（Unlock）。"""
+
+    @abstractmethod
+    def abort(self, track_id: str) -> None:
+        """信号を強制解除する。
+
+        対象タスクのプロセスが終了済みであることを確認してから実行すること。
+        プロセスが生きている状態では効果がない場合がある（実装依存）。
+        """
+
+    @abstractmethod
+    def load_record(self, track_id: str) -> TrainRecord:
+        """列車の運行記録を読み込む。
+
+        ファイルが存在しない場合（始発）は run_id=None の空の TrainRecord を返す。
+        """
+
+    @abstractmethod
+    def save_record(self, track_id: str, record: TrainRecord) -> None:
+        """列車の運行記録を保存する。"""
+
+
+class LocalStation(Station):
+    """Windows/Linux ローカル環境の駅。
+
+    OS のファイルロックで排他制御を行う。
+    単一ホスト専用。複数ホストからの同一タスク実行を防ぐには
+    S3Station を使用すること。
+
+    Args:
+        base_path: シグナルファイルと記録ファイルを格納するディレクトリ。
+    """
+
+    def __init__(
+        self,
+        base_path: str = ".interlocking",
+    ) -> None:
+        self.base_path = Path(base_path)
+        self.base_path.mkdir(parents=True, exist_ok=True)
+        self._signals: Dict[str, int] = {}  # track_id -> ファイルディスクリプタ
+
+    def _get_paths(self, track_id: str) -> tuple[Path, Path]:
+        """シグナルファイルと記録ファイルのパスを返す。"""
+        safe_id = track_id.replace(":", "_").replace("/", "_")
+        return (
+            self.base_path / f"{safe_id}.signal",
+            self.base_path / f"{safe_id}.json",
+        )
+
+    @staticmethod
+    def _try_lock(fd: int) -> bool:
+        """fd の OS ロックを非ブロッキングで試みる。取得できたら True。"""
+        try:
+            if sys.platform == "win32":
+                import msvcrt
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            else:
+                import fcntl
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            return False
+        return True
+
+    @staticmethod
+    def _unlock(fd: int) -> None:
+        if sys.platform == "win32":
+            import msvcrt
+            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(fd, fcntl.LOCK_UN)
+
+    @staticmethod
+    def _is_same_file(fd: int, path: Path) -> bool:
+        """ロックした fd が、パス上のファイルと同一か。ロック中に削除・再作成されていないことの確認。"""
+        try:
+            on_path = os.stat(path)
+        except FileNotFoundError:
+            return False
+        held = os.fstat(fd)
+        return (held.st_ino, held.st_dev) == (on_path.st_ino, on_path.st_dev)
+
+    def _probe_existing(self, sig_path: Path) -> SignalStatus | None:
+        """既存のシグナルファイルの状態を調べる（ロックは保持しない）。
+
+        OS ロックが有効なら実行中（BLOCKED）。ロックが取れるなら、プロセスが
+        消失してファイルだけが残っている（STALE）。確認中にファイルが
+        入れ替わった場合は None（やり直し）。
+        """
+        try:
+            fd = os.open(sig_path, os.O_RDWR)
+        except FileNotFoundError:
+            return None
+        except PermissionError:
+            return SignalStatus.BLOCKED  # 確認できないときは止める側に倒す
+        try:
+            if not self._try_lock(fd):
+                return SignalStatus.BLOCKED
+            try:
+                return SignalStatus.STALE if self._is_same_file(fd, sig_path) else None
+            finally:
+                self._unlock(fd)
+        finally:
+            os.close(fd)
+
+    def check_signal(self, track_id: str, stale_after: int = 600) -> SignalStatus:
+        """シグナルファイルと OS ロックで、信号の状態を確認する。
+
+        OS ロックが有効な間は、経過時間によらず BLOCKED（実行中の Busy とみなす）。
+        プロセスが消失してファイルだけが残っている場合のみ STALE。
+        時間判定は使わないため、stale_after は無視する。
+        """
+        sig_path, _ = self._get_paths(track_id)
+        for _ in range(_MAX_ATTEMPTS):
+            try:
+                fd = os.open(sig_path, os.O_RDWR | os.O_CREAT | os.O_EXCL)
+            except FileExistsError:
+                status = self._probe_existing(sig_path)
+                if status is None:
+                    continue  # 確認中にファイルが入れ替わった → やり直し
+                return status
+            if self._try_lock(fd):
+                self._signals[track_id] = fd
+                return SignalStatus.CLEAR
+            os.close(fd)
+            return SignalStatus.BLOCKED
+        return SignalStatus.BLOCKED  # 確定できないときは止める側に倒す
+
+    def takeover_signal(self, track_id: str, stale_after: int = 600) -> bool:
+        """プロセスが消失して残ったシグナルファイルのロックを取得する。
+
+        OS ロックが取れた場合のみ成功する（実行中のプロセスのロックは奪えない）。
+        """
+        sig_path, _ = self._get_paths(track_id)
+        try:
+            fd = os.open(sig_path, os.O_RDWR | os.O_CREAT)
+        except OSError:
+            return False
+        if not self._try_lock(fd):
+            os.close(fd)
+            return False
+        if not self._is_same_file(fd, sig_path):
+            self._unlock(fd)
+            os.close(fd)
+            return False
+        self._signals[track_id] = fd
+        return True
+
+    def clear_signal(self, track_id: str) -> None:
+        """ロックを解除してファイルディスクリプタを閉じ、シグナルファイルを削除する。"""
+        fd = self._signals.pop(track_id, None)
+        if fd is None:
+            return
+        try:
+            self._unlock(fd)
+        finally:
+            os.close(fd)
+            sig_path, _ = self._get_paths(track_id)
+            try:
+                sig_path.unlink()
+            except OSError:
+                pass  # 削除できなかった場合は残骸として STALE と判定される（止める側に倒す）
+
+    def abort(self, track_id: str) -> None:
+        """シグナルファイルを削除する。
+
+        対象プロセスが既に終了していれば成功する。
+        プロセスが生きている場合、削除に失敗する可能性がある（Windows）、
+        またはファイルは削除できてもロックが残る（Linux）。
+
+        想定フロー:
+          1. タスクプロセスの異常終了を確認
+          2. プロセスが完全に終了していることを確認
+          3. この abort を実行してシグナルファイルを削除
+        """
+        self.clear_signal(track_id)  # fd が残っていれば解放
+        # fd がなくても強制削除を試みる
+        sig_path, _ = self._get_paths(track_id)
+        if sig_path.exists():
+            sig_path.unlink()
+
+    def load_record(self, track_id: str) -> TrainRecord:
+        """記録ファイルを読み込む。存在しない場合（始発）は空の TrainRecord を返す。"""
+        _, record_path = self._get_paths(track_id)
+        if record_path.exists():
+            with open(record_path, "r", encoding="utf-8") as f:
+                try:
+                    return TrainRecord.from_dict(json.load(f))
+                except json.JSONDecodeError:
+                    raise ValueError(f"記録ファイルの読み込みに失敗: {record_path}")
+        return TrainRecord(track_id=track_id)  # run_id=None → 始発
+
+    def save_record(self, track_id: str, record: TrainRecord) -> None:
+        """記録ファイルに保存する。"""
+        _, record_path = self._get_paths(track_id)
+        # 書き込み前にシリアライズし、失敗したときに記録ファイルを空にしない。
+        payload = json.dumps(record.to_dict(), ensure_ascii=False, indent=2)
+        with open(record_path, "w", encoding="utf-8") as f:
+            f.write(payload)
+
+
+class S3Station(Station):
+    """S3 を使った分散環境対応の駅。
+
+    シグナル（排他ロック）に S3 Conditional Write（IfNoneMatch='*'）を使用する。
+    同一オブジェクトが存在しない場合のみ PUT が成功するため
+    複数ホストからの同時実行を防ぐことができる。
+
+    必要な S3 バケット権限:
+        s3:PutObject, s3:DeleteObject, s3:GetObject
+
+    Args:
+        bucket: S3 バケット名。
+        prefix: オブジェクトキーのプレフィックス（末尾スラッシュなし）。
+        boto3_client: boto3 の S3 クライアント。None の場合はデフォルト認証で生成。
+
+    使用例::
+
+        import boto3
+        station = S3Station(
+            bucket="my-bucket",
+            prefix="interlocking/prod",
+            boto3_client=boto3.client("s3", region_name="ap-northeast-1"),
+        )
+    """
+
+    def __init__(
+        self,
+        bucket: str,
+        prefix: str = "interlocking",
+        boto3_client=None,
+    ) -> None:
+        self.bucket = bucket
+        self.prefix = prefix.rstrip("/")
+        if boto3_client is not None:
+            self._s3 = boto3_client
+        else:
+            import boto3 as _boto3
+            self._s3 = _boto3.client("s3")
+
+    def _signal_key(self, track_id: str) -> str:
+        safe_id = track_id.replace(":", "_").replace("/", "_")
+        return f"{self.prefix}/{safe_id}.signal"
+
+    def _record_key(self, track_id: str) -> str:
+        safe_id = track_id.replace(":", "_").replace("/", "_")
+        return f"{self.prefix}/{safe_id}.json"
+
+    def _put_signal(self, key: str, **condition) -> bool:
+        """条件付き PUT でシグナルオブジェクトを書く。競合に負けたら False。
+
+        本文は毎回ユニークにする。空の本文だと ETag（MD5）が常に同じになり、
+        IfMatch の比較が何も区別しなくなる。
+        """
+        from botocore.exceptions import ClientError
+        try:
+            self._s3.put_object(
+                Bucket=self.bucket,
+                Key=key,
+                Body=json.dumps({"token": uuid.uuid4().hex}).encode("utf-8"),
+                ContentType="application/json",
+                **condition,
+            )
+            return True
+        except ClientError as e:
+            if e.response["Error"]["Code"] in (
+                "PreconditionFailed", "ConditionalRequestConflict", "NoSuchKey",
+            ):
+                return False
+            raise
+
+    def check_signal(self, track_id: str, stale_after: int = 600) -> SignalStatus:
+        """S3 Conditional Write でシグナルオブジェクトを排他生成する。
+
+        IfNoneMatch='*' により、オブジェクトが存在しない場合のみ PUT が成功する
+        （CLEAR）。既に存在する場合は、最終更新からの経過時間で判定する。
+
+        - stale_after 未満: BLOCKED（実行中）。
+        - stale_after 以上: STALE（前回ロックの残骸）。ロックは取得しない。
+        """
+        from botocore.exceptions import ClientError
+        key = self._signal_key(track_id)
+        for _ in range(_MAX_ATTEMPTS):
+            if self._put_signal(key, IfNoneMatch="*"):
+                return SignalStatus.CLEAR
+            try:
+                response = self._s3.head_object(Bucket=self.bucket, Key=key)
+            except ClientError as e:
+                if e.response["Error"]["Code"] in ("NoSuchKey", "404"):
+                    continue  # 確認中に解放された → 取得をやり直す
+                raise
+            elapsed = time.time() - response["LastModified"].timestamp()
+            return SignalStatus.STALE if elapsed >= stale_after else SignalStatus.BLOCKED
+        return SignalStatus.BLOCKED  # 確定できないときは止める側に倒す
+
+    def takeover_signal(self, track_id: str, stale_after: int = 600) -> bool:
+        """stale なシグナルオブジェクトを、ETag を条件に上書きして引き継ぐ。
+
+        IfMatch=ETag の条件付き PUT なので、複数プロセスが同時に引き継ごうとしても
+        成功するのは 1 つだけ。削除してから再取得する方式と違い、他のプロセスが
+        取得した新しいロックを消すことがない。
+        """
+        from botocore.exceptions import ClientError
+        key = self._signal_key(track_id)
+        try:
+            response = self._s3.head_object(Bucket=self.bucket, Key=key)
+        except ClientError as e:
+            if e.response["Error"]["Code"] in ("NoSuchKey", "404"):
+                return self._put_signal(key, IfNoneMatch="*")  # 既に解放済み
+            raise
+        elapsed = time.time() - response["LastModified"].timestamp()
+        if elapsed < stale_after:
+            return False  # 更新されて stale ではなくなった
+        return self._put_signal(key, IfMatch=response["ETag"])
+
+    def clear_signal(self, track_id: str) -> None:
+        """シグナルオブジェクトを削除してロックを解放する。"""
+        from botocore.exceptions import ClientError
+        try:
+            self._s3.delete_object(
+                Bucket=self.bucket,
+                Key=self._signal_key(track_id),
+            )
+        except ClientError:
+            pass  # 既に削除済みの場合は無視する
+
+    def abort(self, track_id: str) -> None:
+        """シグナルオブジェクトを削除する。
+
+        S3版では他ホストで実行中のタスクも強制停止できる。
+        タスクプロセス側で signal を確認せずに実行を続けることがあるため、
+        使用には注意が必要（プロセスの終了を確認してから実行することを推奨）。
+        """
+        self.clear_signal(track_id)
+
+    def load_record(self, track_id: str) -> TrainRecord:
+        """記録オブジェクトを読み込む。存在しない場合（始発）は空の TrainRecord を返す。"""
+        from botocore.exceptions import ClientError
+        try:
+            response = self._s3.get_object(
+                Bucket=self.bucket,
+                Key=self._record_key(track_id),
+            )
+            data = json.loads(response["Body"].read().decode("utf-8"))
+            return TrainRecord.from_dict(data)
+        except ClientError as e:
+            if e.response["Error"]["Code"] == "NoSuchKey":
+                return TrainRecord(track_id=track_id)  # run_id=None → 始発
+            raise
+
+    def save_record(self, track_id: str, record: TrainRecord) -> None:
+        """記録オブジェクトを保存する。"""
+        self._s3.put_object(
+            Bucket=self.bucket,
+            Key=self._record_key(track_id),
+            Body=json.dumps(record.to_dict(), ensure_ascii=False, indent=2).encode("utf-8"),
+            ContentType="application/json",
+        )

interlocking-0.0.1.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: interlocking
+Version: 0.0.1
+Summary: A lightweight task dispatcher with explicit control.
+Keywords: task-runner,batch,exclusive-lock,cli,mutex,distributed-lock
+Author: alpine
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Utilities
+Requires-Dist: boto3>1.40.0,<2 ; extra == 'aws'
+Requires-Python: >=3.11
+Provides-Extra: aws
+Description-Content-Type: text/markdown
+
+# Interlocking
+
+> One track, one train.  
+> Easy to run. Explicit to control.
+
+interlocking は、分散環境におけるバックグラウンドタスクの「運行管理」フレームワークです。
+鉄道メタファーにより、バッチタスクのライフサイクル（排他制御・実行記録・CLI 統合）を統一された方法で管理します。
+
+## 特長
+
+- **排他制御**: 同じタスクを同時に走らせない。
+- **実行記録**: 直近の実行結果を記録し、次回実行に引き継ぐ（`Coupler`）。
+- **CLI 統合**: 型ヒントからコマンドラインを組み立て、結果を終了コードで返す。
+- **差し込み**: `Station`（ストレージ）や `TrainMiddleware` で、振る舞いを拡張できる。
+
+## 最小構成
+
+```python
+# tasks.py
+from typing import Annotated
+from interlocking import Line, Coupler
+
+line = Line()
+
+@line.track(name="daily", help="日次処理")
+def daily_task(c: Coupler, target_date: Annotated[str, "対象日付 (YYYY-MM-DD)"]) -> dict:
+    last_id = c.last_data.get("last_id", 0)
+    # ... 処理 ...
+    return {"last_id": 9999}
+```
+
+```python
+# main.py
+import sys
+
+from interlocking import TrainDispatcher, LocalStation, InterlockingCLI
+
+dispatcher = TrainDispatcher(
+    station=LocalStation(base_path=".interlocking"),
+    lines={"batch": "tasks:line"},
+)
+
+cli = InterlockingCLI(dispatcher=dispatcher, prog="my-task", description="バッチタスク")
+sys.exit(cli.execute(cli.parse_args()))  # 結果を終了コードで伝える
+```
+
+```bash
+python main.py batch daily start --target-date 2026-04-01
+```
+
+詳しくは [docs/user/interlocking.md](docs/user/interlocking.md) を参照してください。
+
+## 開発
+
+```bash
+uv sync
+uv run pytest
+```
+
+設計方針は [.github/copilot-instructions.md](.github/copilot-instructions.md) の Design Principles、決定事項は [docs/dev/adr/](docs/dev/adr/) を参照してください。
+
+## ライセンス
+
+MIT

interlocking-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+interlocking/__init__.py,sha256=ZS0ZBqZu_XX9xnOgTF4Pw0CqvtLKkXEuLwOLSs29bFw,1074
+interlocking/cli.py,sha256=JjMxLI5mPgnCc2CDk6ODOqWkVFApwSM-V9gyQaxN8K0,11084
+interlocking/dispatcher.py,sha256=BUhs4cr7VumvJWV475fGqZUxtmYLMptPHCocrBVtmZY,19149
+interlocking/lambda_.py,sha256=gcBllml6N57lGaA7Y4YoBJOrNd7qHsgNu3Aj-HA6yM8,8553
+interlocking/line.py,sha256=-lf2bx7w9XMgbXPoKYOGampEY2VtXB96JyX-qZq4e1E,2756
+interlocking/models.py,sha256=HESGIva7x6hfcZ7cZYrIVn7XY9VBWZ6_ehS95rtILiY,7847
+interlocking/station.py,sha256=MUPhTKlNc72kIJXcBQhaB-8a08l14iCuiQOXwAomVkM,17994
+interlocking-0.0.1.dist-info/licenses/LICENSE,sha256=IkU_8deAc2SO0UoX4mX_Op7eee_2Aqc68joPEIeywVs,1063
+interlocking-0.0.1.dist-info/WHEEL,sha256=si2p8vW03RnhyBnhWl4tj-ObJa78SpE-c9HsEtblGR0,80
+interlocking-0.0.1.dist-info/entry_points.txt,sha256=i2oN8Ae25gU-XoxtDndkB7we3AiSvh8-LPe0e6_tgrM,19
+interlocking-0.0.1.dist-info/METADATA,sha256=gYUG7lAmNo1CD7GYKZzkV-dDrFlhx3p15k9JEkzzfEo,2599
+interlocking-0.0.1.dist-info/RECORD,,

interlocking-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.5
+Root-Is-Purelib: true
+Tag: py3-none-any

interlocking-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+

interlocking-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alpine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.