crontinel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ebf0a7c7a77045bc19c5162da2eba4785aaf2c406a8e2ed6a11b74669434391
+  data.tar.gz: 5050c359b5bd59db3216c2e1259a6d2af0a9dddf563b4579c76472e3bfb7844c
+SHA512:
+  metadata.gz: e91c8ec54ceb8a9e0e4c2f2aa5e79d0221ce380ef74f1046769d7550af606a48e174d71aee02c8ad3ff26baa45d3859918c14d37da5b7b01cb1077756ac3fff2
+  data.tar.gz: 888df4ef9e92f808bd3ddd278113818dc02d47d4903995409fdc195cb543a5fba9570109971011c72c34b09d13de4e4f561deff2a6ef376d65bb9579142cbfa0

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes will be documented in this file.
+
+## [0.1.0] - 2026-04-18
+
+- Initial release
+- Task tracking: `task_started`, `task_finished`, `task_failed`
+- Worker heartbeat support
+- Faraday-based HTTP client
+- Minitest test suite
+- Rubocop linting

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harun R Rayhan
+
+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,118 @@
+# Crontinel Ruby
+
+Ruby SDK for [Crontinel](https://crontinel.com) — open-source monitoring for cron jobs, background workers, and scheduled tasks.
+
+Unlike generic uptime tools, Crontinel knows when a job started but crashed silently, when a queue worker stopped processing, or when a cron fired but did nothing.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "crontinel", "~> 0.1"
+```
+
+Or install directly:
+
+```bash
+gem install crontinel
+```
+
+## Quick Start
+
+```ruby
+require "crontinel"
+
+# Configure with your API key
+client = Crontinel.client(api_key: "your_api_key_here")
+
+# Record a cron job starting
+client.task_started(name: "send-daily-summary")
+
+# Do your work...
+result = send_daily_summary
+
+# Record success
+client.task_finished(name: "send-daily-summary", duration_ms: 520)
+```
+
+### With error handling
+
+```ruby
+client = Crontinel.client(api_key: ENV["CRONTINEL_API_KEY"])
+
+begin
+  client.task_started(name: "process-invoices")
+  process_invoices
+  client.task_finished(name: "process-invoices", duration_ms: 3200)
+rescue => e
+  client.task_failed(name: "process-invoices", error: e.message, duration_ms: 150)
+  raise
+end
+```
+
+### Worker heartbeat
+
+For queue workers (Sidekiq, etc.):
+
+```ruby
+worker = Crontinel.client(api_key: ENV["CRONTINEL_API_KEY"])
+
+# In your worker loop or at intervals
+worker.worker_heartbeat(
+  name: "email-worker",
+  status: "running",
+  jobs_processed: 142,
+  jobs_failed: 2,
+  memory_mb: 128
+)
+```
+
+## Configuration
+
+```ruby
+client = Crontinel.client do |config|
+  config.api_key = ENV["CRONTINEL_API_KEY"]
+  config.endpoint = "https://app.crontinel.com/api/v1" # optional, default works for hosted
+  config.timeout = 10       # seconds, default: 10
+  config.open_timeout = 5    # seconds, default: 5
+end
+```
+
+## API
+
+### `Crontinel.client(api_key:, endpoint: nil)`
+
+Create a new Crontinel client.
+
+### `#task_started(name:, output: nil)`
+
+Record that a task began execution.
+
+### `#task_finished(name:, output: nil, duration_ms: nil)`
+
+Record that a task completed successfully.
+
+### `#task_failed(name:, error: nil, output: nil, duration_ms: nil)`
+
+Record that a task failed.
+
+### `#worker_heartbeat(name:, status:, jobs_processed: nil, jobs_failed: nil, memory_mb: nil)`
+
+Send a heartbeat for a queue worker.
+
+### `#task_runs(name:, limit: 10)`
+
+Get recent task runs. Returns an array of `Crontinel::TaskRun` objects.
+
+### `#health_check`
+
+Returns `true` if Crontinel is reachable, `false` otherwise.
+
+## Supported Ruby Versions
+
+Ruby 2.7+
+
+## License
+
+MIT © Harun R Rayhan

data/lib/crontinel/version.rb

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

data/lib/crontinel.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "time"
+require "crontinel/version"
+
+module Crontinel
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class NetworkError < Error; end
+
+  # Configuration for the Crontinel client
+  class Config
+    attr_accessor :api_key, :endpoint, :timeout, :open_timeout
+
+    def initialize
+      @api_key = nil
+      @endpoint = "https://app.crontinel.com"
+      @timeout = 10
+      @open_timeout = 5
+    end
+
+    def validate!
+      raise ConfigurationError, "api_key is required" if api_key.nil? || api_key.to_s.strip.empty?
+    end
+  end
+
+  # Represents a single scheduled task / cron job run
+  class TaskRun
+    attr_reader :id, :name, :started_at, :finished_at, :status, :duration_ms, :output
+
+    def initialize(attrs = {})
+      @id = attrs["id"]
+      @name = attrs["command"] || attrs["name"]
+      @started_at = attrs["started_at"] ? Time.parse(attrs["started_at"]) : nil
+      @finished_at = attrs["finished_at"] ? Time.parse(attrs["finished_at"]) : nil
+      @status = attrs["last_status"] || attrs["status"] || "unknown"
+      @duration_ms = attrs["duration_ms"]
+      @output = attrs["output"]
+    end
+
+    def success?
+      @status == "completed" || @status == "success"
+    end
+
+    def failed?
+      @status == "failed"
+    end
+
+    def running?
+      @status == "running"
+    end
+  end
+
+  # Represents a worker's current state
+  class WorkerState
+    attr_reader :name, :status, :jobs_processed, :jobs_failed, :memory_mb
+
+    def initialize(attrs = {})
+      @name = attrs["name"]
+      @status = attrs["status"] || "unknown"
+      @jobs_processed = attrs["processed"] || attrs["jobs_processed"] || 0
+      @jobs_failed = attrs["failed"] || attrs["jobs_failed"] || 0
+      @memory_mb = attrs["memory_mb"]
+    end
+
+    def alive?
+      @status == "running" || @status == "active"
+    end
+  end
+
+  # Main Crontinel client
+  class Client
+    attr_reader :config
+
+    NETWORK_ERRORS = [
+      Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+      SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET
+    ].freeze
+
+    def initialize(api_key: nil, endpoint: nil)
+      @config = Config.new
+      @config.api_key = api_key if api_key
+      @config.endpoint = endpoint if endpoint
+      yield @config if block_given?
+      @config.validate!
+    end
+
+    # ── Event reporting (uses MCP notify/*) ───────────────────
+
+    # Record a scheduled task completing successfully
+    def task_finished(name:, output: nil, duration_ms: nil)
+      mcp_call("notify/schedule_run", {
+        command: name,
+        exit_code: 0,
+        duration_ms: duration_ms,
+        output: output,
+        ran_at: Time.now.utc.iso8601(3),
+        app: "ruby",
+      })
+    end
+
+    # Record a scheduled task failing
+    def task_failed(name:, error: nil, output: nil, duration_ms: nil)
+      mcp_call("notify/schedule_run", {
+        command: name,
+        exit_code: error ? 1 : 1,
+        duration_ms: duration_ms,
+        output: output || error,
+        ran_at: Time.now.utc.iso8601(3),
+        app: "ruby",
+      })
+    end
+
+    # Record a queue worker heartbeat / processed batch
+    def worker_heartbeat(name:, status: "running", jobs_processed: nil, jobs_failed: nil, memory_mb: nil)
+      mcp_call("notify/queue_processed", {
+        queue: name,
+        processed: jobs_processed || 0,
+        failed: jobs_failed || 0,
+        ran_at: Time.now.utc.iso8601(3),
+        app: "ruby",
+      }.compact)
+    end
+
+    # Send a custom event
+    def event(key:, message:, state: "info", metadata: {})
+      mcp_call("notify/event", {
+        key: key,
+        message: message,
+        state: state,
+        metadata: metadata,
+        ran_at: Time.now.utc.iso8601(3),
+        app: "ruby",
+      })
+    end
+
+    # Send a Horizon snapshot
+    def horizon_snapshot(supervisors:, failed_jobs_per_minute: 0, paused: false)
+      mcp_call("notify/horizon_snapshot", {
+        supervisors: supervisors,
+        failed_jobs_per_minute: failed_jobs_per_minute,
+        paused: paused,
+        ran_at: Time.now.utc.iso8601(3),
+        app: "ruby",
+      })
+    end
+
+    # ── Query methods (uses MCP tools/call) ───────────────────
+
+    # List all scheduled jobs
+    def scheduled_jobs
+      result = mcp_call("tools/call", { name: "list_scheduled_jobs", arguments: {} })
+      (result["content"] || []).flat_map { |c| JSON.parse(c["text"]) rescue [] }.map { |r| TaskRun.new(r) }
+    end
+
+    # Get status for a specific cron command
+    def cron_status(command:)
+      result = mcp_call("tools/call", { name: "get_cron_status", arguments: { command: command } })
+      (result["content"] || []).flat_map { |c| JSON.parse(c["text"]) rescue [] }.first
+    end
+
+    # List recent alerts
+    def recent_alerts(hours: 24)
+      result = mcp_call("tools/call", { name: "list_recent_alerts", arguments: { hours: hours } })
+      (result["content"] || []).flat_map { |c| JSON.parse(c["text"]) rescue [] }
+    end
+
+    # Check if Crontinel is reachable (direct HTTP, not MCP)
+    def health_check
+      get("/health")
+      true
+    rescue NetworkError, JSON::ParserError
+      false
+    end
+
+    # ── Backward-compatible aliases ───────────────────────────
+    def task_started(name:, output: nil)
+      task_finished(name: name, output: output)
+    end
+
+    def task_runs(name:, limit: 10)
+      scheduled_jobs.select { |r| r.name&.include?(name) }.first(limit)
+    end
+
+    def worker_state(name:)
+      WorkerState.new("name" => name, "status" => "unknown")
+    end
+
+    private
+
+    # Unified MCP JSON-RPC call against /api/mcp
+    def mcp_call(method, params = {})
+      uri = URI("#{@config.endpoint}/api/mcp")
+
+      body = {
+        jsonrpc: "2.0",
+        id: (Time.now.to_f * 1000).to_i,
+        method: method,
+        params: params,
+      }
+
+      req = Net::HTTP::Post.new(uri)
+      req["Authorization"] = "Bearer #{@config.api_key}"
+      req["Content-Type"] = "application/json"
+      req.body = JSON.generate(body)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.timeout
+
+      response = http.start { http.request(req) }
+
+      case response
+      when Net::HTTPSuccess
+        data = JSON.parse(response.body)
+        if data["error"]
+          raise NetworkError, "Crontinel RPC error: #{data["error"]["code"]}: #{data["error"]["message"]}"
+        end
+        data["result"]
+      else
+        raise NetworkError, "Crontinel API error: #{response.code} #{response.message}"
+      end
+    rescue *NETWORK_ERRORS => e
+      raise NetworkError, "Failed to connect to Crontinel: #{e.message}"
+    end
+
+    # Direct HTTP GET (for /health)
+    def get(path)
+      uri = URI("#{@config.endpoint}#{path}")
+      req = Net::HTTP::Get.new(uri)
+      req["Authorization"] = "Bearer #{@config.api_key}"
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.timeout
+
+      response = http.start { http.request(req) }
+
+      case response
+      when Net::HTTPSuccess
+        begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          response.body
+        end
+      else
+        raise NetworkError, "Crontinel API error: #{response.code} #{response.message}"
+      end
+    rescue *NETWORK_ERRORS => e
+      raise NetworkError, "Failed to connect to Crontinel: #{e.message}"
+    end
+  end
+
+  class << self
+    def client(api_key: nil, endpoint: nil, &block)
+      Client.new(api_key: api_key, endpoint: endpoint, &block)
+    end
+
+    # Rails-style configure block (used by crontinel-rails railtie)
+    def configure
+      yield config
+      config
+    end
+    alias_method :setup, :configure
+
+    def config
+      @config ||= Configuration.new
+    end
+  end
+
+  # Configuration object for module-level setup
+  class Configuration
+    attr_accessor :api_key, :endpoint
+
+    def initialize
+      @api_key = ENV.fetch("CRONTINEL_API_KEY", nil)
+      @endpoint = ENV.fetch("CRONTINEL_API_URL", "https://app.crontinel.com")
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: crontinel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Harun R Rayhan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-30 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Crontinel monitors your cron jobs, background workers, and scheduled tasks.
+  Unlike generic uptime tools, Crontinel knows when a job started but crashed silently,
+  when a queue worker stopped processing, or when a cron fired but did nothing.
+email:
+- me@harunray.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/crontinel.rb
+- lib/crontinel/version.rb
+homepage: https://crontinel.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://crontinel.com
+  source_code_uri: https://github.com/crontinel/ruby
+  changelog_uri: https://github.com/crontinel/ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/crontinel/ruby/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Crontinel monitoring SDK for Ruby — track cron jobs and background workers
+test_files: []