cantango 0.8.0

data/wiki/config/ability.markdown

@@ -0,0 +1,18 @@
+You can configure your own Ability factory.
+
+```ruby
+
+class MyCustomAbility < CanTango::Ability
+  def initialize name, options = {}
+    # super
+    # custom logic
+  end
+end
+
+Cantango.configure.ability do |ability|
+  ability.factory Proc.new{|name, options| MyCustomAbility.new name, options }
+end
+```
+
+This feature is currently also used for performance testing of Cantango!
+

data/wiki/config/autoload.markdown

@@ -0,0 +1,31 @@
+Cantango is by default setup to autoload the following:
+
+* Models (app/models)
+* Permits (app/permits)
+
+The autoloading is performed as part of the Cantango Rails engine initialization.
+
+To configure autoloading:
+
+```ruby
+Cantango.configure.autoload do |load|
+  load.models :off
+  load.permits :on
+end
+```
+
+## Models autoloading
+
+Models are autoloaded in order to be sure that the Cantango class macros such as `#tango_user` are executed
+and thus that User and Account modesl are registered with Cantango.
+
+If you don't wont to autoload the models for performance or other
+reasons, you can alternatively register the models directly (see [Models
+registration]]).
+
+## Permits autoloading
+
+Permits autoloading is done so as to ensure they are made available to
+CanTango::Ability. If you want full control over which Permits are
+loaded when, you can disable this feature.
+

data/wiki/config/guest.markdown

@@ -0,0 +1,49 @@
+CanTango operates with the concepts of a Guest user and a Guest account.
+
+## Guest user
+
+In case the `curent_xxx_` method does't return a valid user, Cantango will attempt to return 
+a guest user according to configuration and conventions.
+
+If Cantango has not been configured with specific Guest user configuration, it will see if the User model 
+is available. If so, it will call `#guest` on it (if method available).
+
+## Configuration
+
+Cantango should be configured with how to retrieve (or create) such a guest user via:
+
+`CanTango::Configuration.guest.user obj`
+
+The `obj` argument can be either:
+
+* User instance
+* A procedure in the form of a lambda or Proc
+* A block
+
+The Guest user should normally have restricted permission rules, mostly only :read access.
+We recommend setting the Guest permission rules to: `can :read, :all` and refine from there.
+
+## Guest user account
+
+In case the `curent_xxx_account` method does't return a valid user account, Cantango will attempt to return 
+a guest user account according to configuration and conventions.
+
+If Cantango has not been configured with specific Guest user account configuration, it will 
+see if the UserAccount model is available.
+If so, it will call `#guest` on it (if method available).
+
+## Configuration
+
+Cantango should be configured with how to retrieve (or create) such a guest user via:
+
+`CanTango::Configuration.guest.account obj`
+
+The `obj` argument can be either:
+
+* UserAccount instance
+* A procedure in the form of a lambda or Proc
+* A block
+
+The Guest user account should usually be setup to have a guest user only.
+
+

data/wiki/config/models_registration.markdown

@@ -0,0 +1,16 @@
+CanTango is by default setup to [[autoload models and permits]].
+
+If you don't want to enable models autoloading but have them remain
+lazy-loaded as is the Rails 3 defult, you have to register the core
+models used by Cantango.
+
+In Cantango, registration is done through a Registry like this:
+
+```ruby
+Cantango.configure do |config|
+  config.users.register :user, :admin
+  config.user_accounts.register :user, :admin
+end
+```
+
+

data/wiki/config/role_groups.markdown

@@ -0,0 +1 @@
+Currently not used

data/wiki/config/roles.markdown

@@ -0,0 +1 @@
+Currently not used

data/wiki/engines/cache/config.markdown

