Component Responsibilities (Rough) - Ruby Tuesday - Whenbot

Ruby Tuesday - Group Project - Rough - Component Responsibilities.markdown

Component Responsibilities (Rough)

Note: Numbers in square brackets correspond to the Component Interaction Flows

In this document

1. Whenbot Gem Responsibilities
2. Whenbot UI Responsibilities
3. Channel Responsibilities
4. Service Class Responsibilities
5. Trigger Responsibilities
6. Action Responsibilities
7. Other Components (Responsibilities)
8. Scheduler
9. Authentication / OAuth Module
10. Generators / Rake Tasks
11. Setup Tasks

1. Whenbot Gem Responsibilities

1. Keeps track of all registered Channels
2. Adds each registered Channel to its internal list
   • This list will be used:
     • For displaying the Channel list
     • To find the Channel's Triggers and Actions
3. Determines if a Channel has any Triggers (via metaprogramming)
4. Gets a list of Triggers from a specified channel (via metaprogramming)
5. Determines if a Channel has any Actions (via metaprogramming) [18]
6. Gets a list of Actions for a specified Channel (via metaprogramming) [17]
7. Authentication [7, 21]
   1. Check if a Trigger / Action has authentication credentials stored in the database
   • Q: Shouldn't the Trigger / Action do this?
   2. Store authentication credentials in the database, and encrypt fields as needed
   3. Retrieve and decrypt authentication credentials from the database
   4. Return if a specified Trigger has authentication credentials in the database
   5. Test authentication credentials by trying to connect to the webservice before storage (should this be the Channel's responsibility?)

• Authentication Questions:
  • Should the individual Channels handle most of this?
  • How will Trigger / Action authors test their authentication schemes?
  • Should we just have the User store their credentials in ENV, and we get it via a hash?
    • I.e. The user would set options[:auth_hash][:provider], options[:auth_hash][:oauth_token], etc., perhaps via config or something.
    • The User should be encouraged to store these as environment variables on their system, for now.
    • Then, we can add in storing it in the database later.
    • This would likely make it easier for initial Trigger / Action development as well.
    • We can store credentials in the database in a future iteration

8. Storage of Tasks in the database

• Task Table Fields:
  • trigger_channel:string
  • trigger:string
  • trigger_parameters:text
  • is_polling_trigger:boolean
  • action_channel:string
  • action:string
  • action_params:text
  • extras:text

9. Requests the Trigger to register its Webhook, when appropriate
10. Accepts Webhook callbacks
11. Relays webhook callback data to the appropriate Trigger * We should consider moving this to middleware (e.g. Sinatra) actually, to avoid a lot of the Rails stack, which we don't really need here.
12. Stores / retrieving Webhook registration details (?) (Should the Trigger do this?)
13. Requests appropriate Triggers to perform their polls on regular intervals * Done by loading all Tasks that have is_polling_trigger set to true

2. Whenbot UI Responsibilities

1. List all Triggers on a single page for the user
2. Check if a Trigger has authentication credentials stored in the database (via Gem)
3. Determine (via Gem) if a particular Channel uses OAuth or basic_http_auth for authentication
   • Should this be via an option flag, a query / call to the Channel (or should this be based on action?), or perhaps a table field (if we're storing the credentials in the database)?
4. Display the OAuth / basic_http_auth inputs to gather authentication credentials from the User for storage * Update: As noted above, for the initial version, it may be better to just have a hash of settings, set by the User via config. This is a private, single-user app; so it's not necessary to have a table of credentials. Although, one added benefit would be that we could encrypt the info easily if it was stored in the database. It can be encrypted for storage in the environment as well, but that's more of a pain for the User.
5. Display a list of Trigger Channels to the User [4]
6. Displays the list of Triggers (for a selected Trigger Channel) to the User [10]
7. Generates and displays the appropriate form fields to ask for the Parameters required for a specific Trigger [15]
8. Displays a list of Action Channels to the User [19]
9. Generates and displays the appropriate UI and form fields to ask for the Parameters required for a specific Action [15]

3. Channel Responsibilities

1. Registers with Whenbot Gem, to make it aware of its presence
   • Via config.
   • Or, if we want to get fancy, we can automate this with an #include module -> included do approach.
     • Note: For the beginners, it may make it easier to understand what's going on if they just use a config block.
2. Needs to keep standard Triggers and Actions module names, so that the Whenbot Gem can detect any Triggers and Actions.

4. Service Class Responsibilities

1. Handles the WebService interactions
   • What classname should we use for this? Does it need to be standard?
   • E.g. class Service, class Client, or class GmailService, class GmailClient

1. Connects to the web service
2. Sets up any webhooks, based on the given Trigger and Parameters
3. Polls the service upon request, for the given Triggers and Paramerts

5. Trigger Responsibilities

1. Gives a display name to be shown by the Gem UI
2. Gives a description to be shown by the Gem UI
3. Provides a list of Parameters to be gathered from the user when this Trigger is selected. [14]
4. Creating a poll request when asked, to see anything has happened that should set off a Trigger
5. Check webhook / poll result data to see if the Trigger should be fired

6. Action Responsibilities

1. Gives a display name to be shown by the Gem UI
2. Gives a description to be shown by the Gem UI
3. Provides a list of Parameters to be gathered from the user when this Action is selected. [26]
4. Performs Action, with given parameters, upon request.

---

7. Other Components

7.1. Scheduler

• Handles scheduling of polls
• Really, this is just a method that gets called by a cron job, which in turn calls each Trigger that has to poll for its data.

7.2. Authentication / OAuth module

• Should we get the individual Channel authors to handle this stuff?
• Using config?
  • Each user can get their own API key, or store their credentials in their environment, for access via ENV (or elsewhere, if they prefer)
  • The Channels will need to be able to authentication to the service on connection
  • So, there could be GmailChannel::Service::AUTH hash... or something?

7.3. Generators / Rake Tasks

• Can be called by something like rails generate whenbot:install
• We should generate / update any needed files
  • Routes (if relaying via Rails): match 'webhooks/:channel/callback', to: 'webhooks#callback'
    • Or, a Sinatra app may be better. Push to v2?
  • controller file(s) /app/controllers/webhooks, along with the callback method
• Database setup

---

8. Setup Tasks

In order for a user to get started with using Whenbot, they have to do the following:

1. Add the Whenbot Gem to their Gemfile: ``gem 'whenbot'`
2. Run bundle install
3. Run rails generate whenbot:install. This command will: * setup the database tables * Add any needed routes * Create controllers and view code as needed
4. Add any Channels they would like to use to their Gemfile * E.g. gem `whenbot-gmail'
5. Run bundle install
6. Add the following to config/initializers/whenbot.rb:

# Assuming we're adding the GmailChannel here
Whenbot.config do |config|
  config.add_channel Whenbot::GmailChannel
end