cronbeats-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a49b421ceb99334edb0b7b1305d50c07a681d763f3d4733b89218445055c7960
+  data.tar.gz: e8d4ad7148ca5a62b30eed9ce2b6c8884b4a8a05dea497d850765a9c2db293c7
+SHA512:
+  metadata.gz: 594248ec2d29731561af909b01ab81d37049c1900598348317e8f87607b9f4db6d14520bd044024ffcaadf8e6e136ce76c71e460a5fd2153d65691782226b83d
+  data.tar.gz: 920f785a34beb2adf3d2bf079239e451aae7d8b84fe8afc6c8298d4b754bdc8a60e538dfd90c44cdf163f9ad6ac82b6872e7fecade665bdcbf3b3aa7e4b095d5

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rspec", "~> 3.13"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CronBeats
+
+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,38 @@
+# CronBeats Ruby SDK (Ping)
+
+Official Ruby SDK for CronBeats ping telemetry.
+
+## Install
+
+```bash
+gem install cronbeats-ruby
+```
+
+## Quick Usage
+
+```ruby
+require "cronbeats_ruby"
+
+client = CronBeatsRuby::PingClient.new("abc123de")
+client.start
+# ...your work...
+client.success
+```
+
+## Progress Updates
+
+```ruby
+client.progress(50, "Processing batch 50/100")
+
+client.progress({
+  seq: 75,
+  message: "Almost done"
+})
+```
+
+## Notes
+
+- SDK uses `POST` for telemetry requests.
+- `jobKey` must be exactly 8 Base62 characters.
+- Retries happen only for network errors, HTTP `429`, and HTTP `5xx`.
+- Default 5s timeout ensures the SDK never blocks your cron job if CronBeats is unreachable.

data/lib/cronbeats_ruby/errors.rb

@@ -0,0 +1,19 @@
+module CronBeatsRuby
+  class SdkError < StandardError
+  end
+
+  class ValidationError < SdkError
+  end
+
+  class ApiError < SdkError
+    attr_reader :code, :http_status, :retryable, :raw
+
+    def initialize(code:, message:, http_status: nil, retryable: false, raw: nil)
+      super(message)
+      @code = code
+      @http_status = http_status
+      @retryable = retryable
+      @raw = raw
+    end
+  end
+end

data/lib/cronbeats_ruby/http.rb

