Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hausgold/alarmable
A reusable alarm extension to Active Record models
https://github.com/hausgold/alarmable
activejob activerecord activerecord-callbacks alarms concern gem notifications oss rails ruby ruby-gem
Last synced: about 1 month ago
JSON representation
A reusable alarm extension to Active Record models
- Host: GitHub
- URL: https://github.com/hausgold/alarmable
- Owner: hausgold
- License: mit
- Created: 2017-11-09T10:07:28.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2024-08-19T08:56:13.000Z (4 months ago)
- Last Synced: 2024-09-22T21:23:57.789Z (3 months ago)
- Topics: activejob, activerecord, activerecord-callbacks, alarms, concern, gem, notifications, oss, rails, ruby, ruby-gem
- Language: Ruby
- Homepage: https://rubygems.org/gems/alarmable
- Size: 89.8 KB
- Stars: 1
- Watchers: 11
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://github.com/hausgold/alarmable/actions/workflows/test.yml)
[](https://badge.fury.io/rb/alarmable)
[](https://knowledge.hausgold.de/coverage)
[](https://knowledge.hausgold.de/coverage)
[](https://www.rubydoc.info/gems/alarmable)
This is a reusable alarm concern for Active Record models. It adds support for
the automatic maintenance of Active Job's which are scheduled for the given
alarms. On alarm updates the jobs will be canceled and rescheduled. This is
supported only for Sidekiq, Delayed Job, resque and the Active Job TestAdapter.
(See [ActiveJob::Cancel](https://github.com/y-yagi/activejob-cancel) for the
list of supported adapters)
- [Installation](#installation)
- [Usage](#usage)
- [Database migration](#database-migration)
- [Active Record Model](#active-record-model)
- [Active Job](#active-job)
- [Development](#development)
- [Code of Conduct](#code-of-conduct)
- [Contributing](#contributing)
- [Releasing](#releasing)
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'alarmable'
```
And then execute:
```bash
$ bundle
```
Or install it yourself as:
```bash
$ gem install alarmable
```
## Usage
### Database migration
This concern requires the persistence (and availability) of two properties.
* The first is the JSONB array which holds the alarms. (`alarms`)
* The seconds is the JSONB array which holds the ids of the
scheduled alarm jobs. (`alarm_jobs`)
```bash
$ rails generate migration AddAlarmsAndAlarmJobsToEntity \
alarms:jsonb alarm_jobs:jsonb
```
### Active Record Model
Furthermore a Active Record model which uses this concern must define the
Active Job class which will be scheduled. (`alarm_job`) The user must also
define the base date property of the owning side.
(`alarm_base_date_property`) This base date is mandatory to calculate the
correct alarm date/time. When the base date is not set (`nil`) no new
notification job will be enqueued. When the base date is unset on an update,
the previously enqueued job will be canceled.
```ruby
# Your Active Record Model
class Entity < ApplicationRecord
include Alarmable
self.alarm_job = NotificationJob
self.alarm_base_date_property = :start_at
end
```
The alarms hash needs to be an array in the following format:
```ruby
[
{
"channel": "email", # email, push, web_notification, etc..
"before_minutes": 15 # start_at - before_minutes, >= 1
# [..] you can add custom properties if you like
}
]
```
### Active Job
The given alarm job class will be scheduled with the following two arguments.
* id - The class/instance id of the record which owns the alarm
* alarm - The alarm hash itself (see the format above)
A suitable alarm job perform method should look like this:
```ruby
# Your notification job
class NotificationJob < ApplicationJob
# @param id [String] The entity id
# @param alarm [Hash] The alarm object
def perform(id, alarm)
# Do something special for `alarm.channel` ..
end
end
```
## Development
After checking out the repo, run `make install` to install dependencies. Then,
run `make test` to run the tests. You can also run `make shell-irb` for an
interactive prompt that will allow you to experiment.
## Code of Conduct
Everyone interacting in the project codebase, issue tracker, chat
rooms and mailing lists is expected to follow the [code of
conduct](./CODE_OF_CONDUCT.md).
## Contributing
Bug reports and pull requests are welcome on GitHub at
https://github.com/hausgold/alarmable. Make sure that every pull request adds
a bullet point to the [changelog](./CHANGELOG.md) file with a reference to the
actual pull request.
## Releasing
The release process of this Gem is fully automated. You just need to open the
Github Actions [Release
Workflow](https://github.com/hausgold/alarmable/actions/workflows/release.yml)
and trigger a new run via the **Run workflow** button. Insert the new version
number (check the [changelog](./CHANGELOG.md) first for the latest release) and
you're done.