squash_ruby 1.0.0

data/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,232 @@
+Squash Client Library: Ruby
+===========================
+
+This client library reports exceptions to Squash, the Squarish exception
+reporting and management system.
+
+Documentation
+-------------
+
+Comprehensive documentation is written in YARD- and Markdown-formatted comments
+throughout the source. To view this documentation as an HTML site, run
+`rake doc`.
+
+For an overview of the various components of Squash, see the website
+documentation at https://github.com/SquareSquash/web.
+
+Compatibility
+-------------
+
+This library is compatible with Ruby 1.8.6 and later, including Ruby Enterprise
+Edition.
+
+Requirements
+------------
+
+The only dependency is the `json` gem (http://rubygems.org/gems/json). You can use
+any JSON gem that conforms to the typical standard (`require 'json';
+object.to_json`).
+
+Usage
+-----
+
+Add the Squash client to your Gemfile with
+`gem 'squash_ruby', :require => 'squash/ruby'`. Before you can use Squash, you
+must configure it (see **Configuration** below). At a minimum, you must specify
+the API host and which project you are recording exceptions for:
+
+```` ruby
+Squash::Ruby.configure :api_key => 'YOUR_API_KEY',
+                       :api_host => 'https://your.squash.host',
+                       :environment => 'production'
+````
+
+To use Squash to manage your exceptions, place a `begin::rescue` statement at
+the highest level of your code. Inside the `rescue` block, make a call to
+{Squash::Ruby.notify} with the exception. In general, you probably want to
+rescue all subclasses of `Object`, so you catch every possible exception.
+Example:
+
+```` ruby
+begin
+  all_of_your_code
+rescue Object => err
+  Squash::Ruby.notify err
+  raise
+end
+````
+
+In this example the exception is re-raised to take advantage of Ruby's typical
+last-resort exception handling as well.
+
+There are many additional features you can take advantage of; see **Additional
+Features** below.
+
+### Additional Features
+
+There are a number of other features you can take advantage of to help you debug
+your exceptions:
+
+#### User Data
+
+Exceptions can be annotated with freeform user data. This data can take any
+format and have any meaning, typically being relevant to the exception at hand.
+This is in fact the system that `squash_rails` uses to annotate an exception
+with information about the Rails request.
+
+There are multiple ways to add user data to an exception. By default, user data
+is culled from any instance variables set in the exception. This means that for
+those exceptions that store additional information in instance variables, you
+get user data "for free." An example is the `ActiveRecord::RecordInvalid`
+exception, which stores the invalid record as an instance variable.
+
+You can also add user data using the {Squash::Ruby.add_user_data} method:
+
+```` ruby
+input = gets
+Squash::Ruby.add_user_data(:input => input) do
+  process_input # may raise an exception
+end
+````
+
+And lastly, if you require `squash/ruby/exception_additions`, you can add user
+data directly in the exception constructor:
+
+```` ruby
+require 'squash/ruby/exception_additions'
+
+def process_value(value)
+  raise ArgumentError.new("value must be a number", :value => value) unless value.kind_of?(Fixnum)
+  # [...]
+end
+````
+
+Requiring that file also lets you add user data to exceptions you catch and
+re-raise:
+
+```` ruby
+require 'squash/ruby/exception_additions'
+
+begin
+  do_something_with_input(input)
+rescue ArgumentError => err
+  err.user_data :input => input
+  raise # assumed that Squash::Ruby.notify is called somewhere further up in the stack
+end
+````
+
+If monkey-patching doesn't appeal to you, then don't load
+`squash/ruby/exception_additions`; it's not required for the client to work.
+
+#### Ignoring Exceptions
+
+You can ignore certain exceptions within a block of code if those exceptions are
+not worth sending to Squash. Use the {Squash::Ruby.ignore_exceptions} method:
+
+```` ruby
+Squash::Ruby.ignore_exceptions(SocketError, Net::HTTPError) do
+  some_http_code_that_could_fail
+end
+````
+
+The exceptions _will_ be raised (not eaten) but will _not_ be reported to
+Squash.
+
+You can also globally ignore exceptions using the `ignored_exceptions`
+configuration; see **Configuration** below.
+
+Configuration
+-------------
+
+You can configure the client with the {Squash::Ruby.configure} method. Calling
+this method multiple times will merge new values in with the existing
+configuration. The method takes a hash, which accepts the following (symbol)
+keys:
+
+### General
+
+* `disabled`: If `true`, the Squash client will not report any errors.
+* `api_key`: The API key of the project that exceptions will be associated with.
+  This configuration option is required. The value can be found by going to the
+  project's home page on Squash.
+* `environment`: The environment that exceptions will be associated with.
+* `project_root`: The path to your project's root directory. This path will be
+  stripped from backtrace lines. By default it's set to the working directory.
+
+### Revision Information
+
+Squash can determine the current code revision using one of two methods. Specify
+only one of the following configuration keys:
+
+* `revision_file`: The path to a file storing the SHA1 of the current Git
+  revision. This is the revision of the code that is currently running.
+* `repository_root`: The path to the working directory of the Git repository
+  that is currently running. Use this option if your deployed code is a working
+  Git repository.
+
+By default, `repository_root` is assumed and is set to `Dir.getwd`.
+`revision_file` overrides `repository_root`.
+
+### Error Transmission
+
+* `api_host`: The host on which Squash is running. This field is required.
+* `notify_path`: The path to post new exception notifications to. By default
+  it's set to `/api/1.0/notify`.
+* `transmit_timeout`: The amount of time to wait before giving up on trasmitting
+  an error. By default this is treated as both an open and a read timeout.
+
+### Ignored Exceptions
+
+* `ignored_exception_classes`: An array of exception class names that will not
+  be reported to Squash.
+* `ignored_exception_messages`: A hash mapping an exception class name to an
+  array of regexes. Exceptions of that class whose messages match a regex in the
+  list will not be reported to Squash.
+* `ignored_exception_procs`: An array of `Proc` objects that can be used to
+  filter exceptions. Takes as arguments 1) the exception and 2) the user data
+  hash. Should return `true` if the exception should be ignored (_not_ reported)
+  and false otherwise. The user data hash can include stuff useful to extended
+  client libraries (e.g., Squash Rails client); an example:
+
+```` ruby
+Squash::Ruby.configure :ignored_exception_procs => lambda do |exception, user_data|
+  exception.kind_of?(ActiveRecord::RecordNotFound) && user_data[:headers]['X-Testing'].blank?
+end
+````
+
+### Failsafe Reporting
+
+* `failsafe_log`: The pathname of a log file where failsafe exceptions will be
+  recorded (see **Failsafe Reporting** below). By default, records to a file
+  named `squash.failsafe.log` in the current working directory.
+* `disable_failsafe`: If `true`, the failsafe handler will be disabled.
+  Exceptions raised when Squash is processing another exception will be handled
+  normally by the Ruby interpreter.
+
+Error Transmission
+------------------
+
+Exceptions are transmitted to Squash using JSON-over-HTTPS. A default API
+endpoint is pre-configured, though you can always set your own (see
+**Configuration** above).
+
+By default, `Net::HTTP` is used to transmit errors to the API server. If you
+would prefer to use your own HTTP library, you can override the
+{Squash::Ruby.http_transmit} method. This method is also used for deploy
+notification.
+
+Failsafe Reporting
+------------------
+
+In the event that the Squash client itself raises an exception when processing
+an exception, it will log that exception to the failsafe log. (See the
+`failsafe_log` configuration option, described above.) Both the original
+exception and the failsafe error will be logged. The original exception will
+still be re-raised, but the failsafe error will be "eaten."
+
+If for some reason the exceptions cannot be logged (e.g., a permissions error),
+they will be logged to standard error.
+
+It would behoove the engineers of a project using Squash to periodically check
+the failsafe log, as it may contain exceptions that couldn't be reported due
+to, e.g., bugs in generating user data.

