prismacore 0.1.0

Python SDK for orchestrating sing-box VPN nodes

PrismaCore

Monorepo: REST API для одной sing-box-ноды (server/) и Python SDK для управления несколькими нодами (client/).

License: MIT · English: 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):

pip install prismacore

SDK (из исходников / dev):

git clone https://github.com/YOUR_USER/PrismaCore.git
cd PrismaCore
pip install -e .

Server:

pip install -r server/requirements.txt
# или production: sudo bash deploy/install_server.sh

Импорт SDK: from client import PrismaCore. Публикация новых версий на PyPI — docs/publishing.md.

---

Быстрый старт

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/sdk.md	SDK: конфиг, CRUD, регионы, подписки, кэш, ошибки, модели
docs/server.md	Server API: эндпoинты, auth, env, sing-box, share-ссылки
docs/deploy.md	Production-установка: install_server.sh, systemd, .env
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 and docs/en/.