surveillance_authority

Introduction

This gem provides a dsl to easily write observers in one or more centralized files.

Installation

Install surveillance_authority by adding

gem 'surveillance_authority'

to your Gemfile or install it using

gem install surveillance_authority

Integration into your project

config/initializers

create one or more ruby files in which you can define your surveillance rules. For example:


     SurveillanceAuthority.observe do
       # Do something after a new movie was created
       after "Movie#create" do |movie|
          # ... do stuff
       end
   # Do something before a User gets updated
   before "User#update" do |user|
     # ... do stuff
   end
 end

Uhm ...so what?

surveillance_authority is meant to be used together with some plugins. One of those is varnish_sweeper, which invalidates certain routes.

Writing plugins for surveillance_authority

Making methods available to surveillance_authority

In order to write a plugin for surveillance_authority, simply create a class that inherits from

SurveillanceAuthority::Sanctions

all public methods of that class will be available in the blocks. E.g.


 class VarnishSweeper < SurveillanceAuthority::Sanctions
   def sweep(url, options = {})
     options.reverse_merge(
       :method => :invalidate
     }
     
     options[:method] == :purge ? purge_url(url) : invalidate(url)
   end
 
   private
   def purge_url(url)
     ...
   end
 
   def invalidate(url)
     ...
   end
 end

will make the sweep method available:


 SurveillanceAuthority.observe do
   # Do something after a new movie was updated
   after "Movie#update" do |movie|
      sweep movie_path(movie), :method => :invalidate
   end
 end

Configuration for plugins

Configuring plugins should be made with the central config method provided by surveillance_authority. If we again use a plugin called VarnishSweeper, configuring this plugin should happen like this:

SurveillanceAuthority.config(VarnishSweeper, <hash with options>)

Withing your plugin, you will be able to access your options simply by calling config.

Example: `VarnishSweep` needs to be configured with a base url to varnish

 class VarnishSweeper < SurveillanceAuthority::Sanctions
   default_config(:method => :purge)

   def sweep(url, options = {})
     options.reverse_merge(
       :method => :invalidate
     }
     
     options[:method] == :purge ? purge_url(url) : invalidate(url)
   end
 
   private
   def varnish_base_url
     config[:base_url]
   end

   def purge_url(url)
     ...
   end
 
   def invalidate(url)
     ...
   end
 end

In the project using this plugin:

  SurveillanceAuthority.config(VarnishSweeper, :base_url => "http://varnish.example.com")
  ...

If you want to access the config of other plugins, use:

  `SurveillanceAuthority.config_for(<plugin>)`

Note that you can easily provide default options for your plugin by calling default_config in your plugin file:

 default_config(:method => :purge)

which comes in handy if some config options of your plugin do not need to be set by the users.

Configuration Validator

If your want to make sure that all configuration values of your plugin are valid, you can define a method called validate_configuration that does the necessary checks. It gets called after calling default_config and config= and should get called by methods that take in options that can overwrite the configuration. It should take care of the situation. If validate_configuration validates it should return the @config variable as its result gets returned when calling config=.

 class VarnishSweeper < SurveillanceAuthority::Sanctions
   default_config(:method => :purge)
    
   def validate_configuration
     # make sure the method option is either set to :purge or :header_invalidation
     raise "invalid config" unless [:purge, :header_invalidation].include?( @config[:method] )
     @config
   end

   def sweep(url, options = {})
     options = validate_configuration( self.config.merge(options) )
     ...
   end
 end