prismacore 0.1.0__tar.gz

prismacore-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PrismaCore Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prismacore-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: prismacore
+Version: 0.1.0
+Summary: Python SDK for orchestrating sing-box VPN nodes
+Author: PrismaCore Authors
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/DevGMoree/PrismaCore#readme
+Project-URL: Repository, https://github.com/DevGMoree/PrismaCore
+Project-URL: Issues, https://github.com/DevGMoree/PrismaCore/issues
+Keywords: sing-box,vpn,sdk,proxy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Requires-Dist: redis>=5.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# PrismaCore
+
+Monorepo: REST API для одной sing-box-ноды (`server/`) и Python SDK для управления несколькими нодами (`client/`).
+
+**License:** MIT · **English:** [README.en.md](README.en.md)
+
+---
+
+## Состав
+
+| Часть | Что делает |
+|-------|------------|
+| `server/` | FastAPI: CRUD пользователей, инбаундов, аутбаундов, роутов; генерация share-ссылок; запись конфига sing-box |
+| `client/` | SDK: несколько нод, выбор по региону/latency, сборка подписок |
+| `deploy/` | Установка server на Linux (systemd) |
+
+SDK не отдаёт HTTP-подписку клиентам — вы сами оборачиваете `core.subscriptions.build()` во FastAPI/Flask/nginx.
+
+---
+
+## Требования
+
+- Python 3.10+
+- sing-box (для server)
+- Redis — опционально (кэш на server и в SDK)
+
+---
+
+## Установка
+
+**SDK (PyPI):**
+
+```bash
+pip install prismacore
+```
+
+**SDK (из исходников / dev):**
+
+```bash
+git clone https://github.com/YOUR_USER/PrismaCore.git
+cd PrismaCore
+pip install -e .
+```
+
+**Server:**
+
+```bash
+pip install -r server/requirements.txt
+# или production: sudo bash deploy/install_server.sh
+```
+
+Импорт SDK: `from client import PrismaCore`. Публикация новых версий на PyPI — [docs/publishing.md](docs/publishing.md).
+
+---
+
+## Быстрый старт
+
+```python
+import asyncio
+from client import PrismaCore
+
+async def main():
+    async with PrismaCore.single_node(
+        url="http://127.0.0.1:8000",
+        token="<api-token>",
+        public_host="203.0.113.10",  # публичный IP/домен для share-ссылок на server
+    ) as core:
+        await core.node().users.create_simple("alice", inbound_tags=["vless-in"])
+        sub = await core.subscriptions.build("alice")
+        print(sub[:80])
+
+asyncio.run(main())
+```
+
+Токен API создаётся один раз: `POST /api/v1/auth/token` (см. [docs/server.md](docs/server.md)).
+
+---
+
+## Документация
+
+| Документ | Содержание |
+|----------|------------|
+| [docs/sdk.md](docs/sdk.md) | SDK: конфиг, CRUD, регионы, подписки, кэш, ошибки, модели |
+| [docs/server.md](docs/server.md) | Server API: эндпoинты, auth, env, sing-box, share-ссылки |
+| [docs/deploy.md](docs/deploy.md) | Production-установка: `install_server.sh`, systemd, `.env` |
+| [docs/publishing.md](docs/publishing.md) | PyPI: сборка, первая загрузка, новые версии |
+
+---
+
+## Архитектура
+
+```
+PrismaCore (SDK)
+├── vpn_servers: VpnServerManager     # реестр нод
+├── regions: RegionService            # fastest_node / best_nodes
+├── subscriptions: SubscriptionAggregator
+└── cache: CacheManager               # Redis, опционально
+
+Node (на каждую ноду)
+├── users / inbounds / outbounds / routes / system
+└── HttpClient → server /api/v1/*
+```
+
+Типичный поток подписки:
+
+1. SDK выбирает ноды по регионам (`fastest_only=True` — одна на регион)
+2. На каждой ноде: `GET /api/v1/sublink/{user_name}/all`
+3. Server собирает `vless://` / `hysteria2://` из БД + `HOST`
+4. SDK добавляет meta-строки Happ, кодирует в base64
+
+---
+
+## Структура репозитория
+
+```
+client/
+├── prismacore.py
+├── config.py, models.py, api_funcs.py, cache.py, exceptions.py
+├── nodes/          node.py, vpn.py
+├── resources/      users, inbounds, outbounds, routes, system
+├── regions/        prober.py, registry.py
+└── subscriptions/  aggregator.py
+
+server/
+├── app.py, routes.py, config.py
+├── database.py, models.py, schemas.py
+└── core/           singbox.py, cache.py
+
+deploy/
+├── install_server.sh
+├── prismacore.service
+└── .env.example
+```
+
+---
+
+## Частые ошибки
+
+- **`HOST=localhost` на server** — share-ссылки будут с localhost, клиенты не подключатся. Задайте публичный IP/домен.
+- **Забыли `invalidate` после CRUD** — подписчики получат закэшированную подписку без новых ссылок.
+- **Несколько нод, `core.node()` без имени** — `ConfigError`. Указывайте `core.node("de-1")`.
+- **Токен в заголовке** — server ждёт `?token=...` в query, не Bearer.
+
+---
+
+## English
+
+See [README.en.md](README.en.md) and [docs/en/](docs/en/).

