Roqua::Support

This gem contains all sorts of support utilities and helper methods that are useful to have in RoQua's applications, but have nothing to with the domain.

Usage

Instrumentation

class Example
  include Roqua::Support::Instrumentation

  def methodname
    # This writes a single line to the event log with
    # the given event name and parameters as key=value format.
    eventlog.info 'example.eventname', optional: 'extra parameters'
  end

  def another
    # This automatically emits two lines, one for when the
    # block begins, one for when the block ends. ':started',
    # ':finished', ':failed' are appended to the event name
    # given, and the duration of the block is logged with
    # the :finished log line.
    eventlog.lifecycle 'example.lifecycle', optional: 'params' do
      sleep 5
    end
  end
end

Rails instrumentation for active_interaction operations

# Adds the instrumentation around all active_interaction operations:
# ActiveSupport::Notifications.instrument 'operation.active_interaction',
#                                         class_name: self.class.to_s.underscore do
require 'roqua/core_ext/active_interaction/rails_instrumentation'

Rails logger

You can also add an additional request logger by adding this to config/initializers/request_logger.rb:

require 'roqua/support/request_logger'
Roqua::Support::RequestLogger.attach_to :action_controller

Starting with Rails version 5 and up logging can be redirected to STDOUT by setting the RAILS_LOG_TO_STDOUT environment variable to a non blank value. roqua-support adds similar functionality by providing an alternative environment variable

  • RAILS_LOG_TO_STDOUT_USING_ROQUA_LOGGER - to send the logging output of the custom RoQua logger to STDOUT.

Error reporting

Log and error to Roqua.logger, appsignal and/or airbrake, depending on which is configured.

Roqua::Support::Errors.report(exception, extra: 'params')

Add extra info to all reports (global setting, put in initializer)

Roqua::Support::Errors.extra_parameters = {root_path: Rails.root.to_s}

When you want to add more info, but want to catch the error higher up you can call Errors.add_parameters, which will save them on the current exception instance.

rescue
  raise Roqua::Support::Errors::add_parameters(more: 'params')

Responders

option 1

Create responder including the required responder modules and use it in a controller.

class ApiResponder < ActionController::Responder
  include Roqua::Responders::ApiErrorsResponder
  include Roqua::Responders::ActiveInteractionAwareResponder
end
class ApiAreaController < ApplicationController
  self.responder = ApiResponder
  ...

option 2

Use gem 'responders'

And add required responder modules in a controller.

class ApiAreaController < ApplicationController
  responders :flash, Roqua::Responders::ApiErrorsResponder, Roqua::Responders::ActiveInteractionAwareResponder
  ...

Types

In initializer:

require 'roqua/type'

In models:

# strip whitespace and nil if blank.
attribute :firstname, :stripped_string
# strip, but don't nil if blank.
attribute :firstname, :stripped_string, allow_empty: true 

option 2

require 'roqua/type/stripped_string'

attribute :firstname, Roqua::Type::StrippedString.new(allow_empty: true)

Delayed Job activity monitoring

To add monitoring of whether Delayed Job keeps picking up jobs or checking for new jobs, add the following line to an initializer:

require 'roqua/core_ext/delayed_job/activity_monitoring'

AppSignal Probes

roqua-support contains one generic probe to monitor the current delayed job backlog count: Roqua::Probes::DelayedJobProbe

Enable it in a project by calling:

Roqua::Probes::DelayedJobProbe.enable

Scheduling

For running code in a recurring fashion (for example hourly or daily) a scheduling mechanism is included in roqua-support.

To configure the jobs that need to run you need to create the file config/schedule.rb in the Rails project that you want to schedule jobs for. An example configuration:

Roqua::Scheduling::Schedule.setup do |cron|
  cron.add_task 'hourly', run_at: Roqua::Scheduling::Schedule::BEGINNING_OF_EVERY_HOUR do
    # Put code here that you want to run at the first minute of every hour
  end

  cron.add_task 'daily', run_at: Roqua::Scheduling::Schedule::BEGINNING_OF_EVERY_DAY do
    # Put code here that you want to run every day at 0:00
  end

  cron.add_task 'every_10_minutes', run_at: proc { 10.minutes.from_now } do
    # Put code here that you want to approximately run every 10 minutes. Because the run_at is calculated after a job
    # is finished the time between jobs will be 10 minutes plus the time the job itself takes.
  end
end

Normally the RoQua infrastructure should be prepared so the jobs automatically are run if the application is correctly deployed. An AppSignal probe can be used as a fallback for job triggering. It can be enabled by placing the following code in a Rails initializer: Roqua::Probes::SchedulingProbe.enable

ActiveInteraction extensions

require 'roqua/core_ext/active_interaction/filters/date_time_as_unix_extension'

Allows a date or date_time attribute to be set by a unix time e.g. 1415608242 or '1415608242'.

require 'roqua/core_ext/active_interaction/filters/duration_filter'

class DurationFilterOperation < ActiveInteraction::Base
  duration :duration
  duration :foo, strip: true, default: nil # value is nil if duration is 0.
end

DurationFilterOperation.run(duration: 1.week)
DurationFilterOperation.run(duration: {value: 1, unit: 'weeks'})

Allows you to specify an ActiveSupport::Duration attribute.

Validators

require 'roqua/validators/subset_validator'

In errors.yml (Optional - Given defaults are available)

nl:
  errors:
    messages:
      subset: bevat onbekende keuzes

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request