​​Как протестировать webhook локально?
#package #service

Типичная задача #Nodejs разработчика это создание интеграций посредством webhook-ов. Типичный пример – оповещение об успешной оплате. Webhook это endpoint для оповещения вашего приложения о событии в сторонней системе, с которой вы интегрируетесь.

Webhook должен быть доступен в интернете.

Сервис ngrok.com позволяет сделать ваше локальное окружение доступным в интернете. При запуске он пробрасывает тунель между облаком и указанным портом на вашем компьютере. Вы получаете временный субдомен на ngrok.io, по которому будет доступно ваше локальное приложение. Фронтенд разработчик может таким образом провести демо с локального компьютера. Установка ngrok возможно и как CLI утилита (brew install ngrok для мак), и как npm пакет (npm install ngrok).

Кроме поднятия туннеля ngrok предоставляет на 4040 порту Web Inspection Interface. В нем доступны все запросы и ответы, прошедшие тунель. Вместо повторной отправки запросов из интегрируемой системы используйте кнопку Replay. Это многократно ускоряет отладку.

Как в Node.js узнать местоположение пользователя?
#service #gcp

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

Начинающие #nodejs разработчики устанавливают geoip-lite. В результате приложение потребляет на 100мб памяти больше. Под капотом у пакета GeoLite база от MaxMind, которая будет находиться в памяти.

Продвинутые разработчики используют сторонний сервис. Например, db-ip.com или geoip2. К сожалению, такие решения нельзя назвать дешевыми.

Наиболее опытные разработчики оптимизируют затраты, и поэтому решают эту задачу в Google Cloud Platform. Один из таких разработчиков написал статью Free IP-based GeoLocation with Google Cloud Functions. В ней описано как создать функционал аналогичный db-ip.com.

В Google Cloud Platform можно настроить custom headers так, что запрос в Node.js будет иметь заголовки с нужными данными.

Аналогичный функционал дает geoip2 модуль для nginx, но он доступен только в nginx-plus.

​​Как использовать cron в Node.js?
#kubernetes #service #nestjs

Есть много бизнес задач делать что-то по расписанию. Для этого используют утилиту cron, а расписание описывают crontab выражением. Пример: задача – отправлять отчет на емейл каждый день в 3 часа ночи, график – 0 3 * * *. Разобраться с crontab поможет сервис crontab.guru

Реализовывать cron в #nodejs проекте можно по разному:
❌Cron вызов REST API. Потерян контроль, найти ошибку будет сложно.
❌Использование setInterval/setTimeout. Оставьте это авторам библиотек, сфокусируйтесь на бизнес домене.
⚠️На уровне кода cron можно реализовать одноименным пакетом. В Nest.js есть @nestjs/schedule. Стоить учесть, что только один Node.js процесс должен запускать cron, иначе приложение теряет масштабируемость. Решается введением master process.

✅ На уровне операционной системы. Встроенный OS cron будет вызывать Node.js как CLI утилиту. Хорошо в виртуальных машинах, противопоказано внутри Docker контейнеров (избегайте порождающих процессов).
Для этого используем не библиотеку аля yargs, а cli-framework (см. clipanion и его аналоги).
Для Nest.js есть пакеты nestjs-command и nestjs-console.

✅ Cloud Native подход. Зависит от облака и требуемого способа запуска (serverless или docker). Смотрим документацию облака и консультируемся с DevOps инженером.

✅Kubernetes native подход:
➡️Cron на уровне кода, но его запуск только в одной реплике. Используется StatefulSets, а мастер реплика определяется через _0 postfix. Подробней
➡️Cron на уровне кода, но вынесен в отдельный Deployment с одной репликой.
➡️Если же задачи ресурсоемкие, то правильно использовать CronJob.

Выбирайте решение на правильном уровне!

Как документировать логику?
#architecture #service

Мало кто из #nodejs разработчиков пользуется UML диаграммами. А зря! Это очень наглядно и улучшает поддержку. Благодаря синтаксису PlantUML диаграммы можно не рисовать, а писать. Вот пример кода с картинки:
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml

Данный код описывает самую частую диаграмму – Sequence Diagram (последовательности). Есть и другие. За примерами прошу на сайт PlantUML.

Диаграммы можно описывать как в отдельных .puml файлах, так и вставлять в JSDoc. Рекомендую хранить в git репозитории не только исходники, но и сгенерированные диаграммы. Это упростить изучение проекта.

Для рендеринга можно использовать:
➡️ Расширение для JetBrains PlantUML integration
➡️ Расширение для Visual Code PlantUML
➡️ Онлайн версия

В комментариях напомнили альтернативу на JS – mermaid.