@@ -0,0 +1,31 @@
+The Cantango Cache engine is used to cache rules between requests. It will be referenced here as the 'rules cache'. 
+
+The rules cache needs a store to store the rules. Cantango is setup to
+use a Session store by default. The session store is internally setup to
+wrap a Moneta memory store.
+
+To configure the cache store for the rules cache:
+
+```ruby
+Cantango.configure do |config|
+  config.cache.store do |store|
+    store.default Cantango::Cache::MonetaCache
+    store.default_type :redis
+    store.options = {:port => 5032}
+  end
+end
+```
+
+Alternatively you can define your own Cache store factory:
+
+```ruby
+Cantango.configure do |config|
+  config.cache.store do |store|
+    store.factory Proc.new {|name, options| MyFantasticCache.new name, {:awesome_power => true}.merge(options) }
+  end
+end
+```
+
+
+
+

data/wiki/engines/cache/store.markdown

@@ -0,0 +1,6 @@
+## Marshalling
+
+### Procs
+
+Procs are marshalled via the 'sourcify' gem, that handle converting a
+proc to and from a source code string.

data/wiki/engines/permissions/categories.markdown

@@ -0,0 +1,33 @@
+Cantango comes with the concept of Categories of models. This is useful
+when a group of models logically belong to gether and can be grouped as
+one named category. You can then reference these category from your
+permissions.
+
+Example categories Yaml file:
+
+```yaml
+another_articles:
+  [Post, Article]
+articles:
+  [Article, Post, Comment]
+user_models:
+  [Admin, Guest, User]
+``
+
+The categories can be referenced using the special '^' (pointer) as a prefix.
+
+Note: In the near future you will also be able to reference categories from
+Permit classes.
+
+Example of Using Cateogry pointers in permissions file:
+
+```yaml
+roles:
+  user:
+    can:
+      read:
+      - ^articles
+      - Post
+```
+
+The "^articles" point to the articles Category from the Categories file ;)

data/wiki/engines/permissions/config.markdown

@@ -0,0 +1,60 @@
+Permissions can be defined in a permissions store. A permission store
+should store the following sets:
+
+* roles
+* role groups
+* licenses
+* users
+
+A typical permission store is a simple Yaml file, using the following structure:
+
+```yaml
+roles:
+  admin:
+    can:
+      manage:
+      - all
+  user:
+    can:
+      read:
+      - ^articles
+      - Post
+      write:
+      - Comment
+    cannot:
+      write:
+      - Article
+role_groups:
+  bloggers:
+    can:
+      read:
+      - Article
+      - Comment
+    cannot:
+      write:
+      - Article
+      - Post
+  editors:
+    can:
+      read:
+      - Article
+      - Comment
+    cannot:
+      write:
+      - Article
+      - Post
+licenses:
+  editors:
+    can:
+      manage:
+      - all
+users:
+  stan@theman.com:
+    can:
+      manage:
+      - all
+  kris@thewiz.dk:
+    cannot:
+      read:
+        - Book
+

data/wiki/feature_list.markdown

@@ -0,0 +1,39 @@
+Cantango currently comes with the following features:
+
+* [[Engines]]
+  * [[Cache engine]]
+  * [[Permissions engine]]
+  * [[Permits engine]]
+
+* [[Rules cache]]
+  * [[Session cache]]
+  * [[Moneta cache]]
+
+* [[Rules store]]
+  * [[Yaml store]]
+  * [[Moneta store]] (incomplete)
+
+* [[Permissions]]
+* [[Role Permits]]
+* [[RoleGroup Permits]]
+* [[Licenses]]
+
+[[Masquerading]]
+  * [[User masquerading]]
+  * [[User Account masquerading]]
+
+[[Configuration]]
+  * [[Guest user account]]
+  * [[Guest user]]
+  * [[Autoloading]]
+  * [[Engines config]]
+
+[[Integrations]]
+  * [[CanCan integration]]
+  * [[Devise integration]]
+  * [[Rails 3 integration]]
+
+The following features are currently planned for the future:
+* Role Filters
+* Domain differentiation on rules
+* Customize Ability#initialize process flow via registration of :before and :after hooks

data/wiki/rules_caching.markdown

