arga-clone 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- arga_clone-0.2.0.dist-info/METADATA +2570 -0
- arga_clone-0.2.0.dist-info/RECORD +32 -0
- arga_clone-0.2.0.dist-info/WHEEL +5 -0
- arga_clone-0.2.0.dist-info/entry_points.txt +2 -0
- arga_clone-0.2.0.dist-info/licenses/LICENSE +21 -0
- arga_clone-0.2.0.dist-info/top_level.txt +1 -0
- argaclone/__init__.py +13 -0
- argaclone/chaos.py +280 -0
- argaclone/cli.py +229 -0
- argaclone/client.py +227 -0
- argaclone/gateway.py +323 -0
- argaclone/graders.py +244 -0
- argaclone/mcp_server.py +237 -0
- argaclone/runner.py +383 -0
- argaclone/scenarios.py +443 -0
- argaclone/server.py +557 -0
- argaclone/store.py +461 -0
- argaclone/twin_spec.py +384 -0
- argaclone/twins/__init__.py +15 -0
- argaclone/twins/base.py +436 -0
- argaclone/twins/calendar_twin.py +331 -0
- argaclone/twins/drive_twin.py +334 -0
- argaclone/twins/github_twin.py +2086 -0
- argaclone/twins/gmail_twin.py +413 -0
- argaclone/twins/hubspot_twin.py +212 -0
- argaclone/twins/jira_twin.py +265 -0
- argaclone/twins/linear_twin.py +480 -0
- argaclone/twins/notion_twin.py +415 -0
- argaclone/twins/salesforce_twin.py +456 -0
- argaclone/twins/slack_twin.py +573 -0
- argaclone/twins/stripe_twin.py +1013 -0
- argaclone/webhooks.py +209 -0
argaclone/client.py
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
"""Python SDK:一行接进来,不用记 admin 路由。
|
|
2
|
+
|
|
3
|
+
设计原则:**SDK 只做 HTTP,不在本地替服务端算任何东西**。
|
|
4
|
+
一旦 SDK 开始"帮你想",客户端看到的状态就可能与服务端不一致,
|
|
5
|
+
而这套东西的整个卖点是"状态可信、可复现"。
|
|
6
|
+
|
|
7
|
+
用法:
|
|
8
|
+
from argaclone.client import Client
|
|
9
|
+
|
|
10
|
+
with Client() as c: # 默认 http://127.0.0.1:8787
|
|
11
|
+
run = c.provision(["stripe", "slack"], ttl=600,
|
|
12
|
+
scenario="ecom-duplicate-billing")
|
|
13
|
+
print(run.credentials["stripe"]) # sk_test_twin_xxx
|
|
14
|
+
run.act([{"provider": "stripe", "method": "POST",
|
|
15
|
+
"path": "/v1/customers/cus_DUP_EXTRA",
|
|
16
|
+
"body": {"metadata": {"merged_into": "cus_DUP_KEEP"}}}])
|
|
17
|
+
print(run.grade()["verdict"])
|
|
18
|
+
|
|
19
|
+
零依赖(只用标准库):这套东西要能在 CI 容器里 `pip install -e .` 之前就跑起来。
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import json
|
|
25
|
+
import os
|
|
26
|
+
import urllib.error
|
|
27
|
+
import urllib.request
|
|
28
|
+
from typing import Any
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class ArgacloneError(RuntimeError):
|
|
32
|
+
"""服务端返回了非 2xx。带上状态码与 body,别只留一句 'request failed'。"""
|
|
33
|
+
|
|
34
|
+
def __init__(self, status: int, body: Any, path: str) -> None:
|
|
35
|
+
self.status = status
|
|
36
|
+
self.body = body
|
|
37
|
+
self.path = path
|
|
38
|
+
super().__init__(f"{path} -> HTTP {status}: {body}")
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class Run:
|
|
42
|
+
"""一个已存在的 twin run 的句柄。"""
|
|
43
|
+
|
|
44
|
+
def __init__(self, client: "Client", data: dict) -> None:
|
|
45
|
+
self._client = client
|
|
46
|
+
self._data = data
|
|
47
|
+
|
|
48
|
+
def __getitem__(self, key: str) -> Any:
|
|
49
|
+
return self._data[key]
|
|
50
|
+
|
|
51
|
+
def __repr__(self) -> str:
|
|
52
|
+
return f"<Run {self._data.get('run_id')} twins={','.join(self._data.get('twins') or [])}>"
|
|
53
|
+
|
|
54
|
+
@property
|
|
55
|
+
def run_id(self) -> str:
|
|
56
|
+
return self._data["run_id"]
|
|
57
|
+
|
|
58
|
+
@property
|
|
59
|
+
def twins(self) -> list[str]:
|
|
60
|
+
return list(self._data.get("twins") or [])
|
|
61
|
+
|
|
62
|
+
@property
|
|
63
|
+
def endpoints(self) -> dict[str, str]:
|
|
64
|
+
return dict(self._data.get("endpoints") or {})
|
|
65
|
+
|
|
66
|
+
@property
|
|
67
|
+
def credentials(self) -> dict[str, str]:
|
|
68
|
+
return dict(self._data.get("credentials") or {})
|
|
69
|
+
|
|
70
|
+
def refresh(self) -> "Run":
|
|
71
|
+
self._data = self._client.get_run(self.run_id)
|
|
72
|
+
return self
|
|
73
|
+
|
|
74
|
+
def act(self, actions: list[dict]) -> dict:
|
|
75
|
+
"""执行一批动作。**自动带 run-scoped 凭据**(除非 action 显式给了 Authorization)。"""
|
|
76
|
+
for a in actions:
|
|
77
|
+
headers = dict(a.get("headers") or {})
|
|
78
|
+
if not any(k.lower() == "authorization" for k in headers):
|
|
79
|
+
token = self.credentials.get(a.get("provider") or "")
|
|
80
|
+
if token:
|
|
81
|
+
headers["Authorization"] = f"Bearer {token}"
|
|
82
|
+
a["headers"] = headers
|
|
83
|
+
return self._client.act(self.run_id, actions)
|
|
84
|
+
|
|
85
|
+
def grade(self, spec: dict | None = None) -> dict:
|
|
86
|
+
return self._client.grade(self.run_id, spec)
|
|
87
|
+
|
|
88
|
+
def state(self) -> dict:
|
|
89
|
+
return self._client.state(self.run_id)
|
|
90
|
+
|
|
91
|
+
def stub_hits(self, provider: str | None = None) -> dict:
|
|
92
|
+
return self._client.stub_hits(self.run_id, provider)
|
|
93
|
+
|
|
94
|
+
def reset(self) -> "Run":
|
|
95
|
+
self._data = self._client.reset(self.run_id)
|
|
96
|
+
return self
|
|
97
|
+
|
|
98
|
+
def extend(self, ttl: int = 600) -> "Run":
|
|
99
|
+
self._data = self._client.extend(self.run_id, ttl)
|
|
100
|
+
return self
|
|
101
|
+
|
|
102
|
+
def lock(self) -> "Run":
|
|
103
|
+
self._data = self._client.lock(self.run_id)
|
|
104
|
+
return self
|
|
105
|
+
|
|
106
|
+
def teardown(self) -> dict:
|
|
107
|
+
return self._client.teardown(self.run_id)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
class Client:
|
|
111
|
+
def __init__(self, base: str = "http://127.0.0.1:8787", timeout: float = 30.0,
|
|
112
|
+
admin_token: str | None = None) -> None:
|
|
113
|
+
self.base = base.rstrip("/")
|
|
114
|
+
self.timeout = timeout
|
|
115
|
+
self.admin_token = admin_token
|
|
116
|
+
|
|
117
|
+
@classmethod
|
|
118
|
+
def from_env(cls, base: str | None = None) -> "Client":
|
|
119
|
+
"""服务端开了 --admin-token 时,客户端也得带着,否则每个 admin 调用都是 401。"""
|
|
120
|
+
return cls(
|
|
121
|
+
base or os.environ.get("ARGACLONE_API", "http://127.0.0.1:8787"),
|
|
122
|
+
admin_token=os.environ.get("ARGACLONE_ADMIN_TOKEN") or None,
|
|
123
|
+
)
|
|
124
|
+
|
|
125
|
+
# ---- 传输 ----
|
|
126
|
+
|
|
127
|
+
def _request(self, method: str, path: str, payload: dict | None = None) -> Any:
|
|
128
|
+
data = None if payload is None else json.dumps(payload).encode()
|
|
129
|
+
req = urllib.request.Request(self.base + path, data=data, method=method)
|
|
130
|
+
if data is not None:
|
|
131
|
+
req.add_header("Content-Type", "application/json")
|
|
132
|
+
if self.admin_token:
|
|
133
|
+
req.add_header("X-Admin-Token", self.admin_token)
|
|
134
|
+
try:
|
|
135
|
+
with urllib.request.urlopen(req, timeout=self.timeout) as resp:
|
|
136
|
+
raw = resp.read()
|
|
137
|
+
except urllib.error.HTTPError as exc:
|
|
138
|
+
raw = exc.read()
|
|
139
|
+
try:
|
|
140
|
+
body = json.loads(raw)
|
|
141
|
+
except json.JSONDecodeError:
|
|
142
|
+
body = raw.decode("utf-8", "replace")
|
|
143
|
+
raise ArgacloneError(exc.code, body, path) from None
|
|
144
|
+
if not raw:
|
|
145
|
+
return None
|
|
146
|
+
return json.loads(raw)
|
|
147
|
+
|
|
148
|
+
# ---- 运行环境 ----
|
|
149
|
+
|
|
150
|
+
def provision(self, twins: list[str] | str, ttl: int = 600,
|
|
151
|
+
scenario: str | None = None, prompt: str | None = None,
|
|
152
|
+
strict_tokens: bool = False) -> Run:
|
|
153
|
+
body: dict[str, Any] = {
|
|
154
|
+
"twins": twins if isinstance(twins, str) else ",".join(twins),
|
|
155
|
+
"ttl_seconds": ttl,
|
|
156
|
+
}
|
|
157
|
+
if scenario:
|
|
158
|
+
body["scenario_id"] = scenario
|
|
159
|
+
if prompt:
|
|
160
|
+
body["prompt"] = prompt
|
|
161
|
+
if strict_tokens:
|
|
162
|
+
# 只认 provision 下发的凭据。默认不开:手工调试时随手编一个 token
|
|
163
|
+
# 更方便,但"孪生校验了凭据"在那种模式下是假话。
|
|
164
|
+
body["strict_tokens"] = True
|
|
165
|
+
return Run(self, self._request("POST", "/admin/runs", body))
|
|
166
|
+
|
|
167
|
+
def list_runs(self) -> list[dict]:
|
|
168
|
+
return self._request("GET", "/admin/runs").get("runs", [])
|
|
169
|
+
|
|
170
|
+
def get_run(self, run_id: str) -> dict:
|
|
171
|
+
return self._request("GET", f"/admin/runs/{run_id}")
|
|
172
|
+
|
|
173
|
+
def run(self, run_id: str) -> Run:
|
|
174
|
+
return Run(self, self.get_run(run_id))
|
|
175
|
+
|
|
176
|
+
def reset(self, run_id: str) -> dict:
|
|
177
|
+
return self._request("POST", f"/admin/runs/{run_id}/reset", {})
|
|
178
|
+
|
|
179
|
+
def extend(self, run_id: str, ttl: int = 600) -> dict:
|
|
180
|
+
return self._request("POST", f"/admin/runs/{run_id}/extend", {"ttl": ttl})
|
|
181
|
+
|
|
182
|
+
def lock(self, run_id: str) -> dict:
|
|
183
|
+
return self._request("POST", f"/admin/runs/{run_id}/lock", {})
|
|
184
|
+
|
|
185
|
+
def teardown(self, run_id: str) -> dict:
|
|
186
|
+
return self._request("DELETE", f"/admin/runs/{run_id}")
|
|
187
|
+
|
|
188
|
+
def state(self, run_id: str) -> dict:
|
|
189
|
+
return self._request("GET", f"/admin/runs/{run_id}/state")
|
|
190
|
+
|
|
191
|
+
def act(self, run_id: str, actions: list[dict]) -> dict:
|
|
192
|
+
return self._request("POST", f"/admin/runs/{run_id}/actions", {"actions": actions})
|
|
193
|
+
|
|
194
|
+
def grade(self, run_id: str, spec: dict | None = None) -> dict:
|
|
195
|
+
body = {"spec": spec} if spec else {}
|
|
196
|
+
return self._request("POST", f"/admin/runs/{run_id}/grade", body)
|
|
197
|
+
|
|
198
|
+
def stub_hits(self, run_id: str, provider: str | None = None) -> dict:
|
|
199
|
+
path = f"/admin/runs/{run_id}/stub-hits"
|
|
200
|
+
if provider:
|
|
201
|
+
path += f"?provider={provider}"
|
|
202
|
+
return self._request("GET", path)
|
|
203
|
+
|
|
204
|
+
def clear_stub_hits(self, run_id: str) -> dict:
|
|
205
|
+
return self._request("POST", f"/admin/runs/{run_id}/stub-hits", {})
|
|
206
|
+
|
|
207
|
+
# ---- scenarios ----
|
|
208
|
+
|
|
209
|
+
def scenarios(self) -> list[dict]:
|
|
210
|
+
return self._request("GET", "/admin/scenarios").get("scenarios", [])
|
|
211
|
+
|
|
212
|
+
def scenario(self, scenario_id: str) -> dict:
|
|
213
|
+
return self._request("GET", f"/admin/scenarios/{scenario_id}")
|
|
214
|
+
|
|
215
|
+
def save_scenario(self, scenario: dict) -> dict:
|
|
216
|
+
return self._request("POST", "/admin/scenarios", scenario)
|
|
217
|
+
|
|
218
|
+
def delete_scenario(self, scenario_id: str) -> dict:
|
|
219
|
+
return self._request("DELETE", f"/admin/scenarios/{scenario_id}")
|
|
220
|
+
|
|
221
|
+
# ---- context manager ----
|
|
222
|
+
|
|
223
|
+
def __enter__(self) -> "Client":
|
|
224
|
+
return self
|
|
225
|
+
|
|
226
|
+
def __exit__(self, *exc: Any) -> None:
|
|
227
|
+
return None
|
argaclone/gateway.py
ADDED
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
"""网关:把 Host 解析成 (provider, run_id),再交给对应 twin。
|
|
2
|
+
|
|
3
|
+
为什么用 Host 而不是路径前缀(这是复刻 Arga 时最该抄的架构决定):
|
|
4
|
+
官方 SDK 只认 base URL 的 host。把租户编进 hostname,客户端就真的能"只改一行
|
|
5
|
+
.env"接入,不需要改写任何 URL 拼接逻辑。用路径前缀的话,所有 SDK 都会在拼
|
|
6
|
+
`/v1/customers` 时把前缀吃掉。
|
|
7
|
+
|
|
8
|
+
本地调试时 Host 不方便设置,所以额外支持 `X-Twin-Host` 头和 `__twin` 路径前缀。
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import hashlib
|
|
14
|
+
import re
|
|
15
|
+
from dataclasses import dataclass
|
|
16
|
+
from urllib.parse import parse_qs, urlparse
|
|
17
|
+
|
|
18
|
+
from . import chaos, webhooks
|
|
19
|
+
from .store import RunExpired, RunNotFound, StaleRunVersion, Store
|
|
20
|
+
from .twins.base import Request, Response, TwinRegistry
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass
|
|
24
|
+
class Target:
|
|
25
|
+
provider: str
|
|
26
|
+
run_id: str
|
|
27
|
+
path: str
|
|
28
|
+
query: dict[str, list[str]]
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class Gateway:
|
|
32
|
+
def __init__(self, store: Store, registry: TwinRegistry) -> None:
|
|
33
|
+
self.store = store
|
|
34
|
+
self.registry = registry
|
|
35
|
+
|
|
36
|
+
# ---------- 解析 ----------
|
|
37
|
+
|
|
38
|
+
def resolve(self, host: str, raw_path: str, headers: dict[str, str]) -> Target:
|
|
39
|
+
parsed = urlparse(raw_path)
|
|
40
|
+
path = parsed.path or "/"
|
|
41
|
+
query = parse_qs(parsed.query, keep_blank_values=True)
|
|
42
|
+
|
|
43
|
+
# 1) X-Twin-Host: slack.abc123.twins.local
|
|
44
|
+
override = headers.get("x-twin-host")
|
|
45
|
+
if override:
|
|
46
|
+
t = self._from_host(override)
|
|
47
|
+
if t:
|
|
48
|
+
return Target(t[0], t[1], path, query)
|
|
49
|
+
|
|
50
|
+
# 2) 路径前缀 /__twin/<provider>/<run_id>/<rest>
|
|
51
|
+
m = re.match(r"^/__twin/([^/]+)/([^/]+)(/.*)?$", path)
|
|
52
|
+
if m:
|
|
53
|
+
rest = m.group(3) or "/"
|
|
54
|
+
return Target(m.group(1), m.group(2), rest, query)
|
|
55
|
+
|
|
56
|
+
# 3) 标准 Host
|
|
57
|
+
host_only = host.split(":")[0]
|
|
58
|
+
t = self._from_host(host_only)
|
|
59
|
+
if t:
|
|
60
|
+
return Target(t[0], t[1], path, query)
|
|
61
|
+
|
|
62
|
+
raise RunNotFound(f"cannot resolve twin from host={host!r} path={path!r}")
|
|
63
|
+
|
|
64
|
+
def is_twin_target(self, host: str, headers: dict[str, str]) -> bool:
|
|
65
|
+
"""这个请求是打给某个 twin 的,还是打给服务本身的?
|
|
66
|
+
|
|
67
|
+
只给路由用:`/admin/coverage` 从服务面看是"没有这个 admin 路由",
|
|
68
|
+
从 twin 面看是"这个 twin 的覆盖度"。Host 决定它是哪一个。
|
|
69
|
+
"""
|
|
70
|
+
if (headers or {}).get("x-twin-host"):
|
|
71
|
+
return True
|
|
72
|
+
return self._from_host((host or "").split(":")[0]) is not None
|
|
73
|
+
|
|
74
|
+
def _from_host(self, host: str) -> tuple[str, str] | None:
|
|
75
|
+
host = host.split(":")[0]
|
|
76
|
+
parts = host.split(".")
|
|
77
|
+
# 形如 <provider>.<run_id>.twins.local(允许 provider 前面还有标签)
|
|
78
|
+
for i in range(len(parts) - 3):
|
|
79
|
+
if parts[i + 2] == "twins" and parts[i + 3] == "local":
|
|
80
|
+
return parts[i], parts[i + 1]
|
|
81
|
+
# 两标签简写只在第一段是已知 provider 时才成立。
|
|
82
|
+
# 不加这个条件,example.com 这种"域名配错了"会被报成 unknown_twin,
|
|
83
|
+
# 把真正的问题(base URL 没指过来)掩盖成"provider 拼错了"。
|
|
84
|
+
if len(parts) == 2 and parts[0] and parts[1] and self.registry.has(parts[0]):
|
|
85
|
+
return parts[0], parts[1]
|
|
86
|
+
return None
|
|
87
|
+
|
|
88
|
+
def _strict_credential_check(
|
|
89
|
+
self, run, provider: str, headers: dict[str, str]
|
|
90
|
+
) -> Response | None:
|
|
91
|
+
"""strict 模式下校验 token 逐字等于 provision 时下发的值。返回 None 表示放行。
|
|
92
|
+
|
|
93
|
+
为什么默认关:twin 不维护 token 表时,任何**形状合法**的字符串都会被放行
|
|
94
|
+
(`Bearer definitely-not-valid` 在 jira/linear/notion 上能过)。这在手工
|
|
95
|
+
调试和单元测试里很方便,但它意味着"孪生校验了凭据"这句话是假的。
|
|
96
|
+
打开以后这句话变真:值不对就是 401,与真实 SaaS 一致。
|
|
97
|
+
|
|
98
|
+
为什么没带 token 时不在这里拦:401 的**错误体形状**也是保真的一部分
|
|
99
|
+
(Salesforce 回数组、Jira 回 errorMessages),交给 provider 自己给。
|
|
100
|
+
"""
|
|
101
|
+
if not run.extras.get("strict_tokens"):
|
|
102
|
+
return None
|
|
103
|
+
|
|
104
|
+
raw = headers.get("authorization", "")
|
|
105
|
+
token = raw.split(" ", 1)[1].strip() if " " in raw else ""
|
|
106
|
+
if not token:
|
|
107
|
+
return None
|
|
108
|
+
|
|
109
|
+
issued = (run.extras.get("credentials") or {}).get(provider)
|
|
110
|
+
if not issued or token == issued:
|
|
111
|
+
return None
|
|
112
|
+
|
|
113
|
+
return Response(
|
|
114
|
+
401,
|
|
115
|
+
{
|
|
116
|
+
"error": "invalid_credential",
|
|
117
|
+
"provider": provider,
|
|
118
|
+
"run_id": run.run_id,
|
|
119
|
+
"_twin_hint": (
|
|
120
|
+
"this run has strict_tokens on: only the credential issued by "
|
|
121
|
+
"provision is accepted"
|
|
122
|
+
),
|
|
123
|
+
},
|
|
124
|
+
)
|
|
125
|
+
|
|
126
|
+
# ---------- 处理 ----------
|
|
127
|
+
|
|
128
|
+
def handle(
|
|
129
|
+
self,
|
|
130
|
+
method: str,
|
|
131
|
+
host: str,
|
|
132
|
+
raw_path: str,
|
|
133
|
+
headers: dict[str, str],
|
|
134
|
+
body: bytes,
|
|
135
|
+
) -> Response:
|
|
136
|
+
# 统一小写化 header 名。HTTP 头本来就不区分大小写,但这个入口被
|
|
137
|
+
# HTTP handler、SDK、MCP、测试四条通道共用,它们的 dict 大小写各不相同。
|
|
138
|
+
# 不归一就会出现"HTTP 通道能过、SDK 通道 401"这种只在某条通道上复现的怪事 ——
|
|
139
|
+
# 而 401 会被误读成凭据问题,浪费的是排查时间。
|
|
140
|
+
headers = {k.lower(): v for k, v in (headers or {}).items()}
|
|
141
|
+
try:
|
|
142
|
+
target = self.resolve(host, raw_path, headers)
|
|
143
|
+
except RunNotFound as exc:
|
|
144
|
+
return Response(404, {"error": "unresolvable_target", "detail": str(exc)})
|
|
145
|
+
|
|
146
|
+
if not self.registry.has(target.provider):
|
|
147
|
+
return Response(
|
|
148
|
+
404,
|
|
149
|
+
{
|
|
150
|
+
"error": "unknown_twin",
|
|
151
|
+
"provider": target.provider,
|
|
152
|
+
"available": self.registry.names(),
|
|
153
|
+
},
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
try:
|
|
157
|
+
run = self.store.get(target.run_id)
|
|
158
|
+
except RunNotFound:
|
|
159
|
+
return Response(404, {"error": "run_not_found", "run_id": target.run_id})
|
|
160
|
+
except RunExpired:
|
|
161
|
+
return Response(
|
|
162
|
+
410,
|
|
163
|
+
{
|
|
164
|
+
"error": "run_expired",
|
|
165
|
+
"run_id": target.run_id,
|
|
166
|
+
"_twin_hint": "provision a new run, or reset with a longer TTL",
|
|
167
|
+
},
|
|
168
|
+
)
|
|
169
|
+
|
|
170
|
+
if target.provider not in run.twins:
|
|
171
|
+
return Response(
|
|
172
|
+
404,
|
|
173
|
+
{
|
|
174
|
+
"error": "twin_not_provisioned",
|
|
175
|
+
"provider": target.provider,
|
|
176
|
+
"provisioned": run.twins,
|
|
177
|
+
},
|
|
178
|
+
)
|
|
179
|
+
|
|
180
|
+
# 严格凭据模式:只认本次 run 签发的那一个 token。
|
|
181
|
+
# 放在 twin 之前,是因为这属于"run 的访问控制"而不是"provider 的协议细节"——
|
|
182
|
+
# 12 个 twin 各写一遍同样的比对,必然漏一个。
|
|
183
|
+
denied = self._strict_credential_check(run, target.provider, headers)
|
|
184
|
+
if denied is not None:
|
|
185
|
+
return denied
|
|
186
|
+
|
|
187
|
+
twin = self.registry.get(target.provider)
|
|
188
|
+
run.state.setdefault(target.provider, twin.initial_state())
|
|
189
|
+
|
|
190
|
+
upper = method.upper()
|
|
191
|
+
idem = self._idem_key(headers, upper)
|
|
192
|
+
fingerprint = self._fingerprint(upper, target.path, body)
|
|
193
|
+
# 幂等键在 dispatch 之前判定:命中就直接重放,世界一动不动。
|
|
194
|
+
replayed = self._replay(run, twin, target.provider, idem, fingerprint, upper, target.path)
|
|
195
|
+
if replayed is not None:
|
|
196
|
+
return replayed
|
|
197
|
+
|
|
198
|
+
if run.locked and not headers.get("authorization") and not target.path.startswith("/admin"):
|
|
199
|
+
return Response(403, {"error": "run_locked", "_twin_hint": "this run is public-access-locked"})
|
|
200
|
+
|
|
201
|
+
# 故障注入与限流:插在 twin 之前,因为这是"环境的行为"不是"provider 的
|
|
202
|
+
# 协议"。放在凭据校验之后 —— 认证失败是调用方的问题,不该被 500 盖住,
|
|
203
|
+
# 否则调试时会把"token 错了"读成"服务在抽风"。
|
|
204
|
+
chaos_resp = chaos.guard(run, target.provider, method.upper(), target.path)
|
|
205
|
+
if chaos_resp is not None:
|
|
206
|
+
if (conflict := self._save(run)) is not None:
|
|
207
|
+
return conflict
|
|
208
|
+
return chaos_resp
|
|
209
|
+
|
|
210
|
+
req = Request(
|
|
211
|
+
method=upper,
|
|
212
|
+
path=target.path,
|
|
213
|
+
query=target.query,
|
|
214
|
+
headers=headers,
|
|
215
|
+
body=body,
|
|
216
|
+
run=run,
|
|
217
|
+
run_id=run.run_id,
|
|
218
|
+
store=self.store,
|
|
219
|
+
)
|
|
220
|
+
try:
|
|
221
|
+
resp = twin.dispatch(req)
|
|
222
|
+
except StaleRunVersion as exc:
|
|
223
|
+
# twin 内部(stub 计数、seed 落盘)也可能写盘,同样可能撞版本。
|
|
224
|
+
# 在同一个地方收口,调用方看到的语义才一致。
|
|
225
|
+
return self._conflict(exc)
|
|
226
|
+
self._remember(run, target.provider, idem, fingerprint, upper, target.path, resp)
|
|
227
|
+
# 到这里世界已经变了(twin 的写是在 dispatch 里做的)。"已提交但响应失败"
|
|
228
|
+
# 必须在此时才生效:早一步就变成"根本没提交",晚一步(写盘之后)就变成
|
|
229
|
+
# "响应成功但状态没存" —— 两种都不是要测的那个事故。
|
|
230
|
+
resp = chaos.after_response(run, target.provider, method.upper(), target.path, resp)
|
|
231
|
+
# 事件投递:只在"世界真的变了"时发(写方法 + 2xx)。失败/403/404 都算
|
|
232
|
+
# 没发生变更,发通知等于告诉订阅方一件没发生的事。
|
|
233
|
+
# 同步投递、有超时与重试上限:异步会把"通知丢了"变成无法复现的偶发问题。
|
|
234
|
+
# "世界变了"不等于"调用方看到成功":commit_then_fail 下这次写已经生效,
|
|
235
|
+
# 接收方理应收到事件,而调用方拿到的是 500。这个不对齐正是要测的东西。
|
|
236
|
+
committed = (
|
|
237
|
+
200 <= resp.status < 300
|
|
238
|
+
or resp.headers.get("X-Twin-Fault") == "commit_then_fail"
|
|
239
|
+
)
|
|
240
|
+
if method.upper() not in ("GET", "HEAD") and committed:
|
|
241
|
+
webhooks.deliver(run, target.provider, method.upper(), target.path, req.json())
|
|
242
|
+
# 写请求改完世界就落盘(配了 directory 才有动作)。读请求不落盘:
|
|
243
|
+
# GET 除了 stub 计数以外不改状态,而 stub 计数在 record_stub 里已经存过。
|
|
244
|
+
if method.upper() not in ("GET", "HEAD"):
|
|
245
|
+
if (conflict := self._save(run)) is not None:
|
|
246
|
+
return conflict
|
|
247
|
+
return resp
|
|
248
|
+
|
|
249
|
+
# ---------- 幂等键 ----------
|
|
250
|
+
#
|
|
251
|
+
# 为什么 twin 需要它:`commit_then_fail` 之后调用方看到 500,重试是**正确行为**,
|
|
252
|
+
# 但没有幂等键的重试会把同一件事做两遍。所以"重试"这件事的安全与否,
|
|
253
|
+
# 取决于服务端认不认幂等键 —— 这不是客户端的锅,是环境的性质。
|
|
254
|
+
#
|
|
255
|
+
# 只对写方法生效,且**缓存的是 twin 自己那份响应**(在 chaos 遮成 500 之前),
|
|
256
|
+
# 这样"提交成功但响应丢了"的重试会拿回第一次的 200,而不是再来一遍。
|
|
257
|
+
|
|
258
|
+
@staticmethod
|
|
259
|
+
def _idem_key(headers: dict[str, str], method: str) -> str:
|
|
260
|
+
if method in ("GET", "HEAD"):
|
|
261
|
+
return ""
|
|
262
|
+
return (headers.get("idempotency-key") or "").strip()
|
|
263
|
+
|
|
264
|
+
@staticmethod
|
|
265
|
+
def _fingerprint(method: str, path: str, body: bytes) -> str:
|
|
266
|
+
return hashlib.sha256(method.encode() + b"\n" + path.encode() + b"\n" + (body or b"")).hexdigest()[:32]
|
|
267
|
+
|
|
268
|
+
def _replay(self, run, twin, provider: str, key: str, fingerprint: str, method: str, path: str) -> Response | None:
|
|
269
|
+
if not key:
|
|
270
|
+
return None
|
|
271
|
+
table = (run.extras.get("idempotency") or {}).get(provider) or {}
|
|
272
|
+
seen = table.get(key)
|
|
273
|
+
if not seen:
|
|
274
|
+
return None
|
|
275
|
+
if seen["fingerprint"] != fingerprint:
|
|
276
|
+
# 同一把钥匙配不同的货,真实 Stripe 也是拒的。静默返回旧响应会让
|
|
277
|
+
# 调用方以为新请求生效了 —— 那是更难查的一类事故。
|
|
278
|
+
return twin.idempotency_conflict(
|
|
279
|
+
"Keys for idempotent requests can only be used with the same parameters "
|
|
280
|
+
"they were first used with.",
|
|
281
|
+
f"key 首次用于 {seen['method']} {seen['path']},本次是 {method} {path}",
|
|
282
|
+
)
|
|
283
|
+
cached = seen
|
|
284
|
+
return Response(
|
|
285
|
+
cached["status"],
|
|
286
|
+
cached["body"],
|
|
287
|
+
{**cached.get("headers", {}), "Idempotent-Replayed": "true"},
|
|
288
|
+
)
|
|
289
|
+
|
|
290
|
+
def _remember(self, run, provider: str, key: str, fingerprint: str, method: str, path: str, resp: Response) -> None:
|
|
291
|
+
if not key:
|
|
292
|
+
return
|
|
293
|
+
# 只记住"有结论"的响应:2xx 与 4xx 都是服务端给出的答复,重放它是对的;
|
|
294
|
+
# 5xx 不该被记住 —— 那正是"再来一次可能就好了"的情形,缓存 500 会把
|
|
295
|
+
# 一次瞬时故障变成永久故障。
|
|
296
|
+
if not (200 <= resp.status < 500):
|
|
297
|
+
return
|
|
298
|
+
table = run.extras.setdefault("idempotency", {}).setdefault(provider, {})
|
|
299
|
+
table[key] = {
|
|
300
|
+
"fingerprint": fingerprint,
|
|
301
|
+
"method": method,
|
|
302
|
+
"path": path,
|
|
303
|
+
"status": resp.status,
|
|
304
|
+
"body": resp.body,
|
|
305
|
+
"headers": {k: v for k, v in (resp.headers or {}).items() if k.lower() != "idempotent-replayed"},
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
def _save(self, run) -> Response | None:
|
|
309
|
+
"""写盘失败时把 409 回给调用方,而不是让异常穿到 HTTP 层当 500。
|
|
310
|
+
|
|
311
|
+
为什么回 409 而不是重试一次:重试意味着"我替调用方决定它的改动可以
|
|
312
|
+
基于旧世界"——那正是要防的事。调用方自己重读、自己重放,才是可解释的。
|
|
313
|
+
"""
|
|
314
|
+
try:
|
|
315
|
+
self.store.save(run)
|
|
316
|
+
except StaleRunVersion as exc:
|
|
317
|
+
return self._conflict(exc)
|
|
318
|
+
return None
|
|
319
|
+
|
|
320
|
+
@staticmethod
|
|
321
|
+
def _conflict(exc: StaleRunVersion) -> Response:
|
|
322
|
+
return Response(409, {"error": "stale_run_version", "detail": str(exc),
|
|
323
|
+
"_twin_hint": "重新读取 run 后再改"})
|