polaris-python 0.0.1.dev3__py3-none-any.whl

polaris/plugin/service_router/metadata.py

@@ -0,0 +1,84 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+from polaris.pkg.config.default import DefaultConf
+from polaris.pkg.model import service
+from polaris.pkg.model.error import ErrorCode, SDKError
+from polaris.plugin.service_router.base import BaseServiceRouter, RouteInfo, RouteResult
+from polaris.plugin_manager import InitContext, PluginType, register_plugin
+
+_FAILOVER_KEY = "internal-metadata-failover-type"
+_FAILOVERS = {"none", "all", "others"}
+
+
+def _as_dict(metadata) -> dict:
+    if not metadata:
+        return {}
+    return {key: metadata[key] for key in metadata}
+
+
+def _matches(instance: service.Instance, required: dict) -> bool:
+    metadata = _as_dict(instance.get_metadata())
+    return all(metadata.get(key) == value for key, value in required.items())
+
+
+def _missing_any_key(instance: service.Instance, required: dict) -> bool:
+    metadata = _as_dict(instance.get_metadata())
+    return any(key not in metadata for key in required)
+
+
+@register_plugin(PluginType.SERVICE_ROUTER, DefaultConf.DefaultServiceRouterMetadata)
+class MetadataRouter(BaseServiceRouter):
+    """Keep instances whose metadata contains every requested key and value."""
+
+    def __init__(self, init_ctx: InitContext = None):
+        plugin = {}
+        if init_ctx is not None and init_ctx.config is not None:
+            plugin = init_ctx.config.get_consumer().get_service_router().plugin.get(
+                DefaultConf.DefaultServiceRouterMetadata, {}) or {}
+        failover = plugin.get("metadataFailOverType", plugin.get("metadata_fail_over_type", "all"))
+        if failover not in _FAILOVERS:
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument,
+                           "metadataRouter.metadataFailOverType must be one of none, all, others")
+        self.failover = failover if failover in _FAILOVERS else "all"
+
+    def enable(self, route_info: RouteInfo, instances: service.ServiceInstances) -> bool:
+        if not route_info.chain_enables.get(DefaultConf.DefaultServiceRouterMetadata, True):
+            return False
+        return bool(_as_dict(route_info.metadata))
+
+    def get_filtered_instances(self, route_info: RouteInfo, instances: service.ServiceInstances) -> RouteResult:
+        required = _as_dict(route_info.metadata)
+        matched = [instance for instance in instances.get_instances() if _matches(instance, required)]
+        if matched:
+            return RouteResult(matched)
+
+        failover = self._failover(route_info, instances)
+        if failover == "all":
+            return RouteResult(list(instances.get_instances()))
+        if failover == "others":
+            return RouteResult([instance for instance in instances.get_instances()
+                                if _missing_any_key(instance, required)])
+        service_name = route_info.dest_service.get_service() if route_info.dest_service is not None else ""
+        raise SDKError(ErrorCode.ErrCodeRouteRuleNotMatch,
+                       f"can not find any instance by metadata for service {service_name}")
+
+    def _failover(self, route_info: RouteInfo, instances: service.ServiceInstances) -> str:
+        if route_info.metadata_failover_type in _FAILOVERS:
+            return route_info.metadata_failover_type
+        service_failover = _as_dict(instances.get_metadata()).get(_FAILOVER_KEY)
+        if service_failover in _FAILOVERS:
+            return service_failover
+        return self.failover

polaris/plugin/service_router/recover.py

