anchor.diff:  
   == Builtin Handlers
   
  -=== Cross-Origin Resource Sharing
  +=== Auth
  +
  +The authentication facilites in _catacumba_ are built using link:https://github.com/funcool/buddy[buddy]
  +security library.
  +
  +As _catacumba_ handlers system is very flexible, so you really don't locked to use _buddy_. You can
  +write your own auth facilities and attach them to _catacumba_ using the routing chain.
  +
  +For start using auth facilities in your application, you should add the `auth` handler
  +to you routing chain. Let see an example using session based auth backend:
  +
  +[source, clojure]
  +----
  +(require '[catacumba.handlers :as hs])
  +(require '[catacumba.handlers.auth :as auth])
  +
  +;; Create an instance of auth backend
  +(def auth-backend
  +  (auth/session-backend))
  +
  +(def app
  +  (ct/routes [[:any (hs/session {:storage :inmemory})]
  +              [:any (hs/auth auth-backend)]
  +              [:get some-handler]]))
  +----
  +
  +As we mentioned previously, behind the scenes _buddy_ is used, so almost all auth backends
  +defined in buddy can be used with _catacumba_, such as jws and jwe backens.
  +
  +It there some exceptions, such as the session auth backend, because the sessions works
  +slightly different in _catacumba_ and the buddy session auth backend reliad in a ring
  +session behavior.
  +
  +The buddy access rules are not supported because, the _catacumba_ routing chain system
  +fullfills that gap. You can define concrete authorization rules and attach them directly
  +in a routing chain.
  +
  +You can see a working example using auth facilties <<website-example,here>>.
  +
  +
  +=== Sessions
  +
  +==== Getting Started
  +
  +The http sessions in _catacumba_ are also implemented as chain handler. So, you can add sessions
  +to you application just adding the handler to your routing chain:
  +
  +[source, clojure]
  +----
  +(require '[catacumba.handlers :as hs])
  +
  +(def app
  +  (ct/routes [[:any (hs/session {:storage :inmemory})]
  +              [:get your-handler]]))
  +----
  +
  +All handlers in the route pipeline that are going after the session handler will come with `:session`
  +key in the context with a "atom" like object. You just treat it as atom, so for attach some data
  +to the session you should use the well known `swap!` function:
  +
  +[source, clojure]
  +----
  +(defn my-handler
  +  [context]
  +  (let [session (:session context)]
  +    (swap! session assoc :userid 1)
  +    "my response"))
  +----
  +
  +You can clean the session just reseting to the empty map:
  +
  +[source, clojure]
  +----
  +(reset! session {})
  +----
  +
  +One of the big advantages of using the chain routing for setup session, is that you put session
  +to a concrete subset of urls/resources avoiding unnecesary code execution for hendler that
  +does not need sessions:
  +
  +[source, clojure]
  +----
  +(def app
  +  (ct/routes [[:prefix "admin"
  +               [:any (hs/session {:storage :inmemory})]
  +               [:get your-handler]]
  +              [:prefix "api"
  +               [:get "users" other-handler]
  +               [:get ...]]]))
  +----
  +
  +
  +==== Session storages
  +
  +Currently _catacumba_ comes with one basic session storage, the `:inmemory`. But the session
  +storage system is plugable and is defined in terms of the following protocol:
  +
  +[source, clojure]
  +----
  +(defprotocol ISessionStorage
  +  (read-session [_ key])
  +  (write-session [_ key data])
  +  (delete-session [_ key]))
  +----
  +
  +If you known the ring based session storages, you can observe that the _catacumba_ session
  +storage abstraction is almost identical to the ring session abstracition, so migrate or
  +adapt the ring session storages is really easy.
  +
  +For use a concrete session storage, just pass a instance of it as value of the `:storage`
  +key in a session handler constructor:
  +
  +[source, clojure]
  +----
  +(hs/session {:storage (my-storage-constructor)})
  +----
  +
  +
  +=== Context as Request
  +
  +By default, the _catacumba_'s context allows you direct access to the request and response, that are
  +instances of classes defined in Ratpack. That classes allows you access to all related properties
  +such as headers, the request body, the request method, etc.
  +
  +But _catacumba_ at this moment offers a very limited set of helper functions for interacting with that
  +data: get/set headers and read the body (explained in previous sections).
  +
  +For compensate this, _catacumba_ comes with special chain handler that populates the context with
  +basic request properties such as, headers, path and method:
  +
  +[source, clojure]
  +----
  +(require '[catacumba.handlers :refer [basic-request]])
  +
  +(def app
  +  (ct/routes [[:prefix "api/v1"
  +               [:any basic-request]
  +               [:get "foo" some-handler]
  +               [:post "foo" some-save-handler]]]))
  +----
  +
  +
  +=== Security
  +
  +==== Cross-Origin Resource Sharing
   
   Is a mechanism that allows restricted resources (e.g. fonts, JavaScript, etc.) on a web page to be
   requested from another domain outside the domain from which the resource originated.
  
positive.code: java -Dcatacumba.port=8000 -Dcatacumba.debug=false -jar yourjarhere.jar
  ----
  
  
  == Examples
  
  === Debugging with prone
  
negative.code: The `:origin` key can be a set of possible origins or directlly `"*"` for allow all origins.
  
  
  ==== Content Security Policy
  
  Is a security related chain handler that appropiatelly set the `Content-Security-Policy` headers.
  