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

polaris/pkg/flow/register.py

@@ -0,0 +1,210 @@
+# 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.
+
+"""Instance heartbeat scheduling and Java-compatible re-registration."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import random
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from weakref import WeakValueDictionary
+
+import polaris.api.log as logger
+from polaris.pkg.model.error import SDKError, ServerCode
+from polaris.pkg.model.server import (
+    InstanceDeRegisterRequest,
+    InstanceHeartbeatRequest,
+    InstanceRegisterRequest,
+    InstanceRegisterResponse,
+)
+
+InstanceKey = tuple[str, str, str, int]
+base_logger = logger.get_logger("base")
+
+
+def _instance_key(request: InstanceRegisterRequest | InstanceDeRegisterRequest) -> InstanceKey:
+    return request.namespace, request.service, request.host, request.port
+
+
+@dataclass
+class RegisterState:
+    """Keep a private request snapshot and the tasks for one registered instance."""
+
+    request: InstanceRegisterRequest
+    first_register_time: float
+    heartbeat_task: asyncio.Task[None] | None = None
+    re_register_task: asyncio.Task[None] | None = None
+    heartbeat_fail_count: int = 0
+    re_register_count: int = 0
+    instance_ids: set[str] = field(default_factory=set)
+
+
+class RegisterStateManager:
+    """Own registration tasks on the SDK loop and cancel them before deregistration."""
+
+    def __init__(
+        self,
+        register: Callable[[InstanceRegisterRequest], Awaitable[InstanceRegisterResponse]],
+        heartbeat: Callable[[InstanceHeartbeatRequest], Awaitable[None]],
+        min_register_interval: int,
+    ) -> None:
+        self._register = register
+        self._heartbeat = heartbeat
+        self._min_register_interval = min_register_interval / 1000
+        self._states: dict[InstanceKey, RegisterState] = {}
+        self._locks: WeakValueDictionary[InstanceKey, asyncio.Lock] = WeakValueDictionary()
+        self._closed = False
+
+    def _key_for(self, request: InstanceRegisterRequest | InstanceDeRegisterRequest) -> InstanceKey:
+        if request.instance_id:
+            for key, state in self._states.items():
+                if request.instance_id in state.instance_ids:
+                    return key
+        return _instance_key(request)
+
+    def operation_lock(self, request: InstanceRegisterRequest | InstanceDeRegisterRequest) -> asyncio.Lock:
+        """Serialize explicit registration and deregistration for the same instance."""
+        key = self._key_for(request)
+        lock = self._locks.get(key)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._locks[key] = lock
+        return lock
+
+    async def put(self, request: InstanceRegisterRequest) -> None:
+        """Replace an instance's schedule without creating duplicate heartbeat tasks."""
+        previous = self._states.pop(_instance_key(request), None)
+        if previous is not None:
+            await self._cancel([previous])
+        if self._closed:
+            return
+        state = RegisterState(copy.deepcopy(request), asyncio.get_running_loop().time())
+        state.instance_ids.add(request.instance_id)
+        self._states[_instance_key(request)] = state
+        state.heartbeat_task = asyncio.create_task(self._run_heartbeat(state))
+        base_logger.info(
+            "instance heartbeat task started namespace=%s service=%s host=%s port=%s ttl=%ss",
+            request.namespace, request.service, request.host, request.port, request.ttl,
+        )
+
+    async def remove(
+        self, request: InstanceRegisterRequest | InstanceDeRegisterRequest,
+    ) -> InstanceRegisterRequest | None:
+        """Cancel heartbeats and pending re-registration by instance ID or address."""
+        key = self._key_for(request)
+        state = self._states.get(key)
+        if state is None:
+            return
+        # An explicit ID takes precedence over possibly stale address fields.
+        if request.instance_id and request.instance_id not in state.instance_ids:
+            return
+        self._states.pop(key)
+        await self._cancel([state])
+        return state.request
+
+    async def close(self) -> None:
+        """Stop and await all tasks before the SDK closes its connector."""
+        self._closed = True
+        states = list(self._states.values())
+        self._states.clear()
+        await self._cancel(states)
+
+    @staticmethod
+    async def _cancel(states: list[RegisterState]) -> None:
+        tasks = [task for state in states for task in (state.heartbeat_task, state.re_register_task)
+                 if task is not None]
+        for state in states:
+            if state.heartbeat_task is None:
+                continue
+            request = state.request
+            base_logger.info(
+                "instance heartbeat task stopped namespace=%s service=%s host=%s port=%s",
+                request.namespace, request.service, request.host, request.port,
+            )
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    def _active(self, state: RegisterState) -> bool:
+        return not self._closed and self._states.get(_instance_key(state.request)) is state
+
+    async def _run_heartbeat(self, state: RegisterState) -> None:
+        loop = asyncio.get_running_loop()
+        interval = state.request.ttl
+        next_tick = loop.time() + interval
+        while self._active(state):
+            await asyncio.sleep(max(0, next_tick - loop.time()))
+            if not self._active(state):
+                return
+            await self._heartbeat_once(state)
+            next_tick += interval
+            # Skip missed ticks; do not overlap RPCs or burst after a slow request.
+            if next_tick < loop.time():
+                next_tick = loop.time() + interval
+
+    async def _heartbeat_once(self, state: RegisterState) -> None:
+        request = state.request
+        heartbeat = InstanceHeartbeatRequest(
+            request.service, request.service_token, request.namespace, request.instance_id,
+            request.host, request.port,
+        )
+        try:
+            await self._heartbeat(heartbeat)
+            state.heartbeat_fail_count = 0
+            base_logger.debug(
+                "instance heartbeat success namespace=%s service=%s host=%s port=%s",
+                request.namespace, request.service, request.host, request.port,
+            )
+        except Exception as error:
+            if isinstance(error, SDKError) and error.server_code == ServerCode.NotFoundResource:
+                state.heartbeat_fail_count += 1
+            else:
+                state.heartbeat_fail_count = 0
+            logger.error("instance heartbeat failed for %s: %s", _instance_key(request), error)
+
+        if (not self._active(state) or state.heartbeat_fail_count < 2
+                or asyncio.get_running_loop().time() - state.first_register_time < self._min_register_interval):
+            return
+        if state.re_register_task is not None and not state.re_register_task.done():
+            return
+        attempt = state.re_register_count
+        delay = 0 if attempt == 0 else min(
+            request.ttl * 2 ** min(attempt - 1, 6) + random.randrange(request.ttl), 60,
+        )
+        state.re_register_count += 1
+        state.re_register_task = asyncio.create_task(self._re_register(state, delay))
+
+    async def _re_register(self, state: RegisterState, delay: float) -> None:
+        if delay:
+            await asyncio.sleep(delay)
+        if not self._active(state):
+            return
+        try:
+            response = await self._register(state.request)
+            state.request.instance_id = response.instance_id
+            state.instance_ids.add(response.instance_id)
+            state.heartbeat_fail_count = 0
+            state.re_register_count = 0
+            base_logger.info(
+                "instance re-registered namespace=%s service=%s host=%s port=%s instanceId=%s",
+                state.request.namespace, state.request.service,
+                state.request.host, state.request.port, response.instance_id,
+            )
+        except Exception as error:
+            logger.warning("instance re-registration failed for %s: %s", _instance_key(state.request), error)