@@ -0,0 +1,62 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+from polaris.pkg.config.default import DefaultConf
+from polaris.pkg.model import service
+from polaris.pkg.model.service import CBStatusEnum
+from polaris.plugin.service_router.base import BaseServiceRouter, RouteInfo, RouteResult
+from polaris.plugin_manager import InitContext, PluginType, register_plugin
+
+
+def _config_bool(plugin: dict, *keys, default: bool) -> bool:
+    for key in keys:
+        if key in plugin:
+            value = plugin[key]
+            if isinstance(value, str):
+                return value.strip().lower() in {"1", "true", "yes", "on"}
+            return bool(value)
+    return default
+
+
+@register_plugin(PluginType.SERVICE_ROUTER, DefaultConf.DefaultServiceRouterRecover)
+class RecoverRouter(BaseServiceRouter):
+    """Keep healthy instances and restore the input list when every instance is unavailable."""
+
+    def __init__(self, init_ctx: InitContext = None):
+        plugin = {}
+        if init_ctx is not None and init_ctx.config is not None:
+            plugin = init_ctx.config.get_consumer().get_service_router().plugin.get(
+                DefaultConf.DefaultServiceRouterRecover, {}) or {}
+        self.exclude_circuit_break = _config_bool(
+            plugin, "excludeCircuitBreakInstances", "exclude_circuit_break_instances", default=True)
+        self.all_recover = _config_bool(plugin, "allRecoverEnable", "all_recover_enable", default=True)
+
+    def enable(self, route_info: RouteInfo, instances: service.ServiceInstances) -> bool:
+        return route_info.chain_enables.get(DefaultConf.DefaultServiceRouterRecover, True)
+
+    def get_filtered_instances(self, route_info: RouteInfo, instances: service.ServiceInstances) -> RouteResult:
+        exclude_circuit_break = self.exclude_circuit_break and not route_info.include_circuitbreak_instances
+        healthy = []
+        for instance in instances.get_instances():
+            if not route_info.include_unhealthy_instances and not instance.is_healthy():
+                continue
+            if exclude_circuit_break:
+                status = instance.get_circuit_breaker_status()
+                if status is not None and status.get_status() == CBStatusEnum.Open:
+                    continue
+            healthy.append(instance)
+        if self.all_recover and not healthy:
+            return RouteResult(list(instances.get_instances()))
+        return RouteResult(healthy)

polaris/plugin/service_router/util.py

@@ -0,0 +1,54 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+from polaris.pkg.model.service import Instance
+from typing import List
+from polaris.api.log import get_logger
+
+from .base import RouteInfo
+
+logger = get_logger("route")
+
+
+# 从subset中选取可用的实例
+def get_available_instances(
+        instances: List[Instance], route_info: RouteInfo, percent_of_min_instances: float) -> List[Instance]:
+    available_instances = calc_available_instances(
+        route_info.include_unhealthy_instances, route_info.include_circuitbreak_instances, instances)
+
+    min_instances = int(percent_of_min_instances * len(instances))
+    if len(instances) > 0 and len(available_instances) <= min_instances:
+        logger.warning("all instance is down and return all for %s", route_info.dest_service.get_service())
+        available_instances = instances
+    return available_instances
+
+
+# 计算subset中的可用实例
+def calc_available_instances(
+        include_unhealthy_instances: bool, include_circuitbreak_instances: bool, instances: List[Instance]) -> List[
+    Instance]:
+    available_instances = []
+    if len(instances) == 0:
+        return available_instances
+    for i in range(len(instances)):
+        instance = instances[i]
+        if not include_unhealthy_instances and not instance.is_healthy():
+            continue
+        if not include_circuitbreak_instances:
+            cb_status = instance.get_circuit_breaker_status()
+            if cb_status is not None and not cb_status.is_available():
+                continue
+        available_instances.append(instance)
+    return available_instances

polaris/plugin/skill/__init__.py

@@ -0,0 +1,16 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+"""Read-only Skill transport and persistence plugins."""

polaris/plugin/skill/connector.py

