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

polaris/pkg/model/error.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.
+
+from typing import Any, Iterable
+
+
+class ErrorCode:
+    # 正常
+    ErrCodeSuccess = 0
+    # 接口参数错误，API接口调用时，对接口参数进行校验失败后的错误码
+    ErrCodeAPIInvalidArgument = 1001
+    # 配置参数校验失败
+    ErrCodeAPIInvalidConfig = 1002
+    # 注册插件、初始化插件、获取插件、销毁插件时发生的错误
+    ErrCodePluginError = 1003
+    # API调用超时无正确返回
+    ErrCodeAPITimeoutError = 1004
+    # SDK状态错误，出现在SDK已经销毁还进行API调用
+    ErrCodeInvalidStateError = 1005
+    # 连接server成功，但是server返回了报错信息
+    ErrCodeServerError = 1006
+    # 连接服务端出现网络异常
+    ErrCodeNetworkError = 1007
+    # 服务熔断发生错误
+    ErrCodeCircuitBreakerError = 1008
+    # 一个实例中包含的信息不合法，如host信息无法正常解析
+    ErrCodeInstanceInfoError = 1009
+    # 当今行负载均衡、服务路由时，传入的服务没有实例信息
+    ErrCodeAPIInstanceNotFound = 1010
+    # 路由规则不合法
+    ErrCodeInvalidRouteRule = 1011
+    # 路由规则无法匹配
+    ErrCodeRouteRuleNotMatch = 1012
+    # server返回的信息不合法
+    ErrCodeInvalidResponse = 1013
+    # 获取MaxQueuingTime失败
+    ErrCodeMaxQueuingTimeInvalid = 1015
+    # server返回的信息不合法
+    ErrCodeDataNotChange = 1016
+
+
+class ServerCode:
+    """Polaris response codes used by SDK control flow."""
+
+    ExecuteSuccess = 200000
+    DataNotChange = 200001
+    NoNeedUpdate = 200002
+    ExistedResource = 400201
+    NotFoundResource = 400202
+    NotFoundService = 400301
+
+
+class SDKError(Exception):
+    """SDK failure with a stable local code and optional server response code."""
+
+    def __init__(self, err_code: int, msg: str, server_code: int | None = None):
+        super().__init__(err_code, msg)
+        self.err_code = err_code
+        self.msg = msg
+        self.server_code = server_code
+
+
+def response_code(response: Any) -> int:
+    """Return an integer code from a specification response."""
+    code = getattr(response, "code", None)
+    return int(getattr(code, "value", code or 0))
+
+
+def response_info(response: Any) -> str:
+    """Return response information from a protobuf wrapper."""
+    info = getattr(response, "info", None)
+    return str(getattr(info, "value", info or "Polaris server request failed"))
+
+
+def ensure_response(response: Any, accepted: Iterable[int] = (ServerCode.ExecuteSuccess,)) -> Any:
+    """Validate a Polaris response and preserve data-not-change semantics."""
+    code = response_code(response)
+    if code in accepted:
+        return response
+    if code in {ServerCode.DataNotChange, ServerCode.NoNeedUpdate}:
+        raise SDKError(ErrorCode.ErrCodeDataNotChange, response_info(response), server_code=code)
+    raise SDKError(ErrorCode.ErrCodeServerError, response_info(response), server_code=code)

polaris/pkg/model/event.py

