iprog_worker_heartbeat 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 535a2156f09c87a51fa7f4492795bfa1e3844b847d53972f72920e0e851395c9
+  data.tar.gz: a2124c7edaa42932a50a7cd74421aa80dd1b7d07c7bc18bd09fe80d14d2b9a52
+SHA512:
+  metadata.gz: 54fddb98ba7ce36ecdd97629f941b48469ad314dbe204541b68eb3e164832c811802a63f168cf6fb41a400f8e6d3bf45f210709f7b04b14c1bdefc702614adde
+  data.tar.gz: 1c5d11906a0e6cadc575f5dfb65e55b2146a3e1e6bee067325d455d1c7b20cd39ccc3d2d82c552196cff95689e5059caf04b474f435ded5e0c488e1dbb5be086

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.1] - 2026-03-07
+- Improve generated initializer: prefer `ENV` then Rails credentials for `auth_token` with local manual fallback.
+- Keep only `auth_token` and `callback_url` active by default; comment optional settings.
+- Align README configuration example with generated initializer defaults.
+
+## [0.1.0] - 2026-03-07
+- Initial release with Rails engine, endpoint, logging model, delayed callback job, generator, and failure email alerts.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IPROG TECH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# IprogWorkerHeartbeat
+
+`iprog_worker_heartbeat` provides a Rails engine for worker heartbeat client apps.
+
+## Features
+
+- `POST /worker-heartbeat` endpoint
+- Bearer token + `worker_token` validation
+- Persistence in `worker_heartbeats` table
+- Delayed callback job (default 5 minutes)
+- Failure-only email alerts
+
+## Installation
+
+Add gem to your app:
+
+```ruby
+gem "iprog_worker_heartbeat"
+```
+
+Then run:
+
+```bash
+bin/rails generate iprog_worker_heartbeat:install
+bin/rails db:migrate
+```
+
+## Configuration
+
+Edit `config/initializers/iprog_worker_heartbeat.rb`:
+
+```ruby
+IprogWorkerHeartbeat.configure do |config|
+  config.auth_token = ENV["IPROG_WORKER_HEARTBEAT_AUTH_TOKEN"].presence ||
+    Rails.application.credentials.dig(:iprog_worker_heartbeat, :auth_token).presence ||
+    "local-heartbeat-token"
+  config.callback_url = "https://www.iprogtech.com/worker-heartbeat"
+  # config.failure_email_recipients = ["admin@iprogtech.com"]
+  # config.mailer_from = "IPROG Worker Heartbeat <admin@iprogtech.com>"
+  # config.mail_subject_prefix = "[IPROGSMS Worker Heartbeat]"
+  # config.notify_on_auth_failure = true
+  # config.callback_delay_seconds = 300
+  # config.max_retries = 3
+  # config.retry_wait_seconds = 60
+end
+```
+
+## API Contract
+
+- `POST /worker-heartbeat`
+- Header: `Authorization: Bearer <auth_token>`
+- Body: `{ "worker_token": "..." }`

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"

data/app/controllers/iprog_worker_heartbeat/heartbeats_controller.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module IprogWorkerHeartbeat
+  class HeartbeatsController < ActionController::API
+    def create
+      return render json: { ok: false, error: "Missing bearer token." }, status: :unauthorized if bearer_token.blank?
+      return invalid_auth! unless valid_bearer_token?
+
+      worker_token = heartbeat_params[:worker_token].to_s.strip
+      if worker_token.blank?
+        notify_failure("invalid_payload", "Missing worker_token.")
+        return render json: { ok: false, error: "Missing worker_token." }, status: :unprocessable_entity
+      end
+
+      heartbeat = IprogWorkerHeartbeat::Heartbeat.find_or_initialize_by(worker_token: worker_token)
+      if heartbeat.new_record?
+        heartbeat.assign_attributes(status: :pending, received_at: Time.current)
+        heartbeat.save!
+        IprogWorkerHeartbeat::CallbackJob.set(wait: IprogWorkerHeartbeat.config.callback_delay_seconds.to_i.seconds).perform_later(heartbeat.id)
+        return render json: { ok: true, queued: true }, status: :accepted
+      end
+
+      render json: { ok: true, queued: heartbeat.pending?, status: heartbeat.status }
+    rescue StandardError => e
+      notify_failure("controller_error", e.message)
+      render json: { ok: false, error: "Unable to process worker heartbeat." }, status: :internal_server_error
+    end
+
+    private
+
+    def heartbeat_params
+      params.permit(:worker_token)
+    end
+
+    def bearer_token
+      header = request.authorization.to_s
+      return "" unless header.start_with?("Bearer ")
+
+      header.delete_prefix("Bearer ").strip
+    end
+
+    def valid_bearer_token?
+      expected = IprogWorkerHeartbeat.config.auth_token.to_s
+      return false if expected.blank?
+      return false unless bearer_token.bytesize == expected.bytesize
+
+      ActiveSupport::SecurityUtils.secure_compare(bearer_token, expected)
+    end
+
+    def invalid_auth!
+      notify_failure("auth_failure", "Invalid bearer token") if IprogWorkerHeartbeat.config.notify_on_auth_failure
+      render json: { ok: false, error: "Invalid bearer token." }, status: :unauthorized
+    end
+
+    def notify_failure(event, details)
+      return if IprogWorkerHeartbeat.config.failure_email_recipients_array.empty?
+
+      IprogWorkerHeartbeat::FailureMailer.notify(heartbeat: nil, event: event, details: details).deliver_now
+    end
+  end
+end

