kaeruera 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f10a4c75cdcc7a510f985a61bc48182c27071f89
+  data.tar.gz: 623fd3a7f3f5e74b468b539c57740303e2d41418
+SHA512:
+  metadata.gz: 8212e3adfe8d95d3264bdd53422fed401a09782bf62212e0612c73453e778989d2fbf26a8b6dcd218bf4d7a83f099213631a19c6ed98f7a1713c821be0507eae
+  data.tar.gz: 4e6fee570e76659f25fa767bd190bfdad0669eb95914cef3f4a9bf8c99a0fcb0b5087ca697cdf04ea63e3e7e992dae21b6b20d96e2bd4ed73cfc143860a3cd70

data/CHANGELOG

@@ -0,0 +1,3 @@
+=== 0.1.0
+
+* Initial Public Release

data/MIT-LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2013 Jeremy Evans
+
+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 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.rdoc

@@ -0,0 +1,296 @@
+= KaeruEra
+
+KaeruEra is a bare-bones error tracking application for ruby, tracking
+errors that occur in other ruby applications.
+
+It is similar to Errbit[1] but with a much smaller feature set.  The
+only advantages that KaeruEra has over Errbit are more advanced
+search features, fewer dependencies, and a smaller footprint.  There
+are no notification features, source control integration, issue tracker
+integration, user information tracking, deploy tracking, or GitHub/LDAP
+authentication.  You are responsible for manually integrating the error
+reporter into the applications that will be reporting errors.
+
+As another example of the simplicity, KaeruEra does not do error
+aggregation.  Instead, for each error, it offers the ability to easily
+search for errors with the same class, message, backtrace line, etc..
+Any results of that search can be manipulated as a unit.
+
+KaeruEra is not designed to replace an existing error tracking
+application.  It's designed to supplement an email notification
+about the error.
+
+1. (https://github.com/errbit/errbit)
+
+== Demo
+
+* URL: http://kaeruera.herokuapp.com
+* Login Email: demo
+* Login Password: demo
+
+== Source Control/Issue Tracker
+
+https://github.com/jeremyevans/kaeruera
+
+== License
+
+KaeruEra is licensed under the MIT License.
+
+== Design
+
+The KaeruEra database and web server have a fairly simple design.
+There are only three tables in the database, users, applications,
+and errors.  Each user can have multiple applications, and each
+application multiple errors.
+
+In the database, each error is stored is a single row, document
+style.  This uses PostgreSQL's advanced types, storing the
+backtrace for the error as an array of text fields (text[]),
+the environment as an hstore (string key/string value hash table),
+and the params and session information as json (since they often
+contain nested data).  All of the error columns are indexed for
+easy searching.
+
+The web site has a very basic bootstrap design, with only 4 main
+pages:
+
+* Front page (choose an application)
+* Search page (options for each search field)
+* Error List page (see open errors for applications/search results)
+* Error page (see all information about a particular error,
+  with links to perform searches for similar errors)
+
+=== Error Information Tracked
+
+* Exception Class
+* Exception Message
+* Exception Backtrace
+* Params
+* Environment Variables
+* Session Variables
+
+The exception class, message, and backtrace are required and are
+taken from the underlying ruby exception.
+
+The params, environment, and session information are optional, and
+you have to configure the reporting code to include the
+information.
+
+=== Updating Errors
+
+Most information for errors is immutable.  The two exceptions are that each error has a notes
+field and an open/closed flag.  As long as the error is open, the notes flag can be updated and
+it can be closed.  Once it is closed, the error is completely immutable.
+
+== Reporting Errors
+
+KaeruEra is not airbrake compatible.  Instead, it offers separate
+libraries for reporting errors.  All libraries are shipped in the
+kaeruera gem, installable via:
+
+  gem install kaeruera
+
+=== KaeruEra::DatabaseReporter
+
+This library assumes you can have a direct connection to the
+database, and inserts the error directly into the database.
+
+  require 'kaeruera/database_reporter'
+  REPORTER = KaeruEra::DatabaseReporter.new('postgres://db_user:pass@host:port/database', 'email@example.com', 'app_name')
+
+Here db_user is the PostgreSQL user name for the connection, email
+is the email address for the user account in the KaeruEra application,
+and app_name is the application name in KaeruEra.
+
+=== KaeruEra::Reporter
+
+This library uploads the error information to a server
+running the web application, via json.
+
+  require 'kaeruera/reporter'
+  REPORTER = KaeruEra::Reporter.new('http://host:port/report_error', application_id, 'application_token')
+
+You can use the "Reporter Info" page in the web application to get a line that will work for the given
+application.
+
+=== KaeruEra::AsyncReporter
+
+This library is the same as the KaeruEra::Reporter library,
+except it runs asynchronously, useful if the application does
+not have a fast connection to the KaeruEra server.  The downside
+is you don't get the id of the error, and are not notified
+if there was a problem reporting the error.
+
+  require 'kaeruera/async_reporter'
+  REPORTER = KaeruEra::AsyncReporter.new('http://host:port/report_error', application_id, 'application_token')
+
+=== Usage
+
+All three libraries for reporting errors have the same API:
+
+  REPORTER.report
+
+If called without arguments, it assumes that $! is the error to report.  This makes it easy to use
+in a rescue block:
+
+  begin
+    #code
+  rescue
+    REPORTER.report
+  end
+
+If the error you want to report is not in $!, you can pass it via the :error option:
+
+  begin
+    #code
+  rescue => e
+    begin
+      #more code
+    rescue
+      REPORTER.report(:error => e)
+    end
+  end
+
+The params, session, and environment variables are all passed as options :params, :session, and :env.
+In each case the values for those options should be hashes.
+
+As reporters are designed to be used in rescue blocks, they swallow any errors raised internally,
+since the assumption is that it is better to raise the original error in that case.
+
+The return value of the reporting methods is one of the following:
+
+Integer :: The id of the error, indicating the error was successfully reported.
+false :: There was no error detected (:error option was not set and $! did not indicate an active error)
+true :: The async reporter received a valid error (it cannot tell whether the error was successfully reported).
+StandardError :: an exception occurred when trying to report the error, the return value is the exception.
+
+=== Sinatra
+
+If the application reporting errors is running sinatra, you can probably put this in your error block
+to report errors to KaeruEra:
+
+  REPORTER.report(:params=>params, :env=>env, :session=>session, :error=>request.env['sinatra.error'])
+
+== Runtime Dependencies
+
+=== KaeruEra::App (web server)
+
+* PostgreSQL 9.2+
+* pg
+* sinatra
+* sinatra-flash
+* sequel
+* bcrypt-ruby
+* forme
+* json
+* rack_csrf
+* rack-compatible web server
+
+=== KaeruEra::DatabaseReporter
+
+* pg
+* sequel
+
+=== KaeruEra::Reporter / KaeruEra::AsyncReporter
+
+* rest-client
+* json
+
+== Heroku Setup
+
+  heroku create
+  heroku addons:add heroku-postgresql:dev
+  heroku pg:promote HEROKU_POSTGRESQL_COLOR_URL
+  git push heroku master
+  echo 'CREATE EXTENSION hstore' | heroku pg:psql
+  heroku run rake production_up
+  heroku config:set KAERUERA_SECRET=`ruby -rsecurerandom -e 'puts SecureRandom.hex(30)'`
+  heroku run irb -r ./models
+  irb> User.create(:email=>'foo', :password=>'bar')
+
+== Manual Setup
+
+=== Database Setup
+
+First, copy the example database configuration file:
+
+  cp db_config.rb.example db_config.rb
+
+The rest of the instructions assume you are not modifying the
+default database configuration, and that the database super user
+for your PostgreSQL database cluster is postgres.  If those
+assumptions are inaccurate, you should substitute the appropriate
+values.  Also, the examples below do not use a password for the
+accounts, so they will only work if localhost is trusted in PostgreSQL.
+
+Create a user for the application:
+
+  createuser -U postgres kaeruera
+
+Then, create databases for the application with that user:
+
+  createdb -U postgres -O kaeruera kaeruera_development
+  createdb -U postgres -O kaeruera kaeruera_test
+  createdb -U postgres -O kaeruera kaeruera_production
+
+If you don't have hstore as a default extension in your PostgreSQL
+template database, you'll have to add it:
+
+  echo 'CREATE EXTENSION hstore' | psql -U postgres kaeruera_development
+  echo 'CREATE EXTENSION hstore' | psql -U postgres kaeruera_test
+  echo 'CREATE EXTENSION hstore' | psql -U postgres kaeruera_production
+
+Then, you can migrate the database:
+
+  rake dev_up
+  rake test_up
+  rake production_up
+
+=== User Account Setup
+
+In development mode, the first time the server is started, if you haven't
+set up any users manually, a kaeruera user account (login/password kaeruera)
+and application named KaeruEraApp will automatically be created for you.
+It's recommended that you change the password for this user after logging
+in for the first time in development mode.
+
+In all other cases, you have to setup your user accounts manually:
+
+  $ irb -r ./models
+  User.create(:email=>'foo', :password=>'bar')
+
+It's recommended that you have a kaeruera user and KaeruEraApp application
+for that user, as that is where the web application will log any internal
+errors.
+
+=== Session Secret Setup
+
+Create the session secret file:
+
+  ruby -rsecurerandom -e 'puts SecureRandom.hex(30)' > kaeruera.secret
+
+== Testing
+
+To run all tests, use rake's default task:
+
+  rake
+
+This assumes you have already created the test database and migrated the
+test database to the latest version.  The following are additional
+requirements when running tests:
+
+* Rspec 1
+* Unicorn
+* Capybara
+
+== Naming
+
+KaeruEra is a transliteration of the Japanese words for frog (kaeru)
+and error (era).  One of the first popular error reporting apps for
+ruby was named Hoptoad (later renamed to Airbrake), and Errbit I'm
+guessing was chosen for its similarity to ribbit (the sound a frog
+makes) so this is in keeping with the frog theme.
+
+== Author
+
+Jeremy Evans <code@jeremyevans.net>

data/lib/kaeruera/async_reporter.rb

@@ -0,0 +1,35 @@
+require 'kaeruera/reporter'
+require 'thread'
+
+module KaeruEra
+  # AsyncReporter reports the error to a KaeruEra
+  # application via HTTP, but does it asynchronously.
+  class AsyncReporter
+    # Accepts the same arguments as Reporter.
+    def initialize(url, application_id, token)
+      reporter = Reporter.new(url, application_id, token)
+      @queue = Queue.new
+      Thread.new do
+        loop{reporter.report(@queue.pop) rescue nil}
+      end
+    end
+
+    # If an error cannot be determined, returns false.
+    # Otherwise, adds the error to the queue of errors
+    # to handle asynchronously and returns true.  If
+    # an exception would be raised by this code, returns
+    # the exception instead of raising it.
+    #
+    # Supports the same options as Reporter#report.
+    def report(opts={})
+      unless opts[:error]
+        return false unless $!
+        opts = opts.merge(:error=>$!)
+      end
+      @queue.push(opts)
+      true
+    rescue => e
+      e
+    end
+  end
+end

data/lib/kaeruera/database_reporter.rb

@@ -0,0 +1,58 @@
+require 'sequel'
+
+module KaeruEra
+  # Reporter class that inserts the error information directly
+  # into the database instead of reporting it to a web server via
+  # HTTP.
+  class DatabaseReporter
+    # Exception raised when no matching application is found in the
+    # database (i.e. not matching email and application).
+    class Error < StandardError; end
+
+    # Arguments:
+    # uri :: Either a Sequel::Database instance or a String treated as a URI.
+    #        If a Sequel::Database instance is given, uses given database,
+    #        otherwise, connects to the database specified by the URI via Sequel.
+    # email :: The KaeruEra email/login for the application.
+    # application :: The KaeruEra application name
+    def initialize(uri, email, application)
+      @db = uri.is_a?(Sequel::Database) ? uri : Sequel.connect(uri, :keep_reference=>false)
+      @db.extension :pg_array, :pg_hstore, :pg_json
+      @application_id, @user_id = @db[:applications].where(:user_id=>@db[:users].where(:email=>email).get(:id), :name=>application).get([:id, :user_id])
+      raise(Error, "No matching application in database for #{email}/#{application}") unless @application_id
+    end
+
+    # If an error cannot be determined, returns false.
+    # Otherwise, inserts the error directly into the
+    # database.
+    # If an exception would be raised by this code, returns
+    # the exception instead of raising it.
+    #
+    # Supports the same options as Reporter#report.
+    def report(opts={})
+      return false unless error = opts[:error] || $!
+
+      h = {
+        :user_id=>@user_id,
+        :application_id=>@application_id,
+        :error_class=>error.class.name,
+        :message=>error.message.to_s,
+        :backtrace=>Sequel.pg_array(error.backtrace)
+      }
+
+      if v = opts[:params]
+        h[:params] = Sequel.pg_json(v.to_hash)
+      end
+      if v = opts[:session]
+        h[:session] = Sequel.pg_json(v.to_hash)
+      end
+      if v = opts[:env]
+        h[:env] = Sequel.hstore(v.to_hash)
+      end
+
+      @db[:errors].insert(h)
+    rescue => e
+      e
+    end
+  end
+end

data/lib/kaeruera/reporter.rb

@@ -0,0 +1,59 @@
+require 'rest-client'
+require 'json'
+
+module KaeruEra
+  # The standard Reporter class reports errors via HTTP requests
+  # to a KaeruEra web server.
+  class Reporter
+    # Arguments:
+    # url :: The url to use to report the error.
+    # application_id :: The id for the application on the KaeruEra server.
+    # token :: The application's token on the KaeruEra server.
+    #
+    # You can get this information from looking at the "Reporter Info"
+    # page on the KaeruEra server.
+    def initialize(url, application_id, token)
+      @url = url
+      @application_id = application_id
+      @token = token
+    end
+
+    # If an error cannot be determined, returns false.
+    # Otherwise, reports the error to the KaeruEra server via HTTP.
+    # If an exception would be raised by this code, returns
+    # the exception instead of raising it.
+    #
+    # Options:
+    # :error :: The exception to report
+    # :env :: The environment variables related to this exception.
+    #         For a web application, generally the HTTP request
+    #         environment variables.
+    # :params :: The params related to the exception.  For a web
+    #            application, generally the GET/POST parameters.
+    # :session :: Any session information to the exception.
+    def report(opts={})
+      return false unless error = opts[:error] || $!
+
+      h = {
+        :error_class=>error.class.name,
+        :message=>error.message.to_s,
+        :backtrace=>error.backtrace
+      }
+
+      if v = opts[:params]
+        h[:params] = v
+      end
+      if v = opts[:session]
+        h[:session] = v
+      end
+      if v = opts[:env]
+        h[:env] = v
+      end
+
+      res = RestClient.post @url, {:data=>h, :id=>@application_id, :token=>@token}.to_json, :content_type => :json, :accept => :json
+      JSON.parse(res)['error_id']
+    rescue => e
+      e
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: kaeruera
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeremy Evans
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-07 00:00:00.000000000 Z
+dependencies: []
+description: |
+  KaeruEra is a simple error tracking application. This
+  gem includes 3 separate reporter libaries that can be
+  used to submit errors to KaeruEra.
+email: code@jeremyevans.net
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+- CHANGELOG
+- MIT-LICENSE
+files:
+- MIT-LICENSE
+- CHANGELOG
+- README.rdoc
+- lib/kaeruera/reporter.rb
+- lib/kaeruera/async_reporter.rb
+- lib/kaeruera/database_reporter.rb
+homepage: http://github.com/jeremyevans/kaeruera
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --quiet
+- --line-numbers
+- --inline-source
+- --title
+- Reporter Libraries for KaeruEra
+- --main
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Faster SELECTs when using Sequel with pg
+test_files: []