@@ -0,0 +1,127 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+"""Skill RPCs using a separate specification gRPC connection."""
+
+import asyncio
+
+import grpc
+from polarismesh_specification.api.v1.skill_manage import skill_service_pb2 as pb, skill_service_pb2_grpc
+
+from polaris.pkg.model.error import ErrorCode, SDKError, ServerCode, ensure_response
+from polaris.plugin.server_connector.grpc_connector.connection import GrpcConnection, GrpcSettings, _request_id
+from polaris.plugin_manager import PluginType, register_plugin
+from polaris.plugin.server_connector.grpc_connector.tls import channel_credentials
+
+
+@register_plugin(PluginType.SKILL_CONNECTOR, "polaris")
+class SkillConnector:
+    """Own the independent Skill channels and validate streamed downloads."""
+
+    def __init__(self, init_ctx):
+        self.config = init_ctx.config.get_ai().get_skill().get_server_connector()
+        api = init_ctx.config.get_global().get_api()
+        self.connection = GrpcConnection(
+            GrpcSettings(self.config.addresses, self.config.message_timeout / 1000,
+                         self.config.token, api.max_retry_times, api.retry_interval / 1000,
+                         credentials=channel_credentials(self.config)),
+            context_logger=init_ctx.logger, stub_factory=skill_service_pb2_grpc.PolarisSkillStub,
+        )
+
+    async def get_skill(self, request):
+        """Fetch one published skill and preserve the server response code."""
+        response = ensure_response(await self.connection._unary(
+            "GetSkill", pb.GetSkillRequest(namespace=request.namespace, name=request.name, version=request.version),
+            timeout_seconds=(request.timeout or self.config.message_timeout) / 1000,
+        ), (0, ServerCode.ExecuteSuccess, ServerCode.NotFoundResource))
+        if response.code in (0, ServerCode.ExecuteSuccess):
+            if (response.resource.name != request.name or response.resource.namespace != request.namespace
+                    or not response.version.version or (request.version and response.version.version != request.version)):
+                raise SDKError(ErrorCode.ErrCodeInvalidResponse, "Skill response identity or version mismatch")
+        return response
+
+    async def list_skills(self, request):
+        """Query one remote page of published skills."""
+        fields = ("namespace", "name", "tag", "owner", "scope", "keyword", "order_by", "order_type", "offset", "limit")
+        return ensure_response(await self.connection._unary(
+            "GetSkillList", pb.ListSkillsRequest(**{key: getattr(request, key) for key in fields}),
+            timeout_seconds=(request.timeout or self.config.message_timeout) / 1000,
+        ), (0, ServerCode.ExecuteSuccess, ServerCode.NotFoundResource))
+
+    async def download_skill(self, request):
+        """Reassemble one whole download; a retry always starts with an empty buffer."""
+        connection = self.connection
+        outgoing = pb.DownloadSkillRequest(namespace=request.namespace, name=request.name, version=request.version,
+                                            tag=request.tag, format=request.format)
+        attempts = connection.settings.retry_attempts + 1
+        last_error = None
+        for attempt in range(attempts):
+            address = connection._addresses[connection._address_index % len(connection._addresses)]
+            stream = None
+            try:
+                stub = await connection._stub(address)
+                stream = stub.DownloadSkill(
+                    outgoing, timeout=(request.timeout or (self.config.download_timeout if request.format == "zip"
+                                                          else self.config.message_timeout)) / 1000,
+                    metadata=_request_id("DownloadSkill") + connection._metadata(),
+                )
+                result = None
+                chunks = []
+                async for part in stream:
+                    ensure_response(part, (0, ServerCode.ExecuteSuccess, ServerCode.NotFoundResource))
+                    if result is None:
+                        result = pb.DownloadSkillResponse()
+                        result.CopyFrom(part)
+                        result.zip_chunk = b""
+                    else:
+                        for key in ("version", "content_type", "filename", "total_size"):
+                            value = getattr(part, key)
+                            if value and getattr(result, key) and value != getattr(result, key):
+                                raise SDKError(ErrorCode.ErrCodeInvalidResponse, f"inconsistent Skill download {key}")
+                            if value:
+                                setattr(result, key, value)
+                        result.content += part.content
+                    chunks.append(part.zip_chunk)
+                    if part.code == ServerCode.NotFoundResource:
+                        return part
+                if result is None:
+                    raise SDKError(ErrorCode.ErrCodeInvalidResponse, "empty Skill download stream")
+                result.zip_chunk = b"".join(chunks)
+                if request.version and result.version != request.version:
+                    raise SDKError(ErrorCode.ErrCodeInvalidResponse, "Skill download returned a different version")
+                size = len(result.zip_chunk) if request.format == "zip" else len(result.content.encode("utf-8"))
+                if result.total_size and result.total_size != size:
+                    raise SDKError(ErrorCode.ErrCodeInvalidResponse, "Skill download size mismatch")
+                return result
+            except grpc.aio.AioRpcError as error:
+                last_error = error
+                if error.code() not in connection._RETRYABLE_STATUS or attempt + 1 >= attempts:
+                    break
+                connection._address_index = (connection._address_index + 1) % len(connection._addresses)
+                await asyncio.sleep(connection.settings.retry_backoff_seconds * 2**attempt)
+            finally:
+                if stream is not None:
+                    cancel = getattr(stream, "cancel", None)
+                    if cancel is not None:
+                        cancel()
+                    else:
+                        close = getattr(stream, "aclose", None)
+                        if close is not None:
+                            await close()
+        raise SDKError(ErrorCode.ErrCodeNetworkError, f"Polaris DownloadSkill failed: {last_error}") from last_error
+
+    async def close(self):
+        """Close only the Skill connection belonging to this context."""
+        await self.connection.close()

