stenotype 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 714f7d5fce3afe07cb1f49653fc44410ca0570086a310c8aead9b88229981f08
+  data.tar.gz: 7f69e3448a22a9d1094dbab6a783e206ac36a5c22c1eb10db3f25180ce07d167
+SHA512:
+  metadata.gz: 5ac72dfb39d13e86dfee3617cbef85e06dec175541af1ec681298b74c970f0ef54f4e48a434b305778bc49c219604b6d3eeab3d444a9a670a4db8873ad7a0c94
+  data.tar.gz: 399afa50ff49b2b6b163a07345064193f3bdc18cb20719adb55b1ace92b6cafcedf3128f430df033e597836524138bce7f82134671378f113786e7e1f3948fe3

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+/.rakeTasks
+/.idea

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--order rand

data/.rubocop.yml

@@ -0,0 +1,6 @@
+inherit_gem:
+  spicerack-styleguide:
+    - rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 2.6

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.3
+before_install: gem install bundler -v 2.0.2

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+group :development, :test do
+  gem "rspice"
+end
+
+# Specify your gem's dependencies in Stenotype.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,239 @@
+PATH
+  remote: .
+  specs:
+    stenotype (0.1.0)
+      activesupport (>= 5.0.0)
+      google-cloud-pubsub (~> 1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (5.2.3)
+      actionpack (= 5.2.3)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailer (5.2.3)
+      actionpack (= 5.2.3)
+      actionview (= 5.2.3)
+      activejob (= 5.2.3)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (5.2.3)
+      actionview (= 5.2.3)
+      activesupport (= 5.2.3)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.2.3)
+      activesupport (= 5.2.3)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activejob (5.2.3)
+      activesupport (= 5.2.3)
+      globalid (>= 0.3.6)
+    activemodel (5.2.3)
+      activesupport (= 5.2.3)
+    activerecord (5.2.3)
+      activemodel (= 5.2.3)
+      activesupport (= 5.2.3)
+      arel (>= 9.0)
+    activestorage (5.2.3)
+      actionpack (= 5.2.3)
+      activerecord (= 5.2.3)
+      marcel (~> 0.3.1)
+    activesupport (5.2.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    arel (9.0.0)
+    ast (2.4.0)
+    builder (3.2.3)
+    coderay (1.1.2)
+    concurrent-ruby (1.1.5)
+    crass (1.0.5)
+    diff-lcs (1.3)
+    docile (1.3.2)
+    erubi (1.9.0)
+    faker (1.9.6)
+      i18n (>= 0.7)
+    faraday (0.17.0)
+      multipart-post (>= 1.2, < 3)
+    github-markup (3.0.4)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    google-cloud-core (1.4.1)
+      google-cloud-env (~> 1.0)
+    google-cloud-env (1.3.0)
+      faraday (~> 0.11)
+    google-cloud-pubsub (1.0.2)
+      concurrent-ruby (~> 1.1)
+      google-cloud-core (~> 1.2)
+      google-gax (~> 1.7)
+      googleapis-common-protos (>= 1.3.9, < 2.0)
+      grpc-google-iam-v1 (~> 0.6.9)
+    google-gax (1.8.1)
+      google-protobuf (~> 3.9)
+      googleapis-common-protos (>= 1.3.9, < 2.0)
+      googleauth (~> 0.9)
+      grpc (~> 1.24)
+      rly (~> 0.2.3)
+    google-protobuf (3.10.1-universal-darwin)
+    googleapis-common-protos (1.3.9)
+      google-protobuf (~> 3.0)
+      googleapis-common-protos-types (~> 1.0)
+      grpc (~> 1.0)
+    googleapis-common-protos-types (1.0.4)
+      google-protobuf (~> 3.0)
+    googleauth (0.10.0)
+      faraday (~> 0.12)
+      jwt (>= 1.4, < 3.0)
+      memoist (~> 0.16)
+      multi_json (~> 1.11)
+      os (>= 0.9, < 2.0)
+      signet (~> 0.12)
+    grpc (1.25.0-universal-darwin)
+      google-protobuf (~> 3.8)
+      googleapis-common-protos-types (~> 1.0)
+    grpc-google-iam-v1 (0.6.9)
+      googleapis-common-protos (>= 1.3.1, < 2.0)
+      grpc (~> 1.0)
+    i18n (1.7.0)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.4)
+    json (2.2.0)
+    jwt (2.2.1)
+    loofah (2.3.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.3)
+      mimemagic (~> 0.3.2)
+    memoist (0.16.0)
+    method_source (0.9.2)
+    mimemagic (0.3.3)
+    mini_mime (1.0.2)
+    mini_portile2 (2.4.0)
+    minitest (5.12.2)
+    multi_json (1.14.1)
+    multipart-post (2.1.1)
+    nio4r (2.5.2)
+    nokogiri (1.10.4)
+      mini_portile2 (~> 2.4.0)
+    os (1.0.1)
+    parallel (1.18.0)
+    parser (2.6.5.0)
+      ast (~> 2.4.0)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    public_suffix (4.0.1)
+    rack (2.0.7)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (5.2.3)
+      actioncable (= 5.2.3)
+      actionmailer (= 5.2.3)
+      actionpack (= 5.2.3)
+      actionview (= 5.2.3)
+      activejob (= 5.2.3)
+      activemodel (= 5.2.3)
+      activerecord (= 5.2.3)
+      activestorage (= 5.2.3)
+      activesupport (= 5.2.3)
+      bundler (>= 1.3.0)
+      railties (= 5.2.3)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (5.2.3)
+      actionpack (= 5.2.3)
+      activesupport (= 5.2.3)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.19.0, < 2.0)
+    rainbow (3.0.0)
+    rake (10.5.0)
+    redcarpet (3.5.0)
+    rly (0.2.3)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.2)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.2)
+    rspice (0.14.2)
+      faker (~> 1.8)
+      rspec (~> 3.0)
+    rubocop (0.76.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.6)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    ruby-progressbar (1.10.1)
+    signet (0.12.0)
+      addressable (~> 2.3)
+      faraday (~> 0.9)
+      jwt (>= 1.5, < 3.0)
+      multi_json (~> 1.10)
+    simplecov (0.17.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    sprockets (4.0.0)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (0.20.3)
+    thread_safe (0.3.6)
+    timecop (0.9.1)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.6.0)
+    websocket-driver (0.7.1)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.4)
+    yard (0.9.20)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  github-markup (~> 3.0)
+  pry (~> 0.12)
+  rails (~> 5.2.3)
+  rake (~> 10.0)
+  redcarpet (~> 3.5)
+  rspec (~> 3.0)
+  rspice
+  rubocop (~> 0.76)
+  simplecov (~> 0.17)
+  stenotype!
+  timecop (~> 0.9)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.0.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Roman Kapitonov
+
+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,251 @@
+# Stenotype
+
+This gem is a tool providing extensions to several rails components in order to track events along with the execution context. Currently ActionController and ActionJob are supported to name a few.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'Stenotype'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install Stenotype
+
+## Usage
+
+### Configuration
+
+Configuring the library is as simple as:
+```ruby
+Stenotype.configure do |config|
+  config.targets = [ # Supported targets
+    Stenotype::Adapters::StdoutAdapter.new,
+    Stenotype::Adapters::GoogleCloud.new
+  ]
+
+  config.uuid_generator = SecureRandom
+  config.dispatcher     = Stenotype::Dispatcher.new
+  config.gc_project_id  = 'google_cloud_project_id'
+  config.gc_credentials = 'path_to_key_json'
+  config.gc_topic       = 'google_cloud_topic'
+  config.gc_mode        = :async # either :sync or :async
+end
+```
+
+#### config.targets
+
+Contain an array of targets for the events to be published to. Targets must implement method `#publish(event_data, **additional_arguments)`.
+
+#### config.uuid_generator
+
+An object that must implement method `#uuid`. Used when an event is emitted to generate a unique id for each event.
+
+#### config.dispatcher
+
+Dispatcher used to dispatch the event. A dispatcher must implement method `#publish(even, serializer: Stenotype::EventSerializer)`. By default `Stenotype::EventSerializer` is used, which is responsible for collecting the data from the event and evaluation context.
+
+#### config.gc_project_id
+
+Google cloud project ID. Please refer to Google Cloud management console to get one.
+
+#### config.gc_credentials
+
+Google cloud credentials. Might be obtained from Google Cloud management console.
+
+#### config.gc_topic
+
+Google Cloud topic used for publishing the events.
+
+#### config.gc_mode
+
+Google Cloud publish mode. Two options are available: `:sync, :async`. When in `sync` mode the event will be published in the same thread (which might influence performance). For `async` mode the event will be put into a pull which is going to be flushed after a threshold is met.
+
+#### Configuring context handlers
+
+Each event is emitted in a context which might be an ActionController instance or an ActiveJob instance or potentially any other place. Context handlers are implemented as plain ruby classes, so before using them you must register them. By default a plain `Class` handler is registered when not used with any framework. In case Ruby on Rails is used, then there are two additional context handlers for `ActionController` and `ActiveJob` instances.
+
+### Emitting Events
+
+Emitting an event is as simple as:
+```ruby
+Stenotype::Event.emit!(
+    data,
+    options: additional_options,
+    eval_context: { name_of_registered_context_handler: context_object }
+)
+```
+
+The event is then going to be passed to a dispatcher responsible for sending the evens to targets. Note that a context handler must be registered before using it. See [Custom context handlers](#custom-context-handlers) for more details.
+
+#### ActionController
+
+Upon loading the library `ActionController` is going to be extended with a class method `track_view(*actions)`, where `actions` is a list of trackable controller actions.
+
+Here is an example usage:
+
+```ruby
+class MyController < ActionController::Base
+  track_view :index, :show
+
+  def index
+    # do_something
+  end
+
+  def show
+    # do something
+  end
+end
+```
+
+#### ActiveJob
+
+Upon loading the library `ActiveJob` is going to be extended with a class method `trackable_job!`.
+
+Example:
+```ruby
+class MyJob < ActiveJob::Base
+  trackable_job!
+
+  def perform(data)
+    # do_something
+  end
+end
+```
+
+#### Plain Ruby classes
+
+To track methods from arbitrary ruby classes `Object` is extended. Any instance method of a Ruby class might be prepended with sending an event:
+```ruby
+class PlainRubyClass
+  emit_event_before :some_method, :another_method
+  emit_klass_event_before :class_method
+
+  def some_method(data)
+    # do something
+  end
+
+  def another_method(args)
+    # do something
+  end
+
+  def self.class_method
+    # do something
+  end
+end
+```
+
+You could also use a generic method `emit_event` from anywhere. The method is mixed into `Object` class. It takes several optional kw arguments. `data` is a hash which is going to be serialized and sent as event data, `method` is by default the method you trigger `emit_event` from. `eval_context` is a hash containing the name of context handler and a context object itself.
+
+An example usage is as follows (see [Custom context handlers](#custom-context-handlers) for more details.):
+```ruby
+# BaseClass sets some state
+class BaseClass
+  attr_reader :local_state
+
+  def initialize
+    @local_state = 'some state'
+  end
+end
+
+# A custom handler is introduced
+class CustomHandler < Stenotype::ContextHandlers::Base
+  self.handler_name = :overriden_handler
+
+  def as_json(*_args)
+    {
+      state: context.local_state
+    }
+  end
+end
+
+Stenotype::ContextHandlers.register CustomHandler
+
+# Event is being emitted twice. First time with default options.
+# Second time with overriden method name and eval_context.
+class PlainRubyClass < BaseClass
+  def some_method(data)
+    event_data = collect_some_data_as_a_hash
+    emit_event(event_data) # method name will be `some_method`, eval_context: { klass: self }
+    other_event_data = do_something_else
+    emit_event(other_event_data, method: :custom_method_name, eval_context: { overriden_handler: self })
+  end
+end
+```
+
+### Adding customizations
+
+#### Custom adapters
+By default two adapters are implemented: Google Cloud and simple Stdout adapter.
+
+Adding a new one might be performed by defining a class inheriting from `Stenotype::Adapters::Base`:
+```ruby
+class CustomAdapter < Stenotype::Adapters::Base
+  # A client might be optionally passed to
+  # the constructor.
+  #
+  # def initialize(client: nil)
+  #   @client = client
+  # end
+
+  def publish(event_data, **additional_arguments)
+    # custom publishing logic
+  end
+end
+```
+
+After defining a custom adapter it must be added to the list of adapters:
+```ruby
+Stenotype.config.targets.push(CustomAdapter.new)
+```
+
+#### Custom context handlers
+
+A list of context handlers might be extended by defining a class inheriting from `Stenotype::ContextHandlers::Base` and registering a new context handler. Event handler must have a `self.handler_name` in order to use it during context serialization. Also custom handler must implement method `#as_json`:
+```ruby
+class CustomHandler < Stenotype::ContextHandlers::Base
+  self.handler_name = :custom_handler_name
+
+  def as_json(*_args)
+    {
+      something: something,
+      another: another
+    }
+  end
+
+  private
+
+  def something_from_context
+    context.something
+  end
+
+  def another_from_context
+    context.another
+  end
+end
+```
+
+After defining a new context handler you must register it as follows:
+```ruby
+Stenotype::ContextHandlers.register CustomHandler
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Freshly/Stenotype.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/TODO.md

@@ -0,0 +1,17 @@
+# Stenotype TODO list
+
+ - [x] Figure out how to pass context to data publisher. **Context is passed explicitly**
+ - [x] Switch from synchronous to asynchronous message publishing. **A config option for this is available**
+ - [x] Figure out how to unwind from using a specific framework (e.g Rails), but rather implement events in a general way suitable for plain ruby classes. **Event emitters inject in dynamic way based on what framework the gem is being used in.**
+ - [x] Infer data in extensible way. Given a common context implement context handlers capable of fetching data for specific cases (Controller, ActiveJobs, Models, etc.). **Context handlers are introduced. New handlers might be implemented and registered easily**
+ - [x] Figure out the most common default context handlers (Controller, something else). **Controller, ActiveJob and Plain ruby classes are the case now**
+ - [x] Develop an extensible schema for formatting the messages. **A serializer is introduced**
+ - [x] Cover the existing code with specs. **Coverage increased to 100%**
+ - [ ] Consider using batch publishing in case the load is high (how do we measure this, perhaps rpm?)
+ - [ ] Consider using JSON schema to validate the input for publisher
+ - [ ] Consider enabling an option to publish to multiple topics. Do we need to publish to multiple topics?
+ - [ ] Consider adding state to message dispatcher and instantiate it on every event
+ - [ ] Consider using `::ActiveJob::Base.around_perform` or `::ActiveJob::Base.around_enqueue` in case we need to track all jobs.
+ - [ ] Figure out the params for plain ruby class context handler.
+ - [ ] Consider `ContextHandlers::ActiveJob` params. How to deal with \_args? It won't necessarily respond to `#as_json`.
+ - [ ] Consider a way to switch from evaluating ruby code to using plain modules extension.

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'stenotype'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'pry'
+Pry.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/stenotype/adapters/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Stenotype
+  #
+  # A namespace containing implementations of various adapters
+  # for publishing events to various destinations.
+  # e. g. (Google Cloud, Kafka, Stdout, other)
+  #
+  module Adapters
+    #
+    # An abstract base class for implementing adapters
+    #
+    # @abstract
+    #
+    class Base
+      attr_reader :client
+
+      #
+      # @return {#publish} An adapter implementing method [#publish]
+      #
+      def initialize(client: nil)
+        @client = client
+      end
+
+      #
+      # This method is expected to be implemented by subclasses
+      # @abstract
+      # @raise [NotImplementedError] unless implemented in a subclass
+      #
+      def publish(_event_data, **_additional_arguments)
+        raise NotImplementedError,
+              "#{self.class.name} must implement method #publish"
+      end
+    end
+  end
+end