adalog 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c15c023b9348c277ec76330788aa48ff50e97009
+  data.tar.gz: 1a67e84184ec901ae73f58253decf22e0196e8b5
+SHA512:
+  metadata.gz: c80d618c9f584f39167f2ef97b42ff1f05eddb0c6b8f0dab7664d21bd8183e05bdb471baeff58627db214f48e38e3a94c81b12eea0f15c3e664d2c6e15677e38
+  data.tar.gz: 583ba7212ab7caf2fda0bd7772bbee8af0f7a9b7f59c9ea31c21305593fab93e5f46585e34dd3df75ff9b11fd1b30fa65510d2b3fe567ba78c96af800829c573

data/.gitignore

@@ -0,0 +1,29 @@
+.DS_Store
+lob/*.log
+log/*.log
+tmp/**/*
+*.swp
+*.tmproj
+tmtags
+.project
+.bundle
+*.sublime-project
+*.sublime-workspace
+.vagrant
+.ruby-version
+.ruby-gemset
+*.gem
+*.rbc
+.config
+.yardoc
+InstalledFiles
+Gemfile.lock
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+test/tmp
+test/version_tmp
+config.ru

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,27 @@
+Copyright (c) 2015, Paul Kwiatkowski
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of adalog nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,144 @@
+# Adalog
+
+It pairs some Log-like Repository implementation with a Sinatra app. What an achievement, right? No? I agree, but read on.
+
+
+## Motivation
+
+Far, far too many third party services do not bother to implement competent sandbox environments. If you're doing "the right thing" and wrapping their client libraries in your own adapter layer (of some variety), you can easily swap out for a stub implementation in development, test or staging environments.
+
+Great! But now you have to write a second set test of adapaters yourself. So... not great! And sometimes all you want to do is check they were even sending (or receiving) the right message/data anyway?
+
+In the way that Matz "is not a concurrency guy", I "am not a logging guy". If I'm poking around in a UI while developing, I don't want to cram even more into my logs just to make sure an API call with big chunk of JSON got sent off properly, amidst 30 render statements, 3 or 4 SQL queries, and probably some stuff going in to/out of Redis.
+
+In fact, since I'm already building a webpage, why can't I see it in my browser?
+
+Enter <strong>Log</strong>ging for Stub <strong>Ada</strong>pters: Adalog
+
+
+## We _Can_ Have Nice Things
+
+Adalog really only needs one thing: A repository to put entries into and take them out of. For this purpose, a repository (repo for short) is anything that responds to four messages: `fetch`, `insert`, `clear!`, and `all`.
+
+Adalog even comes with three available repos: `InMemoryRepo`, `PStoreRepo` and `ActiveRecordRepo` which all do exactly what their names suggest.
+
+The Sinatra app has (for now) a single page that lists the output of `Adalog.configuration.repo.all` in reverse chronological order. Ideal for running as its own little service or mounting in a Rails app during in the development environment!
+
+## Example Configuration and Usage
+
+After the usual addition of `gem 'adalog'` to your `Gemfile` and `bundle install` usage can be achieved by the following:
+
+```ruby
+Adalog.configure do |config|
+  # No action needed, however the default repo is a non-threadsafe InMemoryRepo
+end
+
+# Insert something that has a 'title', optionally a 'message' and 'details'
+Adalog.configuration.repo.insert(
+  title:    "StubSendGridAdapter",
+  message:  "Email Sent")
+```
+
+With only one repo in use, Adalog will forward the messages of `insert`, `fetch`, `clear!` and `all` to that one repo. Like so:
+
+```ruby
+Adalog.insert(
+  title:    "StubSendGridAdapter",
+  message:  "Email Sent"
+  details: {
+    to:       "foo@example.com",
+    from:     "bar@example.com",
+    template: "welcome-email"
+  })
+```
+
+The default repos also accept entries with a `timestamp`, which defaults to `Time.now` and a `format` of the `details` attribute to assist in displaying in the Sinatra app's view. The `format` defaults to `'json'`.
+
+Speaking of the app, it can be executed in the usual manner of creating a `config.ru` file:
+
+```ruby
+require 'adalog'
+run Adalog::Web
+```
+
+followed by `rackup` in a terminal. Or, within a Rails app, it can be mounted via `routes.rb` at a particular path:
+
+```ruby
+YourApp::Application.routes.draw do
+
+  unless Rails.env.production?
+    mount Adalog::Web => '/adalog'
+  end
+
+end
+```
+
+Visit the particular URL for the Sinatra standalone or Rails route, and _voilà!_
+
+
+## Configuration Options
+
+Actually, that _"voilà!"_ might have been a little underwhelming. The default `InMemoryRepo` is blank upon each boot (it is in-memory, after all) so the default configuration won't show anything initially. Specifying a different repository will fix that. It is one configuration option among the following:
+
+- **repo:** The repository to store and retreive from. Defaults to `Adalog::InMemoryRepo`.
+- **singleton:** Whether or not to add class methods to the root `Adalog` module to access a singular repo. Defaults to `true`.
+- **time_format:** the `strftime` format string to use when displaying dates in the app's views. Defaults to `"%H:%M:%S - %d %b %Y"`.
+- **web_heading:** the title of the heading in the app's views.
+- **erb_layout:** _(not yet implemented)_ set the layout for the app's views.
+- **views_folder:** _(not yet implemented)_ specify a custom views folder for the Sinatra app if you feel like rolling your own entirely new version of the front-end.
+
+As an example, here is a configuration that uses a threadsafe PStore to persist the log entries, changes the time formatting, and sets a custom heading:
+
+```ruby
+Adalog.configure do |config|
+  pstore_file         = "log/adalog-#{ENV['RACK_ENV']}.pstore"
+  config.repo         = Adalog::PStoreAdapter.new(pstore_file)
+  config.time_format  = "%b %d %H:%M:%S"
+  config.web_heading  = "Poor Richard's Third Party API Calls"
+end
+```
+
+And now if, in the course of building out your application, you can make an adapter which simply calls out to `Adalog.insert` with its data rather than a non-sandboxed third-party service, and you can validate "success" (insofar as your local code succeeded) by visiting a web page instead of checking a logfile!
+
+
+## Included Adapters
+
+Much like how useful repositories come built-in, there are also basic adapters included in the project. Presently the only included adapter that saves you from writing your own, is `SimpleLoggingAdapter`, which uses `method_missing` to write entries for every method call made on it. For example:
+
+```ruby
+# After configuring Adalog
+adapter = Adalog::SimpleLoggingAdapter.new("StubMoosendAdapter", Adalog.repo)
+adapter.unsubscribe_email('baz@example.com')
+```
+
+And now `Adalog.repo` contains the entry:
+```ruby
+{ title:      "StubMoosendAdapter",
+  timestamp:  "...",
+  message:    "unsubscribe_email",
+  details:    "['baz@example.com']",
+  format:     "json"
+}
+```
+
+Although one would obviously want to use a more dependency-injection-esque style when choosing `Adalog::SimpleLoggingAdapter` over whatever the production-mode default adapter is for the service in question.
+
+## Project Status and Goals
+
+This project adheres to [Semantic Versioning](http://semver.org/), including the part whereby being pre-1.0 means that all bets are off, code can and will change radically, and that it should not be considered "production-ready" until said time as version `1.0.0` is declared.
+
+This library is being test-driven by its inclusion within a functioning production application, so rest assured it will get there soon enough. In the mean time, feedback is welcome. Bug reports about functionality that the README claims works but doesn't is welcome. But so as not to distract from the original goals, contributions in the form of pull requests will languish until the project's initial functionality is completed.
+
+
+### Remaining Work Prior to 1.0.0
+
+- Customization of ERB Layout.
+- Customization of Sinatra Layout.
+- Time formats that allow for strictly numeric time or even string-based logical time.
+- A quick script to color-code entries with the same title.
+- Implementations for `InMemoryRepo#fetch` and `PStoreRepo#fetch`.
+- Tests for the three built-in repository classes.
+- A `StubLoggingAdapter` which can be pre-programmed with responses to certain messages.
+- A `MockLoggingAdapter` which can be pre-programmed with responses to certain messages and asked to enforce that some messages were received.
+- A method (working name `MultiWeb`) to allow multiple Sinatra apps to be generated, in case one wants to have a separate route-and-repo combination for every adapter.
+

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs        << "test"
+  t.test_files  = Dir[File.join(File.dirname(__FILE__), 'test/**/*test.rb')]
+end

data/adalog.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'adalog/version'
+
+Gem::Specification.new do |spec|
+  spec.name           = "adalog"
+  spec.version        = Adalog::VERSION
+  spec.platform       = Gem::Platform::RUBY
+  spec.authors        = ["Paul Kwiatkowski"]
+  spec.email          = ["paul@groupraise.com"]
+  spec.summary        = %q{A not-quite logger, with several storage methods. Records occurrences, provides a web app for viewing entries.}
+  spec.description    = %q{A not-quite logger, with several storage methods. Records occurrences, provides a web app for viewing entries. Motivated by the need to record the actions of stubbed-out versions of adapters to third-party services, and for that record to be something other than a traditional logger. Web viewer is built in Sinatra and so can be run standalone via the usual methods or mounted at some route within a Rails app. Comes with three repository implementations for storing/retrieving entries and is trivial to write your own.}
+  spec.homepage       = "https://github.com/swifthand/adalog"
+  spec.license        = "Revised BSD, see LICENSE.md"
+
+  spec.files          = `git ls-files -z`.split("\x0")
+  spec.test_files     = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths  = ["lib"]
+
+  spec.add_runtime_dependency "sinatra", "~> 1.4", ">= 1.4.4"
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest-reporters", "~> 1.1"
+  spec.add_development_dependency "turn-again-reporter", "~> 1.1", ">= 1.1.0"
+end

data/lib/adalog/active_record_repo.rb

@@ -0,0 +1,62 @@
+module Adalog
+  class ActiveRecordRepo
+
+    attr_reader :record_class, :base_relation
+
+    def initialize(record_class, **repo_options)
+      @record_class   = record_class
+      @base_relation  = determine_base_relation(repo_options)
+    end
+
+
+    def fetch(**options)
+      where_options = options.fetch(:where, {})
+      order_options = options.fetch(:order, :none)
+      relation = relation_from_options(where_options, order_options)
+      if options[:first]
+        relation.first(options[:first])
+      elsif options[:last]
+        relation.last(options[:last])
+      else
+        relation.to_a
+      end
+    end
+
+
+    def insert(attr_hash = {}, **attr_args)
+      attrs   = attr_hash.merge(attr_args)
+      record  = record_class.new(**attrs)
+      if record.valid?
+        if record.save
+          [:ok, record]
+        else
+          wtf = "Unknown Non-validation error in call to #{record_class}#save"
+          [:error, [wtf]]
+        end
+      else
+        [:error, record.errors.full_messages]
+      end
+    end
+
+
+    def all
+      record_class.all.to_a
+    end
+
+
+  private ########################################################################
+
+
+    def relation_from_options(where, order)
+      relation = base_relation.dup
+      relation = relation.where(where) if where.any?
+      relation = relation.order(order) if order != :none
+    end
+
+
+    def determine_base_relation(options)
+      options.fetch(:base_relation, record_class.unscoped)
+    end
+
+  end
+end

data/lib/adalog/configuration.rb

@@ -0,0 +1,46 @@
+module Adalog
+
+  class Configuration
+
+    RequiredSettings  = [:repo, :singleton, :html_erb, :time_format, :web_heading].freeze
+    UntouchedValue    = Object.new.freeze
+
+    attr_accessor *RequiredSettings
+
+    def initialize
+      defaults.each_pair do |attr, value|
+        self.send("#{attr}=", value)
+      end
+    end
+
+
+    def defaults
+      { repo:         Adalog::InMemoryRepo.new,
+        singleton:    true,
+        html_erb:     true,
+        time_format:  "%H:%M:%S - %d %b %Y",
+        web_heading:  "Stub Adapter Logs",
+      }
+    end
+
+
+    def web_defaults
+      { repo:         self.repo,
+        time_format:  self.time_format,
+        heading:      self.web_heading,
+      }
+    end
+
+
+    def validate!
+      RequiredSettings.each do |required_attr|
+        if UntouchedValue == self.send(required_attr)
+          raise "Setting '#{required_attr}' for Adalog left unconfigured."
+        end
+      end
+    end
+
+
+  end
+
+end

data/lib/adalog/entry.rb

@@ -0,0 +1,85 @@
+require 'time'
+require 'date'
+
+module Adalog
+  class Entry
+
+    def self.build(obj = nil, **options)
+      arguments =
+        if nil == obj
+          options
+        elsif obj.is_a?(Hash) || obj.respond_to?(:[])
+          obj
+        elsif obj.respond_to?(:to_h)
+          obj.to_h.merge(options)
+        else
+          { title:      obj.respond_to?(:title)     && obj.title,
+            timestamp:  obj.respond_to?(:timestamp) && obj.timestamp,
+            message:    obj.respond_to?(:message)   && obj.message,
+            details:    obj.respond_to?(:details)   && obj.details,
+            format:     obj.respond_to?(:format)    && obj.format,
+          }.merge(options)
+        end
+
+      self.new(
+        title:      arguments[:title]     || arguments['title'],
+        timestamp:  arguments[:timestamp] || arguments['timestamp'],
+        message:    arguments[:message]   || arguments['message'],
+        details:    arguments[:details]   || arguments['details'],
+        format:     arguments[:format]    || arguments['format'],
+      )
+    end
+
+    attr_reader :title, :timestamp, :message, :details, :errors
+
+    def initialize(title: nil, timestamp: nil, message: nil, details: nil, format: nil)
+      @title      = title     || ''
+      @timestamp  = timestamp || Time.now
+      @message    = message   || ''
+      @details    = details   || ''
+      @format     = format    || 'json'
+      validate!
+    end
+
+
+    def valid?
+      @errors.none?
+    end
+
+    ##
+    # TODO: Make this something we store and/or can override.
+    def format
+      :json
+    end
+
+
+    def details_blank?
+      blank?(details)
+    end
+
+
+  private ######################################################################
+
+
+    def validate!
+      @errors = []
+      errors << content_error if no_content?
+    end
+
+
+    def content_error
+      "Must have at least one of: 'title', 'message', 'details'."
+    end
+
+
+    def no_content?
+      blank?(title) && blank?(message) && blank?(details)
+    end
+
+
+    def blank?(val)
+      nil == val || '' == val
+    end
+
+  end
+end

data/lib/adalog/in_memory_repo.rb

@@ -0,0 +1,38 @@
+module Adalog
+  class InMemoryRepo
+
+    attr_reader :storage
+
+    def initialize(**repo_options)
+      @storage = Array.new
+    end
+
+
+    def fetch(**options)
+      all
+    end
+
+
+    def insert(entry = nil, **options)
+      converted_entry = Adalog::Entry.build(entry = nil, **options)
+      if converted_entry.valid?
+        storage.unshift(converted_entry)
+        [:ok, converted_entry]
+      else
+        [:error, converted_entry.errors]
+      end
+    end
+
+
+    def clear!
+      @storage = Array.new
+      :ok
+    end
+
+
+    def all
+      storage.dup
+    end
+
+  end
+end

data/lib/adalog/pstore_repo.rb

@@ -0,0 +1,62 @@
+require 'pstore'
+
+module Adalog
+  class PStoreRepo
+
+    attr_reader :storage
+
+    def initialize(path, **repo_options)
+      @storage  = PStore.new(path, true)
+    end
+
+
+    def fetch(**options)
+      all
+    end
+
+
+    def all
+      storage.transaction do
+        storage.roots.flat_map do |key|
+          storage.fetch(key, [])
+        end
+      end.reverse
+    end
+
+
+    def insert(entry = nil, **options)
+      converted_entry = Adalog::Entry.build(entry, **options)
+      if converted_entry.valid?
+        insert_into_storage(converted_entry)
+        [:ok, converted_entry]
+      else
+        [:error, converted_entry.errors]
+      end
+    end
+
+
+    def clear!
+      storage.transaction do
+        all_keys = storage.roots
+        all_keys.each do |key|
+          storage.delete(key)
+        end
+      end
+      :ok
+    end
+
+
+  private ######################################################################
+
+
+    def insert_into_storage(entry)
+      storage.transaction do
+        key   = Time.now.to_i
+        list  = storage.fetch(key, [])
+        list.unshift(entry)
+        storage[key] = list
+      end
+    end
+
+  end
+end

data/lib/adalog/simple_logging_adapter.rb

@@ -0,0 +1,21 @@
+module Adalog
+  class SimpleLoggingAdapter
+
+    attr_reader :service_name, :repo
+
+    def initialize(service_name, repo)
+      @service_name = service_name
+      @repo         = repo
+    end
+
+    ##
+    # TODO: Record something w.r.t. whether or not a block is given?
+    def method_missing(msg, *args, &block)
+      repo.insert(
+        title:    service_name,
+        message:  msg,
+        details:  args)
+    end
+
+  end
+end

data/lib/adalog/version.rb

@@ -0,0 +1,3 @@
+module Adalog
+  VERSION = "0.4.0"
+end

data/lib/adalog/web/public/javascripts/adalog.js

@@ -0,0 +1,2 @@
+// A namespace all our own, to guard jealously and puts javascript within.
+var adalog = Object.create(null);

data/lib/adalog/web/public/javascripts/entries-list.js

@@ -0,0 +1,82 @@
+adalog.entriesList = (function(js) {
+
+  var showButtonClass     = '-show-details';
+  var hideButtonClass     = '-hide-details';
+  var detailsContentClass = '-details-content';
+  var toggleDetailsClass  = '-toggle-details';
+
+
+  var init = function init() {
+    js.docReady(function() {
+      formatDetailsJSON();
+      // initVisibilityButtons();
+      initDetailsToggle();
+    });
+  };
+
+
+  var formatDetailsJSON = function formatDetailsJSON() {
+    var detailsElements = document.getElementsByClassName('-format-as-json');
+    js.convertArrayLike(detailsElements).forEach(function(elt) {
+      try {
+        var contentsAsObj = JSON.parse(elt.textContent);
+        elt.textContent   = JSON.stringify(contentsAsObj, null, 2);
+      } catch(exc) {
+        console.log("Failed to parse details of element that was expicitly flagged with '-format-as-json'.");
+      }
+    });
+  };
+
+
+  var initDetailsToggle = function initDetailsToggle() {
+    var detailsToggles  = document.getElementsByClassName(toggleDetailsClass);
+    var detailsRegions  = document.getElementsByClassName(detailsContentClass);
+
+    js.convertArrayLike(detailsToggles).forEach(function(elt) {
+      elt.addEventListener('click', function(evt) {
+        var detailsContent = evt.currentTarget.getElementsByClassName(detailsContentClass)[0];
+        js.eltDisplayToggle(detailsContent, 'block');
+      })
+    });
+
+    js.convertArrayLike(detailsRegions).forEach(js.eltHide);
+  };
+
+
+  var initVisibilityButtons = function initVisibilityButtons() {
+    var showButtons     = document.getElementsByClassName(showClass);
+    var hideButtons     = document.getElementsByClassName(hideClass);
+    var detailsRegions  = document.getElementsByClassName(detailsContentClass);
+    var initiallyHidden = js.convertArrayLike(detailsRegions).concat(js.convertArrayLike(hideButtons));
+
+    // Click events for show buttons show content, show a hide button and hide themselves.
+    js.convertArrayLike(showButtons).forEach(function(elt) {
+      elt.addEventListener('click', function(evt) {
+        var hideSibling = js.findSiblingByClassName(evt.currentTarget, hideClass);
+        var details     = js.findSiblingByClassName(evt.currentTarget, detailsContentClass);
+        js.eltShowBlock(details);
+        js.eltShowILBlock(hideSibling);
+        js.eltHide(evt.currentTarget);
+      });
+    });
+
+    // Click events for hide buttons hide content, show a show button and hide themselves.
+    js.convertArrayLike(hideButtons).forEach(function(elt) {
+      elt.addEventListener('click', function(evt) {
+        var showSibling = js.findSiblingByClassName(evt.currentTarget, showClass);
+        var details     = js.findSiblingByClassName(evt.currentTarget, detailsContentClass);
+        js.eltHide(details);
+        js.eltShowBlock(showSibling);
+        js.eltHide(evt.currentTarget);
+      });
+    });
+
+    initiallyHidden.forEach(js.eltHide);
+  };
+
+
+  return {
+    'init': init
+  };
+
+})(adalog.vanillaJS);