(SERVER-116) Reuse client instances

Reuse HTTP client instances in the ruby code rather than creating
a new one for every request.
Merge pull request #284 from fpringvaldsen/SERVER-116-reuse-client-instances

(SERVER-116) Reuse client instances
(MAINT) Update TK and Kitchensink dependencies
Merge branch 'master' into future

* master: (21 commits)
  (MAINT) Ensure gem subcommand tests honor GEM_SOURCE
  (maint) add config for admin API
  (SERVER-208) Improve error message for missing `puppet-admin` section
  (SERVER-114) /environment-cache header handling
  (SERVER-114) specify puppet.conf used by test
  (MAINT) Use GEM_SOURCE env var in Gemfile
  (SERVER-114) add comment about test coverage
  (SERVER-114) make API more RESTful
  (SERVER-114) endpoint to flush environment cache
  (maint) rename functions for clarity + consistency
  (MAINT) Add build & compare urls to travis template.
  (SERVER-167) Added language to syntax highlights
  (SERVER-138) Fixed typo
  Just fixing a spelling mistake
  (SERVER-203) Update to clj-http-client 0.4.0
  (SERVER-113) Add new puppet-admin-api HTTP endpoint
  (SERVER-167) Add documentation on `set_trace_func`
  (SERVER-113) Refactor whitelist logic out to ringutils
  (SERVER-138) Set name of doc section to HttpPool-Related Server Settings
  (SERVER-138) Addressed PR feedback
  ...

Conflicts:
	src/ruby/puppet-server-lib/puppet/server/http_client.rb
(maint) delete a couple unused functions
(SERVER-88) catch errors before they get to Jetty

Add a 'catch-all' middleware to both the Master and CA ring handlers
which catches any Exception, logs it, and returns a simple error message
in the response body.  This prevents Exceptions from propagating all the
way out to Jetty - if this happens, Jetty will generate HTML from the
stacktrace and return this to the client.
(SERVER-88) improve exception handling

* 'wrap-exception-handling' now includes the exception type + message in
  the response body it returns.

* Update the exception handler in the liberator resources to simply
  re-throw exceptions, causing them to be handled in middleware.
(maint) fixup botched merge conflict resolution
Merge pull request #296 from fpringvaldsen/update-to-tk-1.0.1

(MAINT) Update TK and Kitchensink dependencies
fix typo in docstring
Merge pull request #285 from KevinCorcoran/SERVER-88/no-html-in-500s

(SERVER-88) catch errors before they get to Jetty
Merge branch 'master' into future

* master:
  lein-release plugin: bumped version from 0.4.1 to 0.4.2-SNAPSHOT for next development cycle
  lein-release plugin: preparing 0.4.1 release
  (MAINT) Add some notes about debugging / ruby
  (MAINT) Fix typos, simplify git submodule init for quickstart
  (MAINT) Update developer docs re: running from source
  DOC-1281: Puppet Server gems, puppetserver_vs_passenger
(SERVER-150) Use clojure agent to initialize jruby pool

This commit gets rid of our use of a raw `future` when priming the
JRuby pool.  Instead, we use a clojure agent.  This has the
following benefits:

* Will make it easier to re-use the pool initialization logic
* When we expose a way to request for the pool to be flushed,
  will make it possible to prevent multiple pool initializations to
  occur simultaneously
* Gives us more robust options around error handling, since we
  could now call `agent-error` on the agent instance to make
  sure that nothing has gone wrong
* Provides some scaffolding that we can re-use in order to have
  another agent handle the flushing of an existing pool
(SERVER-150) Refactor `prime-pool!` to be more re-usable

The previous implementation of `prime-pool!` required a
`PoolContext` object as input.  This meant that the
function could not be used to prime a pool that was not
yet part of a `PoolContext`.

This commit refactors the function so that it operates on
a `PoolStateContainer` instead; this will allow us to
initialize a pool before putting it into the `PoolContext`.

Conflicts:
	src/clj/puppetlabs/services/jruby/jruby_puppet_core.clj
	src/clj/puppetlabs/services/jruby/jruby_puppet_service.clj
(SERVER-150) Refactor `borrow`, et. al, to use pool directly

Prior to this commit, the `borrow-instance` and related functions
in jruby-core required you to pass a `PoolContext` object in
as input.  This prevented us from using these functions on a pool
that has not yet been added to the context.  This commit modifies
the signatures to accept the pool object directly, rather than
the `PoolContext`.

Conflicts:
	src/clj/puppetlabs/services/jruby/jruby_puppet_service.clj
(SERVER-150) Refactor `return` to not require pool

Prior to this commit, the various `return` functions that would
allow a caller to return a JRuby instance to a pool required
that you also pass in a reference to the pool that the instance
should be returned to.  This allowed the possibility of returning
an instance to a pool that it did not actually originate from.

This commit refactors the creation/borrow/return logic such that
an instance maintains a reference to the pool that it was
borrowed from, and the `return` functions use that reference
when returning the instances to a pool.  This guarantees that
instances will always be returned to the correct pool that they
were originally borrowed from.
(SERVER-150) Convert JRubyPuppetInstance to defrecord

This commit changes the JRubyPuppetInstance schema from a normal,
map-based schema to a schematized `defrecord`.  This may result
in a very minor performance improvement, but the main motivation
is to provide better compatibility with REPL-based developer
utility code.  Since we added a reference to the JRuby pool to
the schema for JRubyPuppetInstance, attempting to print the
objects results in a stack overflow, because Clojure's implementation
of `toString` for maps will recurse into these references to the
pools and attempt to print all of the instances again.

Moving to `defrecord` would allow us to override `toString` if we
wished to do so, but the default implementation of `toString` for
a record does not have the same problem with recursion that the
map objects do, so simply converting to a record solves the issue
and allows all of the utility code to be used in the REPL again.
(SERVER-150) Add service function for flushing JRuby pool

This commit adds a new service function to the JRubyPuppet service.
The new function can be used to request a flush of the JRuby pool.

The function is implemented by creating a new (offline) JRuby pool
and starting to populate it; as soon as the first instance is ready,
we can swap it into the service and remove the old pool, and then
continue initializing the remaining instances and cleaning up the
old pool in parallel.  It uses clojure agents to coordinate the
creation of the new pool and the cleanup of the old pool.
(SERVER-150) Put a 'retry' poison pill in the flushed pool

When we replace the old pool with the new pool during a 'flush'
request, we need to have a way to handle the possible race
condition where some code has a reference to the old pool
and tries to borrow an instance from it after it has already
been flushed.  This commit is the first step towards that;
it puts a RetryPoisonPill into the old queue.
DOC-1281 Puppet Server puppet_conf_setting_diffs edit

Edited puppet_conf_setting_diffs.markdown