union_station_hooks_core 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YThkZmM0ZGI0ZTViOWUxODNkODE4ZDMxZTI1MjM0ZDYxYzk2ODdhNQ==
+  data.tar.gz: !binary |-
+    M2Q5NjgyNzI5MGQxZDlkOGIwZGViYjcwMzllMDI2ZjA4YmNjMTkzYQ==
+SHA512:
+  metadata.gz: !binary |-
+    NzMxNjZiMDRjY2U3N2I5ZDYzZjcwZjIxMjVhNGM0YWU5ZWJiOGM0ZmI5MjA2
+    NGU2NmFiMjMxMjdmY2ZmMTQ3MWRhMmM2ZDJkMjYxZjc2MzlhN2EyMjBlYmVm
+    NGZkOTcyYmVkNDM2MjAwOTZiNDlkYzE1NzZlZTM3YTFhYTUyYTE=
+  data.tar.gz: !binary |-
+    OGJiNTcwNzVlZjZjMzE4NmI1MDdhMjM0MjU3MDg1ZjJiMmI0MDBiNGI1YzVl
+    N2NiNjJkOWU0ZTU0YmQwNzU0ZGQ3NGZhYTkwNWUxMzVjZjI0NDUxYjJkOTlj
+    MGJlZTNhODA3NWQyNjMxMDc1ZGNmNWU1MmIyM2NiZmQwMTk2ZjY=

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2010-2015 Phusion Holding B.V.
+
+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,117 @@
+# Union Station Ruby hooks core
+
+[![Build Status](https://travis-ci.org/phusion/union_station_hooks_core.svg?branch=master)](https://travis-ci.org/phusion/union_station_hooks_core)
+
+[Union Station](https://www.unionstationapp.com) is a web application monitoring and performance analytics platform for Ruby. In order for Union Station to analyze your application, your application must send data to Union Station. This gem allows you to do that.
+
+`union_station_hooks_core` is a web-framework-agnostic gem that **hooks into various Ruby internals** in order to send generic Ruby application analytics information to Union Station. Not all information can be automatically inferred by hooking into the Ruby internals, so this gem also provides an **API** that you can call at key places in the codebase to supply the right information.
+
+### Using Ruby on Rails?
+
+If your application is a Rails application, then you should use the [union_station_hooks_rails](https://github.com/phusion/union_station_hooks_rails) gem instead of this gem. `union_station_hooks_rails` automatically hooks into Rails to send the right information to Union Station, so that you don't have to call any APIs. Under the hood, `union_station_hooks_rails` makes use of the `union_station_hooks_core` API.
+
+**Resources:** [About Union Station](https://www.unionstationapp.com) | [Github](https://github.com/phusion/union_station_hooks_core) | [API docs](http://www.rubydoc.info/github/phusion/union_station_hooks_core/UnionStationHooks)
+
+**Table of contents**
+
+ * [Installation](#installation)
+   - [Using with Passenger](#using-with-passenger)
+   - [Overriding Passenger's version](#overriding-passengers-version)
+   - [Using without Passenger](#using-without-passenger)
+ * [API](#api)
+ * [Legacy code](#legacy-code)
+ * [Contributing](contributing)
+
+---
+
+## Installation
+
+### Using with Passenger
+
+**Note: This documentation section only applies to Passenger X.X.X or later!**
+
+If you use [Passenger](https://www.phusionpassenger.com/), then you do not need to install the `union_station_hooks_core` gem. `union_station_hooks_core` is bundled with Passenger.
+
+The only thing you need to do is to ensure that the code is called during application startup:
+
+    if defined?(UnionStationHooks)
+      UnionStationHooks.initialize!
+    end
+
+(Are you already calling `PhusionPassenger.install_framework_extensions!` from somewhere in your codebase? Please read [Legacy code](#legacy-code) for important information.)
+
+A good place to call this is in your Rackup file, `config.ru`. Or if you are using Rails, you should create a file `config/initializers/union_station.rb` in which you call this.
+
+When you have this call in place, enable Union Station support in Passenger. Here are some examples:
+
+ * _Passenger with Nginx integration mode_<br>
+
+   Insert the following config in your virtual host configuration, then restart Nginx:
+
+        union_station_support on;
+        union_station_key <YOUR KEY HERE>;
+
+ * _Passenger with Apache integration mode_<br>
+
+   Insert the following config in your virtual host configuration, then restart Apache:
+
+        UnionStationSupport on
+        UnionStationKey <YOUR KEY HERE>
+
+ * _Passenger Standalone_<br>
+
+   Start Passenger with the `--union-station-key` parameter:
+
+        $ passenger start --union-station-key <YOUR KEY HERE>
+
+   Or set the `union_station_key` configuration option in Passengerfile.json:
+
+        {
+            "union_station_key": "<YOUR KEY HERE>"
+        }
+
+### Overriding Passenger's version
+
+**_Note: Are you using `union_station_hooks_rails`? Then be sure sure to follow the "Overriding Passenger's version" instructions in that gem's README, in addition to following the instructions below._**
+
+Each version of Passenger bundles its own version of the `union_station_hooks_core` gem. The Passenger maintainers regularly update their bundled version with the latest version. Sometimes, you may wish to use a specific version of `union_station_hooks_core`, overriding the version that came bundled with Passenger. For example, we have may published a new version of `union_station_hooks_core` with some bug fixes, even though Passenger hasn't been updated yet.
+
+You can override Passenger's bundled version as follows.
+
+ 1. Add `union_station_hooks_core` to your Gemfile, like this:
+
+        gem 'union_station_hooks_core'
+
+ 2. Install your gem bundle:
+
+        bundle install
+
+ 3. Ensure that your application calls `require 'union_station_hooks_core'` during startup, before you access anything in the `UnionStationHooks` module (so before the `UnionStationHooks.initialize!` call).
+
+    If you are using Rails, then Rails takes care of that automatically by calling `Bundler.require` in `config/application.rb`, so in that case you don't need to follow this step.
+
+### Using without Passenger
+
+It is currently not possible to use Union Station without Passenger. If you would like to have this feature, please let us know.
+
+## API
+
+Please refer to [the API documentation website](http://www.rubydoc.info/github/phusion/union_station_hooks_core/UnionStationHooks).
+
+## Legacy code
+
+Before Passenger X.X.X, the Union Station setup instructions used to tell you to create a `config/initializers/passenger.rb` in which you call the following code:
+
+    PhusionPassenger.install_framework_extensions! if defined?(PhusionPassenger)
+
+Since Passenger X.X.X, `PhusionPassenger.install_framework_extensions!` has become an alias for `UnionStationHooks.initialize!`, but the former is considered deprecated. Please replace the above code with:
+
+    if defined?(UnionStationHooks)
+      UnionStationHooks.initialize!
+    end
+
+And please also rename `config/initializers/passenger.rb` to `config/initializers/union_station.rb`.
+
+## Contributing
+
+Looking to contribute to this gem? Please read the documentation in the [hacking/](https://github.com/phusion/union_station_hooks_core/blob/master/hacking) directory.

data/lib/union_station_hooks_core.rb

@@ -0,0 +1,360 @@
+#  Union Station - https://www.unionstationapp.com/
+#  Copyright (c) 2015 Phusion Holding B.V.
+#
+#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#
+#  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.
+
+if defined?(UnionStationHooks::VERSION_STRING)
+  if UnionStationHooks.initialized?
+    raise 'Attempted to load union_station_hooks_core even though an ' \
+      'alternative version was already loaded and initialized'
+  end
+  if UnionStationHooks.vendored?
+    # Passenger loaded its vendored Union Station hooks code, but the
+    # application has also included 'union_station_hooks_*' in its Gemfile. We
+    # want the version in the Gemfile to take precedence, so we unload the old
+    # version. At this point, the Union Station hooks aren't installed yet, so
+    # removing the module is enough to unload the old version.
+    #
+    # See also hacking/Vendoring.md
+    config_from_vendored_ush = UnionStationHooks.config
+    initializers_from_vendored_ush = UnionStationHooks.initializers
+    Object.send(:remove_const, :UnionStationHooks)
+  end
+end
+
+# The UnionStationHooks module is the entry point to the
+# `union_station_hooks_core` gem's public API. Note that this API is only
+# available since Passenger X.X.X!
+#
+# **_Not familiar with `union_station_hooks_core`? Please read the
+# [README](https://github.com/phusion/union_station_hooks_core)
+# for an introduction._**
+#
+# ## Places of interest
+#
+# You will probably be most interested in these:
+#
+#  * {UnionStationHooks.initialize!}
+#  * {UnionStationHooks.begin_rack_request} and
+#    {UnionStationHooks.end_rack_request}
+#  * {UnionStationHooks::RequestReporter}
+#
+# ## Rack example
+#
+# Here is a small example showing to use `union_station_hooks_core` with a
+# bare Rack application. There are three main things you see in this example:
+#
+#  1. The `union_station_hooks_*` gems are initialized.
+#  2. Obtaining a RequestReporter object, which is the main object that you
+#     will be using as an application developer to log information to Union
+#     Station.
+#  3. Using the RequestReporter object by calling methods on it.
+#
+# Example code follows:
+#
+#     # (1) Initialize all `union_station_hooks_*` gems.
+#     UnionStationHooks.initialize!
+#
+#     # Define application object.
+#     app = lambda do |env|
+#       body, rendering_time = process_this_request(env)
+#
+#       # (2) You can obtain a RequestReporter object as follows. With that
+#       # object, you can log to Union Station information about the current
+#       # request.
+#       reporter = env['union_station_hooks']
+#       reporter = Thread.current[:union_station_hooks]
+#
+#       # The reporter object may be nil because of various error conditions,
+#       # so you must check for it.
+#       if reporter
+#         # (3) For example you can log the amount of time it took to render
+#         # the view.
+#         reporter.log_total_view_rendering_time(rendering_time)
+#       end
+#
+#       [200, { "Content-Type" => "text/plain" }, body]
+#     end
+#
+#     # Tell the application server to run this application object.
+#     run app
+module UnionStationHooks
+  # The path to the `union_station_hooks_core` Ruby library directory.
+  #
+  # @private
+  LIBROOT = File.expand_path(File.dirname(__FILE__))
+
+  # The path to the `union_station_hooks_core` gem root directory.
+  #
+  # @private
+  ROOT = File.dirname(LIBROOT)
+
+  class << self
+    # This error is raised by {UnionStationHooks.initialize!} if a required
+    # {UnionStationHooks.config configuration option} is missing.
+    class ConfigurationError < StandardError
+    end
+
+    # @private
+    @@config = {}
+    # @private
+    @@context = nil
+    # @private
+    @@initializers = []
+    # @private
+    @@initialized = false
+    # @private
+    @@app_group_name = nil
+    # @private
+    @@key = nil
+    # @private
+    @@vendored = false
+
+    # Initializes the Union Station hooks. If there are any other
+    # `union_station_hooks_*` gems loaded, then they are initialized too.
+    #
+    # Applications must call this during startup. Hooks aren't actually
+    # installed until this method is called, so until you call this you cannot
+    # use the public APIs of any `union_station_hooks_*` gems (besides trivial
+    # things such as {UnionStationHooks.initialized?}).
+    #
+    # A good place to call this is in the Rackup file `config.ru`. Or, if your
+    # application is a Rails app, then you should create an initializer file
+    # `config/initializers/union_station.rb` in which you call this.
+    #
+    # If this method successfully initializes, then it returns true.
+    #
+    # Calling this method may or may not actually initialize the hooks. If
+    # this gem determines that initialization is not desired, then this method
+    # won't do anything and will return `false`. See
+    # {UnionStationHooks#should_initialize?}.
+    #
+    # Initialization takes place according to parameters set in the
+    # {UnionStationHooks.config configuration hash}. If a required
+    # configuration option is missing, then this method will raise a
+    # {ConfigurationError}.
+    #
+    # Initializing twice is a no-op. It only causes this method to return true.
+    #
+    # @raise [ConfigurationError] A required configuration option is missing.
+    # @return [Boolean] Whether initialization was successful.
+    def initialize!
+      return false if !should_initialize?
+      return true if initialized?
+
+      finalize_and_validate_config
+      require_lib('api')
+      create_context
+      install_event_pre_hook
+      initialize_other_union_station_hooks_gems
+      finalize_install
+
+      true
+    end
+
+    # Returns whether the Union Station hooks are initialized.
+    def initialized?
+      @@initialized
+    end
+
+    # Returns whether the Union Station hooks should be initialized. If this
+    # method returns false, then {UnionStationHooks.initialize!} doesn't do
+    # anything.
+    #
+    # At present, this method only returns true when the app is running inside
+    # Passenger. This may change if and when in the future Union Station
+    # supports application servers besides Passenger.
+    def should_initialize?
+      if defined?(PhusionPassenger)
+        PhusionPassenger::App.options['analytics']
+      else
+        true
+      end
+    end
+
+    # Returns whether this `union_station_hooks_core` gem is bundled with
+    # Passenger (as opposed to a standalone gem added to the Gemfile).
+    # See the README and the file `hacking/Vendoring.md` for information
+    # about how Passenger bundles `union_station_hooks_*` gems.
+    #
+    # @private
+    def vendored?
+      @@vendored
+    end
+
+    # @private
+    def vendored=(val)
+      @@vendored = val
+    end
+
+    # @private
+    def require_lib(name)
+      require("#{LIBROOT}/union_station_hooks_core/#{name}")
+    end
+
+    # Returns the configuration hash. This configuration is used by all
+    # `union_station_hooks_*` gems. You are supposed to set this hash
+    # before calling {UnionStationHooks.initialize!}.
+    #
+    # At present, none of the `union_station_hooks_*` gems require
+    # additional configuration. All necessary configuration is pulled from
+    # Passenger. This may change if and when Union Station in the future
+    # supports application servers besides Passenger.
+    #
+    # This hash is supposed to only contain symbol keys, not string keys.
+    # When {UnionStationHooks.initialize!} is called, that method will
+    # convert all string keys to symbol keys before doing anything else
+    # with the config hash, so assigning string keys works even though
+    # we don't recommend it. Furthermore, the config hash is frozen after
+    # initialization.
+    #
+    # @return [Hash]
+    def config
+      @@config
+    end
+
+    # The singleton {Context} object, created during initialization.
+    # All the `union_station_hooks_*` gem internals make use of this context
+    # object.
+    #
+    # @private
+    def context
+      @@context
+    end
+
+    # An array of objects on which `#initialize!` will be called when
+    # {UnionStationHooks.initialize!} is called. Other `union_station_hooks_*`
+    # gems register themselves in this list when they are loaded, so that
+    # a call to {UnionStationHooks.initialize!} will initialize them too.
+    #
+    # @private
+    def initializers
+      @@initializers
+    end
+
+    # @private
+    def app_group_name
+      @@app_group_name
+    end
+
+    # The currently active Union Station key. This is pulled from the
+    # {UnionStationHooks.config configuration}.
+    #
+    # @private
+    def key
+      @@key
+    end
+
+    # @private
+    def call_event_pre_hook(_event)
+      raise 'This method may only be called after ' \
+        'UnionStationHooks.initialize! is called'
+    end
+
+    # Called by Passenger after loading the application, to check whether or
+    # not the application developer forgot to call
+    # {UnionStationHooks.initialize!}
+    #
+    # @private
+    # @raise RuntimeError
+    def check_initialized
+      if should_initialize? && !initialized?
+        if defined?(::Rails)
+          raise 'The Union Station hooks are not initialized. Please ensure ' \
+            'that you have an initializer file ' \
+            '`config/initializers/union_station.rb` in which you call ' \
+            "this:\n\n" \
+            "  if defined?(UnionStationHooks)\n" \
+            "    UnionStationHooks.initialize!\n" \
+            '  end'
+        else
+          raise 'The Union Station hooks are not initialized. Please ensure ' \
+            'that the following code is called during application ' \
+            "startup:\n\n" \
+            "  if defined?(UnionStationHooks)\n" \
+            "    UnionStationHooks.initialize!\n" \
+            '  end'
+        end
+      end
+    end
+
+    def now
+      # When `initialize!` is called, the definition in
+      # `api.rb` will override this implementation.
+      nil
+    end
+
+    def begin_rack_request(_rack_env)
+      # When `initialize!` is called, the definition in
+      # `api.rb` will override this implementation.
+      nil
+    end
+
+    def end_rack_request(_rack_env,
+        _uncaught_exception_raised_during_request = false)
+      # When `initialize!` is called, the definition in
+      # `api.rb` will override this implementation.
+      nil
+    end
+
+  private
+
+    def finalize_and_validate_config
+      final_config = {}
+
+      if defined?(PhusionPassenger)
+        import_into_final_config(final_config, PhusionPassenger::App.options)
+      end
+      import_into_final_config(final_config, config)
+
+      validate_final_config(final_config)
+
+      @@config = final_config
+    end
+
+    def import_into_final_config(dest, source)
+      source.each_pair do |key, val|
+        dest[key.to_sym] = val
+      end
+    end
+
+    def validate_final_config(config)
+      require_non_empty_config_key(config, :union_station_key)
+      require_non_empty_config_key(config, :app_group_name)
+      require_non_empty_config_key(config, :ust_router_address)
+      require_non_empty_config_key(config, :ust_router_password)
+    end
+
+    def require_non_empty_config_key(config, key)
+      if config[key].nil? || config[key].empty?
+        raise ArgumentError,
+          "Union Station hooks configuration option required: #{key}"
+      end
+    end
+  end
+end
+
+UnionStationHooks.require_lib('version')
+
+if config_from_vendored_ush
+  UnionStationHooks.config.replace(config_from_vendored_ush)
+  UnionStationHooks.initializers.replace(initializers_from_vendored_ush)
+end