farscape 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aaaa9b7314cc73ef0fd43a9de2e7f17f78999636
+  data.tar.gz: ff6f62f5301162b952821b23a80be847fac1627e
+SHA512:
+  metadata.gz: 401dc3a255241d08565bc7067e6933b8450e48a97b87af028011e5600a41db720570731059486269daf4e95200c0f283cd5068666c90ff702699fa7de7e2022a
+  data.tar.gz: dbf7b5362bc58a66771ba67b8f8b822a17947eafc92ee5ca043019c3d2a76eb9907272919790b5dc23980e940f35f170e83f72724965509d19d20d2baf5ef5ef

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# 1.2.0
+* Add support for templated URIs and POST requests
+
+# 1.1.2
+* Prevent crash when an embedded resource is not an enumerable
+
+# 1.1.1
+* Add POST method support
+
+# 1.1.0
+* Update Faraday dependency to ~> 0.9
+
+# 0.0.1
+* Initial Release

data/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+Farscape is associated with the [Crichton Library](https://github.com/mdsol/crichton) and follows the same 
+[guidelines](https://github.com/mdsol/crichton/blob/develop/CONTRIBUTING.md).

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'crichton', git: 'https://github.com/mdsol-share/crichton.git', branch: 'develop'
+gem 'moya', git: 'https://github.com/mdsol/moya.git', branch: 'develop'

data/Gemfile.lock

@@ -0,0 +1,192 @@
+GIT
+  remote: git@github.com:mdsol/representors.git
+  revision: 958dc778d62897f09dd0200f3690f96cb5265b98
+  branch: 0-0-stable
+  specs:
+    representors (0.0.3)
+      addressable (~> 2.3)
+      rake
+
+GIT
+  remote: https://www.github.com/mdsol-share/crichton.git
+  revision: 63c74ce781a41538454b81fd8c44dc36117aa92b
+  branch: develop
+  specs:
+    crichton (0.1.0)
+      activesupport (>= 3.2.0)
+      addressable (~> 2.3.0)
+      builder (>= 3.0.0)
+      colorize (~> 0.6.0)
+      dice_bag (~> 0.8)
+      diffy (~> 3.0.1)
+      i18n (>= 0.6.5)
+      nokogiri (>= 1.6.0)
+      rake
+
+GIT
+  remote: https://www.github.com/mdsol/moya.git
+  revision: 6e8b324dee6335e5d56d320ba0a605b6ebae8574
+  branch: develop
+  specs:
+    moya (1.0.0)
+      activeuuid
+      launchy
+      nokogiri
+      rack
+      rails (= 4.1.8)
+      sqlite3
+      yajl-ruby (~> 1.2.0)
+
+PATH
+  remote: .
+  specs:
+    farscape (1.0.1)
+      activesupport
+      addressable (~> 2.3.0)
+      dice_bag
+      faraday (~> 0.8.8)
+      faraday_middleware (~> 0.9)
+      rake
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionmailer (4.1.8)
+      actionpack (= 4.1.8)
+      actionview (= 4.1.8)
+      mail (~> 2.5, >= 2.5.4)
+    actionpack (4.1.8)
+      actionview (= 4.1.8)
+      activesupport (= 4.1.8)
+      rack (~> 1.5.2)
+      rack-test (~> 0.6.2)
+    actionview (4.1.8)
+      activesupport (= 4.1.8)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+    activemodel (4.1.8)
+      activesupport (= 4.1.8)
+      builder (~> 3.1)
+    activerecord (4.1.8)
+      activemodel (= 4.1.8)
+      activesupport (= 4.1.8)
+      arel (~> 5.0.0)
+    activesupport (4.1.8)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    activeuuid (0.6.0)
+      activerecord (>= 3.1)
+      uuidtools
+    addressable (2.3.7)
+    arel (5.0.1.20140414130214)
+    awesome_print (1.1.0)
+    builder (3.2.2)
+    coderay (1.1.0)
+    colorize (0.6.0)
+    crack (0.4.2)
+      safe_yaml (~> 1.0.0)
+    dice_bag (0.8.0)
+      rake
+    diff-lcs (1.2.5)
+    diffy (3.0.7)
+    docile (1.1.5)
+    erubis (2.7.0)
+    faraday (0.8.9)
+      multipart-post (~> 1.2.0)
+    faraday_middleware (0.9.1)
+      faraday (>= 0.7.4, < 0.10)
+    hike (1.2.3)
+    i18n (0.7.0)
+    json (1.8.2)
+    launchy (2.4.3)
+      addressable (~> 2.3)
+    mail (2.6.3)
+      mime-types (>= 1.16, < 3)
+    method_source (0.8.2)
+    mime-types (2.4.3)
+    mini_portile (0.6.2)
+    minitest (5.5.1)
+    multi_json (1.11.0)
+    multipart-post (1.2.0)
+    nokogiri (1.6.6.2)
+      mini_portile (~> 0.6.0)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rack (1.5.2)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails (4.1.8)
+      actionmailer (= 4.1.8)
+      actionpack (= 4.1.8)
+      actionview (= 4.1.8)
+      activemodel (= 4.1.8)
+      activerecord (= 4.1.8)
+      activesupport (= 4.1.8)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 4.1.8)
+      sprockets-rails (~> 2.0)
+    railties (4.1.8)
+      actionpack (= 4.1.8)
+      activesupport (= 4.1.8)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (0.9.6)
+    redcarpet (3.2.2)
+    rspec (2.99.0)
+      rspec-core (~> 2.99.0)
+      rspec-expectations (~> 2.99.0)
+      rspec-mocks (~> 2.99.0)
+    rspec-core (2.99.2)
+    rspec-expectations (2.99.2)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.99.3)
+    safe_yaml (1.0.4)
+    simplecov (0.9.2)
+      docile (~> 1.1.0)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.9.0)
+    simplecov-html (0.9.0)
+    slop (3.6.0)
+    sprockets (2.12.3)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sprockets-rails (2.2.4)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      sprockets (>= 2.8, < 4.0)
+    sqlite3 (1.3.10)
+    thor (0.19.1)
+    thread_safe (0.3.5)
+    tilt (1.4.1)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    uuidtools (2.1.5)
+    webmock (1.13.0)
+      addressable (>= 2.2.7)
+      crack (>= 0.3.2)
+    yajl-ruby (1.2.1)
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print (~> 1.1.0)
+  crichton!
+  farscape!
+  moya!
+  pry
+  rake (~> 0.9)
+  redcarpet
+  representors!
+  rspec (~> 2.14)
+  simplecov (~> 0.7)
+  webmock (~> 1.13.0)
+  yard (~> 0.8.5)

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2013 Medidata Solutions Worldwide
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,189 @@
+# Farscape
+[![Build Status](https://travis-ci.org/mdsol/farscape.svg)](https://travis-ci.org/mdsol/farscape)
+
+Farscape is a hypermedia agent that simplifies consuming Hypermedia API responses. It shoots through wormholes with
+[Crichton](https://github.com/mdsol/crichton) at the helm and takes you to unknown places in the universe!
+
+Checkout the [Documentation][] for more info.
+
+NOTE: THIS IS UNDER HEAVY DEV AND IS NOT READY TO BE USED YET
+
+
+## API Entry
+There are various flavors of configuration that Farscape supports for entering a Hypermedia API. These all assume
+a response with a supported Hypermedia media-type and a root that lists available resources as links.
+
+### A Hypermedia API
+For a interacting with an API (or individual service that supports a list of resources at its root), you enter the
+API and follow your nose using the `enter` method on the agent. This method returns a [Farscape::Representor]() 
+instance with a simple state-machine interface of `attributes` (data) and `transitions` (link/form affordances) for 
+interacting with the resource representations.
+
+```ruby
+agent = Farscape::Agent.new('http://example.com/my_api')
+
+resources = agent.enter
+resources.attributes # => { meta: 'data', or: 'other data' }
+resources.transitions.keys # => ['http://example.com/rel/drds', 'http://example.com/rel/leviathans']
+```
+
+### A Hypermedia Discovery Service
+For interacting with a discovery service, Farscape supports follow your nose entry to select a registered resource
+or immediately loading a discoverable resource if known to be registered in the service *a priori*.
+
+```ruby
+agent = Farscape::Agent.new('http://example.com/my_discovery_service')
+
+resources = agent.enter
+resources.attributes # => { meta: 'data', or: 'other data' }
+resources.transitions.keys # => ['http://example.com/rel/drds', 'http://example.com/rel/leviathans', 'next', 'last']
+
+drds = agent.enter('http://example.com/rel/drds')
+drds.attributes # => { total_count: 25, items: [...] }
+drds.transitions.keys # => ['self', 'search', 'create', 'next', 'last']
+
+agent.enter('http://example.com/rel/unknown_resource') # => raises Farscape::Agent::UnknownEntryPoint
+```
+
+## API Interaction
+Entering an API takes you into its application state-machine and, as such, the interface for interacting with that 
+application state is brain dead simple with Farscape. You have data that you read and hypermedia affordances that tell 
+you what you can do next and you can invoke those affordances to do things. That's it.
+
+Farscape recognizes a number of media-types that support runtime knowledge of the underlying REST uniform-interface 
+methods. For these full-featured media-types, the interaction with with resources is as simple as a browser where 
+implementation of requests is completely abstracted from the user.
+
+The following simple examples highlight interacting with resource state-machines using Farscape.
+
+### Load a resource
+```ruby
+resources = agent.enter
+drds_transition = resources.transitions['http://example.com/rel/drds']
+drds = drds_transition.invoke
+```
+
+### Reload a resource
+```ruby
+self_transition = drds.transitions['self']
+reloaded_drds = self_transition.invoke
+```
+
+### Explore
+
+The sample code given below often depicts the client making *assumptions* that a specific transition or attribute will be available in a certain state. *This is unsafe*, and production code should include conditionals or rescues for the case when an assumption proves incorrect. Whenever possible, Farscape should be used more dynamically, by letting user interaction or a crawling algorithm drive transitions.
+
+### Apply query parameters
+```ruby
+search_transition = drds.transitions['search']
+search_transition.parameters # => ['search_term']
+
+filtered_drds = search_transition.invoke do |builder|
+  builder.parameters = { search_term: '1812' }
+end
+```
+
+You may also invoke transitions with automatic attribute and parameter matching
+```ruby
+drds.transitions['search'].invoke(search_term: '1812')
+```
+
+### Transform resource state
+```ruby
+embedded_drd_items = drds.items
+
+drd = embedded_drd_items.first
+drd.attributes # => { name: '1812' }
+drd.transitions # => ['self', 'edit', 'delete', 'deactivate', 'leviathan']
+
+deactivate_transition = drd.transitions['deactivate']
+
+deactivated_drd = deactivate_transition.invoke
+deactivated_drd.attributes # => { name: '1812' }
+deactivated_drd.transitions # => ['self', 'activate', 'leviathan']
+
+deactivate_transition.invoke # => raise Farscape::Excpetions::Gone error
+```
+
+### Transform application state
+```ruby
+leviathan_transition = deactivated_drd.transitions['leviathan']
+
+leviathan = leviathan_transition.invoke
+leviathan.attributes # => { name: 'Elack' }
+leviathan.transitions # => ['self', 'drds']
+```
+
+### Use attributes
+
+```ruby
+create_transition = drds.transitions['create']
+create_transition.attributes # => ['name']
+
+new_drd = create_transition.invoke do |builder|
+  builder.attributes = { name: 'Pike' }
+end
+
+new_drd.attributes # => { name: 'Pike' }
+new_drd.transitions.keys # => ['self', 'edit', 'delete', 'deactivate', 'leviathan']
+```
+
+For more examples and information on using Faraday with media-types that require specifying uniform-interface methods 
+and other protocol idioms when invoking transitions, see [Using Farscape]().
+
+## Alternate Interface
+
+For developers more used to ActiveRecord syntax, Farscape resources also expose all transitions and attributes as Ruby methods. Safe (i.e. read) transitions are exposed verbatim.
+
+```ruby
+drd.leviathan # => Equivalent to drd.transitions['leviathan'].invoke
+```
+
+Unsafe transitions have an exclamation point at the end.
+
+```ruby
+drd.deactivate # => Raises NoMethodError
+
+drd.deactivate! # => Equivalent to drd = drd.transitions['deactivate'].invoke
+```
+
+Request parameters can be passed as a hash or as a block.
+
+```ruby
+# The following are all equivalent:
+
+drd = drds.create!(name: 'Pike')
+drd = drds.create! { |builder| builder.attributes = {name: 'Pike'} }
+drd = drds.transitions['create'].invoke{ |d| d.attributes = {name: 'Pike'} }
+```
+
+Attributes are read-only.
+
+```ruby
+drd.name # => "Pike"
+
+drd.name = 'Susan' # => Raises NoMethodError
+```
+
+If an attribute or transition's name conflicts with an existing method or reserved word, it will not be methodized and must be accessed through the hash interface.
+
+### Disabling the Alternate Interface
+If you're concerned about namespace collisions, or want to ensure that your code is highly flexible and explicit (albeit verbose), you may turn off the interface with the .safe method.
+```ruby
+safe_drd = drd.safe # => returns a drd resource without the alternate interface
+safe_drd.name # => UndefinedMethod error
+drd.name # => "Pike"
+```
+
+You may reenable the alternate interface with `.unsafe`.
+
+## Contributing
+See [CONTRIBUTING][] for details.
+
+## Copyright
+Copyright (c) 2013 Medidata Solutions Worldwide. See [LICENSE][] for details.
+
+[Crichton]: https://github.com/mdsol/crichton
+[CONTRIBUTING]: CONTRIBUTING.md
+[Documentation]: http://rubydoc.info/github/mdsol/farscape/develop/file/README.md
+[LICENSE]: LICENSE.md

data/Rakefile

@@ -0,0 +1,10 @@
+lib_dir = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib_dir)
+$LOAD_PATH.uniq!
+
+require 'rubygems'
+require 'rake'
+require 'dice_bag/tasks'
+require 'farscape'
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/WRITING_PLUGINS.md

@@ -0,0 +1,162 @@
+# Writing Plugins
+
+Farscape Plugins can be used to add drop-in functionality to Farscape. 
+
+## Farscape Plugin Hash
+
+A Farscape plugin is described with a hash with a set of well defined keys
+
+#### name
+This is a symbol representing the name of the plugin
+
+#### type
+The type of plugin, this is useful for manipulating multiple plguins simultaneously
+
+#### middleware
+Middleware objects as per [Faraday plugins](https://github.com/lostisland/faraday#writing-middleware)
+
+#### extensions
+A hash whos keys are the Farscape clases to be extended and values are a list of classes which will extend the default functionality of Farscape clases.
+Possible keys are: `:Agent`, `:HttpClient`, `:SafeRepresentorAgent`, `:RepresentorAgent`, and `:TransitionAgent`
+
+#### default_state
+When registered, is this :enabled or :disabled by default it is :enabled
+
+### Example
+```ruby
+{
+  name: :PluginName
+  type: :example_type
+  middleware: PluginMiddlewareClass
+  extension: { :Agent => [ExtenstionClass], :RepresentorAgent => [ExtensionClass, Walrus] }
+  default_state: :enabled
+}
+```
+
+# Registration
+
+To register your plugin, run 
+
+```ruby
+Farscape.register_plugin(name: :Cachinator, type: :cache, ...)
+```
+
+Feel free to put this code at the bottom of `cachinator.rb` so that it turns on automatically after the gem is loaded. Consumers who want control can include a line in their initializer reading `Farscape.disable!(:Cachinator)` or `Farscape.disable!(:cache)`. If you'd rather have your plugin be off by default, you could instead wrap the register_plugin call in, say, a `Cachinator.activate` method for the consumer to call as desired. If your plugin is http-specific (say it adds Authentication headers), include `protocol: :http`.
+
+# Managing Plugins
+Of the set of registered plugins, some will be enabled, and others disabled. Enabled plugins will apply their specified functionality to any current Farscape instance.  
+
+## Introspecting plguins
+
+You can get a list of plugins with the `Farscape.plugins` method.  If you want only the enabled plugins you can use `Farscape.enabled_plugins`, and if you want only disabled plguins you can do `Farscape.disabled_plugins`.
+
+## Enabling and Disabling plugins
+
+The default state of a plugin is defined by the Plugin Hash.  To enable a disabled plugin you need to call `Farscape.enable!(options)` where options is a hash containing a `:name` key or a `:type` key.  The name key will only enable plugins with the matching name, whereas type will enable all plugins of that type.
+Likewise you can disable plugins with `Farscape.disable!(options)`, in which case you disable the plugins.
+
+## Example Enable / Disable Workflow
+
+```ruby
+Farscape.register_plugin({name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]})
+Farscape.plugins #=> [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+Farscape.enabled_plugins #=> [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+Farscape.disabled_plugins #=> []
+Farscape.disable!(type: :sebacean)
+Farscape.enabled_plugins #=> []
+Farscape.disabled_plugins #=> [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+Farscape.enable!(name: :Peacekeeper)
+Farscape.enabled_plugins #=> [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+Farscape.disabled_plugins #=> []
+```
+
+## Plugins on instances
+
+Plugins can also be modified on a per instance basis.  Agent, SafeRepresentorAgent, and Representor all support #plugins, #enabled_plugins, and #disabled_plugins on a per instance basis.  These behave the same as their associated Farscape class methods, except they communicate which plugins are enabled or diables for that instance only.
+When an object creates a new object (for example `Agent.new(entry).enter` returns a RepresentorAgent), those instances will have the same plugins enabled as their parent.
+
+### Enabling and Disabling Plugins for Instances
+
+To enable plugins on an instance invoke the `using(name_or_type)` method, to disable plugins on an instance invoke the `omitting(name_or_type)` method.  These methods will return a new instance with the associated plugin(s) in their new state.  They do not modify the original object.
+
+### Example instance workflow
+
+```ruby
+Farscape.enabled_plugins #=> [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+agent = Farscape.Agent.new.omitting(name: :Peacekeeper)
+agent.plugins # => [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+agent.enabled_plugins # => []
+agent.plugins # => [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+resource = agent.enter(entry_point).transitions[:listing].invoke
+resource.plugins # => [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+resource.enabled_plugins # => []
+resource.plugins # => [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+details = resource.using(name: :Peacekeeper).transitions[:items][0].invoke
+details.plugins # => [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+details.enabled_plugins # => []
+details.disabled_plugins # => [{name: :Peacekeeper, type: :sebacean, middleware: [TestMiddleware::NoGetNoProblem]}]
+```
+
+# Adding Middleware
+
+You can probably do what you need to do by writing [Faraday](https://github.com/lostisland/faraday)-style middleware. Middleware can inspect and alter outgoing requests and incoming responses, abort requests, and define hooks that run after a request/response cycle completes. All it needs to do is obey [a simple API](https://github.com/lostisland/faraday#writing-middleware).
+
+To add your middleware to the stack, run
+
+```ruby
+Farscape.register_plugin(name: :Cachinator, type: :cache, middleware: [Cachinator::Middleware], ...)
+```
+
+If you need to partially order your middleware, the elements of the middleware array can be hashes of the form:
+
+```ruby
+{ class: Cachinator::Middleware,
+  before: RequestSigner,
+  after: ['HubSubscriber', 'Ouroborous', :authorization]
+}
+```
+
+In this example, Cachinator::Middleware will be inserted before the RequestSigner middleware if it is present, and after the latest of HubSubscriber, Ouroborous, or any middleware of type "authorization". Note that Middleware classes can and should be given as strings if your plugin is not providing them, so that Ruby won't throw a NameError if they are undefined. If the ordering constraints given are impossible to satisfy, Farscape will throw an error.
+
+You can also add config to your middleware when passing it in hash form:
+
+```ruby
+{ class: Cachinator::Middleware,
+  config: MyApp.config[:cache]
+}
+```
+
+The config hash will be passed to your middleware as a second argument to `new`, as in Faraday. To pass multiple arguments, use `config: [arg1, arg2]`.
+
+# Extending Agent
+
+If you want to provide a more interactive API, or reference the deserialized response using the Representor interface, you can define a module that will be available to mix in to Farscape::Agent.
+
+```ruby
+module Peacekeeper
+  def pacify!
+    raise if representor.transitions.keys.include?(:attack)
+  end
+end
+Farscape.register_plugin(name: :Peacekeeper, type: :security, extensions: [Peacekeeper], extends: [:Agent])
+agent.enter(url).using(:Peacekeeper).pacify!
+```
+
+# Farscape Utilities
+
+Any plugin can reference `Farscape.cache`, which exposes [the same API as Rails.cache](http://apidock.com/rails/ActiveSupport/Cache/Store), `Farscape.logger`, which exposes [the same API as the built-in Ruby logger](http://apidock.com/ruby/Logger). By default, Farscape.cache operates in-memory and Farscape.logger writes to STDOUT. Plugins can provide enhanced versions of these utilities by modifying the global state of the Farscape object:
+
+```ruby
+module Peacekeeper
+  class DalliCache
+    # code that implements the Cache api
+  end
+end
+Farscape.cache = Peacekeeper::DalliCache.new(config)
+```
+
+Future updates will provide Farscape.jobs, a backgrounding utility along similar lines.
+
+# Creating a Client
+
+By default, Farscape uses the [Net::HTTP](http://ruby-doc.org/stdlib-2.1.5/libdoc/net/http/rdoc/Net/HTTP.html) library to make HTTP requests. You can replace this client with `Faraday.clients[:http] = MyClient` or define one for a new protocol with `Faraday.clients[:amqp] = Jessica::Rabbit`. When a Farscape agent follows a link with a given protocol, it will use the client for that protocol if one has been provided. Required interface tk.