observability 0.1.0

data/spec/observability/sender/logger_spec.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../../spec_helper'
+
+require 'observability/sender/logger'
+require 'observability/event'
+
+
+describe Observability::Sender::Logger do
+
+	it "sends events to its own logger" do
+		sender = described_class.new
+		sender.start
+
+		event = Observability::Event.new( 'acme.engine.start' )
+
+		log = []
+		Loggability.outputting_to( log ).formatted_with( :default ).with_level( :debug ) do
+			sender.enqueue( event )
+		end
+		sender.stop
+
+		# Race to find the log
+		expect( log ).to include( a_string_matching(/acme\.engine\.start/) )
+	end
+
+end
+

data/spec/observability/sender/udp_spec.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../../spec_helper'
+
+require 'observability/sender/udp'
+
+
+describe Observability::Sender::UDP do
+
+	before( :all ) do
+		described_class.configure( host: 'localhost', port: 8787 )
+	end
+
+	after( :all ) do
+		described_class.configure
+	end
+
+
+	let( :udp_socket ) { instance_double(UDPSocket) }
+	let( :executor ) do
+		instance_double( Concurrent::SingleThreadExecutor, :auto_terminate= => nil )
+	end
+
+	before( :each ) do
+		allow( UDPSocket ).to receive( :new ).and_return( udp_socket )
+		allow( Concurrent::SingleThreadExecutor ).to receive( :new ).and_return( executor )
+	end
+
+
+	it "sends events via a UDP socket" do
+		event = Observability::Event.new( 'acme.engine.startup' )
+
+		expect( executor ).to receive( :post ) do |*args, &block|
+			block.call( *args )
+		end
+		expect( udp_socket ).to receive( :connect ).with( 'localhost', 8787 )
+		expect( udp_socket ).to receive( :sendmsg_nonblock ) do |msg, flags, **opts|
+			expect( msg ).to match( /\{.*"@type":"acme\.engine\.startup".*\}/ )
+			expect( flags ).to eq( 0 )
+			expect( opts ).to include( exception: false )
+			msg.bytesize
+		end
+
+		sender = described_class.new
+		sender.start
+		sender.enqueue( event )
+	end
+
+
+	it "retries if writing would block" do
+		event = Observability::Event.new( 'acme.engine.startup' )
+		blocked_once = false
+
+		expect( executor ).to receive( :post ) do |*args, &block|
+			block.call( *args )
+		end
+		expect( udp_socket ).to receive( :connect ).with( 'localhost', 8787 )
+		expect( udp_socket ).to receive( :sendmsg_nonblock ) do |msg, flags, **opts|
+			if !blocked_once
+				blocked_once = true
+				:wait_writable
+			elsif msg.bytesize > 5
+				5
+			else
+				msg.bytesize
+			end
+		end.at_least( 2 ).times
+		expect( IO ).to receive( :select ).with( nil, [udp_socket], nil ).
+			and_return( nil, [udp_socket], nil ).
+			once
+
+		sender = described_class.new
+		sender.start
+		sender.enqueue( event )
+	end
+
+
+	it "shuts down the socket when it stops" do
+		expect( udp_socket ).to receive( :shutdown ).with( :WR )
+
+		sender = described_class.new
+		sender.stop
+	end
+
+end
+