data/app/jobs/iprog_worker_heartbeat/callback_job.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module IprogWorkerHeartbeat
+  class CallbackJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(heartbeat_id)
+      heartbeat = IprogWorkerHeartbeat::Heartbeat.find_by(id: heartbeat_id)
+      return if heartbeat.nil? || heartbeat.callback_sent?
+
+      heartbeat.with_lock do
+        return unless heartbeat.pending? || heartbeat.failed?
+
+        attempts = heartbeat.attempts_count + 1
+        heartbeat.update!(attempts_count: attempts, failure_reason: nil)
+
+        IprogWorkerHeartbeat::CallbackClient.deliver!(
+          url: IprogWorkerHeartbeat.config.callback_url,
+          bearer_token: IprogWorkerHeartbeat.config.auth_token,
+          worker_token: heartbeat.worker_token
+        )
+
+        heartbeat.update!(status: :callback_sent, callback_sent_at: Time.current)
+      end
+    rescue StandardError => e
+      handle_failure(heartbeat, e)
+    end
+
+    private
+
+    def handle_failure(heartbeat, error)
+      return if heartbeat.nil?
+
+      heartbeat.update(status: :failed, failure_reason: error.message.to_s.truncate(255))
+      IprogWorkerHeartbeat::FailureMailer.notify(
+        heartbeat: heartbeat,
+        event: "callback_failed",
+        details: error.message.to_s
+      ).deliver_now
+
+      if heartbeat.attempts_count < IprogWorkerHeartbeat.config.max_retries.to_i
+        self.class.set(wait: IprogWorkerHeartbeat.config.retry_wait_seconds.to_i.seconds).perform_later(heartbeat.id)
+      end
+    end
+  end
+end

data/app/mailers/iprog_worker_heartbeat/failure_mailer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IprogWorkerHeartbeat
+  class FailureMailer < ActionMailer::Base
+    def notify(heartbeat:, event:, details:)
+      @heartbeat = heartbeat
+      @event = event
+      @details = details
+
+      recipients = IprogWorkerHeartbeat.config.failure_email_recipients_array
+      return if recipients.empty?
+
+      mail(
+        to: recipients,
+        from: mailer_from,
+        subject: "#{IprogWorkerHeartbeat.config.mail_subject_prefix} #{event}"
+      )
+    end
+
+    private
+
+    def mailer_from
+      IprogWorkerHeartbeat.config.mailer_from.to_s.presence || "IPROG Worker Heartbeat <admin@iprogtech.com>"
+    end
+  end
+end

data/app/models/iprog_worker_heartbeat/heartbeat.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module IprogWorkerHeartbeat
+  class Heartbeat < ApplicationRecord
+    self.table_name = "worker_heartbeats"
+
+    enum :status, {
+      pending: "pending",
+      callback_sent: "callback_sent",
+      failed: "failed"
+    }, default: :pending, validate: true
+
+    validates :worker_token, presence: true, uniqueness: true
+    validates :received_at, presence: true
+  end
+end

data/app/services/iprog_worker_heartbeat/callback_client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module IprogWorkerHeartbeat
+  class CallbackClient
+    def self.deliver!(url:, bearer_token:, worker_token:)
+      uri = URI.parse(url)
+      request = Net::HTTP::Post.new(uri.request_uri.presence || "/", "Content-Type" => "application/json")
+      request["Authorization"] = "Bearer #{bearer_token}"
+      request.body = JSON.generate(worker_token:)
+
+      response = Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: 5,
+        read_timeout: 10
+      ) { |http| http.request(request) }
+
+      return response if response.is_a?(Net::HTTPSuccess)
+
+      raise "worker heartbeat callback failed with status=#{response.code}"
+    end
+  end
+end