prismacore-0.1.0/README.md

@@ -0,0 +1,148 @@
+# PrismaCore
+
+Monorepo: REST API для одной sing-box-ноды (`server/`) и Python SDK для управления несколькими нодами (`client/`).
+
+**License:** MIT · **English:** [README.en.md](README.en.md)
+
+---
+
+## Состав
+
+| Часть | Что делает |
+|-------|------------|
+| `server/` | FastAPI: CRUD пользователей, инбаундов, аутбаундов, роутов; генерация share-ссылок; запись конфига sing-box |
+| `client/` | SDK: несколько нод, выбор по региону/latency, сборка подписок |
+| `deploy/` | Установка server на Linux (systemd) |
+
+SDK не отдаёт HTTP-подписку клиентам — вы сами оборачиваете `core.subscriptions.build()` во FastAPI/Flask/nginx.
+
+---
+
+## Требования
+
+- Python 3.10+
+- sing-box (для server)
+- Redis — опционально (кэш на server и в SDK)
+
+---
+
+## Установка
+
+**SDK (PyPI):**
+
+```bash
+pip install prismacore
+```
+
+**SDK (из исходников / dev):**
+
+```bash
+git clone https://github.com/YOUR_USER/PrismaCore.git
+cd PrismaCore
+pip install -e .
+```
+
+**Server:**
+
+```bash
+pip install -r server/requirements.txt
+# или production: sudo bash deploy/install_server.sh
+```
+
+Импорт SDK: `from client import PrismaCore`. Публикация новых версий на PyPI — [docs/publishing.md](docs/publishing.md).
+
+---
+
+## Быстрый старт
+
+```python
+import asyncio
+from client import PrismaCore
+
+async def main():
+    async with PrismaCore.single_node(
+        url="http://127.0.0.1:8000",
+        token="<api-token>",
+        public_host="203.0.113.10",  # публичный IP/домен для share-ссылок на server
+    ) as core:
+        await core.node().users.create_simple("alice", inbound_tags=["vless-in"])
+        sub = await core.subscriptions.build("alice")
+        print(sub[:80])
+
+asyncio.run(main())
+```
+
+Токен API создаётся один раз: `POST /api/v1/auth/token` (см. [docs/server.md](docs/server.md)).
+
+---
+
+## Документация
+
+| Документ | Содержание |
+|----------|------------|
+| [docs/sdk.md](docs/sdk.md) | SDK: конфиг, CRUD, регионы, подписки, кэш, ошибки, модели |
+| [docs/server.md](docs/server.md) | Server API: эндпoинты, auth, env, sing-box, share-ссылки |
+| [docs/deploy.md](docs/deploy.md) | Production-установка: `install_server.sh`, systemd, `.env` |
+| [docs/publishing.md](docs/publishing.md) | PyPI: сборка, первая загрузка, новые версии |
+
+---
+
+## Архитектура
+
+```
+PrismaCore (SDK)
+├── vpn_servers: VpnServerManager     # реестр нод
+├── regions: RegionService            # fastest_node / best_nodes
+├── subscriptions: SubscriptionAggregator
+└── cache: CacheManager               # Redis, опционально
+
+Node (на каждую ноду)
+├── users / inbounds / outbounds / routes / system
+└── HttpClient → server /api/v1/*
+```
+
+Типичный поток подписки:
+
+1. SDK выбирает ноды по регионам (`fastest_only=True` — одна на регион)
+2. На каждой ноде: `GET /api/v1/sublink/{user_name}/all`
+3. Server собирает `vless://` / `hysteria2://` из БД + `HOST`
+4. SDK добавляет meta-строки Happ, кодирует в base64
+
+---
+
+## Структура репозитория
+
+```
+client/
+├── prismacore.py
+├── config.py, models.py, api_funcs.py, cache.py, exceptions.py
+├── nodes/          node.py, vpn.py
+├── resources/      users, inbounds, outbounds, routes, system
+├── regions/        prober.py, registry.py
+└── subscriptions/  aggregator.py
+
+server/
+├── app.py, routes.py, config.py
+├── database.py, models.py, schemas.py
+└── core/           singbox.py, cache.py
+
+deploy/
+├── install_server.sh
+├── prismacore.service
+└── .env.example
+```
+
+---
+
+## Частые ошибки
+
+- **`HOST=localhost` на server** — share-ссылки будут с localhost, клиенты не подключатся. Задайте публичный IP/домен.
+- **Забыли `invalidate` после CRUD** — подписчики получат закэшированную подписку без новых ссылок.
+- **Несколько нод, `core.node()` без имени** — `ConfigError`. Указывайте `core.node("de-1")`.
+- **Токен в заголовке** — server ждёт `?token=...` в query, не Bearer.
+
+---
+
+## English
+
+See [README.en.md](README.en.md) and [docs/en/](docs/en/).

