tiny_bus 2.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 523256349438598095486d3bcdff8fc0df0c5c2375fef06402bd2385cbeb14e6
-  data.tar.gz: e832821fc355d7bf69a5378601bbc90c16439d683583b189d1f07be8481eccdf
+  metadata.gz: b04a4860504e84547cc02b406c9146d47af4e16563b7509fe2cf3152fe5b6747
+  data.tar.gz: 687328b251069cf527b3de27210ce626884e9e751ccc07ef7accba31a86cd2c6
 SHA512:
-  metadata.gz: f7dc510d91314737850e511ab0e20b3c664ee8950766880a28b128f9b518fb0188acd0bd0c735ec7834c4c78650809f527352c42477fadaba1427f9c2714b127
-  data.tar.gz: fb351e69dacf513efc9198e67a3f6a5fd602f2d7924bcf7f1d3e5a9dfe62116892f360519d7863f6294b8aba65e56c9ee50796d7c6b7f9c5f68c4d8cf8494551
+  metadata.gz: 42eda75efbcdbcdd006c1dcdfeb098b48b17e6aecf5f7b27b9a630d8f383ad9a01064e77f77a486e01916ca98d71e036c726e2e5568a227dd4b36d2dc8f0f52c
+  data.tar.gz: 7c9cef3cf505db81c954aa8666007d30a89a2b0384e5e385759e8034ee39eb63a9f7f4d3da3981f37b63c657abece8c70d0b5b48152e1b82df7e5269f2da6909

data/lib/tiny_bus.rb

@@ -2,6 +2,7 @@ require 'time'
 require 'set'
 require 'securerandom'
 require 'tiny_log'
+require 'tiny_pipe'
 
 # NOTE: This library depends on the TinyLog library.
 #
@@ -11,33 +12,56 @@ require 'tiny_log'
 # - 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
+  ANNOTATION_PREFIX_DEFAULT = '.'
+
   # log:
   #   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 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.
+  # annotation_prefix:
+  #   default: '.'
+  #   if specified, the annotated message attributes ('.time', '.msg_uuid', and
+  #   '.trace') will have the dot ('.') replaced with the specified prefix text
+  def initialize(log: nil, dead: nil, translator: nil, raise_on_dead: false,
+                 annotation_prefix: ANNOTATION_PREFIX_DEFAULT)
     @subs = {}
+    @translator = translator
+    @annotator = TinyPipe.new([
+      ->(m){ m[annotation_prefix + 'time'] = (Time.now.to_f * 1000).to_i; m },
+      ->(m){ m[annotation_prefix + 'msg_uuid'] = SecureRandom.uuid; m },
+      ->(m){ m[annotation_prefix + 'trace'] ||= SecureRandom.uuid; m }
+    ])
+
     @stats = { '.dead' => 0 }
     @log = log || TinyLog.new($stdout)
     @dead = dead || TinyLog.new($stderr)
@@ -45,54 +69,52 @@ class TinyBus
   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
@@ -108,6 +130,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: 2.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Jeff Lunt
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-19 00:00:00.000000000 Z
+date: 2022-12-03 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,