data/app/views/iprog_worker_heartbeat/failure_mailer/notify.html.erb

@@ -0,0 +1,8 @@
+<p>Worker heartbeat failure event detected.</p>
+<ul>
+  <li><strong>Event:</strong> <%= @event %></li>
+  <li><strong>Worker Token:</strong> <%= @heartbeat&.worker_token || "N/A" %></li>
+  <li><strong>Status:</strong> <%= @heartbeat&.status || "N/A" %></li>
+  <li><strong>Attempt Count:</strong> <%= @heartbeat&.attempts_count || 0 %></li>
+  <li><strong>Details:</strong> <%= @details %></li>
+</ul>

data/app/views/iprog_worker_heartbeat/failure_mailer/notify.text.erb

@@ -0,0 +1,7 @@
+Worker heartbeat failure event detected.
+
+Event: <%= @event %>
+Worker Token: <%= @heartbeat&.worker_token || "N/A" %>
+Status: <%= @heartbeat&.status || "N/A" %>
+Attempt Count: <%= @heartbeat&.attempts_count || 0 %>
+Details: <%= @details %>

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+IprogWorkerHeartbeat::Engine.routes.draw do
+  post "/worker-heartbeat", to: "heartbeats#create"
+end

data/lib/generators/iprog_worker_heartbeat/install/install_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module IprogWorkerHeartbeat
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Installs iprog_worker_heartbeat initializer, route mount, and migration"
+
+      def copy_initializer
+        template "iprog_worker_heartbeat_initializer.rb", "config/initializers/iprog_worker_heartbeat.rb"
+      end
+
+      def add_mount_route
+        route_line = 'mount IprogWorkerHeartbeat::Engine => "/"'
+        routes_file = "config/routes.rb"
+        return if File.read(routes_file).include?(route_line)
+
+        inject_into_file routes_file, "  #{route_line}\n", after: "Rails.application.routes.draw do\n"
+      end
+
+      def create_migration_file
+        migration_template "create_worker_heartbeats.rb", "db/migrate/create_worker_heartbeats.rb"
+      end
+
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          format("%03d", current_migration_number(dirname) + 1)
+        end
+      end
+    end
+  end
+end

data/lib/generators/iprog_worker_heartbeat/install/templates/create_worker_heartbeats.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateWorkerHeartbeats < ActiveRecord::Migration[8.0]
+  def change
+    create_table :worker_heartbeats do |t|
+      t.string :worker_token, null: false
+      t.string :status, null: false, default: "pending"
+      t.datetime :received_at, null: false
+      t.datetime :callback_sent_at
+      t.integer :attempts_count, null: false, default: 0
+      t.string :failure_reason
+
+      t.timestamps
+    end
+
+    add_index :worker_heartbeats, :worker_token, unique: true
+    add_index :worker_heartbeats, :status
+  end
+end

data/lib/generators/iprog_worker_heartbeat/install/templates/iprog_worker_heartbeat_initializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+IprogWorkerHeartbeat.configure do |config|
+  config.auth_token = ENV["IPROG_WORKER_HEARTBEAT_AUTH_TOKEN"].presence ||
+    Rails.application.credentials.dig(:iprog_worker_heartbeat, :auth_token).presence ||
+    "local-heartbeat-token"
+  config.callback_url = "https://www.iprogtech.com/worker-heartbeat"
+  # config.failure_email_recipients = ["admin@iprogtech.com"]
+  # config.mailer_from = "IPROG Worker Heartbeat <admin@iprogtech.com>"
+  # config.mail_subject_prefix = "[IPROGSMS Worker Heartbeat]"
+  # config.notify_on_auth_failure = true
+  # config.callback_delay_seconds = 300
+  # config.max_retries = 3
+  # config.retry_wait_seconds = 60
+end

data/lib/iprog_worker_heartbeat/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module IprogWorkerHeartbeat
+  class Configuration
+    attr_accessor :auth_token,
+      :callback_url,
+      :failure_email_recipients,
+      :mailer_from,
+      :mail_subject_prefix,
+      :notify_on_auth_failure,
+      :callback_delay_seconds,
+      :max_retries,
+      :retry_wait_seconds
+
+    def initialize
+      @auth_token = nil
+      @callback_url = "https://www.iprogtech.com/worker-heartbeat"
+      @failure_email_recipients = []
+      @mailer_from = nil
+      @mail_subject_prefix = "[Worker Heartbeat]"
+      @notify_on_auth_failure = false
+      @callback_delay_seconds = 300
+      @max_retries = 3
+      @retry_wait_seconds = 60
+    end
+
+    def failure_email_recipients_array
+      Array(failure_email_recipients).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+    end
+
+    def validate!
+      raise ArgumentError, "IprogWorkerHeartbeat auth_token is required" if auth_token.to_s.strip.empty?
+    end
+  end
+end