@@ -0,0 +1,159 @@
+# 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 event center for capabilities implemented by this SDK."""
+
+from dataclasses import dataclass, field
+from threading import RLock
+import time
+
+
+class SDKEventType:
+    """Only event categories backed by implemented runtime behavior."""
+
+    INSTANCE = "INSTANCE"
+    CIRCUIT_BREAKING = "CIRCUIT_BREAKING"
+
+
+class SDKEventName:
+    INSTANCE_THREAD_END = "InstanceThreadEnd"
+    ON_SERVICE_ADDED = "OnServiceAdded"
+    ON_SERVICE_UPDATED = "OnServiceUpdated"
+    ON_SERVICE_DELETED = "OnServiceDeleted"
+    CIRCUIT_BREAKER_OPEN = "CircuitBreakerOpen"
+    CIRCUIT_BREAKER_HALF_OPEN = "CircuitBreakerHalfOpen"
+    CIRCUIT_BREAKER_CLOSE = "CircuitBreakerClose"
+
+
+class SDKEventStatus:
+    OPEN = "OPEN"
+    CLOSE = "CLOSE"
+    HALF_OPEN = "HALF_OPEN"
+
+
+# Java EventConstants pairs this SDK can emit. Cache lifecycle names stay local.
+_REMOTE_EVENT_KEYS = frozenset({
+    (SDKEventType.INSTANCE, SDKEventName.INSTANCE_THREAD_END),
+    (SDKEventType.CIRCUIT_BREAKING, SDKEventName.CIRCUIT_BREAKER_OPEN),
+    (SDKEventType.CIRCUIT_BREAKING, SDKEventName.CIRCUIT_BREAKER_HALF_OPEN),
+    (SDKEventType.CIRCUIT_BREAKING, SDKEventName.CIRCUIT_BREAKER_CLOSE),
+})
+
+
+def is_remote_reportable(event) -> bool:
+    """Return whether Java EventReporter would accept this event type and name."""
+    return (event.event_type, event.event_name) in _REMOTE_EVENT_KEYS
+
+
+@dataclass(frozen=True)
+class SDKEvent:
+    """One immutable event emitted by an implemented SDK capability."""
+
+    event_type: str
+    event_name: str
+    timestamp: int
+    client_id: str
+    namespace: str
+    service: str
+    client_ip: str = ""
+    old_value: object = None
+    new_value: object = None
+    instance_id: str = ""
+    host: str = ""
+    port: int = 0
+    previous_status: str = ""
+    current_status: str = ""
+    rule_name: str = ""
+    reason: str = ""
+    additional: dict = field(default_factory=dict)
+
+    def to_log_message(self):
+        """Format an event using the Java and Go logger field order."""
+        identity = f"{self.instance_id}@{self.host}:{self.port}" if self.instance_id else ""
+        states = f" {self.previous_status}->{self.current_status}" if self.current_status else ""
+        return (f"{self.event_type}|{self.event_name}|{self.timestamp}|{self.client_id}|"
+                f"{self.client_ip}|{identity}{states}|{self.namespace}|{self.service}|{self.reason}")
+
+
+class EventCenter:
+    """Dispatch context-local events without affecting SDK control flow."""
+
+    def __init__(self, value_context=None):
+        self.value_context = value_context
+        self.logger = value_context.logger.get_logger("event") if value_context.logger is not None else None
+        self._lock = RLock()
+        self._listeners = []
+        self.register_listener(self._log_event)
+        if self.logger is not None:
+            self.logger.info("event center initialized")
+
+    @staticmethod
+    def _listener_name(listener):
+        if hasattr(listener, "__name__"):
+            return listener.__name__
+        return type(listener).__name__
+
+    @staticmethod
+    def _invoke(listener, event):
+        method = getattr(listener, "on_sdk_event", None)
+        if method is not None:
+            return method(event)
+        return listener(event)
+
+    def register_listener(self, listener, event_type: str | None = None):
+        """Register a callable or on_sdk_event object, optionally for one event type."""
+        if not callable(listener) and not hasattr(listener, "on_sdk_event"):
+            raise TypeError("event listener must be callable or implement on_sdk_event")
+        with self._lock:
+            self._listeners.append((listener, event_type))
+
+    def unregister_listener(self, listener, event_type: str | None = None):
+        """Remove one exact listener registration."""
+        with self._lock:
+            self._listeners = [(item, subscribed_type)
+                               for item, subscribed_type in self._listeners
+                               if item is not listener or subscribed_type != event_type]
+
+    def publish(self, event: SDKEvent):
+        """Notify matching listeners and isolate their exceptions."""
+        with self._lock:
+            listeners = list(self._listeners)
+        for listener, event_type in listeners:
+            if event_type is not None and event_type != event.event_type:
+                continue
+            try:
+                self._invoke(listener, event)
+            except Exception as error:
+                if self.logger is not None:
+                    self.logger.warning("event listener %s failed: %s", self._listener_name(listener), error)
+
+    def close(self):
+        """Drop listeners when the owning context is destroyed."""
+        with self._lock:
+            self._listeners.clear()
+        if self.logger is not None:
+            self.logger.info("event center closed")
+
+    def _log_event(self, event):
+        if self.logger is None:
+            return
+        self.logger.info("%s", event.to_log_message())
+
+
+def now_event(client_id: str, event_type: str, event_name: str, **values) -> SDKEvent:
+    """Build a timestamped event for internal emitters."""
+    return SDKEvent(event_type=event_type, event_name=event_name, timestamp=int(time.time() * 1000),
+                    client_id=client_id, **values)

