npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

shardy

v1.0.2

Published

Framework for online games and applications on Node.js

Downloads

10

Readme

Static Badge Static Badge

💬 Описание

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

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

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

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

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

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

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

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

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

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

  1. Склонируйте шаблон сервиса или создайте новый
    git clone [email protected]: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. Используйте бесплатно и радуйтесь. 🎉