teneo_microservice 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18cb01bcee051c684f6526d7ebad58897f65350fa6cbf1cb88ed8d401a9750ee
-  data.tar.gz: 578d8002f4d79b85d6494a729a426a2351b3b64688cf0887b96abf319c7a902d
+  metadata.gz: 5ecd068ae3cca435b92e05c35c8a2a349d82856b3b1038aee477a3ccb3bfb2e2
+  data.tar.gz: e767f8644a5713da4dd802c35dd91732fa5f86bf76de0c93858ae3370136b016
 SHA512:
-  metadata.gz: 456e6546a5060982d17daba9c04d0051340cbaeaae005a4b73c375b963df3d6f804c0f28c7b72a125cfc825a5c2201d784f00d7dea2aa9f910f4242c65ce4d6e
-  data.tar.gz: ba90af2daa768b9b74eff78d686bd76b3da30ab5f475b631406a1423a571c20d622e65fc7b6e0a0f8af5f716241b2652a88be70c64a71b5bd89be73913975acf
+  metadata.gz: c2576f33c60eb8a7cefa49d14ba1b21d20fc5642eedf9f767867ffb6ea6dbd89eeb150da8b5d86fa87adfca02b55587f6444753ffe7311c3d015bd0298eeabef
+  data.tar.gz: b09387f2744ae63ab8528a9746ee811758997d9045bb7d18eb6d59de2f84efbd345c1d6abec4ed1120c6129d2e7779671e97a06c10a84cec744d2a37db75d3f8

data/Gemfile

@@ -6,6 +6,8 @@ gem 'debug', require: false # requires libyaml-dev to be installed on system (Ub
 gem 'dotenv', groups: %i[development test]
 gem 'grpc'
 gem 'grpc-tools'
+gem 'hanna'
+gem 'logging', '~> 2.4'
 gem 'protobuf'
 gem 'rake', '~> 13.0'
 gem 'rspec', '~> 3.0'

data/Gemfile.lock

@@ -42,6 +42,8 @@ GEM
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
     grpc-tools (1.69.0)
+    hanna (1.5.0)
+      rdoc (>= 4)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     io-console (0.8.0)
@@ -50,9 +52,14 @@ GEM
       reline (>= 0.4.2)
     json (2.9.1)
     language_server-protocol (3.17.0.3)
+    little-plugger (1.1.4)
     logger (1.6.5)
+    logging (2.4.0)
+      little-plugger (~> 1.1)
+      multi_json (~> 1.14)
     middleware (0.1.0)
     minitest (5.25.4)
+    multi_json (1.15.0)
     mutex_m (0.3.0)
     parallel (1.26.3)
     parser (3.3.7.0)
@@ -121,6 +128,8 @@ DEPENDENCIES
   dotenv
   grpc
   grpc-tools
+  hanna
+  logging (~> 2.4)
   protobuf
   rake (~> 13.0)
   rspec (~> 3.0)

data/Rakefile

@@ -3,6 +3,7 @@
 require 'bundler/setup' # Required to use gems from local vendor dir
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
+require 'rdoc/task'
 
 Bundler::GemHelper.install_tasks
 
@@ -10,6 +11,10 @@ RSpec::Core::RakeTask.new(:spec)
 
 RuboCop::RakeTask.new
 
+RDoc::Task.new do |rdoc|
+  rdoc.generator = 'hanna'
+end
+
 task default: %w[spec rubocop]
 
 task :proto do

data/lib/teneo_microservice/client.rb

@@ -5,9 +5,15 @@ require_relative 'util/convert'
 require_relative 'grpc_services/cloud_event_enum'
 require_relative 'proto/cloud_event_services_pb'
 
-# Sends data to gRPC services
+##
+# This class represents a client that can communicate with a single gRPC endpoint.
 class Client
-  attr_accessor :socket, :stub
+  ##
+  # The remote endpoint this client is set to communicate with.
+  attr_accessor :socket
+  ##
+  # The object through which Client communicates.
+  attr_accessor :stub
 
   def initialize(socket:)
     Env.valid_settings?