polaris/pkg/model/lossless.py

@@ -0,0 +1,102 @@
+# 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.
+
+"""Lossless online/offline models aligned with the Java LosslessPolicy plugin."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict
+
+
+class RegisterStatus(Enum):
+    """Whether a lossless instance has completed its registration."""
+
+    UNREGISTERED = "UNREGISTERED"
+    REGISTERED = "REGISTERED"
+
+
+@dataclass(frozen=True)
+class LosslessInstance:
+    """Identify one provider instance participating in lossless lifecycle."""
+
+    namespace: str
+    service: str
+    host: str
+    port: int
+    metadata: Dict[str, str] = field(default_factory=dict)
+
+    def __hash__(self):
+        return hash((self.namespace, self.service, self.host, self.port))
+
+    def __eq__(self, other):
+        if not isinstance(other, LosslessInstance):
+            return NotImplemented
+        return (self.namespace, self.service, self.host, self.port) == (
+            other.namespace, other.service, other.host, other.port)
+
+    @classmethod
+    def from_register_request(cls, request) -> "LosslessInstance":
+        return cls(
+            namespace=request.namespace,
+            service=request.service,
+            host=request.host,
+            port=request.port,
+            metadata=dict(getattr(request, "metadata", {}) or {}),
+        )
+
+
+class InstanceProperties:
+    """Properties a lossless policy may set on the instance before registration."""
+
+    def __init__(self) -> None:
+        self._properties: Dict[str, Any] = {}
+
+    def set_property(self, key: str, value: Any) -> None:
+        self._properties[key] = value
+
+    def get_property(self, key: str) -> Any:
+        return self._properties.get(key)
+
+    @property
+    def properties(self) -> Dict[str, Any]:
+        return dict(self._properties)
+
+
+class LosslessActionProvider(ABC):
+    """Callbacks that perform the real register, deregister and health checks."""
+
+    @abstractmethod
+    def get_name(self) -> str:
+        """Return the provider name used in logs."""
+
+    @abstractmethod
+    async def do_register(self, instance_properties: InstanceProperties):
+        """Register the instance after the lossless-online gate."""
+
+    @abstractmethod
+    async def do_deregister(self):
+        """Deregister the instance when lossless offline is triggered."""
+
+    @abstractmethod
+    def is_enable_health_check(self) -> bool:
+        """Return True to register after a successful health check."""
+
+    @abstractmethod
+    async def do_health_check(self) -> bool:
+        """Return True when the instance is ready to receive traffic."""

polaris/pkg/model/rule.py

@@ -0,0 +1,152 @@
+# 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.core import EventType
+from polarismesh_specification.api.v1.service_manage import response_pb2
+from polaris.pkg.model.error import SDKError, ErrorCode
+
+from abc import ABCMeta, abstractmethod
+
+
+# ServiceRule 服务配置通用接口
+class ServiceRule(metaclass=ABCMeta):
+    @abstractmethod
+    def get_type(self):
+        pass
+
+    @abstractmethod
+    def get_value(self):
+        pass
+
+    @abstractmethod
+    def is_initialized(self):
+        pass
+
+    @abstractmethod
+    def get_revision(self):
+        pass
+
+
+# 通用的服务规则实现
+class SimpleServiceRule(ServiceRule):
+    def __init(self, event_type: EventType, value, initialized: bool, revision: str):
+        self.event_type = event_type
+        self.value = value
+        self.initialized = initialized
+        self.revision = revision
+
+    def get_type(self):
+        return self.event_type
+
+    def get_value(self):
+        return self.value
+
+    def is_initialized(self):
+        return self.initialized
+
+    def get_revision(self):
+        return self.revision
+
+
+# 创建通用的服务规则
+def new_simple_service_rule(event_type: EventType, value, revision: str) -> ServiceRule:
+    svc_rule = SimpleServiceRule()
+    svc_rule.event_type = event_type
+    if value is None:
+        svc_rule.initialized = False
+        return svc_rule
+    svc_rule.initialized = True
+    svc_rule.value = value
+    svc_rule.revision = revision
+    return svc_rule
+
+
+# 获取服务规则请求
+class GetServiceRuleRequest:
+    def __init__(self, flow_id: int = 0, namespace: str = "", service: str = "", timeout: int = 0,
+                 retry_count: int = 0):
+        # 可选，流水号，用于跟踪用户的请求，默认0
+        self.flow_id = flow_id
+        # 命名空间
+        self.namespace = namespace
+        # 服务名
+        self.service = service
+        # 可选，仅对同步请求有效，本次查询最大超时信息，可选，默认直接获取全局的超时配置
+        self.timeout = timeout
+        # 可选，重试次数，默认直接获取全局的超时配置
+        self.retry_count = retry_count
+
+    def get_service(self):
+        return self.service
+
+    def get_namespace(self):
+        return self.namespace
+
+    def get_metadata(self):
+        return None
+
+    def set_timeout(self, duration: int):
+        self.timeout = duration
+
+    def set_retry_count(self, retry_count: int):
+        self.retry_count = retry_count
+
+    def validate(self):
+        validate_service_metadata(self)
+
+
+# 服务规则应答
+class ServiceRuleResponse(ServiceRule):
+    def __init__(self, event_type: EventType, value, revision: str):
+        self.event_type = event_type
+        self.value = value
+        self.revision = revision
+
+    def get_type(self):
+        return self.event_type
+
+    def get_value(self):
+        return self.value
+
+    def is_initialized(self):
+        return True
+
+    def get_revision(self):
+        return self.revision
+
+
+class RoutingRuleInProto:
+    @classmethod
+    def new_from_discover_rsp(cls, resp: response_pb2.DiscoverResponse) -> ServiceRule:
+        if resp is None:
+            return new_simple_service_rule(event_type=EventType.Routing, value=None, revision="")
+        elif resp.routing is None:
+            return new_simple_service_rule(event_type=EventType.Routing, value=None, revision="")
+        else:
+            return new_simple_service_rule(event_type=EventType.Routing, value=resp.routing,
+                                           revision=str(resp.routing.revision.value))
+
+
+def validate_service_metadata(svc_meta):
+    if len(svc_meta.get_service()) == 0:
+        raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument, "validate_service_metadata: service is empty")
+    if len(svc_meta.get_namespace()) == 0:
+        raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument, "validate_service_metadata: namespace is empty")
+    metadata = svc_meta.get_metadata()
+    if metadata is not None and len(metadata) > 0:
+        for k, v in svc_meta.get_metadata():
+            if len(k) == 0 or len(v) == 0:
+                raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument,
+                               "validate_service_metadata: metadata has empty key or value")