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.
- mcp_server_ecs_common/__init__.py +10 -0
- mcp_server_ecs_common/convert.py +41 -0
- mcp_server_ecs_common/paginate.py +76 -0
- mcp_server_ecs_common/py.typed +2 -0
- mcp_server_ecs_common/testsupport.py +56 -0
- mcp_server_ecs_common/throttle.py +388 -0
- mcp_server_ecs_common-0.1.0.dist-info/METADATA +37 -0
- mcp_server_ecs_common-0.1.0.dist-info/RECORD +9 -0
- mcp_server_ecs_common-0.1.0.dist-info/WHEEL +4 -0
|
@@ -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,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,,
|