mcp-server-ecs-common 0.1.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.
@@ -0,0 +1,10 @@
1
+ # Copyright (c) 2026 Huawei Technologies Co., Ltd.
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ """Shared utilities for Huawei Cloud ECS MCP servers (ecs & ecs-lifecycle)."""
5
+
6
+ from mcp_server_ecs_common.convert import sdk_to_dict
7
+ from mcp_server_ecs_common.paginate import paginate
8
+ from mcp_server_ecs_common.throttle import call_sdk
9
+
10
+ __all__ = ["call_sdk", "paginate", "sdk_to_dict"]
@@ -0,0 +1,41 @@
1
+ # Copyright (c) 2026 Huawei Technologies Co., Ltd.
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ """JSON-compatible conversion of huaweicloudsdk response objects.
5
+
6
+ The SDK deserializer yields model instances and nested containers; these
7
+ helpers turn an arbitrary response into plain JSON data so the MCP layer can
8
+ serialize it without leaking SDK internals.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from typing import Any
14
+
15
+ _SKIP_ATTRS = {"local_vars_configuration", "discriminator", "swagger_types"}
16
+
17
+
18
+ def sdk_to_dict(obj: Any) -> Any:
19
+ """Recursively convert an SDK response object into plain JSON-compatible data."""
20
+ result: Any
21
+ if obj is None or isinstance(obj, (str, int, float, bool)):
22
+ result = obj
23
+ elif isinstance(obj, bytes):
24
+ result = obj.decode("utf-8", errors="replace")
25
+ elif isinstance(obj, dict):
26
+ result = {str(key): sdk_to_dict(value) for key, value in obj.items()}
27
+ elif isinstance(obj, (list, tuple)):
28
+ result = [sdk_to_dict(item) for item in obj]
29
+ elif hasattr(obj, "to_dict"):
30
+ result = {str(key).lstrip("_"): sdk_to_dict(value) for key, value in obj.to_dict().items()}
31
+ elif not hasattr(obj, "__dict__"):
32
+ # datetime/Decimal/etc. have no __dict__ — the SDK deserializer can emit
33
+ # them for time-typed fields even when models declare plain str.
34
+ result = str(obj)
35
+ else:
36
+ result = {}
37
+ for key, value in vars(obj).items():
38
+ if key in _SKIP_ATTRS or key.startswith("__") or callable(value):
39
+ continue
40
+ result[key.lstrip("_")] = sdk_to_dict(value)
41
+ return result
@@ -0,0 +1,76 @@
1
+ # Copyright (c) 2026 Huawei Technologies Co., Ltd.
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ """Generic page-through helper for huaweicloudsdk list endpoints.
5
+
6
+ Each SDK list call that can return more than one page shares the same
7
+ shape: build a request with a page size, fetch one page, collect the
8
+ items, and keep going until the page comes back short or empty. This
9
+ module factors that loop into one place; the per-endpoint request
10
+ construction and pagination-state advancement stay in the caller.
11
+
12
+ Two paging styles are supported:
13
+
14
+ * offset style (ECS list-servers-details): the caller advances an integer
15
+ offset and the loop stops when a page is empty or short.
16
+ * marker style (IMS list-images, ECS list-flavors, VPC list-subnets): the
17
+ caller reads ``page_info.next_marker`` from the response. When ``advance``
18
+ returns the next marker (a string), the loop follows it; an empty/None
19
+ marker means the last page. This is authoritative — a full last page does
20
+ not cause an extra fetch, and a repeated marker is detected to avoid
21
+ looping forever on a misbehaving endpoint.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ from collections.abc import Callable
27
+ from typing import Any
28
+
29
+ from mcp_server_ecs_common.convert import sdk_to_dict
30
+
31
+
32
+ def paginate(
33
+ fetch: Callable[[], Any],
34
+ *,
35
+ result_key: str,
36
+ page_size: int,
37
+ max_pages: int | None = None,
38
+ advance: Callable[[list[dict[str, Any]], dict[str, Any]], str | None] | None = None,
39
+ ) -> list[dict[str, Any]]:
40
+ """Collect every item a paged list endpoint returns.
41
+
42
+ ``fetch`` builds the SDK request (already carrying the current page
43
+ position) and returns the raw response object for one page. ``advance``,
44
+ when given, receives the batch just received plus the decoded page dict
45
+ and returns the next marker (or ``None`` when there are no more pages).
46
+ Iteration stops when a page is empty, comes back short of ``page_size``
47
+ (offset style), the marker is exhausted (marker style), the marker
48
+ repeats, or ``max_pages`` is exhausted. Without ``advance`` a full page
49
+ keeps the loop going; pass ``max_pages`` to bound it.
50
+
51
+ Runs synchronously; callers wrap it in ``call_sdk`` (which in turn wraps
52
+ ``asyncio.to_thread`` with concurrency limiting and retry) exactly as they
53
+ do for their single-page calls.
54
+ """
55
+ items: list[dict[str, Any]] = []
56
+ pages = 0
57
+ seen_markers: set[str] = set()
58
+ while max_pages is None or pages < max_pages:
59
+ pages += 1
60
+ response = fetch()
61
+ page = sdk_to_dict(response) or {}
62
+ batch = page.get(result_key) or []
63
+ items.extend(batch)
64
+ if not batch or len(batch) < page_size:
65
+ break
66
+ if advance is None:
67
+ continue
68
+ next_marker = advance(batch, page)
69
+ if next_marker is None:
70
+ break
71
+ if next_marker in seen_markers:
72
+ # A marker that repeats means the endpoint is not advancing; stop
73
+ # rather than spin until max_pages on duplicate data.
74
+ break
75
+ seen_markers.add(next_marker)
76
+ return items
@@ -0,0 +1,2 @@
1
+ # Copyright (c) 2026 Huawei Technologies Co., Ltd.
2
+ # SPDX-License-Identifier: MIT
@@ -0,0 +1,56 @@
1
+ # Copyright (c) 2026 Huawei Technologies Co., Ltd.
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ """Test-support helpers shared by the ECS server packages.
5
+
6
+ These are used by ``conftest.py`` fixtures across the ecs and ecs-lifecycle
7
+ packages so the two do not duplicate env-cleaning and server-registration
8
+ boilerplate. They are NOT part of the runtime API; do not import from
9
+ ``mcp_server_ecs_common`` itself.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from typing import Any
15
+
16
+ _ENV_KEYS = [
17
+ "HUAWEICLOUD_ACCESS_KEY",
18
+ "HUAWEICLOUD_SECRET_KEY",
19
+ "HUAWEICLOUD_REGION",
20
+ "HUAWEICLOUD_PROJECT_ID",
21
+ "HUAWEICLOUD_SECURITY_TOKEN",
22
+ "HUAWEICLOUD_ENDPOINT",
23
+ "HUAWEICLOUD_MCP_SKIP_SSL_VERIFY_REGIONS",
24
+ "HUAWEICLOUD_MCP_MAX_CONCURRENT",
25
+ "HUAWEICLOUD_MCP_READ_ONLY",
26
+ "HUAWEICLOUD_MCP_PROTECTED_IDS",
27
+ "HUAWEICLOUD_MCP_PROTECTED_NAMES",
28
+ "HUAWEICLOUD_MCP_PROTECTED_TAGS",
29
+ "HUAWEICLOUD_MCP_GUARDRAILS_CONFIG",
30
+ "HUAWEICLOUD_MCP_AUDIT_FILE",
31
+ "MCP_SERVER_PORT",
32
+ "MCP_SERVER_HOST",
33
+ ]
34
+
35
+
36
+ def register_server(
37
+ client: Any,
38
+ server_id: str,
39
+ name: str | None = None,
40
+ status: str = "ACTIVE",
41
+ **extra: Any,
42
+ ) -> dict[str, Any]:
43
+ """Append one ECS server record (real-SDK-shaped) to a fake client."""
44
+ server: dict[str, Any] = {
45
+ "id": server_id,
46
+ "name": name or server_id,
47
+ "status": status,
48
+ # ram matches the real SDK unit (MB): c7.large.2 = 4096MB
49
+ "flavor": {"id": "c7.large.2", "name": "c7.large.2", "vcpus": 2, "ram": 4096},
50
+ "addresses": {},
51
+ "tags": [],
52
+ "created": "2026-01-01T00:00:00Z",
53
+ }
54
+ server.update(extra)
55
+ client.servers.append(server)
56
+ return server
@@ -0,0 +1,388 @@
1
+ # Copyright (c) 2026 Huawei Technologies Co., Ltd.
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ """Traffic protection for ECS SDK calls: bounded concurrency + retry with backoff.
5
+
6
+ Both ECS MCP servers (``mcp_server_ecs_readonly`` and ``mcp_server_ecs_lifecycle``) share
7
+ one AK/SK (one Huawei Cloud user), so they share one APIG per-user rate-limit
8
+ budget. Two failure modes would otherwise overrun that budget:
9
+
10
+ * **burst** — the Agent fires many independent tool calls at once and they all
11
+ reach APIG in the same instant, tripping the per-user QPS cap.
12
+ * **avalanche** — APIG returns 429 (or the backend 5xx) and the MCP server
13
+ surfaces it as a plain error; the Agent's reflex is to retry at once, which
14
+ trips the cap again and again.
15
+
16
+ ``call_sdk`` sits where ``asyncio.to_thread`` sat in every client method. It
17
+ adds two layers that ``asyncio.to_thread`` does not:
18
+
19
+ 1. A process-wide semaphore caps how many SDK calls run at once. The cap is
20
+ read from ``HUAWEICLOUD_MCP_MAX_CONCURRENT`` (default 20); callers that
21
+ exceed it wait at the semaphore, so the request never reaches APIG. This is
22
+ the *only* knob exposed to the operator — the retry parameters below are
23
+ internal and not configurable, since a wrong value can silently defeat the
24
+ layer and the operator has no better judgment on them than the tuned
25
+ defaults.
26
+ 2. Retryable responses (429 / 5xx) are retried up to three times with backoff
27
+ before the error is surfaced. Sustained 429 means the quota is genuinely
28
+ exhausted, so the retries absorb a transient blip; if all three retries
29
+ fail the Agent receives ``MCP_RATE_LIMITED`` with a hint that says *do not
30
+ retry at once*, not a bare ``HTTP_429`` it would reflexively re-send.
31
+ Transient transport failures (the SDK's ``requests`` layer: connection
32
+ resets, timeouts) get the same treatment: retried up to three times, then
33
+ surfaced as ``MCP_TRANSIENT_ERROR`` with the same slow-down hint — without
34
+ it the Agent would re-send at once and turn a 5-second network blip into an
35
+ avalanche. The backoff schedule is a fixed sequence — 5s, 10s, 20s — rather
36
+ than a blind exponential; the first retry at 5s gives APIG's per-user quota
37
+ a meaningful window to recover, and the fixed cadence is recognizable in
38
+ logs when a 429 storm is in progress.
39
+
40
+ The semaphore is per-process: it bounds only the calls made through this one
41
+ process. When the two ECS servers run as separate processes they each keep
42
+ their own semaphore, so the combined load on APIG is the sum — the ``20`` default
43
+ is a *per-process* cap, not a global one; in that deployment APIG's own
44
+ per-user throttle is the global backstop, and the retry layer here keeps a 429
45
+ from cascading into an avalanche regardless of how many processes are involved.
46
+
47
+ The semaphore value is read from the environment ONCE, on first use, and then
48
+ locked in for the life of the process. Reading it every call and rebuilding the
49
+ semaphore on a change would leave the old semaphore's in-flight holders
50
+ unconstrained by a lowered cap — a brief window where the protection this layer
51
+ provides is defeated. Treating it as a startup-time setting makes "lower the cap"
52
+ actually lower it (after restart), instead of silently exceeding it for a beat.
53
+ Change the value, then restart.
54
+ """
55
+
56
+ from __future__ import annotations
57
+
58
+ import asyncio
59
+ import os
60
+ import random
61
+ from collections.abc import Callable
62
+ from typing import TYPE_CHECKING, Any
63
+
64
+ if TYPE_CHECKING:
65
+ # McpToolError is imported lazily at runtime inside _retryable_error and
66
+ # call_sdk to avoid a hard runtime dep on huaweicloud_mcp_core at module
67
+ # import; this is only for the type checker to resolve the annotations.
68
+ from huaweicloud_mcp_core.errors import McpToolError
69
+
70
+ # Concurrency is the one knob exposed to the operator: it depends on the
71
+ # deployment (how many server processes run, the APIG per-user quota) and the
72
+ # operator is the only one with that information. Bounds guard the env read —
73
+ # a typo (``MAX_CONCURRENT=0``) used to make the server silently hang.
74
+ _CONCURRENT_FLOOR, _CONCURRENT_CEIL = 1, 64
75
+ _DEFAULT_MAX_CONCURRENT = 20
76
+
77
+ # Retry parameters are NOT exposed as environment variables. They are internal
78
+ # to the backoff algorithm, and an operator has no better judgment on them
79
+ # than these tuned defaults — but a wrong value can quietly defeat the layer
80
+ # (base=0+jitter=0 = zero-delay retry = the Agent avalanche it absorbs). Keeping
81
+ # them as constants removes three "set it wrong and break protection" foot-guns
82
+ # while still letting tests override them via explicit ``call_sdk`` arguments.
83
+ #
84
+ # The backoff schedule is a fixed sequence — 5s, 10s, 20s — rather than
85
+ # ``base * 2**attempt``. The fixed schedule makes the wait times predictable
86
+ # for an operator watching logs (a 429 storm shows a recognizable 5/10/20
87
+ # cadence, not an opaque exponential), and the first retry at 5s gives APIG's
88
+ # per-user quota a meaningful window to recover instead of hammering it again
89
+ # in half a second. ``_MAX_RETRIES`` is capped at ``len(_BACKOFF_SECONDS)`` so
90
+ # the schedule never indexes out of range. With ``_MAX_RETRIES = 3`` each of the
91
+ # three schedule entries is used exactly once: 5s before retry 1, 10s before
92
+ # retry 2, 20s before retry 3, then fail.
93
+ _MAX_RETRIES = 3
94
+ _BACKOFF_SECONDS = (5.0, 10.0, 20.0)
95
+ _RETRY_JITTER = 0.25
96
+
97
+ # The transport exception types to treat as transient. huaweicloudsdkcore uses
98
+ # ``requests`` under the hood, so a real network blip surfaces as
99
+ # ``requests.exceptions.*``, NOT Python's built-in ``ConnectionError``/
100
+ # ``TimeoutError`` — the ``requests`` ones subclass ``RequestException``, not
101
+ # the builtins, so matching only the builtins caught none of the real errors
102
+ # and network-retry silently never fired. The tuple is extended lazily on
103
+ # first use (requests is a hard dep of the SDK, so it's present whenever the
104
+ # SDK is — but we degrade to builtins if it somehow is not, not crash).
105
+ _TRANSIENT_NETWORK_EXCS: tuple[type[BaseException], ...] = (
106
+ ConnectionError,
107
+ TimeoutError,
108
+ )
109
+
110
+
111
+ def _transient_network_exceptions() -> tuple[type[BaseException], ...]:
112
+ """Return the transport exception types to treat as transient.
113
+
114
+ Lazily extends the builtin tuple with ``requests.exceptions`` types so the
115
+ import is not paid at module load. ``ConnectionError`` (refused/reset/
116
+ aborted) and ``Timeout`` (connect or read) qualify; ``HTTPError`` does not
117
+ (it is a structured response, handled via :class:`ServiceResponseException`
118
+ above) and ``RequestException`` is too broad (includes 4xx).
119
+ """
120
+ try:
121
+ import requests.exceptions as _re
122
+ except ImportError:
123
+ return _TRANSIENT_NETWORK_EXCS
124
+ return (*_TRANSIENT_NETWORK_EXCS, _re.ConnectionError, _re.Timeout)
125
+
126
+
127
+ def _env_int(name: str, default: int, floor: int, ceil: int) -> int:
128
+ """Read an int env var; non-numeric falls back to default, out-of-range raises.
129
+
130
+ A non-numeric value (``"abc"``, ``""``) is treated as unset and uses the
131
+ default — a stray typo should not take the server down. A numeric-but-
132
+ unreasonable value (``0`` concurrent) is an operator error and raises at
133
+ first use so it is seen, not hidden as a hung server.
134
+ """
135
+ raw = os.getenv(name)
136
+ if raw is None or not raw.strip():
137
+ return default
138
+ try:
139
+ value = int(raw.strip())
140
+ except ValueError:
141
+ return default
142
+ if value < floor or value > ceil:
143
+ raise RuntimeError(
144
+ f"{name}={value!r} is out of range [{floor}, {ceil}]; "
145
+ f"set it within that range or unset it to use the default {default}."
146
+ )
147
+ return value
148
+
149
+
150
+ # A module-level semaphore cannot be constructed at import time: asyncio requires
151
+ # a running event loop to exist, and module import happens before the server's
152
+ # loop starts. It is created lazily on first use and memoized so every caller in
153
+ # the process shares one instance.
154
+ #
155
+ # The value is read from the environment ONCE, on first use, and locked in. This
156
+ # is deliberate: rebuilding the semaphore mid-flight when the env var changes
157
+ # leaves the old semaphore's in-flight holders unconstrained by the new (smaller)
158
+ # cap — a brief window where the very protection this layer provides is defeated.
159
+ # Treating it as a startup-time setting makes "lower the cap" actually lower the
160
+ # cap, instead of silently exceeding it for a beat. Change the value, then
161
+ # restart.
162
+ #
163
+ # The guard lock is also lazy: an ``asyncio.Lock()`` built at import time would
164
+ # bind to whatever loop happened to run first, breaking reuse across loops
165
+ # (tests, embedded hosts, notebook sessions each spin their own). Building it
166
+ # on first use inside ``_get_semaphore`` keeps it bound to the loop that
167
+ # actually calls us, which is the loop the semaphore lives on too. The steady-
168
+ # state read (semaphore already built) is lock-free via double-checked locking;
169
+ # the lock is only taken on the first-ever call.
170
+ _semaphore: asyncio.Semaphore | None = None
171
+ _semaphore_lock: asyncio.Lock | None = None
172
+
173
+
174
+ async def _get_semaphore() -> asyncio.Semaphore:
175
+ """Return the process-wide semaphore, building it on first use.
176
+
177
+ The value is resolved from ``HUAWEICLOUD_MCP_MAX_CONCURRENT`` exactly once —
178
+ on the first call — and is never re-read. A mid-flight change to the env
179
+ var is deliberately ignored (see the module-level note): rebuilding under
180
+ in-flight holders would briefly exceed a lowered cap.
181
+ """
182
+ global _semaphore, _semaphore_lock
183
+ # Steady state: already built. No lock, no env read.
184
+ if _semaphore is not None:
185
+ return _semaphore
186
+ if _semaphore_lock is None:
187
+ _semaphore_lock = asyncio.Lock()
188
+ async with _semaphore_lock:
189
+ if _semaphore is None:
190
+ _semaphore = asyncio.Semaphore(
191
+ _env_int(
192
+ "HUAWEICLOUD_MCP_MAX_CONCURRENT", _DEFAULT_MAX_CONCURRENT,
193
+ _CONCURRENT_FLOOR, _CONCURRENT_CEIL,
194
+ )
195
+ )
196
+ return _semaphore
197
+
198
+
199
+ def _is_retryable(exc: Exception) -> bool:
200
+ """429 and 5xx are transient; everything else fails fast.
201
+
202
+ Network errors raised by ``requests``/the SDK's HTTP layer (timeouts, TLS
203
+ failures, connection resets) are also transient — a blip that resolves in
204
+ seconds is exactly what one retry is for. The transport types matched are
205
+ the ones the SDK actually raises (``requests.exceptions.ConnectionError``
206
+ and ``Timeout``), plus the builtins as a fallback.
207
+
208
+ ``OSError`` is deliberately NOT matched wholesale even though the transport
209
+ errors above are its subclasses. ``socket.gaierror`` (DNS resolution
210
+ failure), ``FileNotFoundError`` and ``PermissionError`` are also ``OSError``
211
+ subclasses, but they signal a *configuration* error (wrong hostname, missing
212
+ certificate, bad file perms), not a blip — retrying only delays the real
213
+ failure report. Matching ``OSError`` would silently retry every one of them.
214
+ """
215
+ try:
216
+ from huaweicloudsdkcore.exceptions.exceptions import ( # type: ignore[import-untyped]
217
+ ServiceResponseException,
218
+ )
219
+ except ImportError:
220
+ pass
221
+ else:
222
+ if isinstance(exc, ServiceResponseException):
223
+ return bool(exc.status_code == 429 or exc.status_code >= 500)
224
+ # Transport blips: the endpoint is right, the transport hiccuped. Match the
225
+ # real requests exceptions the SDK raises, not just the builtins.
226
+ return bool(isinstance(exc, _transient_network_exceptions()))
227
+
228
+
229
+ def _backoff_delay(attempt: int, jitter: float) -> float:
230
+ """Fixed-schedule backoff: 5s, 10s, 20s for attempts 0/1/2, plus uniform jitter.
231
+
232
+ The schedule is a fixed tuple rather than ``base * 2**attempt`` so the wait
233
+ is predictable for an operator watching logs (a 429 storm shows a
234
+ recognizable 5/10/20 cadence). ``attempt`` is clamped to the last entry so
235
+ a caller that somehow exceeds the schedule still gets the longest wait
236
+ rather than an IndexError. Jitter de-synchronizes concurrent retries that
237
+ all hit 429 in the same instant; without it, N callers sleep the same
238
+ duration and all retry at once, tripping the cap again.
239
+ """
240
+ delay = _BACKOFF_SECONDS[min(attempt, len(_BACKOFF_SECONDS) - 1)]
241
+ return float(delay + random.random() * jitter)
242
+
243
+
244
+ def _retryable_error(exc: Exception, max_retries: int) -> McpToolError:
245
+ """Wrap a retryable failure that did not recover as an actionable error.
246
+
247
+ The Agent sees ``MCP_RATE_LIMITED`` (429), ``MCP_SERVER_ERROR`` (5xx) or
248
+ ``MCP_TRANSIENT_ERROR`` (transport blip) with a hint that says *slow down*,
249
+ not a bare ``HTTP_429`` / ``MCP_SDK_ERROR`` it would re-send at once. The
250
+ hint is the whole point for non-SDK errors too: without it the Agent's
251
+ reflex on a transient network failure is to retry at once, which is the
252
+ avalanche this layer exists to stop.
253
+ """
254
+ from huaweicloud_mcp_core.errors import McpToolError, wrap_sdk_error
255
+
256
+ # "after N retries" / "after 1 retry" / "retries disabled" — wording must
257
+ # stay correct for max_retries=0 (no retries attempted) and !=1 alike.
258
+ if max_retries == 0:
259
+ _attempt_suffix = "retries disabled"
260
+ elif max_retries == 1:
261
+ _attempt_suffix = "after 1 retry"
262
+ else:
263
+ _attempt_suffix = f"after {max_retries} retries"
264
+
265
+ is_transport = isinstance(exc, _transient_network_exceptions())
266
+
267
+ try:
268
+ from huaweicloudsdkcore.exceptions.exceptions import (
269
+ ServiceResponseException,
270
+ )
271
+ except ImportError:
272
+ pass
273
+ else:
274
+ if isinstance(exc, ServiceResponseException):
275
+ if exc.status_code == 429:
276
+ return McpToolError(
277
+ code="MCP_RATE_LIMITED",
278
+ message=(
279
+ f"APIG rate-limited the request (429) {_attempt_suffix}; "
280
+ f"the per-user quota is saturated."
281
+ ),
282
+ request_id=getattr(exc, "request_id", None),
283
+ hint=(
284
+ "This is a throttle, not a parameter error — do not change the "
285
+ "arguments and retry. Lower the call rate and retry after a pause; "
286
+ "if it persists, ask the operator to raise the APIG per-user quota."
287
+ ),
288
+ )
289
+ return McpToolError(
290
+ code="MCP_SERVER_ERROR",
291
+ message=f"Backend returned HTTP {exc.status_code} {_attempt_suffix}.",
292
+ request_id=getattr(exc, "request_id", None),
293
+ hint=(
294
+ "The cloud service returned a transient server error. Retry after a "
295
+ "short pause; if it persists, the service may be degraded."
296
+ ),
297
+ )
298
+
299
+ if is_transport:
300
+ return McpToolError(
301
+ code="MCP_TRANSIENT_ERROR",
302
+ message=f"Transport failure ({type(exc).__name__}) {_attempt_suffix}.",
303
+ hint=(
304
+ "This is a transient transport failure, not a parameter error — do not "
305
+ "change the arguments and retry at once. Wait a moment and retry; if it "
306
+ "persists, the network path to the cloud service may be degraded."
307
+ ),
308
+ )
309
+ return wrap_sdk_error(exc)
310
+
311
+
312
+ async def call_sdk(
313
+ fn: Callable[..., Any],
314
+ /,
315
+ *args: Any,
316
+ max_concurrent: int | None = None,
317
+ max_retries: int | None = None,
318
+ retry_jitter: float | None = None,
319
+ **kwargs: Any,
320
+ ) -> Any:
321
+ """Run a synchronous SDK call with bounded concurrency and retry.
322
+
323
+ Drop-in replacement for ``await asyncio.to_thread(fn, *args, **kwargs)``:
324
+ every client method that previously wrote that now writes
325
+ ``await call_sdk(_call)`` instead. ``_call`` is the zero-arg closure each
326
+ method already builds; positional/keyword passthrough keeps it working.
327
+
328
+ The concurrency cap is read from ``HUAWEICLOUD_MCP_MAX_CONCURRENT`` exactly
329
+ once, on first use, and locked in for the life of the process (see
330
+ :func:`_get_semaphore`). ``max_concurrent`` is accepted only so an explicit
331
+ out-of-range value (e.g. ``0``) fails loudly instead of silently building a
332
+ ``Semaphore(0)`` that hangs every call; in production it is always ``None``
333
+ and the env var decides. The retry parameters (``max_retries``/
334
+ ``retry_jitter``) default to module constants and are only overridden via
335
+ explicit arguments — in tests — since a wrong value can silently defeat the
336
+ backoff layer. Passing explicit retry values in production code is not
337
+ supported.
338
+
339
+ The semaphore bounds how many calls are *in flight* to the cloud at once.
340
+ Retry happens *outside* the semaphore slot: a call that hits a transient
341
+ 429/5xx releases its slot, sleeps on backoff (so other calls proceed), then
342
+ re-acquires a slot to retry. This keeps throughput up while a retry sleeps,
343
+ but means an extreme-sustained 429 can starve retries — mitigated by the
344
+ retry cap, after which the caller gets ``MCP_RATE_LIMITED`` and stops.
345
+ """
346
+ from huaweicloud_mcp_core.errors import McpToolError, wrap_sdk_error
347
+
348
+ if max_concurrent is not None and (
349
+ max_concurrent < _CONCURRENT_FLOOR or max_concurrent > _CONCURRENT_CEIL
350
+ ):
351
+ # An explicit caller (tests, or a programmatic integrator) bypassed
352
+ # _env_int; guard the same bounds here too, so max_concurrent=0 does not
353
+ # build a Semaphore(0) and hang every call silently.
354
+ raise RuntimeError(
355
+ f"max_concurrent={max_concurrent!r} is out of range "
356
+ f"[{_CONCURRENT_FLOOR}, {_CONCURRENT_CEIL}]."
357
+ )
358
+ if max_retries is None:
359
+ max_retries = _MAX_RETRIES
360
+ # ``max_retries`` is clamped to the backoff schedule length so a caller that
361
+ # asks for more retries than the schedule has entries cannot index out of
362
+ # range — it just reuses the longest wait (the last entry) for the extra
363
+ # attempts. ``_MAX_RETRIES`` is already within bounds; this only matters for
364
+ # an explicit ``max_retries`` passed in tests.
365
+ if max_retries > len(_BACKOFF_SECONDS):
366
+ max_retries = len(_BACKOFF_SECONDS)
367
+ if retry_jitter is None:
368
+ retry_jitter = _RETRY_JITTER
369
+
370
+ sem = await _get_semaphore()
371
+ attempt = 0
372
+ while True:
373
+ try:
374
+ async with sem:
375
+ return await asyncio.to_thread(fn, *args, **kwargs)
376
+ except McpToolError:
377
+ raise
378
+ except Exception as exc:
379
+ if not _is_retryable(exc) or attempt >= max_retries:
380
+ if _is_retryable(exc):
381
+ raise _retryable_error(exc, max_retries) from exc
382
+ raise wrap_sdk_error(exc) from exc
383
+
384
+ # Transient failure: release the slot, back off, then re-acquire a
385
+ # slot to retry. Other calls proceed during the sleep.
386
+ delay = _backoff_delay(attempt, retry_jitter)
387
+ await asyncio.sleep(delay)
388
+ attempt += 1
@@ -0,0 +1,37 @@
1
+ Metadata-Version: 2.5
2
+ Name: mcp-server-ecs-common
3
+ Version: 0.1.0
4
+ Summary: Shared utilities for Huawei Cloud ECS MCP servers (ecs & ecs-lifecycle)
5
+ License-Expression: MIT
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+
9
+ # mcp-server-ecs-common
10
+
11
+ > **语言切换:** [English](./README_en.md) | 中文
12
+
13
+ 华为云 ECS MCP Server 家族的共享工具库。本包服务于 **ecs-readonly**(`mcp_server_ecs_readonly`)与
14
+ **ecs-lifecycle**(`mcp_server_ecs_lifecycle`)两个 server 包,避免两者重复实现
15
+ SDK 响应转换与分页逻辑。
16
+
17
+ ## 内容
18
+
19
+ - `sdk_to_dict(obj)` —— 递归将 `huaweicloudsdk` 响应对象转为纯 JSON 兼容数据
20
+ (处理标量、bytes、dict、list、带 `to_dict()` 的对象,以及暴露 `__dict__` 的对象)。
21
+ - `paginate(fetch, *, result_key, page_size, max_pages=None, advance=None)` ——
22
+ 收集分页列表接口的全部条目,在 servers / flavors / subnets 等场景共用同一套分页
23
+ 循环骨架。
24
+ - `call_sdk(fn, ...)` —— 两个 server 共享的 SDK 调用流控层,替代
25
+ `asyncio.to_thread`:进程级信号量限并发(`HUAWEICLOUD_MCP_MAX_CONCURRENT`,默认
26
+ 20),429/5xx 与传输层错误重试最多三次(固定退避 5s/10s/20s + 抖动),仍失败抛语义化错误码
27
+ (`MCP_RATE_LIMITED` / `MCP_SERVER_ERROR` / `MCP_TRANSIENT_ERROR`,均带"不要立即
28
+ 重试"的 hint)。
29
+
30
+ ## 开发
31
+
32
+ 本包是 `mcp-server-ecs-readonly` 与 `mcp-server-ecs-lifecycle` 的本地路径依赖。除标准库外
33
+ 无运行时依赖。
34
+
35
+ ```bash
36
+ uv run pytest
37
+ ```
@@ -0,0 +1,9 @@
1
+ mcp_server_ecs_common/__init__.py,sha256=Arl5gGY19Oe3PdsEmR4f0OyrsmQ1CmdskFPaDulmJho,372
2
+ mcp_server_ecs_common/convert.py,sha256=ZZVX4HKMc43dLrxz3Fe0OHzan4e0Jbg5uHDEgqTu5uM,1609
3
+ mcp_server_ecs_common/paginate.py,sha256=gwrYgGT_IO_-YT3weMICiFdMWQ7Jd4oZBMRsXHq6aaM,3078
4
+ mcp_server_ecs_common/testsupport.py,sha256=miYzz2qpU7r2q4-ZfAUnfmR97v6pHnpiVU54YEl-dmA,1681
5
+ mcp_server_ecs_common/throttle.py,sha256=xBoqvHvFm7jnQhMeicPRL-WcdGQAehN8knxFB7KdW5c,18955
6
+ mcp_server_ecs_common/py.typed,sha256=sREocYY17wR152UmxuTfl-GGP-UsnzHuNwfNuybB7UM,82
7
+ mcp_server_ecs_common-0.1.0.dist-info/METADATA,sha256=4WCNQXKls62ZNUXy4ncT78YlU2cuayOa5Fw5sCRBOjs,1578
8
+ mcp_server_ecs_common-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
9
+ mcp_server_ecs_common-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any