magic-pocket 0.2.0__py3-none-any.whl

magic_pocket-0.2.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: magic-pocket
+Version: 0.2.0
+Summary: Deploy system for Django projects.
+Project-URL: Documentation, https://worgue.github.io/magic-pocket/
+Project-URL: Source, https://github.com/worgue/magic-pocket
+Author-email: Masaaki Yasui <yasu@worgue.com>
+License: The MIT License (MIT)
+        
+        Copyright (c) 2024 Masaaki Yasui
+        
+        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.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Requires-Dist: apig-wsgi>=2.18.0
+Requires-Dist: awslambdaric>=2.0.10
+Requires-Dist: boto3>=1.34.28
+Requires-Dist: django-storages!=1.14.3,>=1.14.2
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: pydantic>=2.5.3
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'
+Provides-Extra: django
+Requires-Dist: django>=4.2.0; extra == 'django'
+Provides-Extra: ses
+Requires-Dist: django-ses>=4.0.0; extra == 'ses'
+Provides-Extra: signing
+Requires-Dist: cryptography>=41.0.0; extra == 'signing'
+Description-Content-Type: text/markdown
+
+# Magic Pocket - Django Serverless Deployment
+
+ドキュメントはこちら
+https://worgue.github.io/magic-pocket/
+
+
+magic-pocket の目標は、サーバレスDjangoです。Djangoを以下の環境にデプロイします。
+
+- AWS Lambda
+- Neon Postgres
+- S3 storages
+
+## Motivation
+
+小規模な個人プロジェクトを、1人で複数同時に運用するため開発されたライブラリです。
+気軽に作り、飽きたら放っておく、というスタイルで運用するため、以下の要件が最終目標になっています。
+
+- サーバーの保守が不要
+- 使わない間のコストが不要
+- 環境を作る時にやる気を出す必要なし

magic_pocket-0.2.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+pocket/__init__.py,sha256=zpEJ9DGm23z9S8qj-ify9ENGAOv_o_bo9nfQyJCl9G4,64
+pocket/command_handler.py,sha256=rpwRQgLuMJuSZDzGdgIfdII-1JiVDx9ioANwGWcfmVs,6282
+pocket/context.py,sha256=2vtIPAnmdVNWiq8OrL_DUqvR-xEE5HyU_FL40Fs2pe4,39415
+pocket/general_context.py,sha256=jAUmn8uusRyh1OZZP5WUBjf1KXwhoxHfvGrIFovf8W0,4099
+pocket/general_settings.py,sha256=FKS5-j5X9bD_albdadRtWwHKnpGhcE-PFdE4qeiQgPQ,2296
+pocket/permissions.py,sha256=cny2JqZvdhpvV2XbJ-hD3EztiSTi3J7uoi4-cumQoaM,7698
+pocket/runtime.py,sha256=8F1WbQCxuOC11Ik0neQDiosw4gqVL-ITUJfgZ7MR9E8,10487
+pocket/settings.py,sha256=8ExOvJNkEj3VAw_VHLZARa5GJmJT5vw7-MivhTJgl7o,33262
+pocket/utils.py,sha256=8qD4qjJlzMNNFAAO7yCdGrEFT9BQuBZi92w2et5CuVM,4293
+pocket/django/__init__.py,sha256=nvNCBm-9BLVWmIUpmd_OETtWMFwQ7_fJZqE3PmLP_-4,177
+pocket/django/context.py,sha256=Mvw8EX7Hk-X8NaiJYqrVM1J0Rqq9jRIx7gakmyMkI6k,6021
+pocket/django/lambda_handlers.py,sha256=cXEzivSvxNXaxlAn6Qda6eWDNYE_1Dl0bMTlV60OJ9Y,3540
+pocket/django/runtime.py,sha256=TtBKiWKLyBnPMB0aJRjHO-tsbXkwYibWiZ-Ws1BMlQk,2176
+pocket/django/settings.py,sha256=LFe6t2MZuUzFmu-J8NeGQrqHsUIOlU8l4t7iyErye1w,2904
+pocket/django/spa_auth.py,sha256=5093-a8uWeBPtZT_Pdp8p9IOBJRL8Gwqnidx98uDWmk,5349
+pocket/django/storages.py,sha256=6nzoB25AJoI-O9ZLIq7vgBkD7vmK2KqDE62sQngFT-4,2854
+pocket/django/urls.py,sha256=XZG1HDB8jqwWj8kkmcTW0QPzUSQGmuVp11MugQkZy6U,1581
+pocket/django/utils.py,sha256=E6vm_LXH366xs2-B3xrz82xEX0j8Wk8518LF9T2JV68,12128
+pocket/django/db_backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pocket/django/db_backends/rds/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pocket/django/db_backends/rds/base.py,sha256=YxrA_OXKN32wKvGtRIbiFgPXjjZ0ud_YdXC50S4hcxI,939
+pocket/django/db_backends/rds/credentials.py,sha256=hyNwjrefaM5vbHLXXbtInnkkdhaq-OOLAj6_ZDnLQt4,3654
+pocket/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pocket/resources/base.py,sha256=xOwos3J8RQgVxIpWw9IVYL3QKHHCAAtX6XJujsgBc6c,117
+pocket/resources/aws/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pocket/resources/aws/secretsmanager.py,sha256=WgNg1o3fVdamgm8qbM_w-pJFigGBJhuWzYtqEMs66tA,3496
+pocket/resources/aws/ssm.py,sha256=ToxGnpJFiDev2h5p8Ce0eR13V8M4iCmEbxSMwYtUxGs,3771
+magic_pocket-0.2.0.dist-info/METADATA,sha256=tk1pY28S1ZlN7q50DFEBdKAL2wAtZkwC81-12gM5Ve4,2865
+magic_pocket-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+magic_pocket-0.2.0.dist-info/licenses/LICENSE,sha256=6sI-S9egZe33_sWOqLD7eyix1d7xlHn_oiB-3mlXrZw,1080
+magic_pocket-0.2.0.dist-info/RECORD,,