В чем проектировать структуру базы данных?
#service #database

Как известно, исправлять ошибки на этапе проектирование проще всего. Поэтому делайте дизайн структуры базы данных.

Вот подборка онлайн сервисов с удобной визуализацией и кодогенераций. Все они платные, но бесплатного тарифа хватает для фича дизайна.
➡️ SqlDBM – лучший функционал, активно развивается. Легко переключается режим просмотра.
➡️ drawsql.app – Очень простой и приятный интерфейс. Бесплатный план отлично подойдет для проекта до 15 таблиц.
➡️ dbdiagram.io – есть свой DSL, так называемый Database Markup Language. К сожалению, проект не развивается уже год.

Альтернативы, про которые не стоит забывать:
➡️ Дизайнить в SQL с последующей визуализацией в DataGrip или его аналоге.
➡️ Бумага и карандаш

Где брать сниппеты кода?
#service

Я не сторонник дублирования кода, но ради нескольких хелперов затаскивать в приложение lodash, rambda или их аналоги не стану. Вместо этого я пишу их сам. Большинство JS хелперов пишутся в одну строчку. Многие из моего helpers.ts можно найти на 1loc.dev.

Вот парочка полезных #nodejs разработчику:
➡️ Проверить, что код запущен в Node.js:
const isNode = typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
➡️ memoize для длительных вычислений
const memoize = fn => ((cache = {}) => arg => cache[arg] || (cache[arg] = fn(arg)))();

Как документировать асинхронное API?
#architecture #service

TL;DR Используйте AsynAPI

Упрощенно говоря существует только два способа взаимодействия: Req/Res и Pub/Sub. Еще эти способы называют синхронный и асинхронный.

При Request/Response клиент отправляет запрос на сервер, сервер начинает работу и отправляет ответ клиенту, как только работа будет выполнена. При Publish/Subscribe вместе запроса публикуется событие и ответ не требуется. Некоторые buzzword используемые при PubSub: WebHooks, Event-driven architectures, CQRS.

REST является классическим способом создания Web API и реализует Req/Res взаимодействие. Для его описания традиционно используют OpenApi, старое название Swagger.

Через WebSockets является дву-направленным протоколом, что позволяет создавать на его основе как Req/Res, так и Pub/Sub взаимодействие. Чаще всего WS используют именно для оповещений со стороны сервера, т.е для Pub/Sub. Естественно его следует описывать, использовать Documentation First подход. Для этого и был создан AsynAPI. Он позволяет описывать асинхронное взаимодействия не только по WS, но и по другим протоколам. Рекомендую к использованию.

Обзор сервиса RunKit
#service

Вчера @node_recipes исполнилось 4 месяца. Телеграм-канал это отличный способ ведение мини-блога. Только делиться кодом в канале это боль. Вставлять код картинкой означает, что люди не смогут его скопировать. А формат рецептов – это короткие заметки читаемые находу, которые тут же можно применять. Вставлять код текстом, даже с таким форматом неудобно.

Для сайта лучшим вариантом является RunKit, который позволяет встраивать запускаемые сниппеты кода. Пример можно увидеть в документации lodash.
Вообще основная задача сервиса помогать майнтейнерам npm-пакетов. Пользователи могут без установки попробовать функционал прямо в браузере. Составить воспроизводимый баг репорт. Для этого используется npm.runkit.com. А еще с его помощью можно делать enpoint-ы (бесплатные лямды с маленьким лимитом).

В сервисе есть notebook, упрощенная версия Jupyter notebook. К сожалению, их нельзя запускать без авторизации. В качестве примера, я сделал функцию с AbortController. Получилось не на много удобней GitHub Gist. Так что я еще в поисках как же удобно делиться кодом в канале.

30 days of Postman
#service

Материал в стиле "N days of A" делает обучение быть регулярным. Сегодня в рекомендациях именно такое обучение по Postman. Это самый популярный инструмент для работы с REST.

Задания разбиты на 30 дней. Каждое представлено в виде публичной Postman коллекции. Их сложность чередуется. По их окончанию можно получить байджик. Рекомендую пройти и отправлять ссылку на конкретный день коллегам, когда они спрашивают как сделать ту или иную задачу с помощью Postman.

Ссылки:
🔗 Анонс в блоге
🔗 Задания

Сьогодні хочу пропіарити вам Excalidraw. Це #service для малювання діаграм, які виглядають намальованими від руки. Минулого тижня в блозі було описано огляд оновлень за 2022. Рекомендую прочитати.
А ще це opensource, тобто ви можете використовувати його у своїх продуктах. Наприклад, його прикрутили для малювання архітектурних #gcp діаграм.