data/spec/observability/sender_spec.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../spec_helper'
+
+require 'observability/sender'
+require 'observability/sender/testing'
+require 'observability/event'
+
+
+describe Observability::Sender do
+
+	after( :all ) do
+		described_class.configure
+	end
+
+	before( :each ) do
+		described_class.configure
+	end
+
+
+	it "is an abstract class" do
+		expect {
+			described_class.new
+		}.to raise_error( NoMethodError, /private method `new'/i )
+	end
+
+
+	it "can create an instance of the configured type of sender" do
+		described_class.configure( type: :testing )
+		expect( described_class.configured_type ).to be_a( Observability::Sender::Testing )
+	end
+
+
+	context "concrete subclasses" do
+
+		let( :subclass ) do
+			Class.new( described_class ) do
+				def initialize( * )
+					super
+					@sent = []
+				end
+				attr_reader :sent
+				def send_event( ev )
+					@sent << ev
+				end
+			end
+		end
+
+		let( :instance ) do
+			subclass.new
+		end
+
+
+		it "sends events after it's started" do
+			events = 12.times.map { Observability::Event.new('acme.windowwasher.refill') }
+
+			instance.start
+			instance.enqueue( *events ).wait( 0.5 )
+			instance.stop
+
+			expect( instance.sent ).to contain_exactly( *(events.map(&:resolve)) )
+		end
+
+
+		it "drops events if it hasn't been started yet" do
+			events = 8.times.map { Observability::Event.new('acme.windowwasher.refill') }
+
+			instance.enqueue( *events ).wait( 0.5 )
+
+			expect( instance.sent ).to be_empty
+		end
+
+
+	end
+
+end
+

data/spec/observability_spec.rb

@@ -0,0 +1,132 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require_relative 'spec_helper'
+
+require 'rspec'
+require 'observability'
+require 'observability/observer'
+
+
+describe Observability do
+
+	before( :all ) do
+		@real_hook_mods = Observability.observer_hooks
+		Observability.instance_variable_set( :@observer_hooks, Concurrent::Map.new )
+	end
+
+	before( :each ) do
+		Observability.reset
+		Observability.observer_hooks.keys.each {|key| Observability.observer_hooks.delete(key) }
+	end
+
+	after( :all ) do
+		Observability.instance_variable_set( :@observer_hooks, @real_hook_mods )
+	end
+
+
+	it "can create a singleton observer" do
+		result = described_class.observer
+		expect( result ).to be_a( Observability::Observer )
+	end
+
+
+	it "doesn't race to create the singleton observer" do
+		val1 = Thread.new { described_class.observer }.value
+		val2 = Thread.new { described_class.observer }.value
+
+		expect( val1 ).to be( val2 )
+	end
+
+
+	it "tracks the hook modules of all extended modules" do
+		new_mod = Module.new
+		new_mod.extend( described_class )
+		expect( described_class.observer_hooks.keys ).to include( new_mod )
+		expect( described_class.observer_hooks[new_mod] ).to be_a( Module )
+	end
+
+
+	it "tracks the hook modules of the singleton classes of all extended modules" do
+		new_mod = Module.new
+		new_mod.extend( described_class )
+		s_class = new_mod.singleton_class
+		expect( described_class.observer_hooks.keys ).to include( s_class )
+		expect( described_class.observer_hooks[s_class] ).to be_a( Module )
+	end
+
+
+	it "provides a way to look up the hooks module for an extended module" do
+		new_mod = Module.new
+		new_mod.extend( described_class )
+
+		expect( described_class[new_mod] ).to be( described_class.observer_hooks[new_mod] )
+	end
+
+
+	it "provides a way to look up the hooks module via an instance of an extended class" do
+		new_class = Class.new
+		new_class.extend( described_class )
+
+		instance = new_class.new
+
+		expect( described_class[instance] ).to be( described_class.observer_hooks[new_class] )
+	end
+
+
+	describe "an including class" do
+
+		let( :observed_class ) do
+			the_class = Class.new do
+
+				def self::name
+					return "TestClass"
+				end
+
+				@class_things_done = 0
+				def self::do_a_class_thing
+					@class_things_done += 1
+				end
+
+				def initialize
+					@things_done = 0
+				end
+
+				attr_accessor :things_done
+
+				def do_a_thing
+					self.things_done += 1
+				end
+			end
+
+			the_class.extend( described_class )
+			return the_class
+		end
+
+
+		it "can decorate instance methods with observation" do
+			observed_class.observe_method( :do_a_thing )
+			object = observed_class.new
+
+			expect {
+				object.do_a_thing
+			}.to emit_event( "test_class.do_a_thing" )
+		end
+
+
+		it "can decorate class methods with observation" do
+			observed_class.observe_class_method( :do_a_class_thing )
+
+			# :FIXME: I want this to be the ID of the observed class instead, but
+			# I haven't figured out how to do this yet.
+			id = observed_class.singleton_class.object_id
+
+			expect {
+				observed_class.do_a_class_thing
+			}.to emit_event( "anonymous_class_#{id}.do_a_class_thing" )
+		end
+
+	end
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,155 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'simplecov' if ENV['COVERAGE']
+
+require 'rspec'
+
+require 'loggability/spechelpers'
+require 'observability'
+
+
+module Observability::SpecHelpers
+
+	### Replace the real observer with a new one with a sender of the given
+	### +sender_type+, yield to the block, then restore the real observer.
+	def self::replace_observer( sender_type )
+		real_ivar = Observability.instance_variable_get( :@observer )
+
+		new_sender = Observability::Sender.get_subclass( sender_type )
+		new_observer = Observability::Observer.new( new_sender )
+		new_ivar = Concurrent::IVar.new( new_observer )
+
+		begin
+			Observability.instance_variable_set( :@observer, new_ivar )
+			yield( new_observer )
+		ensure
+			Observability.instance_variable_set( :@observer, real_ivar )
+		end
+	end
+
+
+	# Expectation class to match emitted events.
+	class EventEmittedExpectation
+		include RSpec::Matchers::Composable
+
+		extend Loggability
+		log_to :observability
+
+
+		### Create a new expectation that an event will be emitted that matches the
+		### given +criteria+.
+		def initialize( expected_type )
+			@expected_type = expected_type
+			@prelude_error = nil
+			@sender        = nil
+		end
+
+
+		### RSpec matcher API -- specify that this matcher supports expect with a block.
+		def supports_block_expectations?
+			return true
+		end
+
+
+		### Return +true+ if the +given_proc+ is a valid callable.
+		def valid_proc?( given_proc )
+			return true if given_proc.respond_to?( :call )
+
+			warn "`emit_event` was called with non-proc object #{given_proc.inspect}"
+			return false
+		end
+
+
+		### Returns +true+ if the +given_proc+ results in an observation that matches
+		### the built-up criteria to be sent.
+		def matches?( given_proc )
+			return false unless self.valid_proc?( given_proc )
+			return self.run_with_test_sender( given_proc )
+		end
+
+
+		### RSpec negated matcher API -- return +true+ if an observation is not built when
+		### the +given_proc+ is called.
+		def does_not_match?( given_proc )
+			return false unless self.valid_proc?( given_proc )
+			self.run_with_test_sender( given_proc )
+
+			return !( @prelude_error || self.job_ran_normally? )
+		end
+
+
+		### Run the +given_proc+ with async publication emulation set up.
+		def run_with_test_sender( given_proc )
+			Observability::SpecHelpers.replace_observer( :testing ) do |observer|
+				@sender = observer.sender
+				begin
+					given_proc.call
+				rescue => err
+					@prelude_error = err
+				end
+			end
+
+			return self.job_ran_normally?
+		end
+
+
+		### Returns +true+ if the job ran and succeeded.
+		def job_ran_normally?
+			return @sender.event_was_sent?( @expected_type )
+		end
+
+
+		### Return a failure message based on the current state of the matcher.
+		def failure_message
+			return self.describe_prelude_error if @prelude_error
+			return "no events were emitted" if @sender.enqueued_events.empty?
+			return "no %s events were emitted; emitted events were:\n  %s" %
+				[ @expected_type, @sender.enqueued_events.map(&:type).join("\n ") ]
+		end
+		alias_method :failure_message_for_should, :failure_message
+
+
+		### Return a failure message based on the current state of the matcher when it was
+		### passed to a `to_not`.
+		def failure_message_when_negated
+			return self.describe_prelude_error if @prelude_error
+			return "expected not to emit a %s event, but one was sent" % [ @expected_type ]
+		end
+		alias_method :failure_message_for_should_not, :failure_message_when_negated
+
+
+		### Return a String describing an error which happened in the spec's
+		### block before the event started.
+		def describe_prelude_error
+			return "%p before the event was emitted: %s" % [
+				@prelude_error.class,
+				@prelude_error.full_message( highlight: $stdout.tty?, order: :bottom )
+			]
+		end
+
+	end # class EventEmittedExpectation
+
+
+	### Expect an event matching the given +criteria+ to be emitted.
+	def emit_event( *criteria )
+		return Observability::SpecHelpers::EventEmittedExpectation.new( *criteria )
+	end
+
+end # module Observability::SpecHelpers
+
+
+### Mock with RSpec
+RSpec.configure do |config|
+	config.run_all_when_everything_filtered = true
+	config.filter_run :focus
+	config.order = 'random'
+	config.mock_with( :rspec ) do |mock|
+		mock.syntax = :expect
+	end
+
+	config.include( Loggability::SpecHelpers )
+	config.include( Observability::SpecHelpers )
+end
+
+