magic_pocket-0.2.0.dist-info/WHEEL

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

magic_pocket-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Masaaki Yasui
+
+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.

pocket/__init__.py

@@ -0,0 +1,3 @@
+"""Deploy system for Django projects."""
+
+__version__ = "0.1.1"

pocket/command_handler.py

@@ -0,0 +1,129 @@
+"""SQS イベント駆動の安全な command worker 基盤 ``BaseCommandHandler``.
+
+長時間 job (provisioning 等) を wsgi (request/response) Lambda の中で background
+thread + subprocess で動かすと、Lambda が **レスポンス返却後に execution
+environment を freeze** するため、thread からの最終ステータス書き込みが freeze 跨ぎで
+落ち、状態ストアが ``running`` のまま固着する。これを避けるため、job を「**SQS で
+起動する別 Lambda invocation の本体**」として完走させる。worker は thread ではなく
+invocation そのものなので freeze の影響を受けず、最後まで走り切って finalize できる。
+
+安全境界:
+
+- 実行ファイルは subclass の :meth:`BaseCommandHandler.build_argv` が固定し、argv は
+  **list** で **``shell=False``** で渡す。任意バイナリ / shell injection を不可にする
+  (= ``dangerous_shell_handler`` の安全な後継)。「何を実行させてよいか」の公開ポリシーは
+  enqueue する側 (認証済み API 等) が argv をどう組むかで決める。
+- 出力 / lifecycle の永続化は sink hook (:meth:`on_start` / :meth:`on_output` /
+  :meth:`on_finish` / :meth:`on_crash`) に委譲する。基底は永続化先を知らない。
+
+crash 時の挙動:
+
+- 予期せぬ crash (spawn 失敗 / spec 不正 / sink エラー / OOM / timeout 等) で UI が
+  永遠に running を読まないよう、:meth:`_run` は ``try/finally`` + ``done_ok`` フラグで
+  「正常完了でないまま抜けた」ときだけ :meth:`on_crash` を呼ぶ。``except`` で握りつぶさ
+  ないので、例外はそのまま伝播し CloudWatch traceback + DLQ に残る (AGENTS.md
+  「曖昧な例外キャッチ禁止」と整合)。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from abc import ABC, abstractmethod
+
+
+class BaseCommandHandler(ABC):
+    """SQS event を受け、argv を invocation 本体として完走させる worker 基盤.
+
+    subclass は最低限 :meth:`build_argv` を実装すればよい。ステータス / 出力を永続化
+    したい場合は sink hook (:meth:`on_start` / :meth:`on_output` / :meth:`on_finish` /
+    :meth:`on_crash`) を override する (既定は no-op)。
+
+    ``pocket.toml`` の ``[awscontainer.handlers.<key>]`` の ``command`` が、この
+    クラスのインスタンス (呼び出し可能) を dotted-path で指すように配線する。
+    """
+
+    #: 出力追記中の sink への書き込みを間引く throttle 間隔 (秒)。
+    #: 完了時 (:meth:`on_finish`) は throttle に関係なく確実に書く想定。
+    throttle: float = 1.0
+
+    def __call__(self, event, context):
+        """SQS event source の Lambda entrypoint.
+
+        バッチ内の各 record (= 1 job) を順に完走させる。例外は catch せず伝播させ、
+        SQS の redrive / DLQ に委ねる。
+        """
+        for record in event["Records"]:
+            self._run(json.loads(record["body"]))
+
+    def _run(self, spec: dict) -> None:
+        """1 job 分のコマンドを完走させ、進捗 / 結果を sink hook 経由で永続化する."""
+        self.on_start(spec)
+        done_ok = False
+        try:
+            argv = self.build_argv(spec)
+            # PYTHONUNBUFFERED=1: subprocess 側の stdout を即 flush させ、Pipe 経由の
+            # block buffering でエラー時にログが消える事故を避ける。
+            env = {**os.environ, "PYTHONUNBUFFERED": "1"}
+            proc = subprocess.Popen(
+                argv,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1,
+                env=env,
+            )
+            assert proc.stdout is not None
+
+            last_flush = 0.0
+            for line in proc.stdout:
+                now = time.time()
+                flush = now - last_flush >= self.throttle
+                self.on_output(spec, line.rstrip("\n"), flush=flush)
+                if flush:
+                    last_flush = now
+
+            proc.wait()
+            # 本体内 (= 同一 invocation) での最終 finalize なので freeze の影響を
+            # 受けず確実。
+            self.on_finish(spec, proc.returncode)
+            done_ok = True
+        finally:
+            if not done_ok:
+                # 例外が伝播中 (= worker crash)。UI が failed を読めるよう sink に
+                # 記録する。正常 finalize 後 (done_ok=True) はここを通らない。
+                self.on_crash(spec, sys.exc_info()[1])
+            # 例外は finally を抜けて自然に伝播 (= re-raise) → CloudWatch + DLQ。
+
+    @abstractmethod
+    def build_argv(self, spec: dict) -> list[str]:
+        """job spec を実行する argv (list[str]) に変換する.
+
+        安全境界はここ: 実行ファイルを自分の CLI に固定し、shell を介さず list で
+        渡す。``spec`` の中身 (どの引数を許すか) の検証も必要ならここで行う。
+        """
+        ...
+
+    # --- sink hooks ---
+    # 既定はいずれも stdout への print (= CloudWatch Logs に残る)。subclass が
+    # override してステータス / 出力を任意のストア (S3 snapshot 等) に永続化する。
+    # build_argv だけ実装した subclass でも、最低限ログは CloudWatch に出る。
+
+    def on_start(self, spec: dict) -> None:
+        """job 開始時 (subprocess 起動前)。running 状態の初期化に使う."""
+        print(f"start job: {spec}")
+
+    def on_output(self, spec: dict, line: str, *, flush: bool) -> None:
+        """出力 1 行ごと。``flush`` が True のとき永続化先へ書き出す想定."""
+        print(line)
+
+    def on_finish(self, spec: dict, exit_code: int) -> None:
+        """subprocess 完走時 (exit_code は 0 以外もあり得る = job の失敗)."""
+        print(f"finished: exit {exit_code}")
+
+    def on_crash(self, spec: dict, exc: BaseException | None) -> None:
+        """worker が正常完了せず抜けたとき (crash)。例外はこの後 re-raise される."""
+        print(f"crashed: {type(exc).__name__}: {exc}")