prismacore-0.1.0/client/__init__.py

@@ -0,0 +1,37 @@
+"""PrismaCore SDK — управление sing-box VPN."""
+
+from .prismacore import PrismaCore
+from .config import ServerConfig, CacheConfig, ProbeConfig
+from .models import (
+    UserCreate, UserResponse,
+    InboundCreate, InboundResponse,
+    OutboundCreate, OutboundResponse,
+    RouteCreate, RouteResponse,
+    StatusResponse, Token,
+)
+from .subscriptions.aggregator import SubscriptionAggregator
+from .exceptions import (
+    PrismaCoreError,
+    ConfigError,
+    TransportError,
+    AllServersDownError,
+    APIError,
+    AuthError,
+    NotFoundError,
+    ConflictError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PrismaCore",
+    "ServerConfig", "CacheConfig", "ProbeConfig",
+    "UserCreate", "UserResponse",
+    "InboundCreate", "InboundResponse",
+    "OutboundCreate", "OutboundResponse",
+    "RouteCreate", "RouteResponse",
+    "StatusResponse", "Token",
+    "SubscriptionAggregator",
+    "PrismaCoreError", "ConfigError", "TransportError", "AllServersDownError",
+    "APIError", "AuthError", "NotFoundError", "ConflictError",
+]

prismacore-0.1.0/client/api_funcs.py

