!Static Badge
!Static Badge

Фреймворк для онлайн игр и приложений

Быстрый старт · Документация · Пример сервиса · Unity клиент · Отчёт об ошибке

💬 Описание

Shardy – это фреймворк для онлайн игр и приложений на Node.js. Он предоставляет базовую функциональность для построения микросервисных решений: мобильных, социальных, веб, многопользовательских игр, приложений реального времени, чатов, middleware сервисов и т.п.

Основная цель Shardy – предоставить простое бесплатное решение для создания почти любого интернет-проекта. 💪

✨ Возможности

- Микросервисная парадигма
- Простой API: запросы, команды, подписки и т.п.
- Транспорт данных через сокеты и вебсокеты
- Легкость и быстрота: Node.js и TypeScript
- Поддержка пользовательской сериализации
- Поддержка пользовательской валидации рукопожатий (handshake)
- Продвинутый логгер: теги, фильтры, области
- Гибкое расширение
- Справочные материалы: документация, сниппеты, примеры
- Почти нулевая конфигурация

🚀 Использование

$3

Начните свой проект или backend для мобильной игры с Shardy и будьте уверены в:

- простоте использования: работайте с удобным API и не задумывайтесь о том, как это работает под капотом
- масштабируемой архитектуре: используйте существующие или создавайте свои собственные микросервисы, связывайте их вместе и масштабируйте свое приложение
- быстродействии и легкости: основная сетевая архитектура, основанная на Node.js, без использования сторонних библиотек
- полноте документации: Shardy предоставляет хорошую документацию со всеми необходимыми разделами и ссылками на API, также весь код снабжен комментариями

$3

Начать разработку своего проекта с помощью Shardy очень просто:

1. Склонируйте шаблон сервиса или создайте новый
``
git clone git@github.com:mopsicus/shardy-template.git
`
2. Установите Shardy и все зависимости
`
npm install
`
3. Измените .env.dev
4. Запустить дебаг режим
`
npm run debug
`

Все методы и примеры API приведены в документации.

$3

Ваш (микро)сервис должен использовать интерфейс Service для обработки основных событий. Это место где вы контролируете подключенных и отключенных пользователей и передаете их в своё приложение.

Все ваши остальные объекты, классы, БД и т.д. должны быть связаны с этим классом, иначе вы не сможете получить к ним доступ из команд\запросов.

`ts
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 {
// новый клиент подключился
}

async onDisconnect(client: Client): Promise {
// клиент отключился
}

async onReady(client: Client): Promise {
// клиент готов к работе
}

async onListening(): Promise {
// сервис запущен
}

async onError(error: Error): Promise {
// произошла какая-то ошибка
}

async onClose(): Promise {
// сервис остановлен
}

}
`

$3

Shardy API удобен в использовании, он предоставляет RPC-фреймворк для межпроцессных взаимодействий. Приведенные ниже фрагменты показывают, как можно использовать каждый из них.

Основное различие между запросами и командами в том, что вызываемая сторона должна отвечать на запросы и не отвечает на команды. Это означает, что когда вы делаете запрос, у вас есть обратный вызов с данными ответа. А когда вы посылаете команду, вы просто уведомляете другую сторону о чём-то.

Запрос:

`ts
client.request('status', (data) => {
// отправка запроса и получение ответа с данными
});
`

`ts
client.request('status', (data) => {
// отправка запроса с данными
}, payload);
`

Команда:

`ts
client.command('status'); // отправка команды/события
`

`ts
client.command('status', payload); // отправка команды с данными
`

Подписка:

`ts
client.on('status', (data) => {
// подписка на команду и обработка при каждом получении
});
`

Можно также передавать запрос от сервера к клиенту, об этом см. в документации.

$3

Все команды/запросы экспортируют именованную функцию. Shardy передает все необходимые объекты внутрь ваших команд:

- commander – контроллер текущего соединения
- payload – полученные данные и данные о команде или запросе
- service – ссылка на ваш экземпляр сервиса, для взаимодействия с вашими объектами, базами данных, и т.п.

> [!IMPORTANT]
> Если ваша команда это запрос, то убедитесь, что вы ответили на него, иначе у вызывающей стороны будет таймаут.

`ts
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);
};
`

$3

Когда клиент подключается к серверу, он должен успешно завершить рукопожатие (handshake) перед началом работы. В Shardy используется двухэтапное рукопожатие для соединений.

Этапы рукопожатия:

1. Клиент отправляет данные рукопожатия на сервер
2. Сервер получает и проверяет их:
- Отравляет подтверждение клиенту
- Отключает клиента, если проверка не прошла
3. Клиент получает данные подтверждения и тоже проверяет их:
- Отправляет ответ на подтверждение серверу
- Отключается, если проверка не прошла
4. После успешного рукопожатия и подтверждения, клиент и сервер могут отправлять друг другу запросы и команды.

Если в вашей реализации нет необходимости делать двухэтапное рукопожатие, вы можете установить "заглушки" на этих методах.

Shardy предоставляет интерфейс для валидации рукопожатия. Вы можете реализовать собственную структуру данных рукопожатия и валидацию для всех этих этапов. Наследуйте класс Validator, реализуйте методы и передайте его своему сервису и клиенту.

`ts
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 {
// данные для первичного рукопожатия
}

}
`

> [!NOTE]
> Вы можете использовать простой встроенный валидатор DefaultValidator.

$3

Shardy поддерживает пользовательскую сериализацию передаваемых данных. Вы можете использовать JSON, MessagePack, Protobuf, FlatBuffers и т.д. или свой собственный сериализатор.

Достаточно наследовать класс Serializer, реализовать методы encode/decode и передать его своему сервису и клиенту.

`ts
import { PayloadData, Serializer } from 'shardy';

