aether_observatory 0.0.1pre4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61d7e1ed3ada76ff7ac750bc1a617c90a3280f53468ca76e33e77be8bbc14a4b
+  data.tar.gz: c218497df0007226254a4bdea92856247d60ece8ef6738e541b08b499ffbd6cf
+SHA512:
+  metadata.gz: 7a6067081b5a3c1a98fb968d228e003a352132ee909dc6488a45d978626a065202ca72547ee203eae5ca57106a9bc46b55afde8498aac2ac8a44b38fa599858c
+  data.tar.gz: bcf7b0ef815d37ea110cb0996e8be8afe5612235b8857df27412b06dbde2470d1f9fc9c1925dbd881de3dfdc4f862166ea724925d03a08ef0a989a3ff8e878a4

data/.rubocop.yml

@@ -0,0 +1,17 @@
+require:
+  - rubocop-powerhome
+
+AllCops:
+  TargetRubyVersion: 3.0
+
+Metrics/MethodLength:
+  Exclude:
+    - spec/**/*_spec.rb
+
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - 'gemfiles/*'
+
+Bundler/OrderedGems:
+  Exclude:
+    - 'gemfiles/*'

data/Appraisals

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+appraise "rails-6-0" do
+  gem "rails", "~> 6.0.6"
+end
+
+appraise "rails-6-1" do
+  gem "rails", "~> 6.1.7"
+end
+
+appraise "rails-7-0" do
+  gem "rails", "~> 7.0.8"
+end
+
+appraise "rails-7-1" do
+  gem "rails", "~> 7.1.3"
+end

data/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rubocop-powerhome", path: "../rubocop-powerhome"

data/Rakefile

@@ -0,0 +1,26 @@
+#!/usr/bin/env rake
+
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new(:rubocop)
+
+require "yard"
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
+  t.options = [
+    "--no-private",
+  ]
+end
+
+task default: %i[rubocop spec]

data/aether_observatory.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "lib/aether_observatory/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "aether_observatory"
+  spec.version = AetherObservatory::VERSION
+  spec.authors = ["Terry Finn", "Justin Stanczak"]
+  spec.email = ["terry.finn@powerhrg.com", "justin.stanczak@powerhrg.com"]
+
+  spec.summary = "Aether Observatory"
+  spec.description = "Aether Observatory provides an event broadcast system."
+  spec.homepage = "https://github.com/powerhome/power-tools"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/packages/aether_observatory/docs/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activemodel", ">= 6.0.6.1"
+  spec.add_dependency "activesupport", ">= 6.0.6.1"
+  spec.add_development_dependency "appraisal", "~> 2.5.0"
+
+  spec.add_development_dependency "bundler", "~> 2.1"
+  spec.add_development_dependency "license_finder", "~> 7.0"
+  spec.add_development_dependency "pry", ">= 0.14"
+  spec.add_development_dependency "pry-byebug", "3.10.1"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "simplecov", "0.15.1"
+  spec.add_development_dependency "yard", "0.9.21"
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/doc/dependency_decisions.yml

@@ -0,0 +1,3 @@
+---
+- - :inherit_from
+  - https://raw.githubusercontent.com/powerhome/oss-guide/master/license_rules.yml

data/docs/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.0.1] - 2024-12-06
+
+- Extracts AetherObservatory from Talkbox engine.

data/docs/README.md

