eventhub-processor2 1.25.0 → 1.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d78c7de7448b619cc5dce05f62af274a5310e1abf85986e8cd7e014d49e8bbb5
-  data.tar.gz: c56a15cde07013aea85c6d1c67c674fa55802e7c0cf8299a54f7b6a48f0e7278
+  metadata.gz: a22e1c2fd13d72c1b1a7ca6acd296f6e1a5a6b8fca1398f81d5cb4e2a04c220b
+  data.tar.gz: 18ca7a93b97092c0a66c4dde11a1cce29fdc505259bebb7ed951e1638dd04422
 SHA512:
-  metadata.gz: dc364064bc7c6c54444c15165c204b4314533f7df2e4fd0e1a3d065e2ec19b5b6586501a603e0b1b8e3fb3b8f0357a9a3279b70ab9e45198e061a77c28b29a9b
-  data.tar.gz: 65e9922a923b95ecdbade34deb040abee4a9575772df22cf183340182d26f9353a04f53b39ea69b6346c2ae4858ec9b8265095b98bb241ceefea673aaf3458ea
+  metadata.gz: 7965f0be501e337c8a0e8d6873417f13e884107016fad8f080550d69be14636cf3cdd31c7f884dda0a811a475cb73bba16ad1c2b2b85fdce76de95fd3785d02f
+  data.tar.gz: 70c95a713c4600c748a5e3bf5d625fd848110aa37c94b5bbcf3df2dcff847f1d6bd2c5bc4c1a69e6673a26065c9f42d4c02bbd627af235d53998a4ea81ed2ab0

data/.github/workflows/{ci.yml → 01_test.yml}

@@ -1,4 +1,4 @@
-name: ci
+name: 01 - Test
 
 on:
   push:

data/.github/workflows/02_test_build_and_release.yml

@@ -0,0 +1,57 @@
+name: 02 - Test, Build and Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+
+  test:
+    runs-on: ubuntu-latest
+    env:
+      CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '4.0'
+        bundler: latest
+        bundler-cache: true
+        cache-version: 4
+
+    - name: Setup RabbitMQ
+      run: |
+        cd docker && docker build -t processor-rabbitmq .
+        docker run -d -p 5672:5672 -p 15672:15672 --name processor-rabbitmq processor-rabbitmq
+
+    - name: Run default task
+      run: |
+        bundle exec rake
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for OIDC
+      contents: write  # Required for pushing tags
+
+    steps:
+    - name: Checkout current code
+      uses: actions/checkout@v6
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '4.0'
+        bundler-cache: true
+        cache-version: 1
+
+    - name: Build gem
+      run: gem build *.gemspec
+
+    - name: Push to Rubygems
+      uses: rubygems/release-gem@v1

data/.tool-versions

@@ -1 +1 @@
-ruby 4.0.1
+ruby 4.0.2

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog of EventHub::Processor2
 
+# 1.26.0 / 2026-03-18
+
+* Add HTTP resources for version, docs, changelog, and configuration with HTML rendering
+* Add processor hooks for HTTP resource customization: `version`, `company_name`, `readme_as_html`, `changelog_as_html`, `configuration_as_html`, `sensitive_keys`, and `http_resources`
+* Heartbeat endpoint returns detailed JSON status (version, pid, uptime, messages)
+* Add distributed tracing with correlation_id and execution_id in structured log output
+* Simplify HTTP configuration with shared `http.bind_address`, `http.port`, and `http.base_path`
+* Add kramdown dependency for markdown to HTML conversion
+* Rename GitHub Actions workflows and add test step to release workflow
+
 # 1.25.0 / 2026-01-13
 
 * Replace uuidtools dependency with Ruby's built-in SecureRandom

data/README.md

