Прием уведомлений от внешних сервисов, или зачем был сделан Hooksler
В последнее время большую популярность приобрел сервис для командной коммуникации Slack. Из коробки он имеет немалое количество интеграций с различными сервисами + довольно удобное внешнее API. Но при всем при этом на бесплатных аккаунтах есть ограничение в 5 интеграций. Прицепили мы github, newrelic + пару досок с trello и все, количество их закончилось. Можно использовать универсальный Incoming WebHook, но он само собой имеет свой формат и никак не совместим с другими сервисами. Но программист не был бы программистом, если бы не решил эту задачу.
Решение простое как молоток. Принимаем хуки от сервисов на себя, обрабатываем и кидаем в Slack в том виде, в котором нам нужно.
Наряду с интеграциями в списке был обнаружен hammock, который написан на PHP и имеет некоторый набор плагинов, но данное решение не особо понравилось. Хоть и есть готовые интеграции, но увы, тех что нужно нет, а так как я знаком с PHP на уровне чтения кода и «что-то поправить по справочнику», то писать свои не было желания.
Потому принял решения написать свой сервис. Строить решил полностью на модульной основе: ядро и отдельно модули для «ввода» и «вывода». В качестве языка использовал Ruby, его динамическая природа очень помогла в реализации задуманного.
Итак, встречайте,
Hooksler!
Позволяет с минимумом кода собрать сервис для приема уведомлений и дальнейшей их отправки. Для конфигурирования используется свой DSL:
require 'hooksler/slack'
require 'hooksler/newrelic'
require 'hooksler/trello'
require 'dotenv'
Dotenv.load
Hooksler::Router.config do
secret_code 'very_secret_code'
host_name 'http://example.com'
endpoints do
input 'simple', type: :simple
input 'newrelic', type: :newrelic
input 'trello', type: :trello,
create: false,
public_key: ENV['TRELLO_KEY'],
member_token: ENV['TRELLO_TOKEN'],
board_id: ENV['TRELLO_ID1']
output 'black_hole', type: :dummy
output 'slack_out', type: :slack, url: ENV['SLACK_WEBHOOK_URL'], channel: '#test'
end
route 'simple' => 'slack_out'
route 'trello' => ['black_hole', 'slack_out']
route 'newrelic' => ['black_hole', 'slack_out']
end
В начале объявляются точки ввода вывода, каждая имеет свое имя и тип, а так же может содержать дополнительные параметры для инициализации. Далее указываются маршруты. Можно указывать в разном виде: один к одному, один ко многим и наоборот.
Так же на каждый маршрут можно повесить фильтры, которые могут как модифицировать сообщение, так и фильтровать его. Таким образом получаем достаточно гибкое ядро для маршрутизации сообщений из точки A в точку B.
Сообщения внутри передаются во внутреннем представлении, при этом известно из какого сервиса (его тип) оно было получено + исходное сообщение. При получении заполняются типичные поля: пользователь, текст, заголовок, ссылка, уровень. В дальнейшем они могут использоваться для формирования уведомления.
На текущий момент полностью реализовано, проверено и покрыто тестами ядро. Так же реализовано несколько интеграций: trello, newrelic, slack. Свои интеграции написать очень просто.
Немного практики
Прием сообщений
Для примера сделаем модуль, который позволит помещать тело POST запроса в поле message.
class DummyInput
extend Hooksler::Channel::Input
register :dummy
def initialize(params)
@params = params
end
def load(request)
build_message({}) do |msg|
msg.message = request.body.read
end
end
end
Объявим класс и расширим его соответствующим модулем. После чего зарегистрируем его имя. Все, после этого мы готовы принимать и обрабатывать входящие данные. Обработка запросов выполняется в методе load, принимающий лишь один параметр — объект класса Rack: Request. Никакой сложной обработки нам не требуется, поэтому сразу создаем сообщение и заполняем поле. После этого оно пойдет далее по описанным в конфигурации маршрутам. Для отправки может быть создано несколько сообщений сразу, т.е. метод load вернет массив. В дальнейшем каждый объект обрабатывается отдельно.
Отправка сообщений
Не менее просто сделать модуль для отправки, который позволит нам видеть полученные сообщения в консоли:
class DummyOutput
extend Hooksler::Channel::Output
register :dummy
def initialize(params)
@params = params
end
def dump(message)
puts "-- #{message.title} : #{message.level} --"
puts message.user
puts message.message
puts message.url
end
end
Выполняем аналогичные действия что и для входящего, только выбираем соответствующий модуль расширения. Отправка, в нашем случае вывод в консоль, выполняется в методе dump. Имя метода спорное, но send уже было занято, переопределять не хотелось.
Теперь соберем это все и опишем маршруты:
Hooksler::Router.config do
secret_code 'very_secret_code'
host_name 'http://example.com'
endpoints do
input 'in', type: :dummy
output 'out', type: :dummy
end
route 'in' => 'out'
end
Указываем код, который используется для генерации путей и хост, на котором будет висеть наш сервис. Запускаем и готово. Конечные пути можно глянуть обратившись по адресу http://example.com/_endpoints_, в ответе будет JSON. Более развернутый пример можно посмотреть в DEMO приложении: github.com/hooksler/hooksler-demo
Таким образом, без больших усилий можно настроить пересылку сообщений одновременно в разные точки: получать изменения из Trello, пересылать их в Slack, либо особо важные (например содержащие ключевые слова или метки) отправлять через push на телефон. Можно придумать кучу схем, благо основа гибкая.
Более практичный пример
На днях встала задача автоматизировать процесс приглашения пользователей в Slack. Добавлять каждого вручную — долго и нудно, а сделать отрытую регистрацию из коробки нельзя. В интернете есть готовая форма на nodejs. Но т.к. у себя уже держу работающий hooksler решил сделать на нем. Для начала, нужно как-то получить корректную почту, для этого воспользовался возможностью Mandrill заворачивать входящие сообщения в Webhook (прям то что доктор прописал). Далее, создаем входящий ящик, настраиваем Webhook и пишем наш приемник:
require 'hashie'
module Hooksler
module Mandrill
class Input
extend Hooksler::Channel::Input
register :mandrill
def initialize(params)
@params = Hashie::Mash.new(params)
end
def load(request)
return unless request.content_type == 'application/x-www-form-urlencoded'
action, payload = request.POST.first
return unless action == 'mandrill_events'
payload = MultiJson.load(payload)
payload.map do |event|
build_message(event) do |msg|
begin
method_name = "for_#{event['event']}"
self.send method_name, msg, event if respond_to? method_name
rescue
end
end
end
end
def for_inbound(msg, event)
msg.message = event['msg']['text'] || event['msg']['html']
msg.title = event['msg']['subject']
msg.user = event['msg']['headers']['From']
end
end
end
end
Принимаем события, заворачиваем в Message и шлем дальше. Теперь нам нужен код, который будет выполнять приглашение пользователей:
class SlackInviteOutbound
extend Hooksler::Channel::Output
register :slack_invite
def initialize(params)
@params = params
end
def dump(message)
return unless message.source == :mandrill
email = message.raw['msg']['from_email']
url = "https://#{@params[:team]}.slack.com/api/users.admin.invite"
HTTParty.post url, body: { email: email, token: @params[:token], set_active: true }
end
end
Принимаем сообщение, проверяем что оно пришло из Mandrill, получаем email, запрос и пользователь приглашен. При этом, мы точно уверены что ящик валидный.
В качестве последнего штриха настройка маршрутизации:
endpoints do
input 'slack_invite', type: :mandrill
output 'slack_invite', type: :slack_invite, team: 'myteam', token: 'mysupersecrettoken'
end
route 'slack_invite' => 'slack_invite'
Запускаем и наслаждаемся процессом.
В заключение
Данное решение использую у себя уже некоторое время, пока проблем не возникало — все ходит стабильно. Единственное, для trello не все случаи обработаны, уж больно много у них различных типов уведомлений. Так же, для Slack были сделаны свои модули форматирования, кому интересно могут посмотреть пример здесь.
В дальнейшем, в планах расширять количество адаптеров как для приема, так и для отправки сообщений. Надеюсь, данное решение будет ещё кому-то полезным.
Критика и предложения приветствуются, сообщения об ошибках в тексте в личку.
Сам Hooksler и адаптеры доступны на Github: github.com/hooksler
