Metadata-Version: 2.4
Name: ember-chat
Version: 0.1.0
Summary: Simple, open and extensible chat server with plugin system
Author-email: sipm1ner <kirillbelakov2222@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/supminer/emberchat
Project-URL: Repository, https://github.com/supminer/emberchat
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets>=12.0
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

🌟 Ember Chat — Простой, открытый и расширяемый мессенджер

Ember Chat — это минималистичный чат-сервер с архитектурой «ядро + плагины».
Главная идея: максимальная простота ядра и бесконечная расширяемость через плагины.

Вы можете:

    Общаться через CLI, веб, Telegram, LoRa, Bluetooth и любые другие транспорты.
    Отправлять файлы, изображения, команды — всё через единый протокол.
    Писать свои плагины за 10 минут и подключать их без перекомпиляции.

    💡 Вдохновлён философией Unix: делай одну вещь хорошо, и позволяй другим инструментам дополнять тебя.

📦 Содержание

    Основные возможности
    Архитектура
    Быстрый старт
    Как писать плагины
    Формат сообщений
    Клиенты
    Безопасность
    Планы и дорожная карта
    Лицензия

✨ Основные возможности

    ✅ Ядро < 100 строк — только рассылка сообщений.
    ✅ Автоматическая загрузка плагинов — просто положи .py-файл в папку.
    ✅ Единый JSON-протокол — совместимость между всеми клиентами.
    ✅ Поддержка файлов через встроенный HTTP-сервер.
    ✅ Готовые плагины: TCP (CLI), HTTP-файлы.
    ✅ Лёгкая интеграция с Telegram, LoRa, MQTT, Serial, WebSocket и др.

🧱 Архитектура

ember-chat/
├── core/              # Ядро: broadcast, клиенты, обработка
├── plugins/           # Все плагины автоматически загружаются отсюда
├── clients/           # Примеры клиентов
├── config.yaml        # Настройки плагинов (опционально)
└── main.py            # Точка входа

Принцип работы:

    Ядро (core/server.py) управляет списком клиентов и рассылает сообщения.
    Плагины подключаются к ядру и могут:
        вводить сообщения (например, из Telegram),
        выводить сообщения (например, в LoRa или файл),
        добавлять новых клиентов (TCP, WebSocket и т.д.).
    Все сообщения передаются в едином формате JSON.

🚀 Быстрый старт
1. Установка

bash
git clone https://github.com/supminer/emberchat.git
cd ember-chat
pip install pyyaml  # для поддержки config.yaml

2. Запуск сервера

bash
python main.py

Вы увидите:

[TCP Plugin] Слушаю 0.0.0.0:12345
[HTTP File Plugin] Запущен на порту 8000
[Main] Найдено плагинов: 2
  ✅ tcp_transport активирован
  ✅ http_file_share активирован

[Ember Chat] Сервер запущен. Нажмите Ctrl+C для выхода.

3. Запуск CLI-клиента

В новом терминале:

bash
python clients/cli_client.py

Введите имя и начните чат!
Отправьте файл командой: /sendfile /путь/к/файлу.

Файлы будут доступны по: http://localhost:8000/<имя_файла>
🔌 Как писать плагины
Шаг 1. Создайте файл в plugins/

Например: plugins/my_plugin.py
Шаг 2. Реализуйте функцию init_plugin(core, config=None)

python
# plugins/example_logger.py
def init_plugin(core, config=None):
    print("[Logger Plugin] Активирован!")
    
    def log_handler(core, message, source):
        # Эта функция вызывается при каждом входящем сообщении
        sender = message.get("from", "??")
        content = message.get("content", str(message))
        print(f"[LOG] {sender}: {content}")
    
    # Подписываемся на все сообщения
    core.add_message_handler(log_handler)

Шаг 3. (Опционально) Добавьте настройки в config.yaml

yaml

plugins:
  example_logger:
    verbose: true

Теперь config в init_plugin будет содержать {"verbose": true}.
Шаг 4. Перезапустите сервер

Плагин загрузится автоматически!
📌 Типы плагинов
Тип
	
Что делает
	
Пример
Транспорт
	
Добавляет способ подключения клиентов
	
tcp_transport.py, websocket_ui.py
Мост
	
Связывает чат с внешней системой
	
telegram_bridge.py, lora_gateway.py
Обработчик
	
Реагирует на сообщения
	
auto_responder.py, logger.py
Сервис
	
Предоставляет функционал (файлы, база и т.д.)
	
http_file_share.py
📨 Формат сообщений

Все сообщения — это словари Python, сериализованные в JSON.
Обязательные поля:

    from — имя отправителя (строка)
    type — тип сообщения (например, "text", "file")



    ⚠️ Важно: бинарные данные (файлы) всегда кодируются в base64 при передаче через JSON.

💻 Клиенты
1. CLI-клиент (clients/cli_client.py)

    Работает через TCP.
    Поддерживает текст и файлы (/sendfile).

2. Собственные клиенты

Вы можете написать клиент на любом языке, если реализуете:

    Подключение к TCP-порту.
    Отправку: [4 байта длины][JSON в UTF-8].
    Приём: чтение 4 байт → длина → чтение N байт → парсинг JSON.




Текущая версия:

    Не имеет аутентификации.
    Не шифрует трафик.
    Доверяет всем входящим данным.

Рекомендации:

    Используйте только во внутренней сети.
    Для публичного доступа добавьте:
        TLS (через reverse proxy: nginx + Let's Encrypt)
        Авторизацию в плагине
        Валидацию входящих данных
    Ограничьте размер файлов в http_file_share.py.

🗺️ Планы и дорожная карта

    Плагин: WebSocket UI (красивый веб-чат)
    Плагин: Telegram Bridge
    Плагин: LoRa Gateway (ESP32 + Raspberry Pi)
    Поддержка аккаунтов и истории
    CLI-утилита для управления сервером
    Docker-образ

📜 Лицензия

MIT License — делайте что угодно, сохраняя авторство.
❤️ Вдохновение

Этот проект создан для тех, кто верит, что:

    Простота — залог надёжности, а открытость — двигатель прогресса.

Присоединяйся! Пиши плагины, делай форки, делись идеями.