polaris/pkg/flow/skill.py

@@ -0,0 +1,110 @@
+# 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 orchestration with network-error persistence fallback."""
+
+from dataclasses import fields
+
+from polaris.pkg.model.error import ErrorCode, SDKError, ServerCode
+from polaris.pkg.model.skill import (
+    SkillDownloadResponse, SkillGetResponse, SkillListResponse, SkillResource,
+    SkillResourceVersion, SkillStorageInfo, SkillVersionInfo,
+)
+from polaris.plugin.skill.persistence import SkillPersistentHandler
+
+
+def _resource(proto):
+    values = {item.name: getattr(proto, item.name) for item in fields(SkillResource)}
+    values.update(tags=list(proto.tags), examples=list(proto.examples), ext=dict(proto.ext),
+                  version_info=SkillVersionInfo(proto.version_info.active_version,
+                                               proto.version_info.latest_version, proto.version_info.total_versions))
+    return SkillResource(**values)
+
+
+def _version(proto):
+    values = {item.name: getattr(proto, item.name) for item in fields(SkillResourceVersion)}
+    values["storage"] = SkillStorageInfo(proto.storage.provider, list(proto.storage.files),
+                                         proto.storage.scope, proto.storage.content_digest)
+    return SkillResourceVersion(**values)
+
+
+class SkillFlow:
+    """Run Skill reads on a context's owner loop and persist successful responses."""
+
+    def __init__(self, connector, config, logger):
+        self.connector = connector
+        self.config = config
+        self.logger = logger
+        self.persistence = None
+        if config.persist_enable:
+            try:
+                self.persistence = SkillPersistentHandler(config, logger)
+            except OSError as error:
+                self.logger.warning("Skill backup initialization failed; using remote reads only: %s", error)
+
+    async def _read(self, request, operation):
+        loaded = False
+        try:
+            method = self.connector.get_skill if operation == "get" else self.connector.download_skill
+            result = await method(request)
+        except SDKError as error:
+            if (error.err_code != ErrorCode.ErrCodeNetworkError or not self.config.fallback_to_local_cache
+                    or self.persistence is None):
+                raise
+            result = await self.persistence.load(request, operation)
+            if result is None or result.code not in (0, ServerCode.ExecuteSuccess):
+                raise error
+            loaded = True
+            self.logger.warning("use local Skill backup for %s/%s", request.namespace, request.name)
+        if loaded:
+            version = result.version.version if operation == "get" else result.version
+            if (not version or (request.version and request.version != version)
+                    or (operation == "get" and (result.resource.name != request.name
+                                                or result.resource.namespace != request.namespace))):
+                raise SDKError(ErrorCode.ErrCodeInvalidResponse, "Skill backup identity or version mismatch")
+            if operation == "download" and result.total_size:
+                size = len(result.zip_chunk) if request.format == "zip" else len(result.content.encode("utf-8"))
+                if size != result.total_size:
+                    raise SDKError(ErrorCode.ErrCodeInvalidResponse, "Skill backup size mismatch")
+        if not loaded and result.code in (0, ServerCode.ExecuteSuccess) and self.persistence is not None:
+            try:
+                self.persistence.save_success(request, result, operation)
+            except (OSError, SDKError) as error:
+                self.logger.warning("failed to persist Skill %s/%s: %s", request.namespace, request.name, error)
+        return result, loaded
+
+    async def get_skill(self, request):
+        """Fetch published content with network-only local fallback."""
+        response, loaded = await self._read(request, "get")
+        return SkillGetResponse(_resource(response.resource), _version(response.version), response.content,
+                                loaded, response.code, response.info)
+
+    async def list_skills(self, request):
+        """Fetch remote search results without storing or falling back to a list."""
+        response = await self.connector.list_skills(request)
+        return SkillListResponse(response.total, [_resource(item) for item in response.resources],
+                                 response.code, response.info)
+
+    async def download_skill(self, request):
+        """Return one complete download with network-only local fallback."""
+        response, loaded = await self._read(request, "download")
+        return SkillDownloadResponse(response.version, response.content_type, response.content,
+                                     response.zip_chunk, response.total_size, response.filename, loaded,
+                                     response.code, response.info)
+
+    def destroy(self):
+        """Drain pending backups when the context closes."""
+        if self.persistence is not None:
+            self.persistence.destroy()