@@ -0,0 +1,17 @@
+The Cantango Cache engine is used to cache rules between requests. The
+[[Cantango Ability]] receives a candidate and an options hash.
+
+If caching is enabled, caching proceeds as follows:
+
+1. Cache key is generated for candidate
+2. Rules are generated
+3. Rules are stored in Caching store for the cache key
+4. In subsequent requests with same key, rules are retrieved from cache
+
+## Cache key
+
+A cache key is generated for the candidate in order to ensure that the
+rules are cached for that exact candidate and not reused for another
+candidate.
+
+

data/wiki/users/masquerading.markdown

@@ -0,0 +1,29 @@
+Maquerading is the concept of one user acting as though he/she was
+another user. In Cantango we enhance this to also be possible to
+masquerade account login if needed.
+
+In order to masquerade, you simply do:
+
+```ruby
+user.masquerade_as other_user
+```
+
+If you are using the 'friendly_id' gem, you can even do:
+
+```ruby
+admin_user.masquerade_as 'stanislaw'
+```
+
+This requires that you have configured your user model with a friendly id, in this case `username`.
+
+## Masquerading accounts
+
+Account masquerading allows a user to act as if he is logged into
+another account.
+
+```ruby
+admin_account.masquerade_as normal_account
+```
+
+
+

data/wiki/when_to_use.markdown

@@ -0,0 +1,64 @@
+Choosing the right access control system is an important decission in
+any project. The following is an attempt at an objective guide to help
+you make the right decission.
+
+It is important to stress, that it is never recommended to choose an
+overly complex solution to handle simple requirements.
+In many simple access control scenarios, a simple access control system
+will do just fine and even allow for greater flexibility!
+
+## When to use CanCan
+
+CanCan is useful to use on its own when:
+
+* Access rule requirements are simple
+* There are few roles (and/or role groups)
+* A few can? statements in critical views and controllers
+* Access is mostly controlled on the controller REST method level
+* Guest user logic is simple
+* You have a simple User model class and a #current_user method that
+  works for all logged in users.
+
+If this fits with your requirements, by all means start off with just
+CanCan. It should be pretty easy to upgrade to CanTango if you need to
+in the future.
+
+## When to use CanTango
+
+If you find that your requirements go beyond what CanCan can satisfy out
+of the box without too much tweaking on your own part, CanTango just
+might be the solution you are looking for.
+
+Complexity and fine control
+* Access rule requirements are somewhat complex
+* Access must be controlled on a more fine grained level
+
+Users
+* You have multiple types of users, fx User, Guest and Admin
+* There are more than a few roles (and/or role groups)
+
+Performance
+* Access control should be fast, you need caching of permits for each user
+* Users not logged in should be granted a Guest user instance
+
+User accounts:
+* Your app has multiple User accounts, one for each sub-app
+* Access control logic can differ for each account
+* A user can be logged into one or more accounts simultaneously
+* Some users are allowed to masquerade as other users
+* Some users are allowed to masquerade as if logged into a
+  different account
+
+Administration
+* Access control (permisssions) should be maintained in logical
+  containers, on a per-role or role group basis
+* Access control should be maintained and administrated in a permission
+  store, fx a Yaml file
+
+If more than a few items on this list reflect your requirements, give
+CanTango a chance!
+
+If your requirements go beyond this, create your own extension or even
+better help enhance CanTango directly!
+
+Have FUN! Let's Tango!

data/wiki/why_to_use.markdown

@@ -0,0 +1,11 @@
+Why use Cantango?
+
+* Performance (rules caching)
+* Partition permission rules into seperate classes for each role and
+  role group
+* Reuse of permission rules using inheritance and licenses (mixins)
+* Maintain and administrate permissions in a rules store, fx a Yaml file
+* Masquerading of users and accounts
+* Guest users and Gues account integration
+* Designed for devise integration, with support for multiple devise
+  users `#current_user`, `#current_admin` etc.