export class MyJsonSerializer implements Serializer {

encode(body: PayloadData): Buffer {
// перекодируйте PayloadData в Buffer для отправки
}

decode(body: Buffer): PayloadData {
// декодируйте полученные данные и сериализуйте в PayloadData
}

}
`

> [!NOTE]
> Вы можете использовать простой встроенный сериализатор DefaultSerializer.

$3

Вы можете улучшить свои Shardy-сервисы с помощью расширений. Достаточно наследовать класс Extension, реализовать необходимые методы и выбрать режим ExtensionMode для обработки: использовать расширение до методов сервиса или после, подключить их до старта сервера.

`ts
const server = new Server(process.env.SERVICE_HOST, process.env.SERVICE_PORT, service, { validator, serializer, commands });
server.use(new MyExtension());
server.use(new MyExtension2());
server.use(new MyExtension3());
...
server.start();
`

Все методы в расширении такие же как и в Service.

> [!NOTE]
> Вы можете использовать готовые расширения среди свои сервисов или сделать их публичными с помощью реестра NPM.

`ts
import { Extension, ExtensionMode } from 'shardy';

export class MyExtension implements Extension {
/**
* Название расширения
*/
name: string = 'my-extension';

/**
* Режим обработки, до или после
*/
mode: ExtensionMode = ExtensionMode.After;

/**
* Встроенный логгер
*
* @type {Logger}
*/
log!: Logger;

async init(): Promise {
// инициализация
}

async onClientConnect(client: Client): Promise {
// новый клиент подключился
}

async onClientDisconnect(client: Client, reason: DisconnectReason): Promise {
// клиент отключился
}

async onClientReady(client: Client): Promise {
// клиент готов к работе
}

async onServiceListening(): Promise {
// сервис запущен
}

async onServiceClose(): Promise {
// сервис остановлен
}
}
``

🗓️ Планы

Планы реально грандиозные! Развитие экосистемы для разработчиков, которые смогут создавать свои игры на основе существующих или собственных Shardy-сервисов, почти как из готовых блоков.

Ниже список сервисов которые планирую сделать:
- сервис обнаружения
- мониторинг
- резервное копирование

В дальнейшем, по мере необходимости, планируется делать сервисы, необходимые практически для любого многопользовательского игрового проекта:
- сервис статики
- liveops
- авторизация
- уведомления
- чаты
- покупки
- достижения
- реклама

На самом деле список бесконечный... Следите за новостями.

🏗️ Развитие

Мы приглашаем вас внести свой вклад и помочь улучшить Shardy. Пожалуйста, ознакомьтесь с документом. 🤗

Вы также можете внести свой вклад в проект Shardy:

- Помогая другим пользователям
- Мониторя список существующих проблем
- Рассказав о проекте в своих соцсетях
- Используя его в своих проектах

🤝 Поддержка

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

* Bitcoin (BTC): 1VccPXdHeiUofzEj4hPfvVbdnzoKkX8TJ
* USDT (TRC20): TMHacMp461jHH2SHJQn8VkzCPNEMrFno7m
* TON: UQDVp346KxR6XxFeYc3ksZ_jOuYjztg7b4lEs6ulEWYmJb0f
* Карты Visa, Mastercard через Boosty
* Карты МИР через CloudTips

✉️ Контактная информация

Перед тем как задать вопрос, лучшим решением будет посмотреть уже существующие проблемы, это может помочь. В любом случае, вы можете задать любой вопрос или отправить предложение по email или Telegram.

🔑 Лицензия

Shardy выпущен под лицензией MIT. Используйте бесплатно и радуйтесь. 🎉