tiny_bus 1.0.4 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80e736518279f690809f359a1a1c4c96fd32154d3c847b83fe249e409bf5fd56
-  data.tar.gz: a1557163fb8fb490e79cbf159411989de8fc0e49bb8b5436d43cd7392c554031
+  metadata.gz: 33fd7e7b558ef0142c5edccdd2f680edd44b1b857a9bd6b39c6c6c554b3fc007
+  data.tar.gz: 75c523e3d559488de425a0ebe96c2e36253d85e226f2cc83de35c72bc56254b3
 SHA512:
-  metadata.gz: eb83e912761d438bc17d93a4121e0c897c3d88b212ec50a842d088cedcaa028b84b6e797727be10a817fe63ad93e941f0f82278ffc79bea5587d13e516398e0d
-  data.tar.gz: bcf4adbfa6c0f959410b3b25ede768690c5e2c8bf47cd28e0d0b38e3d05941af44496656a9d75ce468da66d7e456a2761141413383bfba71b3c6759a38e61c88
+  metadata.gz: 8e12dff36fe08ad554645939c3b5509e9f8718bbb4eedc4819a1dbb53460093459c1e77fae52b1dd6b20ae4b25fe840a06651c446c46b8dcfac81c0a8b9a065e
+  data.tar.gz: f30197ba6ef9502d38066d6223789c2c6dccdf704abc289b1f022e8cbc8aa75bcd14ea5c3553546d5e7ca5bb9d8f1ec63370da167d55fb576d79f1373bc73fe5

data/lib/tiny_bus.rb

@@ -2,95 +2,112 @@ require 'time'
 require 'set'
 require 'securerandom'
 require 'tiny_log'
+require 'tiny_pipe'
 
+# NOTE: This library depends on the TinyLog library.
+#
 # This class implements a very simpler PubSub system where:
 # - subscribers can subscribe via the #sub method
 # - subscribers can unsubscribe via the #unsub method
 # - msgs can enter the TinyBus via the #msg method
 #
 # The messages that come into this TinyBus are assumed to be Hash-like, in the
-# sense that they have a 'topic' key that can be accessed using Hash-like key
-# access syntax, and that the 'topic' key will serve as the method of
+# sense that they have a '.topic' key that can be accessed using Hash-like key
+# access syntax, and that the '.topic' key will serve as the method of
 # distribution.
 #
 # Usage:
 #   t = TinyBus.new
 #   t.sub('news', <some object that responds to #msg)
-#   t.msg({'topic' => 'news', 'details' => 'Historic happenings!})     # goes to 'news' subscribers
-#   t.msg({'topic' => 'whatever', 'details' => 'Historic happenings!}) # goes to dead letter output, or raises exception, depending on the configuration
+#   t.msg({'.topic' => 'news', 'details' => 'Historic happenings!})     # goes to 'news' subscribers
+#   t.msg({'.topic' => 'whatever', 'details' => 'Historic happenings!}) # goes to dead letter output, or raises exception, depending on the configuration
 #
 # Initialization options:
-#   TinyBus.new(log: <a filename for log output>)                 # will log all normal msgs in this file
-#   TinyBus.new(dead: <a filename for dead message log output>)   # will log all undeliverable msgs in this file
-#   TinyBus.new(raise_on_dead: true)                              # strict mode for undeliverable messages, defaults to false
+#   TinyBus.new(log: <a TinyLog for output>)           # will log all normal msgs in this file
+#   TinyBus.new(dead: <a TinyLog for dead messages>)   # will log all undeliverable msgs in this file
+#   TinyBus.new(raise_on_dead: true)                   # strict mode for undeliverable messages, defaults to false
 class TinyBus
   # log:
-  #   if specified it should be a valid filename
-  #   if not specified will default to $stdout
+  #   if specified, it should be a TinyLog instance
+  #   if not specified, it will create a new TinyLog instance for $stdout
   # dead:
-  #   if specified it should be a valid filename for dead letter logging
-  #   if not specified will default to $stderr
+  #   if specified, it should be a TinyLog instance
+  #   if not specified, it will create a new TinyLog instance for $stderr
+  # translator:
+  #   the translator is an instance of TinyPipe, if you want to translate the
+  #   incoming masssage (i.e. annotate with additional fields, change
+  #   keys/values on incoming messges). if not specified no translatioins will
+  #   be made on incoming messages other than the default annotations
+  #   NOTE: all messages are automatically annotated with three fields:
+  #   - .time: the Unix time the message is received in Integer milliseconds,
+  #   - .msg_uuid: a unique UUID for the incoming message
+  #   - .trace: a unique UUID for chains of messages (if not present)
   # raise_on_dead:
-  #   kind of a strict mode. if false, then messages with a topic with no
-  #   subscribers will go to the dead file. if true, then messages with a topic
-  #   with no subscribers will raise an exception.
-  def initialize(log: nil, dead: nil, raise_on_dead: false)
+  #   kind of a strict mode. if false, then messages with a '.topic' with no
+  #   subscribers will go to the dead file. if true, then messages with a
+  #   '.topic' with no subscribers will raise an exception.
+  def initialize(log: nil, dead: nil, translator: nil, raise_on_dead: false)
     @subs = {}
+    @translator = translator
+    @annotator = TinyPipe.new([
+      ->(m){ m['.time'] = (Time.now.to_f * 1000).to_i; m },
+      ->(m){ m['.msg_uuid'] = SecureRandom.uuid; m },
+      ->(m){ m['.trace'] ||= SecureRandom.uuid; m }
+    ])
+
     @stats = { '.dead' => 0 }
-    @log = log ? TinyLog.new(log) : TinyLog.new($stdout)
-    @dead = dead ? TinyLog.new(dead) : TinyLog.new($stderr)
+    @log = log || TinyLog.new($stdout)
+    @dead = dead || TinyLog.new($stderr)
     @raise_on_dead = raise_on_dead
   end
 
   # adds a subscriber to a topic
-  #
-  # topics can be any string that doesn't start with a dot (.) - dot topics are
-  # reserved for internal TinyBus usage, such as:
-  # - .log
   def sub(topic, subber)
-    raise TinyBus::SubscriptionToDotTopicError.new("Cannot subscribe to dot topic `#{topic}', because those are reserved for internal use") if topic.start_with?('.')
     raise TinyBus::SubscriberDoesNotMsg.new("The specified subscriber type `#{subber.class.inspect}' does not respond to #msg") unless subber.respond_to?(:msg)
 
     @subs[topic] ||= Set.new
     @subs[topic] << subber
     @stats[topic] ||= 0
+
+    msg({ '.topic' => 'sub', 'to_topic' => topic, 'subber' => subber.to.s })
   end
 
   # removes a subscriber from a topic
   def unsub(topic, subber)
     @subs[topic]&.delete(subber)
+
+    msg({ '.topic' => 'unsub', 'from_topic' => topic, 'subber' => subber.to.s })
   end
 
   # takes an incoming message and distributes it to subscribers
   #
-  # this method also annotates incoming messages with two dot properties:
-  # - .time: the current timestamp, accurate to the microsecond
-  # - .msg_uuid: a UUID to uniquely identify this message
+  # msg: the incoming message to be distributed
+  # lvl (optional): the logging level
   #
   # NOTE: it modifies the incoming msg object in place in order to avoid
   # unnecessary object allocations
+  #
+  # NOTE: keys that begin with dot (.), such as '.time' are reserved for
+  # TinyBus and show not be altered by outside code, otherwise undefined
+  # behavior may result.
   def msg(msg, lvl='info')
-    topic = msg['topic']
+    msg = @annotator.pipe(msg)
+    msg = @translator&.pipe(msg) || msg
 
-    raise TinyBus::SendToDotTopicError.new("Cannot send to dot topic `#{topic}', because those are reserved for internal use") if topic.start_with?('.')
+    topic = msg['topic']
 
     subbers = @subs[topic]
 
-    annotated = msg.merge!({
-                '.time' => Time.now.utc.iso8601(6),
-                '.msg_uuid' => SecureRandom.uuid
-              })
-
     if subbers
       @stats[topic] += 1
-      subbers.each{|s| s.msg(annotated) }
-      @log.sent annotated
+      subbers.each{|s| s.msg(msg) }
+      @log.sent msg
     else
       if @raise_on_dead
         raise TinyBus::DeadMsgError.new("Could not deliver message to topic `#{topic}'")
       else
         @stats['.dead'] += 1
-        @dead.dead annotated
+        @dead.dead msg
       end
     end
   end
@@ -106,6 +123,4 @@ class TinyBus
 end
 
 class TinyBus::DeadMsgError < RuntimeError; end
-class TinyBus::SubscriptionToDotTopicError < RuntimeError; end
 class TinyBus::SubscriberDoesNotMsg < RuntimeError; end
-class TinyBus::SendToDotTopicError< RuntimeError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tiny_bus
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 3.0.0
 platform: ruby
 authors:
 - Jeff Lunt
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-18 00:00:00.000000000 Z
+date: 2022-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tiny_log
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: tiny_pipe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: a tiny pubsub message bus with almost no features
 email: jefflunt@gmail.com
 executables: []
@@ -35,7 +49,7 @@ homepage: https://github.com/jefflunt/tiny_bus
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -50,8 +64,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.3.7
+signing_key:
 specification_version: 4
 summary: want to have an in-memory message bus that takes hash-like objects and distributes
   them out to subscribers based on a 'topic' key, with logging to $stdout or a file,