data/lib/teneo_microservice/error_classes/env_settings_error.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
-# This error should get raised when the environment does not provide
-# the required attributes.
+##
+# This class represents an error that should get raised when the
+# environment variables do not provide the required attributes.
+#
+# Thus indicating a faulty configuration.
 class EnvSettingsError < StandardError
   def initialize(msg = 'ERROR: invalid settings in .env file')
     super(msg)

data/lib/teneo_microservice/error_classes/socket_format_error.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-# This error should get raised when a socket string has an invalid format
+##
+# This class represents an error that should get raised when the
+# socket string has an invalid format.
 class SocketFormatError < StandardError
   def initialize(msg = 'invalid socket')
     super(msg)

data/lib/teneo_microservice/grpc_services/cloud_event_enum.rb

@@ -4,12 +4,20 @@ require 'securerandom'
 
 require_relative '../util/convert'
 
-# CloudEventEnum provides an Enumerator of cloud events
+##
+# This class represents a stream of CloudEvents.
+#
+# Such a stream is only used in cases where the CloudEvent proto-generated code
+# requires a stream of CloudEvents in the method argument list and/or
+# the return value.
 class CloudEventEnum
   def initialize(array:)
     @array = array
   end
 
+  ##
+  # each makes this class enumerable by returning an enumerator of
+  # the data given at initialization converted as CloudEvents.
   def each
     return enum_for(:each) unless block_given?
 

data/lib/teneo_microservice/server.rb

@@ -4,18 +4,27 @@ require_relative 'client'
 require_relative 'service_orchestrator'
 require_relative 'util/env'
 
-# Encapsulating class for all gRPC communication
+##
+# This class encapsulates both a gRPC endpoint and a list of gRPC clients.
+#
+# This makes Server able to function as a gRPC server while also being able
+# to communicate with other gRPC endpoints.
 class Server
-  attr_accessor :socket, :remote_hosts, :clients
+  ##
+  # The endpoint this server is listening to.
+  attr_accessor :socket
+  ##
+  # A list of clients used for communicating with all registered remote hosts.
+  attr_accessor :clients
 
   def initialize
     Env.valid_settings?
 
     @socket = "#{ENV["LISTEN_ADDRESS"]}:#{ENV["PORT"]}"
-    @remote_hosts = ENV['REMOTE_HOSTS'].split('|') unless ENV['REMOTE_HOSTS'].nil?
+    remote_hosts = ENV['REMOTE_HOSTS'].split('|') unless ENV['REMOTE_HOSTS'].nil?
 
     @clients = []
-    @remote_hosts&.each do |remote|
+    remote_hosts&.each do |remote|
       client = Client.new(socket: remote)
       @clients.push(client)
     end
@@ -24,10 +33,17 @@ class Server
     @orchestrator.initialize_listener
   end
 
+  ##
+  # register_service registers a service to the gRPC server.
+  #
+  # A service provides the actual executable methods used for communication,
+  # and registering these to the server makes them available for implementation.
   def register_service(service:)
     @orchestrator.add(service)
   end
 
+  ##
+  # start_listening_for_data readies the server for accepting traffic.
   def start_listening_for_data
     @orchestrator.start
   end

data/lib/teneo_microservice/service_orchestrator.rb

@@ -1,20 +1,50 @@
 # frozen_string_literal: true
 
+require 'logging'
 require 'grpc'
 
 require_relative 'error_classes/socket_format_error'
 
-# Listener for gRPC data
+module GRPC
+  extend Logging.globally
+end
+
+##
+# This class represents a gRPC endpoint with which clients can communicate.
 class ServiceOrchestrator
+  ##
+  # The endpoint this server is listening to.
   attr_accessor :socket
 
   def initialize(socket:)
     @socket = socket
+
+    Logging.logger.root.appenders = Logging.appenders.stdout
+    Logging.logger.root.level = configured_log_level
   end
 
-  def initialize_listener
-    puts 'initializing gRPC service'
+  ##
+  # configured_log_level returns the correct token to be used to set the
+  # gRPC log level based on the configured setting.
+  def configured_log_level
+    error_level_hash = {
+      'DEBUG' => :debug,
+      'INFO' => :info,
+      'WARN' => :warn,
+      'ERROR' => :error,
+      'FATAL' => :fatal
+    }
 