@@ -0,0 +1,131 @@
+"""HTTP-транспорт SDK (httpx)."""
+
+import asyncio
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import (
+    APIError,
+    AuthError,
+    ConflictError,
+    NotFoundError,
+    TransportError,
+)
+
+API_PREFIX = "/api/v1"
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class HttpClient:
+    """Асинхронный HTTP-клиент к одной ноде."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        retry_backoff: float = 0.5,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.max_retries = max_retries
+        self.retry_backoff = retry_backoff
+        self._client = httpx.AsyncClient(base_url=self.base_url, timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "HttpClient":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict] = None,
+        params: Optional[dict] = None,
+    ) -> Any:
+        url = f"{API_PREFIX}{path}"
+        query = dict(params or {})
+        query["token"] = self.token
+
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(1, self.max_retries + 1):
+            try:
+                response = await self._client.request(method, url, json=json, params=query)
+            except httpx.RequestError as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    await asyncio.sleep(self.retry_backoff * attempt)
+                    continue
+                raise TransportError(
+                    f"Не удалось соединиться с нодой за {self.max_retries} попыток: {exc}",
+                    url=self.base_url,
+                ) from exc
+
+            if response.status_code in _RETRYABLE_STATUS and attempt < self.max_retries:
+                await asyncio.sleep(self.retry_backoff * attempt)
+                continue
+
+            return self._handle_response(response)
+
+        raise TransportError(
+            f"Запрос не выполнен: {last_exc}", url=self.base_url
+        )
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        if 200 <= response.status_code < 300:
+            if not response.content:
+                return None
+            try:
+                return response.json()
+            except ValueError as exc:
+                raise APIError(
+                    "Сервер вернул не-JSON в успешном ответе",
+                    status_code=response.status_code,
+                    url=self.base_url,
+                ) from exc
+
+        detail = None
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                detail = body.get("detail")
+        except ValueError:
+            detail = response.text or None
+
+        message = f"Сервер вернул ошибку {response.status_code}: {detail or 'без описания'}"
+
+        if response.status_code == 403:
+            raise AuthError(message, status_code=403, detail=detail, url=self.base_url)
+        if response.status_code == 404:
+            raise NotFoundError(message, status_code=404, detail=detail, url=self.base_url)
+        if response.status_code == 409:
+            raise ConflictError(message, status_code=409, detail=detail, url=self.base_url)
+
+        raise APIError(
+            message,
+            status_code=response.status_code,
+            detail=detail,
+            url=self.base_url,
+        )
+
+    async def get(self, path: str, *, params: Optional[dict] = None) -> Any:
+        return await self.request("GET", path, params=params)
+
+    async def post(self, path: str, *, json: Optional[dict] = None, params: Optional[dict] = None) -> Any:
+        return await self.request("POST", path, json=json, params=params)
+
+    async def put(self, path: str, *, json: Optional[dict] = None, params: Optional[dict] = None) -> Any:
+        return await self.request("PUT", path, json=json, params=params)
+
+    async def delete(self, path: str, *, params: Optional[dict] = None) -> Any:
+        return await self.request("DELETE", path, params=params)

prismacore-0.1.0/client/cache.py

@@ -0,0 +1,81 @@
+"""Redis-кэш SDK."""
+
+import json
+from typing import Any, Awaitable, Callable, Optional
+
+from pydantic import BaseModel
+
+from .config import CacheConfig
+
+
+class CacheManager:
+    """Redis-кэш (опционально)."""
+
+    def __init__(self, config: Optional[CacheConfig] = None):
+        self.config = config or CacheConfig()
+        self._redis = None
+
+    def _get_redis(self):
+        if self._redis is None:
+            import redis.asyncio as aioredis
+
+            self._redis = aioredis.from_url(self.config.redis_url, decode_responses=True)
+        return self._redis
+
+    @staticmethod
+    def _json_default(value: Any) -> Any:
+        if isinstance(value, BaseModel):
+            return value.model_dump(mode="json")
+        raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+    async def create_cache(self, data: Any, key: str) -> None:
+        if not self.config.enabled:
+            return
+        try:
+            json_data = json.dumps(data, ensure_ascii=False, default=self._json_default)
+            await self._get_redis().set(name=key, value=json_data)
+        except Exception as e:
+            print(f"[cache] Ошибка при кэшировании ключа '{key}': {e}")
+
+    async def get_cache_data(self, key: str) -> Optional[Any]:
+        if not self.config.enabled:
+            return None
+        try:
+            cache = await self._get_redis().get(key)
+        except Exception as e:
+            print(f"[cache] Ошибка при чтении кэша по ключу '{key}': {e}")
+            return None
+        if not cache:
+            return None
+        return json.loads(cache)
+
+    async def delete(self, key: str) -> None:
+        if not self.config.enabled:
+            return
+        try:
+            await self._get_redis().delete(key)
+        except Exception as e:
+            print(f"[cache] Ошибка при удалении ключа '{key}': {e}")
+
+    async def get_or_fetch(
+        self,
+        key: str,
+        fetcher: Callable[[], Awaitable[Any]],
+        *,
+        serializer: Optional[Callable[[Any], Any]] = None,
+        deserializer: Optional[Callable[[Any], Any]] = None,
+    ) -> Any:
+        cached = await self.get_cache_data(key)
+        if cached is not None:
+            return deserializer(cached) if deserializer is not None else cached
+        value = await fetcher()
+        value_to_cache = serializer(value) if serializer is not None else value
+        await self.create_cache(value_to_cache, key)
+        return value
+
+    async def close(self) -> None:
+        if self._redis is not None:
+            try:
+                await self._redis.close()
+            except Exception:
+                pass

prismacore-0.1.0/client/config.py

@@ -0,0 +1,69 @@
+"""Конфигурация SDK."""
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+from urllib.parse import urlparse
+
+from .exceptions import ConfigError
+
+VpnNodeRole = Literal["vpn", "backup_vpn"]
+
+
+@dataclass
+class ServerConfig:
+    """Параметры одной VPN-ноды."""
+
+    url: str
+    token: str
+    region: str = "default"
+    role: VpnNodeRole = "vpn"
+    name: str = ""
+    public_host: str = ""
+    timeout: float = 10.0
+
+    def __post_init__(self) -> None:
+        self.url = self.url.rstrip("/")
+        self.token = self.token.strip()
+
+        if not self.url:
+            raise ConfigError("ServerConfig.url не может быть пустым")
+        if not self.token:
+            raise ConfigError("ServerConfig.token не может быть пустым")
+        if self.role not in ("vpn", "backup_vpn"):
+            raise ConfigError(
+                f"Недопустимая роль {self.role!r}. Допустимо: 'vpn', 'backup_vpn'"
+            )
+
+        if not self.name:
+            self.name = self.url
+
+        if self.public_host:
+            self.public_host = self.public_host.strip()
+        else:
+            self.public_host = self._host_from_url(self.url)
+
+    @staticmethod
+    def _host_from_url(url: str) -> str:
+        normalized = url if "://" in url else f"http://{url}"
+        parsed = urlparse(normalized)
+        if parsed.hostname:
+            return parsed.hostname
+        return url.split("/")[0].split(":")[0]
+
+
+@dataclass
+class CacheConfig:
+    """Redis-кэш SDK."""
+
+    enabled: bool = False
+    redis_url: str = "redis://localhost:6379/0"
+
+
+@dataclass
+class ProbeConfig:
+    """Параметры замера latency."""
+
+    samples: int = 3
+    timeout: float = 5.0
+    cache_ttl: float = 60.0
+    health_path: Optional[str] = None