Master - стабильная ветка.
Develop - ветка для добавления нового функционала.
-
Python 3.10 - язык программирования
-
FastAPI - основной фреймворк
-
SQLObject - ORM для работы с базой данный
-
Pydantic - валидация данных
-
Starlette - легковесный ASGI фреймворк/тулкит
-
websockets - реализация протокола Websockets в Python (RFC 6455 & 7692)
- /admin
- /templates - шаблоны страниц админки
- admin.py
- control.py
- login.py
- logs.py
- /mod
- /db
- dbhandler.py - модуль предназначен для выполнения запросов к БД
- models.py - модуль отвечает за описание таблиц БД для работы через ОРМ.
- /protocol
- /matrix
- api.py - модуль отвечает за описание API, а так же валидацию данных.
- worker.py - реализация протокола
- /mtp
- api.py - модуль отвечает за описание API, а так же валидацию данных.
- worker.py - модуль отвечает за реализацию методов описанных в Morelia Protocol.
- error.py - модуль отвечает за проверку и генерацию ответов с кодами ошибок.
- controller.py - модуль обрабатывает запрос в соответствии с типом протокола
- lib.py - модуль отвечает за хеширование пароля, сравнения пароля с его хэш-суммой, создание хеша для auth_id.
- logging.py - модуль настройки логирования.
- config.py - модуль читает настройки из config.ini
- /matrix
- /db
- /static -
- server.py - основной код сервера
- manage.py - менеджер миграции для БД (создание и удаление таблиц базы данных)
- /tests
- fixtures/ - json-файлы с заранее подготовленными данными, для проведения тестов.
- config.ini - конфиг сервера для проведения тестов
- test_*.py - тесты
- debug_server.py - обёртка для server.py для дебага через утилиту
pdb
. - example_config.ini - файл содержащий пример настроек сервера, перед запуском сервера просто переименуйте в
config.ini
. - client.py - мини-клиент для проверки работы сервера.
Установить Python версией 3.10 или выше.
Загрузить и установить последнюю версию git.
Если нужен GUI, установить GitHub Desktop.
Настроить Git или GitHub Desktop введя свои username
и email
от аккаунта созданного на github.
Если ты не включен в команду на GitHub'е проекта, то необходимо сначала форкнуть к себе репозиторий Morelia Server перейдя по ссылке.
Клонировать репозиторий к себе на локальный компьютер используя командную строку и git
git clone https://github.com/{username}/morelia_server.git
cd morelia_server
Переключаемся на ветку develop
git checkout develop
Синхронизируем свой форк с оригинальным репозиторием upstream
Morelia Server
git remote add upstream https://github.com/MoreliaTalk/morelia_server.git
Проверяем появились ли репозиторий upstream
в списке удалённых репозиториев
git remote -v
> origin https://github.com/{username}/morelia_server.git (fetch)
> origin https://github.com/{username}/morelia_server.git (push)
> upstream https://github.com/MoreliaTalk/morelia_server.git (fetch)
> upstream https://github.com/MoreliaTalk/morelia_server.git (push)
При использовании GitHub
выбрать в меню File
пункт Clone repository...
далее следовать инструкциям
Для работы с проектом необходимо установить библиотеки которые он использует и настроить т.н. виртуальное рабочее окружение
или virtualenv
, для этого используется утилита Pipenv
Если не установлен pipenv, выполнить
python -m pip install pipenv
Создать виртуальное окружение в директории с проектом
pipenv shell
Установить все требуемые библиотеки из Pipfile
pipenv install --ignore-pipfile
Перед запуском сервера необходимо выполнить некоторые настройки (создать БД, таблицы и добавить первого пользователя - администратора)
Откройте файл example_config.ini
, найдите параметр URI, замените его на путь к базе данных, пример:
URI = 'sqlite:db_sqlite.db'
, сохраните файл как config.ini
Создаём базу данных с пустыми таблицами:
pipenv run python ./manage.py --db create
Если необходимо удалить все таблицы в созданной базе данных (ВНИМАНИЕ удаляются только таблицы, БД не удаляется):
pipenv run pipenv run python ./manage.py --db delete
Добавляем администратора в созданную БД:
python ./manage.py superuser-create
Дополнительно можно создать flow
с типом группа:
pipenv run python ./manage.py --table flow
Информация о всех возможностях менеджера настроек:
pipenv run python ./manage.py --help
Для запуска сервера используйте команду:
uvicorn server:app --host 0.0.0.0 --port 8000 --reload --use-colors --http h11 --ws websockets
Дополнительные параметры которые можно передать серверу:
--log-level <str>
- Set the log level. Options: 'critical', 'error', 'warning', 'info', 'debug', 'trace'. Default: 'info'.
--use-colors / --no-use-colors
- Enable / disable colorized formatting of the log records, in case this is not set it will be auto-detected. This option is ignored if the --log-config
CLI option is used.
--loop <str>
- Set the event loop implementation. The uvloop implementation provides greater performance, but is not compatible with Windows or PyPy. Options: 'auto', 'asyncio', 'uvloop'. Default: 'auto'.
--http <str>
- Set the HTTP protocol implementation. The httptools implementation provides greater performance, but it is not compatible with PyPy, and requires compilation on Windows. Options: 'auto', 'h11', 'httptools'. Default: 'auto'.
--ws <str>
- Set the WebSockets protocol implementation. Either of the websockets and wsproto packages are supported. Use 'none' to deny all websocket requests. Options: 'auto', 'none', 'websockets', 'wsproto'. Default: 'auto'.
--lifespan <str>
- Set the Lifespan protocol implementation. Options: 'auto', 'on', 'off'. Default: 'auto'.
--interface
- Select ASGI3, ASGI2, or WSGI as the application interface. Note that WSGI mode always disables WebSocket support, as it is not supported by the WSGI interface. Options: 'auto', 'asgi3', 'asgi2', 'wsgi'. Default: 'auto'.
--limit-concurrency <int>
- Maximum number of concurrent connections or tasks to allow, before issuing HTTP 503 responses. Useful for ensuring known memory usage patterns even under over-resourced loads.
--limit-max-requests <int>
- Maximum number of requests to service before terminating the process. Useful when running together with a process manager, for preventing memory leaks from impacting long-running processes.
--backlog <int>
- Maximum number of connections to hold in backlog. Relevant for heavy incoming traffic. Default: 2048
--ssl-keyfile <path>
- SSL key file
--ssl-certfile <path>
- SSL certificate file
--ssl-version <int>
- SSL version to use (see stdlib ssl module's)
--ssl-cert-reqs <int>
- Whether client certificate is required (see stdlib ssl module's)
--ssl-ca-certs <str>
- CA certificates file
--ssl-ciphers <str>
- Ciphers to use (see stdlib ssl module's)
--timeout-keep-alive <int>
- Close Keep-Alive connections if no new data is received within this timeout. Default: 5.
Для лёгкого запуска сервера в режиме отладки нужно всего лишь запустить debug_server.py
:
pipenv run python ./debug_server.py
Для проверки работы сервера запустите мини-клиент client.py
в консоли:
pipenv run python -i ./client.py
После запуска клиент отправит на сервер сообщение об авторизации (AUTH), ответ сервера будет выведен в консоль, после чего python
перейдёт в режим интерактивной строки >>>
, для того чтобы была возможность провести дополнительные проверки.
В интерактивной консоли будет доступна одна функция отправки сообщений send_message
которая принимает два аргумента message
-сообщение и uri
-адрес сервера. В аргументе message
необходимо передать объект с типом "dict" или "str", можно использовать готовые примеры запросов: AUTH, GET_UPDATE, ADD_FLOW, ALL_FLOW. В аргументе необходимо передать объект с типом "str", можно использовать готовый пример адреса сервера: LOCALHOST.
>>> send_message(GET_UPDATE, LOCALHOST)
Если в функцию не передать ни одного аргумента, по умолчанию будет отправлено сообщение AUTH на LOCALHOST.
Получение последних изменений из develop-ветки Morelia Server
git pull upstream develop
Отправка изменений в develop-ветку своего форка
git push
Для создания пулл-реквеста, необходимо перейти на GitHub, выбрать свой форк и в правом меню нажать на New pull request
, после чего выбрать бранч из которого будет производиться перенос изменений в develop-ветку Morelia Server и нажать Create pull request
.
Перед началом работы рекомендуется прочитать PEP 8 - руководство по написанию кода на Python. Обязательно использовать линтер (flake8, pylint или подобный).
Используется библиотека loguru
Уровни логирования которыми можно пользоваться в коде:
Level name | Logger method
DEBUG | logger.debug()
INFO | logger.info()
SUCCESS | logger.success()
WARNING | logger.warning()
ERROR | logger.error()
| logger.exception()
CRITICAL | logger.critical()
Для написания тестов используется встроенный модуль Unittest.
Для запуска тестов выполните (вместо звёздочки подставьте наименование теста)
pipenv run python -v ./tests/test_*.py
Для запуска дебагера в полевых условиях, через консоль
python -m pdb ./debug_server.py
Для получения справки в дебаг-режиме
(pdb) help
Telegram - группа где обсуждаются насущные вопросы.
Slack - альтернативный вариант обсуждения проекта.
Copyright (c) 2020 - настоящее время NekrodNIK, Stepan Skriabin, rus-ai и другие. Смотрите полный список в файле AUTHORS.md.
Morelia Server находится под лицензией GNU Lesser General Public License версии 3 или более поздней(LGPL-3.0-or-later). Подробности смотрите в файле COPYING.LESSER.