+    return :info unless error_level_hash.key?(ENV['LOG_LEVEL'])
+
+    error_level_hash[ENV['LOG_LEVEL']]
+  end
+
+  ##
+  # initialize_listener creates a usable traffic listener.
+  #
+  # It does not yet accept data at this point.
+  def initialize_listener
     raise SocketFormatError unless @socket =~ /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}:\d{1,5}$/
 
     @listener = GRPC::RpcServer.new
@@ -22,25 +52,36 @@ class ServiceOrchestrator
     GRPC.logger.info("... running insecurely on #{@socket}")
   end
 
+  ##
+  # add registers a service to the gRPC server.
+  #
+  # A service provides the actual executable methods used for communication,
+  # and registering these to the server makes them available for implementation.
   def add(service)
     @listener.handle(service)
   end
 
+  ##
+  # start readies the server for accepting traffic.
   def start
-    puts "listening insecurely on #{@socket}"
     @listener.run_till_terminated_or_interrupted([1, 'int', 'SIGQUIT'])
   end
 
+  ##
+  # wait_till_running halts the program until the listener is running.
   def wait_till_running
     @listener.wait_till_running
   end
 
+  ##
+  # running? returns whether the listener is accepting traffic or not.
   def running?
     @listener.running?
   end
 
+  ##
+  # stop makes the listener not accept traffic anymore.
   def stop
-    puts 'shutting down gRPC server'
     @listener.stop if running?
   end
 end

data/lib/teneo_microservice/util/convert.rb

@@ -6,8 +6,22 @@ require 'securerandom'
 require_relative '../proto/cloud_event_services_pb'
 require_relative '../grpc_services/cloud_event_enum'
 
-# The Convert module provides functionality on custom data conversion operations.
+##
+# This module provides functionality for custom data conversion.
 module Convert
+  ##
+  # json_to_cloudevent encapsulates the given JSON-string into a CloudEvent.
+  #
+  # Apart from the data, the generated CloudEvent is initialized with:
+  #   - A random UUID
+  #   - Source (based on config settings)
+  #   - SpecVersion (based on config settings)
+  #   - Type (based on config settings)
+  #   - Attributes whiwh contain:
+  #     ° Datacontenttype set to application/json
+  #     ° Timestamp
+  #
+  # Returns an error if the provided data is not a valid JSON-string.
   def self.json_to_cloudevent(data:)
     raise JSON::ParserError, "invalid JSON: '#{data}'" unless valid_json?(json: data)
 
@@ -24,6 +38,10 @@ module Convert
     )
   end
 
+  ##
+  # generate_attributes returns a hash of default attributes containing:
+  #   - Datacontenttype set to application/json
+  #   - Timestamp
   def self.generate_attributes
     now = Time.now
 
@@ -40,10 +58,15 @@ module Convert
     }
   end
 
+  ##
+  # array_to_cloudevent_enum converts an array of JSON-strings to an
+  # enumerator of CloudEvents.
   def self.array_to_cloudevent_enum(array:)
     CloudEventEnum.new(array: array)
   end
 
+  ##
+  # valid_json? checks if the provided JSON-string is valid.
   def self.valid_json?(json:)
     JSON.parse(json)
     true

data/lib/teneo_microservice/util/env.rb

@@ -5,8 +5,17 @@ require 'securerandom'
 require_relative '../error_classes/env_settings_error'
 require_relative '../error_classes/socket_format_error'
 
-# The Env module provides functionality for env variable settings.
+##
+# This module provides functionality for working with env variable settings.
 module Env
+  ##
+  # valid_settings? checks if all mandatory settings are present within the
+  # available environment variables.
+  #
+  # Raises an EnvSettingsError is not all mandatory settings are found.
+  #
+  # Raises a SocketFormatError if the socket information in the environment
+  # variables is invalid.
   def self.valid_settings?
     mandatory_settings = %w[LISTEN_ADDRESS PORT CLOUDEVENTS_SPEC_VERSION CLOUDEVENTS_TYPE_PREFIX]
     mandatory_settings.each do |setting|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: teneo_microservice
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Ruben Vanoverschelde
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-03-03 00:00:00.000000000 Z
+date: 2025-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grpc