@@ -0,0 +1,30 @@
+require "json"
+require "net/http"
+require "uri"
+
+module CronBeatsRuby
+  class NetHttpClient
+    def request(method:, url:, headers:, body:, timeout_ms:)
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      timeout = [timeout_ms.to_f / 1000.0, 0.001].max
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+      req = Net::HTTP.const_get(method.capitalize).new(uri.request_uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body unless body.nil?
+
+      res = http.request(req)
+      {
+        status: res.code.to_i,
+        body: res.body.to_s,
+        headers: res.to_hash.transform_keys(&:downcase),
+      }
+    rescue StandardError => e
+      raise SdkError, e.message
+    end
+  end
+end

data/lib/cronbeats_ruby/ping_client.rb

@@ -0,0 +1,184 @@
+require "json"
+
+module CronBeatsRuby
+  class PingClient
+    def initialize(job_key, options = {})
+      assert_job_key(job_key)
+
+      @job_key = job_key
+      @base_url = (options[:base_url] || "https://cronbeats.io").to_s.sub(%r{/+$}, "")
+      @timeout_ms = Integer(options[:timeout_ms] || 5000)
+      @max_retries = Integer(options[:max_retries] || 2)
+      @retry_backoff_ms = Integer(options[:retry_backoff_ms] || 250)
+      @retry_jitter_ms = Integer(options[:retry_jitter_ms] || 100)
+      @user_agent = (options[:user_agent] || "cronbeats-ruby-sdk/0.1.0").to_s
+      @http_client = options[:http_client] || NetHttpClient.new
+    end
+
+    def ping
+      request("ping", "/ping/#{@job_key}")
+    end
+
+    def start
+      request("start", "/ping/#{@job_key}/start")
+    end
+
+    def end(status = "success")
+      status_value = status.to_s.strip.downcase
+      unless %w[success fail].include?(status_value)
+        raise ValidationError, 'Status must be "success" or "fail".'
+      end
+
+      request("end", "/ping/#{@job_key}/end/#{status_value}")
+    end
+
+    def success
+      self.end("success")
+    end
+
+    def fail
+      self.end("fail")
+    end
+
+    def progress(seq_or_options = nil, message = nil)
+      seq = nil
+      msg = message
+
+      if seq_or_options.is_a?(Integer)
+        seq = seq_or_options
+      elsif seq_or_options.is_a?(Hash)
+        seq = seq_or_options.key?(:seq) ? Integer(seq_or_options[:seq]) : nil
+        msg = (seq_or_options[:message] || msg || "").to_s
+      end
+
+      if !seq.nil? && seq.negative?
+        raise ValidationError, "Progress seq must be a non-negative integer."
+      end
+
+      safe_msg = (msg || "").to_s
+      safe_msg = safe_msg[0, 255] if safe_msg.length > 255
+
+      unless seq.nil?
+        return request("progress", "/ping/#{@job_key}/progress/#{seq}", { message: safe_msg })
+      end
+
+      body = { message: safe_msg }
+      body[:progress] = seq_or_options if seq_or_options.is_a?(Integer)
+      request("progress", "/ping/#{@job_key}/progress", body)
+    end
+
+    private
+
+    def request(action, path, body = {})
+      attempt = 0
+      url = "#{@base_url}#{path}"
+
+      payload =
+        begin
+          body.empty? ? nil : JSON.generate(body)
+        rescue StandardError
+          raise SdkError, "Failed to encode request payload."
+        end
+
+      loop do
+        begin
+          response = @http_client.request(
+            method: "post",
+            url: url,
+            headers: {
+              "Content-Type" => "application/json",
+              "Accept" => "application/json",
+              "User-Agent" => @user_agent,
+            },
+            body: payload,
+            timeout_ms: @timeout_ms
+          )
+        rescue SdkError => e
+          if attempt >= @max_retries
+            raise ApiError.new(
+              code: "NETWORK_ERROR",
+              http_status: nil,
+              retryable: true,
+              message: e.message,
+              raw: e
+            )
+          end
+
+          attempt += 1
+          sleep_with_backoff(attempt)
+          next
+        end
+
+        status = response[:status].to_i
+        decoded = safe_json(response[:body].to_s)
+
+        if status >= 200 && status < 300
+          return normalize_success(action, decoded)
+        end
+
+        error = map_error(status)
+        if error[:retryable] && attempt < @max_retries
+          attempt += 1
+          sleep_with_backoff(attempt)
+          next
+        end
+
+        raise ApiError.new(
+          code: error[:code],
+          http_status: status,
+          retryable: error[:retryable],
+          message: (decoded["message"] || "Request failed").to_s,
+          raw: decoded
+        )
+      end
+    end
+
+    def normalize_success(action, payload)
+      {
+        "ok" => true,
+        "action" => (payload["action"] || action).to_s,
+        "jobKey" => (payload["job_key"] || @job_key).to_s,
+        "timestamp" => (payload["timestamp"] || "").to_s,
+        "processingTimeMs" => float_or_zero(payload["processing_time_ms"]),
+        "nextExpected" => payload.key?("next_expected") ? payload["next_expected"]&.to_s : nil,
+        "raw" => payload,
+      }
+    end
+
+    def map_error(status)
+      return { code: "VALIDATION_ERROR", retryable: false } if status == 400
+      return { code: "NOT_FOUND", retryable: false } if status == 404
+      return { code: "RATE_LIMITED", retryable: true } if status == 429
+      return { code: "SERVER_ERROR", retryable: true } if status >= 500
+
+      { code: "UNKNOWN_ERROR", retryable: false }
+    end
+
+    def assert_job_key(job_key)
+      return if /\A[a-zA-Z0-9]{8}\z/.match?(job_key.to_s)
+
+      raise ValidationError, "jobKey must be exactly 8 Base62 characters."
+    end
+
+    def sleep_with_backoff(attempt)
+      base_ms = @retry_backoff_ms * (2**[attempt - 1, 0].max)
+      jitter_ms = rand(0..[@retry_jitter_ms, 0].max)
+      Kernel.sleep((base_ms + jitter_ms) / 1000.0)
+    end
+
+    def safe_json(raw)
+      parsed = JSON.parse(raw)
+      return parsed if parsed.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    ensure
+      return({ "message" => "Invalid JSON response" }) if defined?(parsed).nil? || !parsed.is_a?(Hash)
+    end
+
+    def float_or_zero(value)
+      Float(value)
+    rescue StandardError
+      0.0
+    end
+  end
+end

data/lib/cronbeats_ruby/version.rb

@@ -0,0 +1,3 @@
+module CronBeatsRuby
+  VERSION = "0.1.0"
+end

data/lib/cronbeats_ruby.rb

@@ -0,0 +1,7 @@
+require_relative "cronbeats_ruby/version"
+require_relative "cronbeats_ruby/errors"
+require_relative "cronbeats_ruby/http"
+require_relative "cronbeats_ruby/ping_client"
+
+module CronBeatsRuby
+end

data/spec/ping_client_spec.rb

@@ -0,0 +1,175 @@
+require "json"
+require "cronbeats_ruby"
+
+RSpec.describe CronBeatsRuby::PingClient do
+  class StubHttpClient
+    attr_reader :calls
+
+    def initialize(responses: [], network_failures: 0)
+      @responses = responses
+      @network_failures = network_failures
+      @calls = []
+    end
+
+    def request(method:, url:, headers:, body:, timeout_ms:)
+      @calls << { method: method, url: url, body: body, timeout_ms: timeout_ms, headers: headers }
+
+      if @network_failures.positive?
+        @network_failures -= 1
+        raise CronBeatsRuby::SdkError, "socket timeout"
+      end
+
+      @responses.shift || { status: 200, body: "{}", headers: {} }
+    end
+  end
+
+  it "rejects invalid job key" do
+    expect { described_class.new("invalid-key") }.to raise_error(CronBeatsRuby::ValidationError)
+  end
+
+  it "normalizes success response" do
+    stub = StubHttpClient.new(
+      responses: [
+        {
+          status: 200,
+          body: JSON.generate(
+            {
+              status: "success",
+              message: "OK",
+              action: "ping",
+              job_key: "abc123de",
+              timestamp: "2026-02-25 12:00:00",
+              processing_time_ms: 8.25,
+            }
+          ),
+          headers: {},
+        },
+      ]
+    )
+    client = described_class.new("abc123de", http_client: stub)
+    result = client.ping
+    expect(result["ok"]).to eq(true)
+    expect(result["action"]).to eq("ping")
+    expect(result["jobKey"]).to eq("abc123de")
+    expect(result["processingTimeMs"]).to eq(8.25)
+  end
+
+  it "maps 404 to NOT_FOUND" do
+    stub = StubHttpClient.new(
+      responses: [
+        { status: 404, body: JSON.generate({ status: "error", message: "Job not found" }), headers: {} },
+      ]
+    )
+    client = described_class.new("abc123de", http_client: stub, max_retries: 0)
+    expect { client.ping }.to raise_error(CronBeatsRuby::ApiError) { |err|
+      expect(err.code).to eq("NOT_FOUND")
+      expect(err.retryable).to eq(false)
+      expect(err.http_status).to eq(404)
+    }
+  end
+
+  it "retries on 429 and then succeeds" do
+    stub = StubHttpClient.new(
+      responses: [
+        { status: 429, body: JSON.generate({ status: "error", message: "Too many requests" }), headers: {} },
+        {
+          status: 200,
+          body: JSON.generate(
+            {
+              status: "success",
+              message: "OK",
+              action: "ping",
+              job_key: "abc123de",
+              timestamp: "2026-02-25 12:00:00",
+              processing_time_ms: 7.1,
+            }
+          ),
+          headers: {},
+        },
+      ]
+    )
+    client = described_class.new(
+      "abc123de",
+      http_client: stub,
+      max_retries: 2,
+      retry_backoff_ms: 1,
+      retry_jitter_ms: 0
+    )
+    result = client.ping
+    expect(result["ok"]).to eq(true)
+    expect(stub.calls.length).to eq(2)
+  end
+
+  it "does not retry on 400" do
+    stub = StubHttpClient.new(
+      responses: [
+        { status: 400, body: JSON.generate({ status: "error", message: "Invalid request" }), headers: {} },
+      ]
+    )
+    client = described_class.new("abc123de", http_client: stub, max_retries: 2)
+    expect { client.ping }.to raise_error(CronBeatsRuby::ApiError) { |err|
+      expect(err.code).to eq("VALIDATION_ERROR")
+      expect(err.retryable).to eq(false)
+    }
+    expect(stub.calls.length).to eq(1)
+  end
+
+  it "retries on network errors and then succeeds" do
+    stub = StubHttpClient.new(
+      responses: [
+        {
+          status: 200,
+          body: JSON.generate(
+            {
+              status: "success",
+              message: "OK",
+              action: "ping",
+              job_key: "abc123de",
+              timestamp: "2026-02-25 12:00:00",
+              processing_time_ms: 4.2,
+            }
+          ),
+          headers: {},
+        },
+      ],
+      network_failures: 1
+    )
+    client = described_class.new(
+      "abc123de",
+      http_client: stub,
+      max_retries: 2,
+      retry_backoff_ms: 1,
+      retry_jitter_ms: 0
+    )
+    result = client.ping
+    expect(result["ok"]).to eq(true)
+    expect(stub.calls.length).to eq(2)
+  end
+
+  it "normalizes progress and truncates message to 255" do
+    stub = StubHttpClient.new(
+      responses: [
+        {
+          status: 200,
+          body: JSON.generate(
+            {
+              status: "success",
+              message: "OK",
+              action: "progress",
+              job_key: "abc123de",
+              timestamp: "2026-02-25 12:00:00",
+              processing_time_ms: 8,
+            }
+          ),
+          headers: {},
+        },
+      ]
+    )
+    long_msg = "x" * 300
+    client = described_class.new("abc123de", http_client: stub)
+    client.progress({ seq: 50, message: long_msg })
+    expect(stub.calls[0][:url]).to end_with("/ping/abc123de/progress/50")
+    sent = JSON.parse(stub.calls[0][:body])
+    expect(sent["message"].length).to eq(255)
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: cronbeats-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- CronBeats
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-25 00:00:00.000000000 Z
+dependencies: []
+description: Ruby client for CronBeats ping, start/end, and progress telemetry APIs.
+email:
+- support@cronbeats.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lib/cronbeats_ruby.rb
+- lib/cronbeats_ruby/errors.rb
+- lib/cronbeats_ruby/http.rb
+- lib/cronbeats_ruby/ping_client.rb
+- lib/cronbeats_ruby/version.rb
+- spec/ping_client_spec.rb
+homepage: https://github.com/cronbeats/cronbeats-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/cronbeats/cronbeats-ruby
+  source_code_uri: https://github.com/cronbeats/cronbeats-ruby
+  bug_tracker_uri: https://github.com/cronbeats/cronbeats-ruby/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key:
+specification_version: 4
+summary: Official CronBeats Ping SDK for Ruby.
+test_files: []