@@ -0,0 +1,368 @@
+# AetherObservatory Guide
+
+In this guide we are going to walk through example code to illustrate the
+usage of the `AetherObservatory::`. When finished you will have a class to
+create events and a class that subscribes to those events.
+
+#### Table of Contents
+- [Creating Events](#creating-events)
+- [Creating an Observer and Subscribing to Events](#creating-an-observer-and-subscribing-to-events)
+- [Sending an Event to your Observer](#sending-an-event-to-your-observer)
+- [Stopping Observers](#stopping-observers)
+- [Using Dynamic Event Names](#using-dynamic-event-names)
+- [Multiple Event Topics](#multiple-event-topics)
+
+## Creating Events
+
+To begin create an `ApplicationEvent` class that extends the
+`AetherObservatory::EventBase` class. Next configure a prefix for event
+names using `event_prefix`. This is optional, but encouraged to help prevent
+naming collisions with other domains. Every domain event we define as a
+sub-class to the `ApplicationEvent` will inherit this prefix.
+
+```ruby
+module AetherObservatory
+  module Examples
+    class ApplicationEvent < AetherObservatory::EventBase
+      event_prefix 'talkbox'
+    end
+  end
+end
+```
+
+Next we create an event class called `ExampleEvent` that extends our
+`ApplicationEvent`. In this class we define the topic we would like our
+event sent to using the `event_name` method. Lastly we will define our
+data using the `attribute` method.
+
+```ruby
+module AetherObservatory
+  module Examples
+    class ExampleEvent < AetherObservatory::Examples::ApplicationEvent
+      event_name 'example1'
+
+      attribute :message
+      attribute :timestamp, default: -> { Time.current }
+    end
+  end
+end
+```
+
+Now we have a class to create new events. Each time you create a new event,
+it will be sent to each topic you added via the `event_name` method.
+
+```ruby
+AetherObservatory::Examples::ExampleEvent.create(message: 'hello world')
+```
+
+Running the command above will display a log message like you see below.
+
+```irb
+irb(main):018:0> AetherObservatory::Examples::ExampleEvent.create(message: 'hello world')
+[AetherObservatory::Examples::ExampleEvent] Create event for topic: [talkbox.example1]
+=> nil
+irb(main):019:0> 
+```
+
+Now that we have an `ExampleEvent` class to create events we need to create
+an observer to listen for those events.
+
+<div align="right">
+  <a href="#aetherobservatory-guide">Top</a>
+</div>
+
+## Creating an Observer and Subscribing to Events
+
+Our new event class `ExampleEvent` creates a new event on the
+`talkbox.example1` topic so this is the topic we need to create a observer for.
+
+We start by creating another class called `ExampleObserver` that extends
+the `AetherObservatory::ObserverBase` class. Next we use the `subscribe_to`
+method to register this observer to the topic `talkbox.example1`. We also
+need to define a `process` method that will be called each time your observer
+receives an event. In this `process` method you have access to `event_payload`
+and `event_name` objects for your own logic.
+
+```ruby
+module AetherObservatory
+  module Examples
+    class ExampleObserver < AetherObservatory::ObserverBase
+      subscribe_to 'talkbox.example1'
+
+      def process
+        puts <<-EVENT
+          ************************************
+          Event processed:
+          Name: #{event_name.inspect}
+          Message: #{event_payload.message}
+          Timestamp: #{event_payload.timestamp}
+          Event Payload: #{event_payload.inspect}
+          ************************************
+        EVENT
+      end
+    end
+  end
+end
+```
+Now that we have a new observer named `ExampleObserver`, we will need to
+start our observer before it will process any events. Observers default
+to `stopped`, so we need to call `start` on each observer before they will
+recieve events. Inside an initilizer is the recommended location to start
+your observers.
+
+```ruby
+AetherObservatory::Examples::ExampleObserver.start
+```
+
+<div align="right">
+  <a href="#aetherobservatory-guide">Top</a>
+</div>
+
+## Sending an Event to your Observer
+
+Now that you have all your classes created you can send events to your
+observer via the `create` method.
+
+```ruby
+AetherObservatory::Examples::ExampleEvent.create(message: 'hello world')
+```
+
+Calling create on your `ExampleEvent` class will trigger the `process`
+method in the `ExampleObserver` class. You should see the following logged
+output.
+
+```irb
+irb(main):040:0> AetherObservatory::Examples::ExampleEvent.create(message: 'hello world')
+  ************************************
+  Event processed:
+  Name: "talkbox.example1"
+  Message: hello world
+  Timestamp: 2024-05-23 15:17:16 UTC
+  Event Payload: #<AetherObservatory::Examples::ExampleEvent:0x0000aaaadc2b2118 @attributes=#<ActiveModel::AttributeSet:0x0000aaaadc2b1f38 @attributes={"message"=>#<ActiveModel::Attribute::FromUser:0x0000aaaadc2b1fb0 @name="message", @value_before_type_cast="hello world", @type=#<ActiveModel::Type::Value:0x0000aaaadc101d28 @precision=nil, @scale=nil, @limit=nil>, @original_attribute=#<ActiveModel::Attribute::WithCastValue:0x0000aaaadc2b2dc0 @name="message", @value_before_type_cast=nil, @type=#<ActiveModel::Type::Value:0x0000aaaadc101d28 @precision=nil, @scale=nil, @limit=nil>, @original_attribute=nil>, @value="hello world">, "timestamp"=>#<ActiveModel::Attribute::UserProvidedDefault:0x0000aaaadc2b1f60 @user_provided_value=#<Proc:0x0000aaaadc0f3b38 (irb):15 (lambda)>, @name="timestamp", @value_before_type_cast=#<Proc:0x0000aaaadc0f3b38 (irb):15 (lambda)>, @type=#<ActiveModel::Type::Value:0x0000aaaadc0f3ac0 @precision=nil, @scale=nil, @limit=nil>, @original_attribute=nil, @memoized_value_before_type_cast=Thu, 23 May 2024 15:17:16.082153128 UTC +00:00, @value=Thu, 23 May 2024 15:17:16.082153128 UTC +00:00>}>>
+  ************************************
+[AetherObservatory::Examples::ExampleEvent] Create event for topic: [talkbox.example1]
+=> nil
+```
+
+<div align="right">
+  <a href="#aetherobservatory-guide">Top</a>
+</div>
+
+## Stopping Observers
+
+To stop your observer from processing events you can call the `stop` method
+on your observer class. This stops only that observer class from processing
+events.
+
+```ruby
+AetherObservatory::Examples::ExampleObserver.stop
+```
+
+<div align="right">
+  <a href="#aetherobservatory-guide">Top</a>
+</div>
+
+## Using Dynamic Event Names
+
+Create a new class called `RandomEvent` that extends `ApplicationEvent`.
+Then pass a block to the `event_name` method. This allows you to dynamiclly
+select your topic at the time of event creation.
+
+<sup>*Note: [ApplicationEvent](#creating-events) class was created at the
+beginning of this guide.*</sup>
+
+```ruby
+module AetherObservatory
+  module Examples
+    class RandomEvent < AetherObservatory::Examples::ApplicationEvent
+      event_name { select_a_topic_at_random }
+
+      attribute :message
+
+    private
+
+      def select_a_topic_at_random
+        %w(test support customer).sample
+      end
+    end
+  end
+end
+```
+
+You can now create a few events with your new class using the `create`
+method of that class.
+
+```ruby
+AetherObservatory::Examples::RandomEvent.create(message: 'hello world')
+```
+
+As you can see from the following output a random event name is selected
+each time you call `create`.
+
+```irb
+irb(main):078:0> AetherObservatory::Examples::RandomEvent.create(message: 'hello world')
+[AetherObservatory::Examples::RandomEvent] Create event for topic: [talkbox.support]
+=> nil
+irb(main):079:0> AetherObservatory::Examples::RandomEvent.create(message: 'hello world')
+[AetherObservatory::Examples::RandomEvent] Create event for topic: [talkbox.test]
+=> nil
+irb(main):080:0> AetherObservatory::Examples::RandomEvent.create(message: 'hello world')
+[AetherObservatory::Examples::RandomEvent] Create event for topic: [talkbox.support]
+=> nil
+irb(main):081:0> AetherObservatory::Examples::RandomEvent.create(message: 'hello world')
+[AetherObservatory::Examples::RandomEvent] Create event for topic: [talkbox.customer]
+=> nil
+```
+
+<div align="right">
+  <a href="#aetherobservatory-guide">Top</a>
+</div>
+
+## Multiple Event Topics
+
+In this example we are going to create an event class that sends events to
+two different topics based on the `level` attribute from the event class.
+We are also going to make two observer classes that subscribe to different
+events based on their role in the system.
+
+<sup>*Note: [ApplicationEvent](#creating-events) class was created at the
+beginning of this guide.*</sup>
+
+We first create the `TalkboxCallQueueEvent` class. This class will send each
+event to the `talkbox.call_queues.events.all` topic and to the `level` scoped
+topic.
+
+```ruby
+module AetherObservatory
+  module Examples
+    class TalkboxCallQueueEvent < AetherObservatory::Examples::ApplicationEvent
+      event_name 'call_queues.events.all'
+      event_name { "call_queues.events.#{level}" }
+
+      attribute :level, default: 'info'
+    end
+  end
+end
+```
+
+The new `TalkboxCallQueueEvent` class will send all events to the `all`
+topic. However the events will also be sent to their specific event `level`
+scoped topic. This allows us to have one observer logging call history and
+a second observer that handles events with the scoped `level` or error for
+topic `talkbox.call_queues.events.error`.
+
+Next we need to create a new class called `TalkboxCallHistoryObserver`. This
+observer will subscribe to the `talkbox.call_queues.events.all` topic. This
+classes function is to record all call queue events. 
+
+```ruby
+module AetherObservatory
+  module Examples
+    class TalkboxCallHistoryObserver < AetherObservatory::ObserverBase
+      subscribe_to 'talkbox.call_queues.events.all'
+
+      delegate :level, to: :event_payload
+
+      def process
+        puts <<-EVENT
+          ************************************
+          Event processed:
+          Name: #{event_name.inspect}
+          Level: #{event_payload.level}
+          Event Payload: #{event_payload.inspect}
+          ************************************
+        EVENT
+      end
+    end
+  end
+end
+```
+
+Next we need a class called `TalkboxCallErrorObserver`. This class only
+subscribes to the `talkbox.call_queues.events.error` topic. It only cares
+about `error` level events and nothing else. 
+
+```ruby
+module AetherObservatory
+  module Examples
+    class TalkboxCallErrorObserver < AetherObservatory::ObserverBase
+      subscribe_to 'talkbox.call_queues.events.error'
+
+      def process
+        puts <<-EVENT
+          ************************************
+          Error Event processed:
+          Name: #{event_name.inspect}
+          Level: #{event_payload.level}
+          Event Payload: #{event_payload.inspect}
+          ************************************
+        EVENT
+      end
+    end
+  end
+end
+```
+
+We need to be sure to start our new observers before they will recieve
+any events.
+
+```ruby
+AetherObservatory::Examples::TalkboxCallHistoryObserver.start
+AetherObservatory::Examples::TalkboxCallErrorObserver.start
+```
+
+Finally we are ready to create a new event and see what happens. First we
+create an event with a default level.
+
+```ruby
+AetherObservatory::Examples::TalkboxCallQueueEvent.create
+```
+
+Running the create with no parameters will have a default level of `info`.
+You will see the following output.
+
+```irb
+irb(main):058:0> AetherObservatory::Examples::TalkboxCallQueueEvent.create
+  ************************************
+  Event processed:
+  Name: "talkbox.call_queues.events.all"
+  Level: info
+  Event Payload: #<AetherObservatory::Examples::TalkboxCallQueueEvent:0x0000aaab112f75d0 @attributes=#<ActiveModel::AttributeSet:0x0000aaab112f5e88 @attributes={"level"=>#<ActiveModel::Attribute::UserProvidedDefault:0x0000aaab112f73a0 @user_provided_value="info", @name="level", @value_before_type_cast="info", @type=#<ActiveModel::Type::Value:0x0000aaab13a76e08 @precision=nil, @scale=nil, @limit=nil>, @original_attribute=nil, @value="info">}>>
+  ************************************
+[AetherObservatory::Examples::TalkboxCallQueueEvent] Create event for topic: [talkbox.call_queues.events.all]
+[AetherObservatory::Examples::TalkboxCallQueueEvent] Create event for topic: [talkbox.call_queues.events.info]
+=> nil
+```
+
+Next we will try creating a new event but this time we set the `level`
+to `error`.
+
+```ruby
+AetherObservatory::Examples::TalkboxCallQueueEvent.create(level: 'error')
+```
+
+As you can see from the output, setting the `level` to `error` will send
+an event to both classes. 
+
+```irb
+irb(main):059:0> AetherObservatory::Examples::TalkboxCallQueueEvent.create(level: 'error')
+  ************************************
+  Event processed:
+  Name: "talkbox.call_queues.events.all"
+  Level: error
+  Event Payload: #<AetherObservatory::Examples::TalkboxCallQueueEvent:0x0000aaab135cff30 @attributes=#<ActiveModel::AttributeSet:0x0000aaab135cfe18 @attributes={"level"=>#<ActiveModel::Attribute::FromUser:0x0000aaab135cfe68 @name="level", @value_before_type_cast="error", @type=#<ActiveModel::Type::Value:0x0000aaab13a76e08 @precision=nil, @scale=nil, @limit=nil>, @original_attribute=#<ActiveModel::Attribute::UserProvidedDefault:0x0000aaab135e0bc8 @user_provided_value="info", @name="level", @value_before_type_cast="info", @type=#<ActiveModel::Type::Value:0x0000aaab13a76e08 @precision=nil, @scale=nil, @limit=nil>, @original_attribute=nil>, @value="error">}>>
+  ************************************
+[AetherObservatory::Examples::TalkboxCallQueueEvent] Create event for topic: [talkbox.call_queues.events.all]
+  ************************************
+  Error Event processed:
+  Name: "talkbox.call_queues.events.error"
+  Level: error
+  Event Payload: #<AetherObservatory::Examples::TalkboxCallQueueEvent:0x0000aaab135cef90 @attributes=#<ActiveModel::AttributeSet:0x0000aaab135ceea0 @attributes={"level"=>#<ActiveModel::Attribute::FromUser:0x0000aaab135cef40 @name="level", @value_before_type_cast="error", @type=#<ActiveModel::Type::Value:0x0000aaab13a76e08 @precision=nil, @scale=nil, @limit=nil>, @original_attribute=#<ActiveModel::Attribute::UserProvidedDefault:0x0000aaab135e0bc8 @user_provided_value="info", @name="level", @value_before_type_cast="info", @type=#<ActiveModel::Type::Value:0x0000aaab13a76e08 @precision=nil, @scale=nil, @limit=nil>, @original_attribute=nil>, @value="error">}>>
+  ************************************
+[AetherObservatory::Examples::TalkboxCallQueueEvent] Create event for topic: [talkbox.call_queues.events.error]
+=> nil
+```
+
+<div align="right">
+  <a href="#aetherobservatory-guide">Top</a>
+</div>

data/gemfiles/rails_6_0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rubocop-powerhome", path: "../../rubocop-powerhome"
+gem "rails", "~> 6.0.6"
+
+gemspec path: "../"