polaris/pkg/flow/sync_flow.py

@@ -0,0 +1,20 @@
+# 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.flow.impl import Engine
+
+
+class SyncEngine(Engine):
+    """Legacy name for the Engine's shared synchronous and asynchronous flows."""

polaris/pkg/model/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+

polaris/pkg/model/context.py

@@ -0,0 +1,53 @@
+# 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 threading import RLock
+from uuid import uuid4
+
+ContextKeyEngine = "engine"
+ContextKeyEventCenter = "event_center"
+
+
+class ValueContext:
+    """Hold identity and thread-safe values belonging to one SDK context."""
+
+    def __init__(self):
+        self.client_id = str(uuid4())
+        self.logger = None
+        self.core_map = {}
+        self._lock = RLock()
+
+    def set_value(self, key: str, value):
+        """Store a value without touching any other SDK context."""
+        with self._lock:
+            self.core_map[key] = value
+
+    def get_value(self, key: str):
+        """Read a value owned by this context."""
+        with self._lock:
+            return self.core_map[key]
+
+    def get_client_id(self) -> str:
+        """Return the stable, unique identity used in ReportClient."""
+        return self.client_id
+
+    def clear(self):
+        """Release runtime references after context destruction."""
+        with self._lock:
+            self.core_map.clear()
+
+
+def new_value_context():
+    return ValueContext()

polaris/pkg/model/contract.py