polaris/plugin/skill/persistence.py

@@ -0,0 +1,94 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+"""Versioned Skill backups sharing the SDK's atomic writer and retry semantics."""
+
+import os
+from dataclasses import dataclass
+from types import SimpleNamespace
+from urllib.parse import quote_plus
+
+from google.protobuf import json_format
+from polarismesh_specification.api.v1.skill_manage import skill_service_pb2 as pb
+
+from polaris.pkg.config.api import LocalCacheConfig
+from polaris.plugin.local_registry.file_cache import LocalFileCache
+
+
+@dataclass(frozen=True)
+class SkillCacheKey:
+    """Identify one persisted payload independently of instance resources."""
+
+    namespace: str
+    name: str
+    version: str
+    operation: str
+    format: str = ""
+
+
+class SkillPersistentHandler(LocalFileCache):
+    """Persist complete responses and a last-seen active-version pointer."""
+
+    def __init__(self, config, logger):
+        cache = LocalCacheConfig(persist_dir=config.persist_dir,
+                                 persist_max_read_retry=config.persist_max_read_retry,
+                                 persist_max_write_retry=config.persist_max_write_retry,
+                                 persist_retry_interval=config.persist_retry_interval)
+        cache.set_default()
+        context = SimpleNamespace(config=SimpleNamespace(get_consumer=lambda: SimpleNamespace(get_local_cache=lambda: cache)),
+                                  logger=logger)
+        super().__init__(context)
+        self.max_write_retry = config.persist_max_write_retry
+        self.max_read_retry = config.persist_max_read_retry
+
+    def _copy_request(self, key):
+        return key
+
+    def _copy_response(self, data):
+        snapshot = type(data)()
+        snapshot.CopyFrom(data)
+        return snapshot
+
+    def _parse_response(self, key, buf):
+        message = pb.DownloadSkillResponse() if key.operation == "download" else pb.GetSkillResponse()
+        return json_format.Parse(buf.decode("utf-8"), message)
+
+    def get_cache_file_path(self, key):
+        parts = [key.namespace, key.name, key.version, key.operation, key.format]
+        return os.path.join(self.base_dir, "skill#" + "#".join(quote_plus(part, safe="") for part in parts) + ".json")
+
+    def save_success(self, request, response, operation):
+        """Queue the resolved payload before publishing its active pointer."""
+        version = response.version.version if operation == "get" else response.version
+        if not version:
+            return
+        key = SkillCacheKey(request.namespace, request.name, version, operation, getattr(request, "format", ""))
+        self.save(key, response)
+        if not request.version:
+            pointer = pb.GetSkillResponse(code=200000, version={"version": version})
+            self.save(SkillCacheKey(request.namespace, request.name, "", "active"), pointer)
+
+    async def load(self, request, operation):
+        """Resolve a requested or last active version and load its complete payload."""
+        version = request.version
+        if not version:
+            pointer = await self.async_get(SkillCacheKey(request.namespace, request.name, "", "active"), expire=None)
+            if pointer is None:
+                return None
+            version = pointer.version.version
+        if not version:
+            return None
+        return await self.async_get(SkillCacheKey(request.namespace, request.name, version, operation,
+                                                getattr(request, "format", "")), expire=None)

polaris/plugin/stat_reporter/__init__.py

@@ -0,0 +1,16 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+from .prometheus import PrometheusReporter

polaris/plugin/stat_reporter/base.py

@@ -0,0 +1,34 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+"""Context-owned invocation metric exporter contract."""
+
+from abc import ABC, abstractmethod
+
+
+class BaseStatReporter(ABC):
+    """Collect invocation results independently of service governance."""
+
+    @abstractmethod
+    def report(self, result):
+        """Record one invocation."""
+
+    @abstractmethod
+    async def start(self, engine):
+        """Start export on the SDK owner loop."""
+
+    @abstractmethod
+    async def close(self):
+        """Stop export and release HTTP resources."""