@@ -1,5 +1,6 @@
 [![Gem Version](https://badge.fury.io/rb/eventhub-processor2.svg)](https://badge.fury.io/rb/eventhub-processor2)
-[![ci](https://github.com/thomis/eventhub-processor2/actions/workflows/ci.yml/badge.svg)](https://github.com/thomis/eventhub-processor2/actions/workflows/ci.yml)
+[![01 - Test](https://github.com/thomis/eventhub-processor2/actions/workflows/01_test.yml/badge.svg)](https://github.com/thomis/eventhub-processor2/actions/workflows/01_test.yml)
+[![02 - Test, Build and Release](https://github.com/thomis/eventhub-processor2/actions/workflows/02_test_build_and_release.yml/badge.svg)](https://github.com/thomis/eventhub-processor2/actions/workflows/02_test_build_and_release.yml)
 
 # EventHub::Processor2
 
@@ -10,7 +11,7 @@ Processor2 has currently the following sub-components implemented
 * Publisher - responsible for message publishing
 * Watchdog - Checks regularly broker connection and defined listener queue(s)
 * Listener AMQP - Listens to defined AMQP queues, parses recevied message into a EventHub::Message instance and calls handle_message method as defined in derived class.
-* Listener HTTP - Provides an http endpoint for health checks (Exp.  /svc/{class_name}/heartbeat)
+* Listener HTTP - Provides HTTP endpoints for health checks and monitoring (e.g. /svc/{class_name}/heartbeat, /svc/{class_name}/version)
 
 Processor2 is using Bunny http://rubybunny.info a feature complete RabbitMQ Client to interact with message broker. Processor2 can deal with long running message processing.
 
@@ -65,6 +66,7 @@ module EventHub
       # => :content_type
       # => :priority
       # => :delivery_tag
+      # => :correlation_id (if present in incoming AMQP message)
 
       # if an exception is raised in your code
       # it will be automatically catched by
@@ -114,6 +116,73 @@ I, [2018-02-09T15:22:35.658522 #37966]  INFO -- : Listener is starting...
 I, [2018-02-09T15:22:35.699161 #37966]  INFO -- : Listening to queue [example]
 ```
 
+## Logging
+
+By default, Processor2 logs to both stdout (standard format) and a logstash file. For containerized environments (Docker, Kubernetes), use the `--console-log-only` option to output structured JSON logs to stdout only:
+
+```bash
+bundle exec ruby example.rb --console-log-only
+```
+
+This outputs logs in JSON format suitable for log aggregation systems:
+
+```json
+{"@timestamp":"2026-01-18T10:00:00.000Z","@version":"1","severity":"INFO","host":"server1","application":"example","environment":"production","message":"example (1.0.0): has been started"}
+```
+
+## Correlation ID
+
+Processor2 supports automatic propagation of correlation IDs for distributed tracing. While EventHub messages already contain an `execution_id` in the message body for tracing, the AMQP `correlation_id` provides an additional benefit: it's part of the message metadata (envelope), not the payload. This means it's available even when the JSON body is invalid and cannot be parsed - useful for error tracking and debugging malformed messages.
+
+When an incoming AMQP message includes a `correlation_id` in its metadata:
+
+1. **Automatic logging**: All log messages during message processing will include `correlation_id` as a separate field in structured JSON output
+2. **Automatic publishing**: Any messages published during processing will automatically include the same correlation_id in their AMQP headers
+3. **Available in args**: The correlation_id is passed to `handle_message` via `args[:correlation_id]`
+4. **Consistent execution_id**: When creating new messages, `execution_id` is automatically set to match `correlation_id`, ensuring consistent tracing across both AMQP metadata and message body
+
+This happens transparently without any changes to your `handle_message` implementation:
+
+```ruby
+def handle_message(message, args = {})
+  # correlation_id is available in args if needed
+  correlation_id = args[:correlation_id]
+
+  # Logging automatically includes correlation_id in JSON output
+  EventHub.logger.info("Processing order")
+
+  # Publishing automatically includes correlation_id
+  publish(message: response.to_json)
+
+  message.copy
+end
+```
+
+You can also explicitly set or override the correlation_id when publishing:
+
+```ruby
+publish(message: msg.to_json, correlation_id: "550e8400-e29b-41d4-a716-446655440000")
+```
+
+If no `correlation_id` is present in the AMQP metadata, the message body's `execution_id` is used as fallback to ensure tracing continuity.
+
+### How it works
+
+1. **Received**: When an AMQP message arrives, `correlation_id` is extracted from the message metadata
+2. **Fallback**: If no `correlation_id` in AMQP metadata, the message body's `execution_id` is used instead (ensuring tracing continuity)
+3. **Stored**: The value is stored in thread-local storage (`Thread.current`) for the duration of message processing
+4. **Passed**: The `correlation_id` is passed to `handle_message` via `args[:correlation_id]`
+5. **Logging**: The logger automatically reads from thread-local storage and includes it in JSON output
+6. **Publishing**: The publisher automatically reads from thread-local storage and adds it to outgoing AMQP message headers (can be overwritten by passing `correlation_id:` explicitly)
+7. **New messages**: When creating a new `EventHub::Message`:
+   - With `correlation_id` present → `execution_id` is set to match `correlation_id`
+   - Without `correlation_id` → `execution_id` is set to a new UUID (default behavior)
+8. **Cleared**: After message processing completes, the stored value is cleared
+
+This design ensures correlation_id flows transparently through the entire message processing lifecycle. No code changes are required for existing implementations - just update the processor2 gem dependency.
+
+**Note:** We use `correlation_id` (snake_case) to follow Ruby naming conventions, AMQP standard message properties, and stay consistent with other args keys like `:queue_name`, `:content_type`, etc. The `correlation_id` value is typically a UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`).
+
 ## Configuration
 
 If --config option is not provided processor tries to load config/{class_name}.json. If file does not exist it loads default values as specified below.
@@ -133,10 +202,10 @@ If --config option is not provided processor tries to load config/{class_name}.j
       "tls_ca_certificates": [],
       "verify_peer": false,
       "show_bunny_logs": false,
-      "heartbeat": {
+      "http": {
         "bind_address": "localhost",
         "port": 8080,
-        "path": "/svc/{class_name}/heartbeat"
+        "base_path": "/svc/{class_name}"
       }
     },
     "processor": {
@@ -228,6 +297,239 @@ Final configuration result
 
 ```
 
+## HTTP Resources
+
+Processor2 exposes HTTP resources for health checks and monitoring. All resources share the same HTTP server configuration.
+
+**Configuration:**
+```json
+{
+  "server": {
+    "http": {
+      "bind_address": "localhost",
+      "port": 8080,
+      "base_path": "/svc/{class_name}"
+    }
+  }
+}
+```
+
+Resources are mounted under the `base_path`:
+- `{base_path}/heartbeat` - Health check
+- `{base_path}/version` - Version info as JSON
+- `{base_path}/docs` - README documentation as HTML
+- `{base_path}/docs/configuration` - Configuration as HTML table
+- `{base_path}/docs/changelog` - CHANGELOG as HTML
+- `{base_path}/assets/*` - Static assets (CSS, images)
+
+Accessing `{base_path}` or `{base_path}/` redirects to `{base_path}/docs`.
+
+**Backward Compatibility:** If you have existing configuration using the old `heartbeat` block with `bind_address`, `port`, and `path`, it will continue to work. The new `http` configuration takes precedence when both are present.
+
+### Heartbeat
+
+Returns detailed processor status information as JSON.
+
+```
+GET {base_path}/heartbeat
+```
+
+**Response:** `200 OK` with JSON body
+```json
+{
+  "version": "1.0.0",
+  "pid": 12345,
+  "environment": "production",
+  "heartbeat": {
+    "started": "2026-01-18T10:00:00.000Z",
+    "stamp_last_request": "2026-01-18T12:30:00.000Z",
+    "uptime_in_ms": 9000000,
+    "heartbeat_cycle_in_ms": 300000,
+    "queues_consuming_from": ["my_processor"],
+    "queues_publishing_to": ["event_hub.inbound"],
+    "host": "server1.example.com",
+    "addresses": [
+      {"interface": "en0", "host_name": "server1", "ip_address": "192.168.1.100"}
+    ],
+    "messages": {
+      "total": 1000,
+      "successful": 995,
+      "unsuccessful": 5,
+      "average_size": 2048,
+      "average_process_time_in_ms": 50,
+      "total_process_time_in_ms": 50000
+    }
+  }
+}
+```
+
+### Version
+
+Returns the processor version as JSON.
+
+```
+GET {base_path}/version
+```
+
+**Response:** `200 OK` with JSON body
+```json
+{
+  "version": "1.0.0"
+}
+```
+
+The version is taken from the `version` method in your derived processor class. If not defined, it returns `"?.?.?"`.
+
+```ruby
+class MyProcessor < EventHub::Processor2
+  def version
+    "1.0.0"  # your version
+  end
+end
+```
+
+### Docs
+
+Serves README.md as HTML with a built-in layout.
+
+```
+GET {base_path}/docs
+```
+
+**Response:** `200 OK` with HTML page
+
+By default, looks for `README.md` in the current directory, then `doc/README.md`. You can customize the path via configuration:
+
+```json
+{
+  "server": {
+    "http": {
+      "docs": {
+        "readme_path": "/custom/path/to/README.md"
+      }
+    }
+  }
+}
+```
+
+Or override completely by defining a `readme_as_html` method in your processor:
+
+```ruby
+class MyProcessor < EventHub::Processor2
+  def readme_as_html
+    "<h1>Custom Documentation</h1><p>Your content here.</p>"
+  end
+end
+```
+
+### Changelog
+
+Serves CHANGELOG.md as HTML with a built-in layout.
+
+```
+GET {base_path}/docs/changelog
+```
+
+**Response:** `200 OK` with HTML page
+
+By default, looks for `CHANGELOG.md` in the current directory, then `doc/CHANGELOG.md`. You can customize the path via configuration:
+
+```json
+{
+  "server": {
+    "http": {
+      "docs": {
+        "changelog_path": "/custom/path/to/CHANGELOG.md"
+      }
+    }
+  }
+}
+```
+
+Or override completely by defining a `changelog_as_html` method in your processor:
+
+```ruby
+class MyProcessor < EventHub::Processor2
+  def changelog_as_html
+    "<h1>Custom Changelog</h1><p>Your changes here.</p>"
+  end
+end
+```
+
+### Configuration
+
+Displays the active configuration as an HTML table. Sensitive values (passwords, tokens, keys) are automatically redacted.
+
+```
+GET {base_path}/docs/configuration
+```
+
+**Response:** `200 OK` with HTML page
+
+By default, the following keys are redacted: `password`, `secret`, `token`, `api_key`, `credential`. You can customize the list by defining a `sensitive_keys` method in your processor:
+
+```ruby
+# Override the entire list
+class MyProcessor < EventHub::Processor2
+  def sensitive_keys
+    %w[password secret token api_key credential connection_string]
+  end
+end
+
+# Or extend the default list
+class MyProcessor < EventHub::Processor2
+  def sensitive_keys
+    EventHub::DocsRenderer::DEFAULT_SENSITIVE_KEYS + %w[connection_string]
+  end
+end
+```
+
+Or override the entire page by defining a `configuration_as_html` method:
+
+```ruby
+class MyProcessor < EventHub::Processor2
+  def configuration_as_html
+    "<h1>Custom Configuration</h1><p>Your content here.</p>"
+  end
+end
+```
+
+### Disabling Resources
+
+By default, all HTTP resources are enabled. You can control which resources are available by defining an `http_resources` method in your processor. The navbar adapts automatically.
+
+```ruby
+class MyProcessor < EventHub::Processor2
+  def http_resources
+    [:heartbeat, :version, :docs, :changelog, :configuration]  # default: all enabled
+  end
+end
+```
+
+To disable the configuration page for example:
+
+```ruby
+class MyProcessor < EventHub::Processor2
+  def http_resources
+    [:heartbeat, :version, :docs, :changelog]
+  end
+end
+```
+
+### Customizing Footer
+
+The documentation pages display company name, version, and environment in the footer. Company name defaults to "Novartis" but can be customized by defining a `company_name` method in your processor:
+
+```ruby
+class MyProcessor < EventHub::Processor2
+  def company_name
+    "My Company"
+  end
+end
+```
+
+**Future Extension:** A future version could allow overriding the default layout template and CSS assets using convention over configuration (e.g., placing custom files in `doc/layout.erb` or `doc/app.css`).
+
 ## Development
 
 ```
@@ -244,13 +546,21 @@ Final configuration result
   bundle exec rake
 ```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Publishing
 
-This project uses [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) to securely publish gems to RubyGems.org. Trusted Publishing eliminates the need for long-lived API tokens by using OpenID Connect (OIDC) to establish a trusted relationship between GitHub Actions and RubyGems.org.
-
-With Trusted Publishing configured, gem releases are automatically published to RubyGems when the release workflow runs, providing a more secure and streamlined publishing process.
+This project uses [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) to securely publish gems to RubyGems.org via GitHub Actions. To release a new version:
+
+1. Update the version number in `lib/eventhub/version.rb`
+2. Merge changes to `main`
+3. Create a version tag either via command line or GitHub:
+   ```
+   git tag v1.x.x
+   git push origin v1.x.x
+   ```
+   Or on GitHub: go to **Releases** → **Create a new release** → enter the tag name (e.g. `v1.26.0`), select `main` as target, and publish.
+4. The `02 - Test, Build and Release` workflow triggers automatically, runs tests, builds the gem, and publishes it to [rubygems.org](https://rubygems.org)
 
 ## Contributing
 

data/eventhub-processor2.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "eventhub-components", "~> 0.4"
   spec.add_dependency "base64", "~> 0.3.0"
   spec.add_dependency "logger", "~> 1.6"
+  spec.add_dependency "kramdown", "~> 2.4"
 
   spec.add_development_dependency "rake", "~> 13.2"
   spec.add_development_dependency "rspec", "~> 3.13"

data/example/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [1.0.0] 2026-01-18
+
+* Initial release
+* Routes messages from example.outbound to example.inbound queue
+  * Supports JSON message format
+  * Preserves message headers

data/example/receiver.rb

@@ -2,6 +2,44 @@ require_relative "../lib/eventhub/base"
 
 module EventHub
   class Receiver < Processor2
+    def version
+      "2.0.0"
+    end
+
+    def company_name
+      "Example Company"
+    end
+
+    # Custom README served via method instead of file
+    def readme_as_html
+      <<~HTML
+        <h1>Receiver Processor</h1>
+        <p>This processor receives messages and deletes associated files.</p>
+        <h2>Features</h2>
+        <ul>
+          <li>Receives messages from the queue</li>
+          <li>Deletes files based on message ID</li>
+          <li>Logs all operations</li>
+        </ul>
+        <h2>Configuration</h2>
+        <p>No special configuration required.</p>
+      HTML
+    end
+
+    # Custom CHANGELOG served via method instead of file
+    def changelog_as_html
+      <<~HTML
+        <h1>Changelog</h1>
+        <h2>[2.0.0] 2026-01-18</h2><ul>
+          <li>Added custom documentation via methods</li>
+          <li>Improved error handling</li>
+        </ul>
+        <h2>[1.0.0] 2025-01-01</h2><ul>
+          <li>Initial release</li>
+        </ul>
+      HTML
+    end
+
     def handle_message(message, args = {})
       id = message.body["id"]
       EventHub.logger.info("[#{id}] - Received")

data/example/router.rb

@@ -3,6 +3,10 @@ require_relative "../lib/eventhub/base"
 module EventHub
   # Demo class
   class Router < Processor2
+    def version
+      "1.0.0"
+    end
+
     def handle_message(message, args = {})
       id = message.body["id"]
       EventHub.logger.info("Received: [#{id}]")

data/lib/eventhub/actor_heartbeat.rb

@@ -13,7 +13,8 @@ module EventHub
     end
 
     def start
-      EventHub.logger.info("Heartbeat is starting...")
+      cycle = Configuration.processor[:heartbeat_cycle_in_s]
+      EventHub.logger.info("Heartbeat is starting [cycle: #{cycle}s]...")
 
       every(60 * 60 * 24) { EventHub.logger.info("Actual actors: #{Celluloid::Actor.all.size}: #{Celluloid::Actor.all.map { |a| a.class }.join(", ")}") }
 

data/lib/eventhub/actor_listener_amqp.rb

@@ -16,8 +16,18 @@ module EventHub
     end
 
     def start
-      EventHub.logger.info("Listener amqp is starting...")
-      EventHub::Configuration.processor[:listener_queues].each_with_index do |queue_name, index|
+      server = EventHub::Configuration.server
+      queues = EventHub::Configuration.processor[:listener_queues]
+      settings = [
+        server[:user],
+        server[:host],
+        server[:port],
+        server[:vhost],
+        "tls=#{server[:tls]}",
+        queues.join(", ")
+      ].join(", ")
+      EventHub.logger.info("Listener amqp is starting [#{settings}]...")
+      queues.each_with_index do |queue_name, index|
         async.listen(queue_name: queue_name, index: index)
       end
     end
@@ -30,21 +40,26 @@ module EventHub
       with_listen(args) do |connection, channel, consumer, queue, queue_name|
         EventHub.logger.info("Listening to queue [#{queue_name}]")
         consumer.on_delivery do |delivery_info, metadata, payload|
-          EventHub.logger.info("#{queue_name}: [#{delivery_info.delivery_tag}]" \
-                                 " delivery")
-
-          @processor_instance.statistics.measure(payload.size) do
-            handle_payload(payload: payload,
-              connection: connection,
-              queue_name: queue_name,
-              content_type: metadata[:content_type],
-              priority: metadata[:priority],
-              delivery_tag: delivery_info.delivery_tag)
-            channel.acknowledge(delivery_info.delivery_tag, false)
+          CorrelationId.with(metadata[:correlation_id]) do
+            EventHub.logger.info("#{queue_name}: [#{delivery_info.delivery_tag}]" \
+                                   " delivery")
+
+            @processor_instance.statistics.measure(payload.size) do
+              handle_payload(payload: payload,
+                connection: connection,
+                queue_name: queue_name,
+                content_type: metadata[:content_type],
+                priority: metadata[:priority],
+                delivery_tag: delivery_info.delivery_tag,
+                correlation_id: metadata[:correlation_id])
+              channel.acknowledge(delivery_info.delivery_tag, false)
+            end
+
+            EventHub.logger.info("#{queue_name}: [#{delivery_info.delivery_tag}]" \
+                                 " acknowledged")
+          ensure
+            ExecutionId.clear
           end
-
-          EventHub.logger.info("#{queue_name}: [#{delivery_info.delivery_tag}]" \
-                               " acknowledged")
         end
         queue.subscribe_with(consumer, block: false)
       end
@@ -77,6 +92,15 @@ module EventHub
       # convert to EventHub message
       message = EventHub::Message.from_json(args[:payload])
 
+      # set execution_id for logging
+      ExecutionId.current = message.process_execution_id if message.valid?
+
+      # use execution_id as correlation_id if not already set from AMQP metadata
+      if CorrelationId.current.nil? && message.valid?
+        CorrelationId.current = message.process_execution_id
+        args[:correlation_id] ||= message.process_execution_id
+      end
+
       # append to execution history
       message.append_to_execution_history(EventHub::Configuration.name)
 
@@ -105,7 +129,7 @@ module EventHub
     end
 
     def pass_arguments(args = {})
-      keys_to_pass = [:queue_name, :content_type, :priority, :delivery_tag]
+      keys_to_pass = [:queue_name, :content_type, :priority, :delivery_tag, :correlation_id]
       args.select { |key| keys_to_pass.include?(key) }
     end