h1. CanTango

CanTango is an advanced Access Control (permissions) system for Rails 3. It:

* extends "CanCan":http://github.com/ryanb/cancan and offers a more role oriented design
* integrates with _role_ and _authentication_ systems in a non-intrusive manner
* can _cache_ ability rules between requests for increased performance
* can _store_ abilites in a permission store, including a YAML file, for easy administration
* works well with multiple user accounts and sub applications
* supports multiple "Devise":https://github.com/plataformatec/devise users

h3. Will CanTango meet my Access Control (permission) requirements?

* "CanCan vs CanTango":https://github.com/kristianmandrup/cantango/wiki/CanCan-vs-CanTango
* "CanTango overview":https://github.com/kristianmandrup/cantango/wiki

h2. Installation

h3. Ruby versions

CanTango has been tested to work with _Ruby 1.9+_ and currently doesn't support _Ruby 1.8.7_
If you require ruby 1.8.7 support, please help patch it and make a pull request ;)

h3. Install in current environment (or gemset)

@gem install cantango@

h3. Install in application

Insert into Gemfile

@gem 'cantango'@

Run bundler in a terminal/console from the folder of your Gemfile (root folder of app)

@$ bundle@

h2. Update Nov 3, 2011

Version 0.9.4.1 has been released with the following featuring and improvements:

* Redesign of Cache and Ability execution
  * Caching at the individual engine level that can be switched (configured) on/off
  * Individual caching for each type of Permit in the Permit engine
  * Each engine return a set of rules which are merged into one rule set for that particular execution mode
* Caching for the new User AC engine
* Ability to register your own Permit base classes simply by subclassing CanTango::Permit!
  * This is useful if you want to go beyond the built in types, see the @custom_permit_spec.rb@ for an example
* Some bug fixes

The :user_ac engine is a port of the Permission system from the _Rails in Action_ book.
With this engine a user can have many permissions defined, where each such permission is a persisted Permission model instance that describes a 'can' action on a specific type of object.

The new modal Ability model allows you to define rules that are run in Cache mode and others that can be run in no-cache mode. This enables you to circumvent the previos restriction that didn't allow you to use normal conditional ruby logic outside blocks if you enabled caching.

<pre>
class UserPermit < CanTango::UserPermit
  def static_rules
    can :access, Article
  end

  module Cached
    def permit_rules
      can :read, Project
    end
  end

  module NonCached
    def permit_rules
      can :edit, Article
    end
  end
end
</pre>

Any rule method defined directly for the permit is run for any (or both) modes. To define rules specifically for cache or no-cache modes, you should place them in a nested module to signify this as shown in this example.

You can configure modes with the new config object @CanTango.config.ability.modes@ and set it via @CanTango.config.ability.mode = :no_cache@ . The valid modes are: :cache, :no_cache, and :both. You can similarly configure which modes each engine should participate in, fx via @CanTango.config.permit_engine.mode = :cache@

h2. Quickstart

See the "Quickstart guide":https://github.com/kristianmandrup/cantango/wiki/Quickstart in the wiki.

For devise integration, see "Quickstart with Devise":https://github.com/kristianmandrup/cantango/wiki/Quickstart-cantango-with-devise

The following scenarios demonstrate some of the problems CanTango can help solve in an elegant way

* "Simple scenario":https://github.com/kristianmandrup/cantango/wiki/Simple-scenario
* "Complex scenario":https://github.com/kristianmandrup/cantango/wiki/Complex-scenario

h3. Generators

Cantango comes with a set of "Generators":https://github.com/kristianmandrup/cantango/wiki/Generators to get your app dancing...
Simply start with:

* cantango:install

To use the Permit generators please see the Generators wiki page ;)

h3. Rails 3 configuration

The CanTango "Configuration":https://github.com/kristianmandrup/cantango/wiki/Configuration consists of a nice DSL that let's you configure most of the things we imagine you would want to customize. Feel free to suggest more configuration options!

h3. Abilities via Permits and Permissions

Abilities are Access Control rules. With CanTango, the AC rules can be defined in both:

* "Permissions":https://github.com/kristianmandrup/cantango/wiki/Permissions (fx a yaml file)
* "Permits":https://github.com/kristianmandrup/cantango/wiki/Permits (special classes)

Note: For the simplest cases, you can define a @#permit_rules@ instance method directly in _CanTango::Ability_

Abilities can be defined for the following conceptual entities:

* User models
* User Account models
* Roles
* Role groups
* Users

h3. Debugging Abilities and Permits

See "Debugging permits"::https://github.com/kristianmandrup/cantango/wiki/Debugging-permits

h3. Design overview

The default CanTango Ability pattern is simple.

1. Return cached ability rules for candidate if available
2. Generate rules for candidate
3. Cache rules for candidate

A candidate is typically either a user or an account instance.

Caching can be enabled or disabled. To generate the rules, one or more engines are executed.

CanTango comes with the following engines:

* "Permit engine"::https://github.com/kristianmandrup/cantango/wiki/Permit-engine
* "Permission engine":https://github.com/kristianmandrup/cantango/wiki/Permission-engine

You can however freely plugin or unplug engines as you wish as described in "Pluggable engines":https://github.com/kristianmandrup/cantango/wiki/Pluggable-engines

h3. Dependencies, Adapters and Loading

CanTango had been designed to be minimally intrusive and not require too many external dependencies.

If you want to enable Moneta for caching or storage, you must execute an adapter macro: @CanTango.adapter :moneta@

This will setup lazy-loading of Moneta cache and Moneta store respectively.
If you want to enable compilation of dynamic rules (using blocks) you must use the @:compiler@ adapter

If you use any of these adapters, you must manually include the following in your Rails app Gemfile.

@gem 'dkastner-moneta'@ for moneta adapter and @gem 'sourcify'@ for the compiler adapter.

CanTango uses @autoload_modules@ from the "sweetloader":https://github.com/kristianmandrup/sweet_loader.git gem.
This ensures that all such modules are lazy-loaded. Thus if you configure CanTango to exclude an engine, the code for that engine will never be loaded, minimizing the load time and memory print.

h2. You need help?

Please post ideas, questions etc. in the "cantango group":http://groups.google.com/group/cantango on Google.

h3. Bugs, issues or feature request/ideas?

If you encounter bugs, raise an issue or:

* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
  future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

h2. Contributors

* Kristian Mandrup
* "Stanislaw Pankevich":https://github.com/stanislaw

h3. Copyright

Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.