Skip to content

Latest commit

 

History

History
272 lines (191 loc) · 13.7 KB

README.ru.md

File metadata and controls

272 lines (191 loc) · 13.7 KB

Static Badge Static Badge

Shardy

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

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

💬 Описание

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

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

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

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

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

Зачем использовать Shardy?

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

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

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

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

  1. Склонируйте шаблон сервиса или создайте новый 
    git clone git@github.com:mopsicus/shardy-template.git
  2. Установите Shardy и все зависимости 
    npm install
  3. Измените .env.dev
  4. Запустить дебаг режим 
    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 используется двухэтапное рукопожатие для соединений.

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

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

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

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. Используйте бесплатно и радуйтесь. 🎉