fufu-cloud-cli 0.5.0__py3-none-any.whl

fufu_cloud_cli/docker_backend.py

@@ -0,0 +1,578 @@
+"""只操作本機 Docker daemon；不呼叫任何雲端控制 API。"""
+
+import contextlib
+try:
+    import fcntl
+except ImportError:
+    fcntl = None
+import hashlib
+import ipaddress
+import json
+import os
+import platform
+import re
+import shutil
+import signal
+import socket
+import stat
+import subprocess
+import tempfile
+import time
+import uuid
+import zipfile
+from pathlib import Path, PurePosixPath
+from urllib import error, request
+
+from .errors import FufuError, require
+from .manifest import environment, name
+from .lambda_adapter import PROTOCOL
+
+PYTHON_IMAGE = "python:3.12-slim@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de"
+LAMBDA_IMAGES = {
+    "python3.12": "public.ecr.aws/lambda/python:3.12@sha256:c3692e82744acb2ceab8feb1fe6e9a4ee60b28beb4b3f7ea4e23b4d15a8ab710",
+    "python3.10": "public.ecr.aws/lambda/python:3.10@sha256:e74c50d8626878f0ca02bda970f671bd87dfdb530733b3f99fde7238d156390c",
+}
+FUNCTIONS_IMAGE = "fufu-cloud-cli-functions:local"
+INGRESS_IMAGE = "fufu-cloud-cli-ingress:local"
+LABEL = "io.fufu.cloud-cli"
+KINDS = {"cloud-run-http", "cloud-run-functions-http", "cloud-functions-gen1-http", "aws-lambda-sync"}
+MAX_PAYLOAD = 6 * 1024 * 1024
+
+
+def run(args, *, timeout=30, env=None, cwd=None, input_data=None, max_output=2 * 1024 * 1024):
+    """不經 shell；限制輸出量並停止逾時程序群組。錯誤不回顯設定與日誌。"""
+    child_env = {k: os.environ[k] for k in ("PATH", "LANG", "LC_ALL", "TMPDIR") if k in os.environ}
+    child_env.update(env or {})
+    with tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
+        try:
+            with subprocess.Popen(args, cwd=cwd, env=child_env, stdin=subprocess.PIPE,
+                                  stdout=out, stderr=err, start_new_session=True) as p:
+                try:
+                    p.communicate(input_data, timeout=timeout)
+                except subprocess.TimeoutExpired:
+                    os.killpg(p.pid, signal.SIGTERM)
+                    try:
+                        p.wait(timeout=3)
+                    except subprocess.TimeoutExpired:
+                        os.killpg(p.pid, signal.SIGKILL)
+                        p.wait(timeout=3)
+                    raise FufuError("OPERATION_TIMEOUT", "操作超過期限；未輸出原始日誌。")
+                require(p.returncode == 0, "DOCKER_OPERATION_FAILED", "Docker 操作失敗；請核對本機映像、來源及執行狀態。")
+                require(out.tell() <= max_output, "OUTPUT_LIMIT", "操作輸出超過限制。")
+                out.seek(0)
+                return out.read().decode("utf-8").strip()
+        except FileNotFoundError as exc:
+            raise FufuError("DEPENDENCY_MISSING", "需要本機 Docker CLI 與可用的 Docker daemon。") from exc
+
+
+def docker(*args, **kw):
+    # 固定本機 Unix socket，不繼承 Docker context、雲端 registry 認證或遠端主機設定。
+    with tempfile.TemporaryDirectory(prefix='fufu-docker-client-') as config:
+        return run(["docker", "--config", config, "--host", "unix:///var/run/docker.sock", *args], **kw)
+
+
+def object_json(text):
+    try:
+        return json.loads(text)
+    except (TypeError, ValueError) as exc:
+        raise FufuError("INVALID_DOCKER_RESPONSE", "Docker 回應無法解析。") from exc
+
+
+def inspect_image(image):
+    require(isinstance(image, str) and image and len(image) <= 256 and not image.startswith("-"),
+            "INVALID_IMAGE", "必須指定本機映像。")
+    # 只保留相容性檢查必要欄位，避免讀出映像內環境變數。
+    data = object_json(docker("image", "inspect", image, "--format",
+                             '{"id":{{json .Id}},"arch":{{json .Architecture}},"os":{{json .Os}}}'))
+    expected = {"x86_64": "amd64", "aarch64": "arm64"}.get(platform.machine())
+    require(data["os"] == "linux" and data["arch"] == expected,
+            "ARCHITECTURE_MISMATCH", "本機 daemon 與映像必須使用相同的 Linux CPU 架構。")
+    return data["id"]
+
+
+def read_container(container_id):
+    require(isinstance(container_id, str) and re.fullmatch(r"[a-f0-9]{64}", container_id),
+            "INVALID_STATE", "本機狀態中的容器識別格式不符。")
+    return object_json(docker("container", "inspect", container_id, "--format",
+        '{"labels":{{json .Config.Labels}},"running":{{json .State.Running}},'
+        '"ports":{{json .NetworkSettings.Ports}},"networks":{{json .NetworkSettings.Networks}}}'))
+
+
+def available_subnet(seed):
+    """避開既有 Docker 與主機路由，不改共用 daemon 的 address pool。"""
+    require(shutil.which("ip") is not None, "DEPENDENCY_MISSING", "需要 Linux iproute2 以檢查本機網路衝突。")
+    occupied = []
+    ids = docker("network", "ls", "--quiet").splitlines()
+    require(len(ids) <= 512, "NETWORK_LIMIT", "主機網路數量超過本機預檢限制。")
+    if ids:
+        configs = docker("network", "inspect", *ids, "--format", "{{json .IPAM.Config}}")
+        for line in configs.splitlines():
+            for entry in object_json(line) or []:
+                if entry.get("Subnet"):
+                    occupied.append(ipaddress.ip_network(entry["Subnet"]))
+    routes = object_json(run(["ip", "-j", "-4", "route", "show", "table", "all"], timeout=15))
+    for entry in routes:
+        dst = entry.get("dst")
+        if dst and dst != "default":
+            network = ipaddress.ip_network(dst, strict=False)
+            if network.prefixlen:
+                occupied.append(network)
+    pool = list(ipaddress.ip_network("10.240.0.0/12").subnets(new_prefix=24))
+    start = int(hashlib.sha256(seed.encode()).hexdigest()[:8], 16) % len(pool)
+    for offset in range(len(pool)):
+        candidate = pool[(start + offset) % len(pool)]
+        if not any(candidate.overlaps(n) for n in occupied if n.version == 4):
+            return str(candidate)
+    raise FufuError("NETWORK_POOL_UNAVAILABLE", "沒有可避開既有網路與路由的 FUFU 子網路；未變更 daemon 設定。")
+
+
+class Backend:
+    def __init__(self, *, workspace=None, state_dir=None):
+        require(fcntl is not None and platform.system() == "Linux", "UNSUPPORTED_PLATFORM",
+                "本機 Docker backend 需要 Linux；其他平台請使用 FUFU API backend。")
+        require(os.environ.get("FUFU_BACKEND", "local-docker") in {"docker", "local-docker"}, "UNSUPPORTED_BACKEND",
+                "此部署核心需要 local-docker 模式；API 模式不會轉為本機部署。")
+        self.workspace = name(workspace or os.environ.get("FUFU_WORKSPACE", "fufu"))
+        self.root = Path(state_dir or os.environ.get("FUFU_STATE_DIR", str(Path.home() / ".local/state/fufu-cloud-cli"))).expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self.path = self.root / self.workspace
+        require(not self.path.is_symlink(), "INVALID_STATE", "Workspace 不接受符號連結。")
+        self.path.mkdir(mode=0o700, exist_ok=True)
+        self.scope = hashlib.sha256(f"{self.root}:{os.getuid()}:{self.workspace}".encode()).hexdigest()[:16]
+        self.network = f"fufu-cli-{self.scope}"
+        self.ingress_network = f"{self.network}-ingress"
+        self.state_file = self.path / "state.json"
+
+    @contextlib.contextmanager
+    def locked(self):
+        fd = os.open(self.path / "state.lock", os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+        with os.fdopen(fd, "a") as lock:
+            deadline = time.monotonic() + 5
+            while True:
+                try:
+                    fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except BlockingIOError:
+                    require(time.monotonic() < deadline, "WORKSPACE_BUSY", "同 workspace 正在操作；鎖等待已到期。")
+                    time.sleep(0.05)
+            try:
+                yield
+            finally:
+                fcntl.flock(lock, fcntl.LOCK_UN)
+
+    def read_state(self):
+        if not self.state_file.exists():
+            return {"schema": 1, "services": {}}
+        try:
+            require(not self.state_file.is_symlink() and self.state_file.stat().st_size <= 1048576,
+                    "INVALID_STATE", "本機狀態檔格式不符。")
+            data = json.loads(self.state_file.read_text())
+            require(data.get("schema") == 1 and isinstance(data.get("services"), dict),
+                    "INVALID_STATE", "本機狀態 schema 不符；不會覆写原檔。")
+            for key, r in data["services"].items():
+                require(isinstance(r, dict) and r.get("kind") in KINDS and key == f"{r['kind']}:{name(r.get('name'))}",
+                        "INVALID_STATE", "本機服務狀態不符。")
+                require(re.fullmatch(r"[a-f0-9]{64}", r.get("container_id", "")), "INVALID_STATE", "容器狀態不符。")
+                require(re.fullmatch(r"[a-f0-9]{64}", r.get("ingress_id", "")), "INVALID_STATE", "Ingress 狀態不符。")
+            return data
+        except FufuError:
+            raise
+        except Exception as exc:
+            raise FufuError("INVALID_STATE", "本機狀態損毀；不會覆寫或重新建立既有狀態。") from exc
+
+    def save_state(self, data):
+        if self.state_file.exists():
+            shutil.copy2(self.state_file, self.path / f"state.{time.time_ns()}.bak")
+        fd, p = tempfile.mkstemp(dir=self.path, prefix="state-", suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w") as f:
+                json.dump(data, f, sort_keys=True)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(p, self.state_file)
+        finally:
+            if os.path.exists(p):
+                os.unlink(p)
+
+    def owned(self, container_id):
+        d = read_container(container_id)
+        require(d["labels"].get(LABEL) == "local" and d["labels"].get(f"{LABEL}.scope") == self.scope,
+                "OWNERSHIP_MISMATCH", "資源不屬於這個 workspace；拒絕操作。")
+        return d
+
+    def ensure_network(self, runtime_network=None):
+        for network, internal in ((runtime_network or self.network, True), (self.ingress_network, False)):
+            ids = docker("network", "ls", "--filter", f"name=^{network}$", "--format", "{{.ID}}").splitlines()
+            if ids:
+                d = object_json(docker("network", "inspect", network, "--format",
+                    '{"internal":{{json .Internal}},"labels":{{json .Labels}}}'))
+                require(d["internal"] == internal and (d["labels"] or {}).get(f"{LABEL}.scope") == self.scope,
+                        "NETWORK_MISMATCH", "同名網路不屬於此 workspace 或隔離設定不符。")
+            else:
+                flags = ["--internal"] if internal else []
+                subnet = available_subnet(self.scope + network)
+                docker("network", "create", *flags, "--subnet", subnet, "--label", f"{LABEL}=local",
+                       "--label", f"{LABEL}.scope={self.scope}", network)
+
+    def url(self, record):
+        network = record.get('network', self.network)
+        require(network == self.network or re.fullmatch(re.escape(self.network) + r'-[a-f0-9]{8}', network), 'NETWORK_MISMATCH', 'Workload network 不屬於此 workspace。')
+        d = self.owned(record["container_id"])
+        require(d["running"], "SERVICE_NOT_RUNNING", "容器未執行。")
+        require(set(d["networks"]) == {network}, "NETWORK_MISMATCH", "容器網路與隔離契約不符。")
+        require(not any(d["ports"].values()), "PORT_MISMATCH", "應用容器不能直接發布 port。")
+        ingress = self.owned(record["ingress_id"])
+        require(ingress["running"] and set(ingress["networks"]) == {network, self.ingress_network},
+                "NETWORK_MISMATCH", "Ingress 執行狀態或網路不符。")
+        ports = ingress["ports"].get("8080/tcp") or []
+        require(len(ports) == 1 and ports[0]["HostIp"] == "127.0.0.1", "PORT_MISMATCH", "服務必須只綁定 loopback。")
+        return f"http://127.0.0.1:{int(ports[0]['HostPort'])}"
+
+    def public(self, r):
+        return {"name": r["name"], "kind": r["kind"], "workspace": self.workspace,
+                "revision": r["revision"], "url": self.url(r), "readiness": "tcp",
+                **{k: r[k] for k in ("runtime", "handler", "role", "sdkTransport", "iamEnforced") if k in r},
+                "status": "running", "backend": "local-docker"}
+
+    def deploy(self, *, kind, service, image, port=8080, env=None, command=None,
+               startup_timeout=30, replace=True, require_existing=False, runtime=None, handler=None, preserve_environment=False,
+               runtime_env=None, role=None, gateway_container=None):
+        name(service)
+        require(kind in KINDS, "UNSUPPORTED_SERVICE", "未支援此服務。")
+        require(type(port) is int and 1024 <= port <= 65535, "INVALID_PORT", "無效的容器 port。")
+        require(1 <= startup_timeout <= 120, "INVALID_TIMEOUT", "啟動期限須介於 1–120 秒。")
+        env = environment(dict(env or {}))
+        require(not role or (runtime_env and gateway_container), 'IAM_BACKEND_REQUIRED', 'IAM workload role 需要已配置的遠端 gateway；本機 Docker 模式不假裝執行 IAM。')
+        image_id = inspect_image(image)
+        ingress_image_id = inspect_image(INGRESS_IMAGE)
+        key = f"{kind}:{service}"
+        with self.locked():
+            state = self.read_state()
+            old = state["services"].get(key)
+            require(replace or old is None, "ALREADY_EXISTS", "同名服務已存在；create-function 不會覆寫。")
+            require(not require_existing or old is not None, "NOT_FOUND", "更新目標不存在；未建立新服務。")
+            if old:
+                self.owned(old["container_id"])
+                self.owned(old["ingress_id"])
+            if preserve_environment:
+                require(old is not None and 'environment_names' in old, 'UNSUPPORTED_CONFIG', '原部署缺少環境欄位資訊；拒絕可能改變設定的程式碼更新。')
+                original = object_json(docker('container', 'inspect', old['container_id'], '--format', '{{json .Config.Env}}'))
+                original_env = dict(item.split('=', 1) for item in original if '=' in item)
+                env = environment({k: original_env[k] for k in old['environment_names']})
+            network = self.network + '-' + uuid.uuid4().hex[:8] if runtime_env else self.network
+            self.ensure_network(network)
+            gateway = None
+            if runtime_env:
+                require(gateway_container is not None, 'GATEWAY_UNAVAILABLE', 'Workload gateway 尚未配置。')
+                gateway = object_json(docker('container', 'inspect', gateway_container, '--format',
+                    '{"id":{{json .Id}},"labels":{{json .Config.Labels}},"networks":{{json .NetworkSettings.Networks}},"running":{{json .State.Running}}}'))
+                require(gateway['running'] and gateway['labels'].get('com.docker.compose.service') == 'local-cloud-console',
+                        'GATEWAY_UNAVAILABLE', '指定 gateway 必須是正在執行的 FUFU Console。')
+                if network not in gateway['networks']:
+                    docker('network', 'connect', '--alias', 'fufu-api', network, gateway['id'])
+            revision = f"{service}-{uuid.uuid4().hex[:8]}"
+            cname = f"fufu-cli-{self.scope}-{uuid.uuid4().hex[:12]}"
+            supplied = dict(env)
+            supplied.update(runtime_env or {})
+            supplied["AWS_EC2_METADATA_DISABLED"] = "true"
+            if kind == "aws-lambda-sync":
+                supplied.update(AWS_LAMBDA_FUNCTION_NAME=service, AWS_REGION=(runtime_env or {}).get('AWS_REGION', 'us-east-1'),
+                                AWS_DEFAULT_REGION=(runtime_env or {}).get('AWS_REGION', 'us-east-1'))
+            else:
+                supplied.update(PORT=str(port), K_SERVICE=service, K_REVISION=revision, K_CONFIGURATION=service)
+            args = ["run", "--detach", "--pull=never", "--name", cname,
+                    "--label", f"{LABEL}=local", "--label", f"{LABEL}.scope={self.scope}",
+                    "--network", network,
+                    "--user", "10001:10001", "--read-only", "--tmpfs", "/tmp:rw,nosuid,nodev,size=64m",
+                    "--cap-drop", "ALL", "--security-opt", "no-new-privileges:true",
+                    "--pids-limit", "128", "--memory", "512m", "--cpus", "1",
+                    "--log-opt", "max-size=5m", "--log-opt", "max-file=1"]
+            for k in sorted(supplied):
+                args.extend(["--env", k])
+            args.append(image_id)
+            args.extend(command or [])
+            candidate = None
+            ingress_candidate = None
+            committed = False
+            try:
+                # 環境值經子程序環境注入，不出現在命令列、狀態或部署輸出。
+                candidate = docker(*args, env=supplied)
+                record = {"name": service, "kind": kind, "container_id": candidate,
+                          "port": port, "revision": revision,
+                          **({'network': network, 'gateway_id': gateway['id']} if gateway else {}),
+                          **({'role': role, 'sdkTransport': 'fufu-workload-token', 'iamEnforced': True} if role else {}),
+                          **({"environment_names": sorted(env)} if kind != 'cloud-run-http' else {}),
+                          **({"runtime": runtime, "handler": handler} if runtime is not None else {})}
+                deadline = time.monotonic() + startup_timeout
+                while True:
+                    detail = self.owned(candidate)
+                    require(detail["running"], "SERVICE_NOT_RUNNING", "容器未執行；原部署保留。")
+                    require(set(detail["networks"]) == {network}, "NETWORK_MISMATCH", "應用容器網路不符。")
+                    address = detail["networks"][network]["IPAddress"]
+                    require(ipaddress.ip_address(address).is_private, "NETWORK_MISMATCH", "容器必須位於本機 private network。")
+                    try:
+                        # Docker published port 的 proxy 可能先開始監聽；直接查容器 port。
+                        with socket.create_connection((address, port), timeout=0.5):
+                            break
+                    except OSError:
+                        require(time.monotonic() < deadline, "STARTUP_TIMEOUT", "容器未在期限內監聽；原部署保留。")
+                        time.sleep(0.1)
+                # 新版 Docker 不替 internal-only 網路發布 port；固定 upstream 的 ingress
+                # 橋接 loopback 與 internal network，應用本身始終沒有外部路由。
+                ingress_candidate = docker("create", "--pull=never", "--name", cname + "-ingress",
+                    "--label", f"{LABEL}=local", "--label", f"{LABEL}.scope={self.scope}",
+                    "--network", self.ingress_network, "--publish", "127.0.0.1::8080",
+                    "--user", "10001:10001", "--read-only", "--cap-drop", "ALL",
+                    "--security-opt", "no-new-privileges:true", "--pids-limit", "64", "--memory", "64m", "--cpus", "0.25",
+                    "--log-opt", "max-size=1m", "--log-opt", "max-file=1",
+                    "--env", "FUFU_UPSTREAM_HOST", "--env", "FUFU_UPSTREAM_PORT", ingress_image_id,
+                    env={"FUFU_UPSTREAM_HOST": cname, "FUFU_UPSTREAM_PORT": str(port)})
+                docker("network", "connect", network, ingress_candidate)
+                docker("start", ingress_candidate)
+                record["ingress_id"] = ingress_candidate
+                deadline = time.monotonic() + startup_timeout
+                while True:
+                    ingress = self.owned(ingress_candidate)
+                    require(ingress["running"], "SERVICE_NOT_RUNNING", "Ingress 未執行。")
+                    address = ingress["networks"][self.ingress_network]["IPAddress"]
+                    try:
+                        with socket.create_connection((address, 8080), timeout=0.5):
+                            break
+                    except OSError:
+                        require(time.monotonic() < deadline, "STARTUP_TIMEOUT", "Ingress 未在期限內就緒。")
+                        time.sleep(0.1)
+                result = self.public(record)
+                state["services"][key] = record
+                self.save_state(state)
+                committed = True
+                if old:
+                    try:
+                        self.owned(old["container_id"])
+                        self.owned(old["ingress_id"])
+                        docker("container", "rm", "--force", old["ingress_id"], old["container_id"])
+                        self.cleanup_workload_network(old)
+                    except FufuError:
+                        result["warning"] = "新部署已就緒；舊容器待 fufu down 回收。"
+                return result
+            finally:
+                if candidate is None and not committed:
+                    candidates = docker("container", "ls", "--all", "--quiet", "--no-trunc",
+                                        "--filter", f"name=^{cname}$", "--filter", f"label={LABEL}.scope={self.scope}").splitlines()
+                    if len(candidates) == 1:
+                        candidate = candidates[0]
+                if candidate and not committed:
+                    if ingress_candidate:
+                        self.owned(ingress_candidate)
+                        docker("container", "rm", "--force", ingress_candidate)
+                    self.owned(candidate)
+                    docker("container", "rm", "--force", candidate)
+                    if gateway: self.cleanup_workload_network({'network': network, 'gateway_id': gateway['id']})
+
+    def cleanup_workload_network(self, record):
+        network = record.get('network')
+        if not network: return
+        require(re.fullmatch(re.escape(self.network) + r'-[a-f0-9]{8}', network), 'NETWORK_MISMATCH', 'Workload network 不符。')
+        info = object_json(docker('network', 'inspect', network, '--format', '{"labels":{{json .Labels}},"containers":{{json .Containers}}}'))
+        require(info['labels'].get(f'{LABEL}.scope') == self.scope, 'OWNERSHIP_MISMATCH', 'Workload network 不符。')
+        require(set(info['containers']).issubset({record['gateway_id']}), 'NETWORK_BUSY', 'Workload network 仍有其他資源，未清除。')
+        if record['gateway_id'] in info['containers']:
+            docker('network', 'disconnect', network, record['gateway_id'])
+        docker('network', 'rm', network)
+
+    def describe(self, kind, service):
+        name(service)
+        with self.locked():
+            r = self.read_state()["services"].get(f"{kind}:{service}")
+            require(r is not None, "NOT_FOUND", "此 workspace 沒有該服務。")
+            return self.public(r)
+
+    def listing(self, kind=None):
+        with self.locked():
+            return [self.public(r) for r in self.read_state()["services"].values() if kind is None or r["kind"] == kind]
+
+    def delete(self, kind, service):
+        name(service)
+        with self.locked():
+            state = self.read_state()
+            key = f"{kind}:{service}"
+            r = state["services"].get(key)
+            require(r is not None, "NOT_FOUND", "此 workspace 沒有該服務。")
+            self.owned(r["container_id"])
+            self.owned(r["ingress_id"])
+            docker("container", "rm", "--force", r["ingress_id"], r["container_id"])
+            del state["services"][key]
+            self.save_state(state)
+            self.cleanup_workload_network(r)
+            return {"deleted": service, "kind": kind}
+
+    def down(self):
+        with self.locked():
+            self.read_state()  # 損毀狀態不得觸發自動清除。
+            ids = docker("container", "ls", "--all", "--quiet", "--no-trunc", "--filter",
+                         f"label={LABEL}=local", "--filter", f"label={LABEL}.scope={self.scope}").splitlines()
+            for cid in ids:
+                self.owned(cid)
+                docker("container", "rm", "--force", cid)
+            self.save_state({"schema": 1, "services": {}})
+            for network in (self.ingress_network, self.network):
+                networks = docker("network", "ls", "--filter", f"name=^{network}$", "--format", "{{.ID}}").splitlines()
+                if networks:
+                    d = object_json(docker("network", "inspect", network, "--format", "{{json .Labels}}"))
+                    require(d.get(f"{LABEL}.scope") == self.scope, "OWNERSHIP_MISMATCH", "網路不屬於此 workspace。")
+                    docker("network", "rm", network)
+            return {"workspace": self.workspace, "removed_containers": len(ids)}
+
+    def invoke(self, kind, service, payload, *, path="/", timeout=15):
+        require(1 <= timeout <= 120, "INVALID_TIMEOUT", "請求期限須介於 1–120 秒。")
+        require(len(payload) <= MAX_PAYLOAD, "PAYLOAD_LIMIT", "Payload 超過 6 MiB。")
+        require(isinstance(path, str) and path.startswith("/") and not path.startswith("//")
+                and "\r" not in path and "\n" not in path, "INVALID_PATH", "只能使用本機服務相對路徑。")
+        data = self.describe(kind, service)
+        route = "/2015-03-31/functions/function/invocations" if kind == "aws-lambda-sync" else path
+
+        class NoRedirect(request.HTTPRedirectHandler):
+            def redirect_request(self, *args, **kw):
+                return None
+
+        opener = request.build_opener(request.ProxyHandler({}), NoRedirect())
+        req = request.Request(data["url"] + route, data=payload, headers={"Content-Type": "application/json"})
+        try:
+            try:
+                response = opener.open(req, timeout=timeout)
+            except error.HTTPError as e:
+                response = e
+            with response:
+                body = response.read(MAX_PAYLOAD + 1)
+                require(len(body) <= MAX_PAYLOAD, "RESPONSE_LIMIT", "服務回應超過 6 MiB。")
+                function_error = response.headers.get("X-Amz-Function-Error") or response.headers.get("Lambda-Runtime-Function-Error-Type")
+                status = response.status
+        except (TimeoutError, OSError, error.URLError) as exc:
+            # 客戶端逾時不宣稱已終止 handler，RIE 與正式 Lambda 的執行管理不同。
+            raise FufuError("INVOKE_TRANSPORT_FAILED", "本機請求失敗或逾時；handler 可能仍在執行。") from exc
+        if kind == "aws-lambda-sync" and status == 200:
+            try:
+                envelope = json.loads(body)
+                require(isinstance(envelope, dict) and envelope.get("protocol") == PROTOCOL
+                        and set(envelope) == {"protocol", "result", "error"},
+                        "LAMBDA_RUNTIME_FAILED", "Lambda runtime 未完成可驗證的 handler 執行；不會當作成功。")
+                failed = envelope["error"] is not None
+                if failed:
+                    require(isinstance(envelope["error"], dict) and "errorType" in envelope["error"],
+                            "LAMBDA_RUNTIME_FAILED", "Lambda runtime 錯誤格式不符。")
+                body = json.dumps(envelope["error"] if failed else envelope["result"], ensure_ascii=False).encode()
+                function_error = "Unhandled" if failed else None
+            except (ValueError, UnicodeDecodeError) as exc:
+                raise FufuError("LAMBDA_RUNTIME_FAILED", "Lambda runtime 回應無法解析。") from exc
+        return status, body, function_error
+
+
+def build_image(context, tag, *, network="none"):
+    require(shutil.disk_usage(context).free >= 2 * 1024**3, "DISK_SPACE", "建置前至少需要 2 GiB 可用空間。")
+    docker("build", "--quiet", "--pull=false", "--network", network, "--tag", tag, str(context), timeout=300)
+    return inspect_image(tag)
+
+
+def prepare_runtime(runtimes=("python3.12",)):
+    require(all(r in LAMBDA_IMAGES for r in runtimes), "UNSUPPORTED_RUNTIME", "不支援的 Lambda runtime。")
+    for image in (PYTHON_IMAGE, *(LAMBDA_IMAGES[r] for r in runtimes)):
+        try:
+            inspect_image(image)
+        except FufuError as exc:
+            if exc.code != "DOCKER_OPERATION_FAILED":
+                raise
+            docker("pull", image, timeout=240)
+            inspect_image(image)
+    runtime_dir = Path(__file__).with_name("runtime")
+    build_image(runtime_dir / "functions", FUNCTIONS_IMAGE, network="default")
+    build_image(runtime_dir / "ingress", INGRESS_IMAGE)
+    return {"prepared": ["functions-python312", "ingress", *runtimes], "backend": "local-docker"}
+
+
+def build_function(source, target, *, network="default"):
+    require(re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", target or ""), "INVALID_HANDLER", "入口必須是有效 Python 函式名稱。")
+    src = Path(source).resolve()
+    require(src.is_dir() and (src / "main.py").is_file(), "INVALID_SOURCE", "Python function 來源需包含 main.py。")
+    inspect_image(FUNCTIONS_IMAGE)
+    base = FUNCTIONS_IMAGE
+    with tempfile.TemporaryDirectory(prefix="fufu-function-") as tmp:
+        dst = Path(tmp)
+        files = [p for p in src.rglob("*") if p.is_file() and (p.suffix == ".py" or p.name == "requirements.txt")
+                 and not any(part.startswith(".") or part in {"__pycache__", "node_modules"} for part in p.relative_to(src).parts)]
+        require(len(files) <= 1000 and sum(p.stat().st_size for p in files) <= 32 * 1024**2,
+                "SOURCE_LIMIT", "Python 來源超過檔案數或大小限制。")
+        for p in files:
+            require(not p.is_symlink() and p.resolve().is_relative_to(src), "INVALID_SOURCE", "來源不接受符號連結。")
+            q = dst / "app" / p.relative_to(src)
+            q.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(p, q)
+            q.chmod(0o644)
+        sdk = dst / 'app/_fufu_runtime_sdk.py'
+        require(not sdk.exists(), 'RESERVED_FILE', '來源與 FUFU SDK 的保留檔名衝突。')
+        shutil.copyfile(Path(__file__).with_name('runtime_sdk.py'), sdk)
+        sdk.chmod(0o644)
+        requirements = dst / "app/requirements.txt"
+        if not requirements.exists():
+            requirements.write_text("")
+        # 原始 requirements 可安裝應用相依；build 有網路，runtime 不開放 egress。
+        dockerfile = (f"FROM {base}\nUSER 0\nCOPY app/requirements.txt /tmp/requirements.txt\n"
+                      "RUN python -m pip install --index-url https://pypi.org/simple --disable-pip-version-check --no-cache-dir --retries 1 --timeout 20 -r /tmp/requirements.txt\n"
+                      "COPY --chown=10001:10001 app/ /app/\nWORKDIR /app\nUSER 10001:10001\n"
+                      + "CMD " + json.dumps(["functions-framework", "--target", target, "--signature-type", "http",
+                                             "--host", "0.0.0.0", "--port", "8080"]) + "\n")
+        (dst / "Dockerfile").write_text(dockerfile)
+        return build_image(dst, f"fufu-cli-function:{uuid.uuid4().hex}", network=network)
+
+
+def extract_zip(archive, destination):
+    require(archive.is_file() and archive.stat().st_size <= 50 * 1024**2, "INVALID_ZIP", "ZIP 必須存在且不超過 50 MiB。")
+    try:
+        with zipfile.ZipFile(archive) as z:
+            info = z.infolist()
+            require(len(info) <= 10000 and sum(i.file_size for i in info) <= 250 * 1024**2,
+                    "ZIP_LIMIT", "ZIP 解壓縮超過檔案數或大小上限。")
+            seen = set()
+            for i in info:
+                p = PurePosixPath(i.filename)
+                mode = i.external_attr >> 16
+                require(i.filename and "\\" not in i.filename and not p.is_absolute() and ".." not in p.parts
+                        and not stat.S_ISLNK(mode) and not i.flag_bits & 1 and str(p) not in seen,
+                        "INVALID_ZIP", "ZIP 含路徑穿越、符號連結、加密或重複檔案。")
+                seen.add(str(p))
+            for i in info:
+                dst = destination / i.filename
+                require(dst.resolve().is_relative_to(destination.resolve()), "INVALID_ZIP", "ZIP 路徑超出目的地。")
+                if i.is_dir():
+                    dst.mkdir(parents=True, exist_ok=True)
+                else:
+                    dst.parent.mkdir(parents=True, exist_ok=True)
+                    with z.open(i) as src, dst.open("wb") as out:
+                        shutil.copyfileobj(src, out)
+                    dst.chmod(0o755 if (i.external_attr >> 16) & 0o111 else 0o644)
+    except FufuError:
+        raise
+    except Exception as exc:
+        raise FufuError("INVALID_ZIP", "ZIP 無法安全解壓縮。") from exc
+
+
+def build_lambda(archive, runtime, handler):
+    require(runtime in LAMBDA_IMAGES, "UNSUPPORTED_RUNTIME", "目前只支援 Python 3.10 與 3.12 Lambda ZIP。")
+    require(re.fullmatch(r"[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)+", handler or ""), "INVALID_HANDLER", "Lambda handler 格式應為 module.function。")
+    base = LAMBDA_IMAGES[runtime]
+    inspect_image(base)
+    with tempfile.TemporaryDirectory(prefix="fufu-lambda-") as tmp:
+        dst = Path(tmp)
+        app = dst / "app"
+        app.mkdir()
+        extract_zip(Path(archive), app)
+        module = app / (handler.rsplit(".", 1)[0].replace(".", "/") + ".py")
+        require(module.is_file(), "INVALID_HANDLER", "ZIP 缺少指定 handler 模組。")
+        adapter = app / "_fufu_runtime_adapter.py"
+        require(not adapter.exists(), "RESERVED_FILE", "ZIP 與 FUFU runtime adapter 的保留檔名衝突。")
+        shutil.copyfile(Path(__file__).with_name("lambda_adapter.py"), adapter)
+        adapter.chmod(0o644)
+        sdk = app / '_fufu_runtime_sdk.py'
+        require(not sdk.exists(), 'RESERVED_FILE', 'ZIP 與 FUFU SDK 的保留檔名衝突。')
+        shutil.copyfile(Path(__file__).with_name('runtime_sdk.py'), sdk)
+        sdk.chmod(0o644)
+        (dst / "Dockerfile").write_text(f"FROM {base}\nENV FUFU_HANDLER={handler}\nCOPY --chown=10001:10001 app/ ${{LAMBDA_TASK_ROOT}}/\nCMD " + json.dumps(["_fufu_runtime_adapter.handler"]) + "\n")
+        return build_image(dst, f"fufu-cli-lambda:{uuid.uuid4().hex}")

fufu_cloud_cli/errors.py

@@ -0,0 +1,11 @@
+class FufuError(Exception):
+    def __init__(self, code: str, message: str, exit_code: int = 1):
+        self.code = code
+        self.message = message
+        self.exit_code = exit_code
+        super().__init__(message)
+
+
+def require(condition, code, message):
+    if not condition:
+        raise FufuError(code, message)

fufu_cloud_cli/lambda_adapter.py

@@ -0,0 +1,30 @@
+"""將原 handler 的成功與例外明確編碼；不以業務 payload 欄位猜測失敗。"""
+
+import importlib
+import json
+import os
+import traceback
+
+PROTOCOL = "fufu.lambda-envelope.v1"
+
+
+def handler(event, context):
+    error_type = None
+    try:
+        if os.environ.get('FUFU_RUNTIME_ENDPOINT'):
+            from _fufu_runtime_sdk import install
+            install()
+        module, function = os.environ["FUFU_HANDLER"].rsplit(".", 1)
+        original = getattr(importlib.import_module(module), function)
+        value = original(event, context)
+        try:
+            json.dumps(value, allow_nan=False)
+        except (ValueError, TypeError):
+            error_type = "Runtime.MarshalError"
+            raise
+        return {"protocol": PROTOCOL, "result": value, "error": None}
+    except Exception as exc:
+        failure = {"errorMessage": str(exc), "errorType": error_type or type(exc).__name__,
+                   "requestId": context.aws_request_id,
+                   "stackTrace": traceback.format_list(traceback.extract_tb(exc.__traceback__))}
+        return {"protocol": PROTOCOL, "result": None, "error": failure}