data/lib/iprog_worker_heartbeat/engine.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module IprogWorkerHeartbeat
+  class Engine < ::Rails::Engine
+    isolate_namespace IprogWorkerHeartbeat
+
+    initializer "iprog_worker_heartbeat.validate_config" do
+      config.after_initialize do
+        next if Rails.env.test?
+
+        IprogWorkerHeartbeat.config.validate!
+      rescue ArgumentError => e
+        Rails.logger.error("iprog_worker_heartbeat config error: #{e.message}")
+        raise if Rails.env.production?
+      end
+    end
+  end
+end

data/lib/iprog_worker_heartbeat/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module IprogWorkerHeartbeat
+  VERSION = "0.1.1"
+end

data/lib/iprog_worker_heartbeat.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails"
+require_relative "iprog_worker_heartbeat/version"
+require_relative "iprog_worker_heartbeat/configuration"
+require_relative "iprog_worker_heartbeat/engine"
+
+module IprogWorkerHeartbeat
+  class << self
+    attr_writer :config
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config)
+    end
+  end
+end

data/spec/callback_client_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "../app/services/iprog_worker_heartbeat/callback_client"
+
+RSpec.describe IprogWorkerHeartbeat::CallbackClient do
+  it "raises on non-success response" do
+    response = instance_double(Net::HTTPUnauthorized, code: "401")
+    allow(response).to receive(:is_a?).with(Net::HTTPSuccess).and_return(false)
+    allow(Net::HTTP).to receive(:start).and_return(response)
+
+    expect do
+      described_class.deliver!(url: "https://example.com/worker-heartbeat", bearer_token: "x", worker_token: "y")
+    end.to raise_error(RuntimeError, /status=401/)
+  end
+end

data/spec/configuration_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe IprogWorkerHeartbeat::Configuration do
+  it "requires auth_token in validate!" do
+    config = described_class.new
+    expect { config.validate! }.to raise_error(ArgumentError)
+  end
+
+  it "normalizes failure recipients" do
+    config = described_class.new
+    config.failure_email_recipients = [" admin@iprogtech.com ", "", "admin@iprogtech.com"]
+    expect(config.failure_email_recipients_array).to eq(["admin@iprogtech.com"])
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "iprog_worker_heartbeat"
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = ".rspec_status"
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: iprog_worker_heartbeat
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Jayson Presto
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Provides /worker-heartbeat endpoint handling, persistence, delayed callback
+  job, and failure-only email alerts.
+email:
+- jaysonpresto.iprog21@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/iprog_worker_heartbeat/heartbeats_controller.rb
+- app/jobs/iprog_worker_heartbeat/callback_job.rb
+- app/mailers/iprog_worker_heartbeat/failure_mailer.rb
+- app/models/iprog_worker_heartbeat/heartbeat.rb
+- app/services/iprog_worker_heartbeat/callback_client.rb
+- app/views/iprog_worker_heartbeat/failure_mailer/notify.html.erb
+- app/views/iprog_worker_heartbeat/failure_mailer/notify.text.erb
+- config/routes.rb
+- lib/generators/iprog_worker_heartbeat/install/install_generator.rb
+- lib/generators/iprog_worker_heartbeat/install/templates/create_worker_heartbeats.rb
+- lib/generators/iprog_worker_heartbeat/install/templates/iprog_worker_heartbeat_initializer.rb
+- lib/iprog_worker_heartbeat.rb
+- lib/iprog_worker_heartbeat/configuration.rb
+- lib/iprog_worker_heartbeat/engine.rb
+- lib/iprog_worker_heartbeat/version.rb
+- spec/callback_client_spec.rb
+- spec/configuration_spec.rb
+- spec/spec_helper.rb
+homepage: https://rubygems.org/gems/iprog_worker_heartbeat
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://rubygems.org/gems/iprog_worker_heartbeat
+  source_code_uri: https://github.com/iprog21/iprog_worker_heartbeat
+  changelog_uri: https://github.com/iprog21/iprog_worker_heartbeat/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.21
+signing_key:
+specification_version: 4
+summary: Rails worker-heartbeat client workflow for monitor callbacks
+test_files: []