@@ -0,0 +1,89 @@
+# 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.
+
+"""Framework-independent service contract models."""
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+from polarismesh_specification.api.v1.service_manage import contract_pb2
+
+from polaris.pkg.model.error import ErrorCode, SDKError
+
+
+class ServiceFeatureType(IntEnum):
+    """Capability categories defined by the service contract protocol."""
+
+    MCP_TOOL = contract_pb2.Service_Feature_Type_MCP_Tool
+    MCP_RESOURCE = contract_pb2.Service_Feature_Type_MCP_Resource
+    MCP_PROMPT = contract_pb2.Service_Feature_Type_MCP_Prompt
+
+
+class ServiceFeatureStatus(IntEnum):
+    """Availability of a published service capability."""
+
+    ENABLED = contract_pb2.Service_Feature_Status_Enabled
+    DISABLED = contract_pb2.Service_Feature_Status_Disabled
+
+
+@dataclass
+class ServiceFeature:
+    """One tool, resource or prompt in a service contract."""
+
+    type: int
+    name: str
+    description: str = ""
+    content: str = ""
+    status: int = ServiceFeatureStatus.ENABLED
+
+
+@dataclass
+class InterfaceDescriptor:
+    """One request or notification handler exposed by a service."""
+
+    name: str = ""
+    method: str = ""
+    path: str = ""
+    content: str = ""
+
+
+@dataclass
+class GetServiceContractRequest:
+    """Identify a service contract by namespace, service, protocol and version."""
+
+    namespace: str
+    service: str
+    protocol: str = ""
+    version: str = ""
+    timeout: int = 0
+
+    def validate(self):
+        """Check the service identity and timeout."""
+        if not self.namespace.strip() or not self.service.strip() or self.timeout < 0:
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument, "contract namespace/service are required, timeout >=0")
+
+
+@dataclass
+class ServiceContract(GetServiceContractRequest):
+    """A service contract used for reporting and retrieval."""
+
+    name: str = ""
+    revision: str = ""
+    content: str = ""
+    service_features: list[ServiceFeature] = field(default_factory=list)
+    interfaces: list[InterfaceDescriptor] = field(default_factory=list)
+
+
+ReportServiceContractRequest = ServiceContract

polaris/pkg/model/core.py

@@ -0,0 +1,51 @@
+# 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.
+
+class EventType:
+    Unknown = 0
+
+    Instance = 0x2001
+
+    Routing = 0x2002
+
+
+# 服务的唯一标识key
+class ServiceKey:
+    def __init__(self, namespace: str, service: str):
+        self.namespace: str = namespace
+        self.service: str = service
+
+    def __hash__(self):
+        return hash(self.namespace + self.service)
+
+    def get_namespace(self):
+        return self.namespace
+
+    def get_service(self):
+        return self.service
+
+
+class ServiceEventKey(ServiceKey):
+    def __init__(self, namespace: str, service: str, event_type: int):
+        ServiceKey.__init__(self, namespace, service)
+        self.event_type = event_type
+
+    def __eq__(self, other):
+        return (self.service == other.service and
+                self.namespace == other.namespace and
+                self.event_type == other.event_type)
+
+    def __hash__(self):
+        return hash(self.namespace + self.service + str(self.event_type))

polaris/pkg/model/engine.py

@@ -0,0 +1,83 @@
+# 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 ServiceCallResult
+from polaris.pkg.model.rule import GetServiceRuleRequest, ServiceRuleResponse
+from polaris.pkg.model.server import (
+    InstanceDeRegisterRequest,
+    InstanceHeartbeatRequest,
+    InstanceRegisterRequest,
+    InstanceRegisterResponse,
+)
+
+
+class BaseEngine(object):
+    def destroy(self):
+        pass
+
+    def sync_get_one_instance(self, request):
+        pass
+
+    def sync_get_instances(self, request):
+        pass
+
+    def sync_register(self, request: InstanceRegisterRequest) -> InstanceRegisterResponse:
+        pass
+
+    def sync_deregister(self, request: InstanceDeRegisterRequest) -> None:
+        pass
+
+    async def async_register(self, request: InstanceRegisterRequest) -> InstanceRegisterResponse:
+        pass
+
+    async def async_deregister(self, request: InstanceDeRegisterRequest) -> None:
+        pass
+
+    async def async_get_one_instance(self, request):
+        pass
+
+    async def async_get_instances(self):
+        pass
+
+    def sync_get_services(self):
+        pass
+
+    async def async_get_services(self):
+        pass
+
+    def sync_heartbeat(self, request: InstanceHeartbeatRequest) -> None:
+        pass
+
+    async def async_heartbeat(self, request: InstanceHeartbeatRequest) -> None:
+        pass
+
+    def sync_update_service_call_result(self, req: ServiceCallResult):
+        pass
+
+    def sync_get_service_rule(self, event_type: int, req: GetServiceRuleRequest) -> ServiceRuleResponse:
+        pass
+
+    def sync_lossless_register(self, request) -> None:
+        pass
+
+    async def async_lossless_register(self, request) -> None:
+        pass
+
+    def sync_lossless_deregister(self, request) -> None:
+        pass
+
+    async def async_lossless_deregister(self, request) -> None:
+        pass
+