data/lib/squash/ruby.rb

@@ -0,0 +1,531 @@
+# Copyright 2012 Square Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+require 'yaml'
+require 'socket'
+require 'net/https'
+
+require 'json'
+begin
+  Gem::Specification.find_by_name('system_timer')
+  require 'system_timer'
+rescue Gem::LoadError
+end
+
+# Container for methods relating to notifying Squash of exceptions.
+
+module Squash
+  module Ruby
+    # Reserved instance variables that cannot be keys in a user-data hash.
+    EXCEPTION_RESERVED_IVARS = %W( mesg bt )
+    # Default values for different configuration variables.
+    CONFIGURATION_DEFAULTS   = {
+        :notify_path                => "/api/1.0/notify",
+        :deploy_path                => "/api/1.0/deploy",
+        :open_timeout               => 15,
+        :transmit_timeout           => 15,
+        :ignored_exception_classes  => [],
+        :ignored_exception_messages => {},
+        :ignored_exception_procs    => [],
+        :failsafe_log               => "squash.failsafe.log",
+        :repository_root            => Dir.getwd,
+        :project_root               => Dir.getwd
+    }
+    # Types that are serialized directly to JSON, rather than to a hash of
+    # object information. Subclasses are not considered members of this array.
+    JSON_NATIVE_TYPES        = [String, NilClass, TrueClass, FalseClass, Integer,
+                                Fixnum, Float]
+    # Array of user-data fields that should be moved out of the user data to
+    # become top-level attributes. A Rails client library would expand this
+    # constant to include Rails-specific fields, for example.
+    TOP_LEVEL_USER_DATA      = []
+
+    # Notifies Squash of an exception.
+    #
+    # @param [Object] exception The exception. Must at least duck-type an
+    #   `Exception` subclass.
+    # @param [Hash] user_data Any additional context-specific information about
+    #   the exception.
+    # @return [true, false] Whether the exception was reported to Squash. (Some
+    #   exceptions are ignored and not reported to Squash.)
+    # @raise [StandardError] If Squash has not yet been fully configured (see
+    #   {.configure}).
+
+    def self.notify(exception, user_data={})
+      occurred = Time.now
+
+      return false if configuration(:disabled)
+      unless exception.respond_to?(:backtrace)
+        failsafe_log 'notify', "Tried to pass notify something other than an exception: #{exception.inspect}"
+        return false
+      end
+      unless exception.backtrace
+        failsafe_log 'notify', "Tried to pass notify an exception with no backtrace: #{exception}"
+        return false
+      end
+
+      raise "The :api_key configuration is required" unless configuration(:api_key)
+      raise "The :api_host configuration is required" unless configuration(:api_host)
+      raise "The :environment configuration is required" unless configuration(:environment)
+
+      begin
+        exception, parents = unroll(exception)
+        return false if ignored?(exception, user_data)
+        check_user_data user_data
+
+        hsh = exception_info_hash(exception, occurred, user_data, parents)
+        http_transmit configuration(:api_host) + configuration(:notify_path), {}, hsh.inject({}) { |h, (k, v)| h[k.to_s] = v; h }.to_json
+        return true
+      rescue Object => nested_error
+        raise if configuration(:disable_failsafe)
+        failsafe_handler exception, nested_error
+        :failsafe # a perfect example of http://thedailywtf.com/Articles/What_Is_Truth_0x3f_.aspx
+      end
+    end
+
+    # Raises an exception and immediately catches it and sends it to Squash. The
+    # exception is then eaten. This is meant to be used as a hackneyed form of
+    # event logging. You can pass in any user data you wish to record with the
+    # event.
+    #
+    # It should be emphasized that Squash is not a logging system, and there are
+    # far more appropriate products for this kind of thing, but this method is
+    # here nonetheless.
+    #
+    # @overload record(exception_class, message, user_data={})
+    #   Specify both the exception class and the message.
+    #   @param [Class] exception_class The exception class to raise.
+    #   @param [String] message The exception message.
+    #   @param [Hash] user_data Additional information to give to {.notify}.
+    # @overload record(message, user_data={})
+    #   Specify only the message. The exception class will be `StandardError`.
+    #   @param [String] message The exception message.
+    #   @param [Hash] user_data Additional information to give to {.notify}.
+
+    def self.record(exception_class_or_message, message_or_options=nil, data=nil)
+      if message_or_options && data
+        exception_class = exception_class_or_message
+        message         = message_or_options
+      elsif message_or_options.kind_of?(String)
+        message         = message_or_options
+        exception_class = exception_class_or_message
+      elsif message_or_options.kind_of?(Hash)
+        data            = message_or_options
+        message         = exception_class_or_message
+        exception_class = StandardError
+      elsif message_or_options.nil?
+        message         = exception_class_or_message
+        exception_class = StandardError
+      else
+        raise ArgumentError
+      end
+
+      begin
+        raise exception_class, message
+      rescue exception_class => error
+        notify error, data || {}
+      end
+    end
+
+    # Suppresses reporting of certain exceptions within a block of code. Any
+    # exceptions raised in the block will continue to be raised, however.
+    #
+    # Let's take a few examples. If `exception_classes` is `[RangeError]`, then
+    # obviously any raised `RangeError`s will not be reported. If
+    # `StandardError` is raised, it _will_ be reported, because it's a
+    # superclass of `RangeError`. If `FloatDomainError` is raised, it _will not_
+    # be reported because it is a _subclass_ of `RangeError`. Confusing? Sure,
+    # but I'm pretty sure this is the behavior most people would expect.
+    #
+    # @param [Array<Class>] exception_classes A list of exception classes to
+    #   ignore. If not provided, ignores all exceptions raised in the block.
+    # @yield The code to ignore exceptions in.
+    # @return The result of the block.
+
+    def self.ignore_exceptions(exception_classes=nil)
+      raise ArgumentError, "Squash::Ruby.ignore_exceptions must be called with a block" unless block_given?
+      exception_classes = [exception_classes] if exception_classes.kind_of?(Class)
+
+      begin
+        yield
+      rescue Object => err
+        err.instance_variable_set(:@_squash_do_not_report, true) if exception_classes.nil? || exception_classes.map { |e| e.ancestors }.flatten.include?(err.class)
+        raise
+      end
+    end
+
+    # Adds user data to any exception raised within a block of code, and
+    # re-raises the exception.
+    #
+    # @param [Hash] user_data User data to add to an exception.
+    # @yield The code to run.
+    # @return The result of the block.
+    # @raise [ArgumentError] If `data` contains the keys `mesg` or `bt`.
+
+    def self.add_user_data(user_data)
+      raise ArgumentError, "Squash::Ruby.add_user_data must be called with a block" unless block_given?
+      check_user_data user_data
+
+      begin
+        yield
+      rescue Object => err
+        user_data.each { |ivar, val| err.send :instance_variable_set, :"@#{ivar}", val }
+        raise
+      end
+    end
+
+    # Sets configuration options for the client from a hash. See the README for
+    # a list of configuration options. Subsequent calls will merge in new
+    # configuration options.
+    #
+    # You must at a minimum specify the `:api_key` and `:environment` settings
+    # (see the README.md file).
+    #
+    # @param [Hash] options Configuration options.
+
+    def self.configure(options)
+      @configuration = (@configuration || CONFIGURATION_DEFAULTS.dup).merge(options.inject({}) { |hsh, (k, v)| hsh[(k.to_sym rescue k)] = v; hsh })
+    end
+
+    # @private
+    def self.check_user_data(data)
+      bad_ivars = EXCEPTION_RESERVED_IVARS.select { |name| data.keys.map { |k| k.to_s }.include? name }
+      raise ArgumentError, "The following cannot be used as user-data keys: #{bad_ivars.join(', ')}" unless bad_ivars.empty?
+    end
+
+    protected
+
+    # Posts an exception or deploy notification to the API endpoint. Only POST
+    # requests are supported. This method is used internally only. It is
+    # documented so that, in the event you wish to use an alternative HTTP
+    # library (other than `Net::HTTP`), you can override this method.
+    #
+    # This method will make a `POST` request to the given URL. The request will
+    # contain the given headers and body. It should not eat any exceptions
+    # relating to HTTP connectivity issues.
+    #
+    # Your implementation should also respect the value of the
+    # `transmit_timeout` configuration, which is accessible using
+    # `configuration(:transmit_timeout)`.
+    #
+    # @param [String] url The URL to post to. Could be an HTTP or HTTPS URL.
+    # @param [Hash<String, String>] headers The request headers.
+    #   `Content-Type: application/json` is added by default.
+    # @param [String] body The request body.
+    # @return [true, false] Whether or not the response was successful.
+
+    def self.http_transmit(url, headers, body)
+      uri  = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http_options(uri).each { |k, v| http.send :"#{k}=", v }
+
+      block = lambda do
+        http.start do |http|
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request.add_field 'Content-Type', 'application/json'
+          headers.each { |k, v| request.add_field k, v }
+          request.body = body
+          response     = http.request request
+          if response.kind_of?(Net::HTTPSuccess)
+            return true
+          else
+            self.failsafe_log 'http_transmit', "Response from server: #{response.code}"
+            return false
+          end
+        end
+      end
+
+      if defined?(SystemTimer)
+        SystemTimer.timeout_after configuration(:open_timeout), &block
+      else
+        block.call
+      end
+    end
+
+    # Notifies Squash of a new deploy. Squash will then determine which bug
+    # fixes have been deployed and then mark those bugs as fix-deployed.
+    #
+    # @param [String] env The name of the environment that was deployed.
+    # @param [String] revision The repository revision that was deployed.
+    # @param [String] from_host The hostname of the computer that performed the
+    #   deploy.
+    # @raise [StandardError] If an invalid response is received from the HTTP
+    #   request.
+
+    def self.notify_deploy(env, revision, from_host)
+      return if configuration(:disabled)
+
+      success = http_transmit(
+          configuration(:api_host) + configuration(:deploy_path),
+          {},
+          {
+              'project'     => {'api_key' => configuration(:api_key)},
+              'environment' => {'name' => env},
+              'deploy'      => {
+                  'deployed_at' => Time.now,
+                  'revision'    => revision,
+                  'hostname'    => from_host
+              }
+          }.to_json
+      )
+      $stderr.puts "[Squash] Bad response; see failsafe log" unless success
+    rescue Timeout::Error
+      $stderr.puts "[Squash] Timeout when trying to notify of the deploy"
+    end
+
+    # @abstract
+    #
+    # Override this method to filter sensitive information from any data that
+    # Squash intends to add to an occurrence. This method receives every object
+    # that Squash is about to serialize -- instance variables, user data,
+    # (for Rails) sessions, params, etc., just before serialization and
+    # transmission.
+    #
+    # This method gives you the opportunity to alter the object before
+    # serialization, for example to remove sensitive information. It's probably a
+    # good idea to clone the object, modify it, and then return the clone, so that
+    # the original object remains unmodified.
+    #
+    # The base implementation returns `value` unmodified.
+    #
+    # @param value A value that is about to be serialized for transmission.
+    # @return The object to serialize (filtered as necessary). May be a different
+    #   object.
+    def self.value_filter(value) value end
+
+    private
+
+    def self.http_options(uri)
+      options = {:use_ssl      => uri.scheme == 'https',
+                 :open_timeout => configuration(:transmit_timeout),
+                 :read_timeout => configuration(:transmit_timeout)}
+      options[:verify_mode] = OpenSSL::SSL::VERIFY_NONE if configuration(:skip_ssl_verification)
+      options
+    end
+
+    def self.configuration(key)
+      (@configuration || CONFIGURATION_DEFAULTS)[key] || CONFIGURATION_DEFAULTS[key]
+    end
+
+    def self.ignored?(exception, user_data)
+      return true if exception.instance_variable_get(:@_squash_do_not_report)
+
+      return true if Array(configuration(:ignored_exception_classes)).map do |class_name|
+        constantize class_name
+      end.compact.any? { |klass| exception.kind_of?(klass) }
+
+      return true if configuration(:ignored_exception_messages).any? do |class_name, ignored_messages|
+        ignored_messages = Array(ignored_messages).map { |str| str.kind_of?(String) ? Regexp.compile(str) : str }
+        (klass = constantize(class_name)) && exception.kind_of?(klass) && ignored_messages.any? { |msg| exception.to_s =~ msg }
+      end
+
+      return true if Array(configuration(:ignored_exception_procs)).any? do |proc|
+        proc.call(exception, user_data)
+      end
+
+      return false
+    end
+
+    def self.exception_info_hash(exception, occurred, user_data, parents)
+      top_level_user_data = Hash.new
+      user_data.delete_if do |key, value|
+        if TOP_LEVEL_USER_DATA.include?(key.to_s)
+          top_level_user_data[key.to_s] = valueify(value, true)
+          true
+        else
+          false
+        end
+      end
+
+      environment_data.merge(top_level_user_data).merge(
+          'class_name'        => exception.class.to_s,
+          'message'           => exception.to_s,
+          'backtraces'        => [["Active Thread/Fiber", true, prepare_backtrace(exception.backtrace)]],
+          'occurred_at'       => occurred,
+          'revision'          => current_revision,
+
+          'environment'       => configuration(:environment).to_s,
+          'api_key'           => configuration(:api_key).to_s,
+          'client'            => client_name,
+
+          'ivars'             => instance_variable_hash(exception),
+          'user_data'         => valueify(user_data, true),
+
+          'parent_exceptions' => parents.nil? ? nil : parents.map do |parent|
+            {'class_name'  => parent.class.to_s,
+             'message'     => parent.to_s,
+             'backtraces'  => [["Active Thread/Fiber", true, prepare_backtrace(parent.backtrace)]],
+             'association' => 'original_exception',
+             'ivars'       => instance_variable_hash(parent)}
+          end
+      )
+    end
+
+    def self.prepare_backtrace(bt)
+      if defined?(JRuby)
+        bt.map do |element|
+          if element =~ /^((?:[a-z0-9_$]+\.)*(?:[a-z0-9_$]+))\.(\w+)\((\w+.java):(\d+)\)$/i
+            # special JRuby backtrace element of the form "org.jruby.RubyHash$27.visit(RubyHash.java:1646)"
+            ['_JAVA_', $3, $4.to_i, $2, $1]
+          else
+            if element.include?(' at ')
+              method, fileline = element.split(' at ')
+              method.lstrip!
+              file, line = fileline.split(':')
+            else
+              file, line, method = element.split(':')
+              if method =~ /^in `(.+)'$/
+                method = $1
+              end
+              method = nil if method && method.empty?
+            end
+            line = line.to_i
+            line = nil if line < 1
+            if method =~ /^in `(.+)'$/
+              method = $1
+            end
+            method = nil if method && method.empty?
+
+            # it could still be a java backtrace, even if it's not the special format
+            if file[-5, 5] == '.java'
+              ['_JAVA_', file.split('/').last, line, method, file.sub(/\.java$/, '').gsub('/', '.')]
+            else
+              # ok now we're sure it's a ruby backtrace
+              file.slice! 0, configuration(:project_root).length + 1 if file[0, configuration(:project_root).length + 1] == configuration(:project_root) + '/'
+              [file, line, method]
+            end
+          end
+        end
+      else
+        bt.map do |element|
+          file, line, method = element.split(':')
+          line               = line.to_i
+          line = nil if line < 1
+
+          file.slice! 0, configuration(:project_root).length + 1 if file[0, configuration(:project_root).length + 1] == configuration(:project_root) + '/'
+
+          if method =~ /^in `(.+)'$/
+            method = $1
+          end
+          method = nil if method && method.empty?
+          [file, line, method]
+        end
+      end
+    end
+
+    def self.valueify(instance, elements_only=false)
+      if JSON_NATIVE_TYPES.any? { |klass| instance.class == klass }
+        instance
+      elsif instance.kind_of?(Hash) && elements_only
+        instance.inject({}) { |hsh, (k, v)| hsh[k.to_s] = valueify(v); hsh }
+      elsif instance.kind_of?(Array) && elements_only
+        instance.map { |i| valueify(i) }
+      else
+        filtered = value_filter(instance)
+        {
+            'language'   => 'ruby',
+            'class_name' => filtered.class.to_s,
+            'inspect'    => filtered.inspect,
+            'yaml'       => (filtered.to_yaml rescue nil),
+            'json'       => (filtered.to_json rescue nil),
+            'to_s'       => (filtered.to_s rescue nil)
+        }
+      end
+    end
+
+    def self.instance_variable_hash(object)
+      object.instance_variables.inject({}) do |hsh, cur|
+        hsh[cur.to_s[1..-1]] = valueify(object.send(:instance_variable_get, cur.to_sym))
+        hsh
+      end
+    end
+
+    def self.constantize(class_name)
+      return class_name if class_name.kind_of?(Class)
+
+      parts    = class_name.split('::').reject { |i| i.empty? }
+      constant = Object
+      while parts.any? do
+        begin
+          constant = constant.const_get(parts.shift)
+        rescue NameError
+          return nil
+        end
+      end
+      constant
+    end
+
+    # @private
+    def self.environment_data
+      {
+          'pid'       => Process.pid,
+          'hostname'  => Socket.gethostname,
+          'env_vars'  => ENV.inject({}) { |hsh, (k, v)| hsh[k.to_s] = valueify(v); hsh },
+          'arguments' => ARGV.join(' ')
+      }
+    end
+
+    # @private
+    def self.failsafe_handler(original_error, nested_error)
+      log_entries = [
+          "#{Time.now.to_s} - Original error: (#{original_error.class.to_s}) #{original_error.to_s}",
+          (original_error.backtrace || []).map { |l| '  ' + l }.join("\n"),
+          "#{Time.now.to_s} - Error raised when reporting original error: (#{nested_error.class.to_s}) #{nested_error.to_s}",
+          nested_error.backtrace.map { |l| '  ' + l }.join("\n"),
+          "--- END SQUASH FAILSAFE ERROR ---"
+      ]
+      log_entries.each { |message| self.failsafe_log 'failsafe_handler', message }
+    end
+
+    # @private
+    def self.failsafe_log(tag, message)
+      File.open(configuration(:failsafe_log), 'a') do |f|
+        f.puts "#{Time.now.to_s}\t[#{tag}]\t#{message}"
+      end
+    rescue Object => err
+      $stderr.puts "Couldn't write to failsafe log (#{err.to_s}); writing to stderr instead."
+      $stderr.puts "#{Time.now.to_s}\t[#{tag}]\t#{message}"
+    end
+
+    # @private
+    def self.current_revision
+      revision = if configuration(:revision_file)
+                   File.read(configuration(:revision_file)).chomp.strip
+                 else
+                   head_file = File.join(configuration(:repository_root), '.git', 'HEAD')
+                   if File.exist?(head_file)
+                     rev = File.read(head_file).chomp.strip
+                     rev = File.read(File.join(configuration(:repository_root), '.git', $1)).chomp.strip if rev =~ /^ref: (.+?)$/
+                     rev
+                   else
+                     raise "You must set the :revision_file configuration if the code is not running in a Git checkout"
+                   end
+                 end
+      raise "Unknown Git revision #{revision.inspect}" unless revision =~ /^[0-9a-f]{40}$/
+      revision
+    end
+
+    # @private
+    def self.unroll(exception)
+      if exception.respond_to?(:original_exception)
+        [exception.original_exception, [exception]]
+      else
+        [exception, nil]
+      end
+    end
+
+    # @private
+    def self.client_name() 'ruby' end
+  end
+end

data/lib/squash/ruby/exception_additions.rb

@@ -0,0 +1,55 @@
+# Copyright 2012 Square Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+# Reopens the `Exception` class to add a convenient way of appending user data
+# to an exception at the time of the raise.
+#
+# @example
+#   raise ArgumentError.new("value must be a number", :value => value) unless value.kind_of?(Fixnum)
+
+class Exception
+
+  # @overload new(message, user_data={})
+  #   Creates a new exception instance, optionally with user data.
+  #   @param [String] message The exception message.
+  #   @param [Hash] user_data Additional data to report to Squash about the
+  #     exception.
+  #   @return [Exception] The initialized exception.
+  #   @raise [ArgumentError] If `data` contains the keys `mesg` or `bt`.
+
+  def self.new(*args)
+    user_data = if args.last.is_a?(Hash)
+                  args.pop
+                else
+                  {}
+                end
+    Squash::Ruby.check_user_data user_data
+    super(*args).user_data(user_data)
+  end
+
+  # Annotates this exception with user data. Merges in any new data with
+  # existing user data.
+  #
+  # @param [Hash] data The user data to add.
+  # @return [Exception] The receiver.
+  # @raise [ArgumentError] If `data` contains the keys `mesg` or `bt`.
+
+  def user_data(data)
+    Squash::Ruby.check_user_data data
+    data.each do |ivar, value|
+      instance_variable_set :"@#{ivar}", value
+    end
+    self
+  end
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification 
+name: squash_ruby
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Tim Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-12-07 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  name: json
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  name: rspec
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  name: yard
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  name: redcarpet
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  name: jeweler
+  version_requirements: *id005
+description: This client library records Ruby exceptions to Squash.
+email: tim@squareup.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.md
+files: 
+- LICENSE.txt
+- README.md
+- lib/squash/ruby.rb
+- lib/squash/ruby/exception_additions.rb
+homepage: http://github.com/SquareSquash/ruby
+licenses: 
+- Apache 2.0
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Squash client for Ruby projects
+test_files: []
+