shardy
v1.0.2
Published
Framework for online games and applications on Node.js
Downloads
10
Maintainers
Readme
💬 Описание
Shardy – это фреймворк для онлайн игр и приложений на Node.js. Он предоставляет базовую функциональность для построения микросервисных решений: мобильных, социальных, веб, многопользовательских игр, приложений реального времени, чатов, middleware сервисов и т.п.
Основная цель Shardy – предоставить простое бесплатное решение для создания почти любого интернет-проекта. 💪
✨ Возможности
- Микросервисная парадигма
- Простой API: запросы, команды, подписки и т.п.
- Транспорт данных через сокеты и вебсокеты
- Легкость и быстрота: Node.js и TypeScript
- Поддержка пользовательской сериализации
- Поддержка пользовательской валидации рукопожатий (handshake)
- Продвинутый логгер: теги, фильтры, области
- Гибкое расширение
- Справочные материалы: документация, сниппеты, примеры
- Почти нулевая конфигурация
🚀 Использование
Зачем использовать Shardy?
Начните свой проект или backend для мобильной игры с Shardy и будьте уверены в:
- простоте использования: работайте с удобным API и не задумывайтесь о том, как это работает под капотом
- масштабируемой архитектуре: используйте существующие или создавайте свои собственные микросервисы, связывайте их вместе и масштабируйте свое приложение
- быстродействии и легкости: основная сетевая архитектура, основанная на Node.js, без использования сторонних библиотек
- полноте документации: Shardy предоставляет хорошую документацию со всеми необходимыми разделами и ссылками на API, также весь код снабжен комментариями
Быстрый старт
Начать разработку своего проекта с помощью Shardy очень просто:
- Склонируйте шаблон сервиса или создайте новый
git clone [email protected]:mopsicus/shardy-template.git
- Установите Shardy и все зависимости
npm install
- Измените
.env.dev
- Запустить дебаг режим
npm run debug
Все методы и примеры API приведены в документации.
Интерфейс сервиса
Ваш (микро)сервис должен использовать интерфейс Service
для обработки основных событий. Это место где вы контролируете подключенных и отключенных пользователей и передаете их в своё приложение.
Все ваши остальные объекты, классы, БД и т.д. должны быть связаны с этим классом, иначе вы не сможете получить к ним доступ из команд\запросов.
import { TransportType, Service, Client } from 'shardy';
export class MyService implements Service {
//
// добавляйте свои объекты, базы данных или что-нибудь ещё в этот класс
//
// укажите название сервиса
name = process.env.SERVICE_NAME;
// укажите тип транспорта
transport = process.env.SERVICE_TRANSPORT as TransportType;
async onConnect(client: Client): Promise<void> {
// новый клиент подключился
}
async onDisconnect(client: Client): Promise<void> {
// клиент отключился
}
async onReady(client: Client): Promise<void> {
// клиент готов к работе
}
async onListening(): Promise<void> {
// сервис запущен
}
async onError(error: Error): Promise<void> {
// произошла какая-то ошибка
}
async onClose(): Promise<void> {
// сервис остановлен
}
}
Запросы и команды
Shardy API удобен в использовании, он предоставляет RPC-фреймворк для межпроцессных взаимодействий. Приведенные ниже фрагменты показывают, как можно использовать каждый из них.
Основное различие между запросами и командами в том, что вызываемая сторона должна отвечать на запросы и не отвечает на команды. Это означает, что когда вы делаете запрос, у вас есть обратный вызов с данными ответа. А когда вы посылаете команду, вы просто уведомляете другую сторону о чём-то.
Запрос:
client.request('status', (data) => {
// отправка запроса и получение ответа с данными
});
client.request('status', (data) => {
// отправка запроса с данными
}, payload);
Команда:
client.command('status'); // отправка команды/события
client.command('status', payload); // отправка команды с данными
Подписка:
client.on('status', (data) => {
// подписка на команду и обработка при каждом получении
});
Можно также передавать запрос от сервера к клиенту, об этом см. в документации.
Структура команды
Все команды/запросы экспортируют именованную функцию. Shardy передает все необходимые объекты внутрь ваших команд:
- commander – контроллер текущего соединения
- payload – полученные данные и данные о команде или запросе
- service – ссылка на ваш экземпляр сервиса, для взаимодействия с вашими объектами, базами данных, и т.п.
[!IMPORTANT] Если ваша команда это запрос, то убедитесь, что вы ответили на него, иначе у вызывающей стороны будет таймаут.
import { Commander, PayloadData, Service } from 'shardy';
export const status = (commander: Commander, payload: PayloadData, service: Service) => {
// работа с полученными данными
console.log('data', payload.data);
// ответ на запрос
commander.response(payload);
// ответ ошибкой на запрос
commander.error(payload);
};
Валидация
Когда клиент подключается к серверу, он должен успешно завершить рукопожатие (handshake) перед началом работы. В Shardy используется двухэтапное рукопожатие для соединений.
Этапы рукопожатия:
- Клиент отправляет данные рукопожатия на сервер
- Сервер получает и проверяет их:
- Отравляет подтверждение клиенту
- Отключает клиента, если проверка не прошла
- Клиент получает данные подтверждения и тоже проверяет их:
- Отправляет ответ на подтверждение серверу
- Отключается, если проверка не прошла
- После успешного рукопожатия и подтверждения, клиент и сервер могут отправлять друг другу запросы и команды.
Если в вашей реализации нет необходимости делать двухэтапное рукопожатие, вы можете установить "заглушки" на этих методах.
Shardy предоставляет интерфейс для валидации рукопожатия. Вы можете реализовать собственную структуру данных рукопожатия и валидацию для всех этих этапов. Наследуйте класс Validator
, реализуйте методы и передайте его своему сервису и клиенту.
import { Validator, ValidatorState } from 'shardy';
export class MyHandshake implements Validator {
verifyHandshake(body: Buffer): ValidatorState {
// проверка первоначального рукопожатия
}
verifyAcknowledgement(body: Buffer): ValidatorState {
// проверка данных подтверждения
}
acknowledgement(body: Buffer): Buffer {
// данные для подтверждения после успешного первичного рукопожатия
}
handshake(body?: Buffer): Buffer {
// данные для первичного рукопожатия
}
}
Сериализация
Shardy поддерживает пользовательскую сериализацию передаваемых данных. Вы можете использовать JSON, MessagePack, Protobuf, FlatBuffers и т.д. или свой собственный сериализатор.
Достаточно наследовать класс Serializer
, реализовать методы encode/decode и передать его своему сервису и клиенту.
import { PayloadData, Serializer } from 'shardy';
export class MyJsonSerializer implements Serializer {
encode(body: PayloadData): Buffer {
// перекодируйте PayloadData в Buffer для отправки
}
decode(body: Buffer): PayloadData {
// декодируйте полученные данные и сериализуйте в PayloadData
}
}
🏗️ Развитие
Мы приглашаем вас внести свой вклад и помочь улучшить Shardy. Пожалуйста, ознакомьтесь с документом. 🤗
Вы также можете внести свой вклад в проект Shardy:
- Помогая другим пользователям
- Мониторя список существующих проблем
- Рассказав о проекте в своих соцсетях
- Используя его в своих проектах
🤝 Поддержка
Вы можете поддержать проект любым из способов ниже:
- Bitcoin (BTC): 1VccPXdHeiUofzEj4hPfvVbdnzoKkX8TJ
- USDT (TRC20): TMHacMp461jHH2SHJQn8VkzCPNEMrFno7m
- TON: UQDVp346KxR6XxFeYc3ksZ_jOuYjztg7b4lEs6ulEWYmJb0f
- Карты Visa, Mastercard через Boosty
- Карты МИР через CloudTips
✉️ Контактная информация
Перед тем как задать вопрос, лучшим решением будет посмотреть уже существующие проблемы, это может помочь. В любом случае, вы можете задать любой вопрос или отправить предложение по email или Telegram.
🔑 Лицензия
Shardy выпущен под лицензией MIT. Используйте бесплатно и радуйтесь. 🎉