rails_orbit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 324f351194399de6bab396eda353654d014715422f8dd0b552d9a2df150240f8
+  data.tar.gz: 26243ec5f12b9425e94ba3201685ecc3d554af0b5e617b67927f49362bb6c3b1
+SHA512:
+  metadata.gz: 869988c024f9969d5d24019062d54670a2dc4d6b4c0c1e3bc1e8248defabf6423dd23226467ab8bcb7f020398c9f829d85802b77c5435616115d94ffdb1b0271
+  data.tar.gz: 20cc91a576016168bbd8f66a2eadee06beb2c3940dd5ee6e30b158b2b52f3f74605c7f444960ce095e27e420ffd36ddb2eaf3f3db6495a41301a99b888fb0499

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0] - 2026-03-24
+
+- Initial release
+- Multi-adapter storage (SQLite, host DB, external)
+- Instrumentation for solid_queue, solid_cache, solid_errors
+- Hotwire-powered dashboard with Turbo Streams
+- Kamal infrastructure poller (opt-in)
+- Data retention job
+- Install generator

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 dev-ham
+
+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,241 @@
+# rails_orbit
+
+[![CI](https://github.com/dev-ham/rails_orbit/actions/workflows/ci.yml/badge.svg)](https://github.com/dev-ham/rails_orbit/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/rails_orbit.svg)](https://badge.fury.io/rb/rails_orbit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+A mountable Rails engine that gives you an observability dashboard for applications running the Solid stack — `solid_queue`, `solid_cache`, and `solid_errors`. Mount it, and you get real-time metrics without external services.
+
+## Why rails_orbit
+
+Rails 8 ships with Solid Queue, Solid Cache, and Solid Errors. They work great, but there is no single place to see how they are performing. rails_orbit fills that gap:
+
+- One `/orbit` route gives you jobs, cache, and error metrics in a single dashboard.
+- Zero external dependencies — no Redis, no Datadog, no Prometheus.
+- Non-blocking writes using `concurrent-ruby` so your app stays fast.
+- Works with SQLite, Postgres, MySQL, or any database URL.
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.1
+- At least one of: `solid_queue`, `solid_cache`, `solid_errors`
+
+## Quick Start
+
+```ruby
+# Gemfile
+gem "rails_orbit"
+```
+
+```bash
+bundle install
+bin/rails generate rails_orbit:install
+```
+
+The generator creates an initializer, a migration, and mounts the engine route. What happens next depends on your storage adapter:
+
+**SQLite (default):** The table is created automatically when the app boots. No migration needed — Orbit uses its own `db/rails_orbit.sqlite3` file, separate from your app's database.
+
+**Host database or external:** Run the migration so the table lands in your primary database:
+
+```bash
+bin/rails db:migrate
+```
+
+Set credentials for the dashboard:
+
+```bash
+export ORBIT_USER=admin
+export ORBIT_PASSWORD=secret
+```
+
+Visit `/orbit` in your browser. That is it.
+
+### Useful Commands
+
+```bash
+bin/rails rails_orbit:setup   # manually create the metrics table
+bin/rails rails_orbit:status  # show config, adapter, table status, metric count
+```
+
+## Dashboard
+
+The dashboard has four pages, all with a dark theme and live updates via Turbo Streams.
+
+Every page includes a **date range picker** — choose from 1h, 6h, 24h (default), 7d, or 30d to view historical data.
+
+### Overview
+
+The main page shows your application health at a glance:
+
+- **Jobs** — enqueued, failed, retried, and discarded counts with hourly trend arrows
+- **Cache** — hit rate with a visual bar, plus hits, misses, and write counts
+- **Errors** — total error count with severity coloring
+- **Interactive charts** — three SVG area charts for Job Duration, Cache Hit Rate, and Error Count. Hover over any point to see the exact value and timestamp.
+- **Live refresh** — a "last updated" indicator shows when data was last fetched
+
+Each card has a colored left border that shifts from green to amber to red based on thresholds.
+
+Charts use bucketed SQL aggregation (not raw data) so they stay fast even at the 30-day range.
+
+### Jobs
+
+A detailed per-queue breakdown:
+
+- Summary cards at the top — total enqueued, average duration, failed, discarded
+- A table showing each queue with columns for enqueued, avg duration, failed, retried, and discarded
+- Rows with failures get a subtle red background so they stand out
+- All counts scoped to the selected date range
+
+### Cache
+
+Full cache performance visibility:
+
+- Total reads split into hits and misses (not just a combined number)
+- A visual hit-rate bar — green fill represents the hit percentage
+- Write, delete, and fetch-hit counts
+- Miss rate shown separately so you can spot cache warming issues
+
+### Errors
+
+Exceptions grouped by class for faster triage:
+
+- Each exception class shows occurrence count and "last seen" time
+- Up to 5 recent messages displayed per group
+- Resolved status shown if solid_errors supports it
+- Scoped to the selected date range
+
+## Storage Adapters
+
+| Adapter | Config | When to Use |
+|---------|--------|-------------|
+| SQLite (default) | `:sqlite` | Local dev, VPS, persistent volumes |
+| Host database | `:host_db` | Heroku, Railway, managed PaaS |
+| External URL | `:external` | PlanetScale, Neon, Turso |
+
+Using `:sqlite` on platforms with ephemeral filesystems (Heroku, Railway) will lose data on deploy. The gem detects this and warns you.
+
+```ruby
+RailsOrbit.configure do |config|
+  config.storage_adapter = :host_db
+end
+```
+
+For an external database:
+
+```ruby
+RailsOrbit.configure do |config|
+  config.storage_adapter = :external
+  config.storage_url     = ENV["ORBIT_DATABASE_URL"]
+end
+```
+
+## Configuration
+
+```ruby
+# config/initializers/rails_orbit.rb
+RailsOrbit.configure do |config|
+  config.storage_adapter  = :sqlite       # :sqlite, :host_db, or :external
+  config.retention_days   = 7             # auto-purge metrics older than this
+  config.poll_interval    = 5             # seconds between live updates
+  config.dashboard_title  = "Orbit"       # shown in nav and page title
+  config.kamal_enabled    = false         # enable Kamal container stats
+end
+```
+
+## Authentication
+
+The dashboard is protected by a configurable auth block. Three common patterns:
+
+### HTTP Basic (default)
+
+Set `ORBIT_USER` and `ORBIT_PASSWORD` environment variables. No code changes needed.
+
+### Devise
+
+```ruby
+config.authenticate_with do |controller|
+  controller.authenticate_user!
+  controller.head(:forbidden) unless controller.current_user&.admin?
+end
+```
+
+### Custom
+
+```ruby
+config.authenticate_with do |controller|
+  unless controller.session[:orbit_authenticated]
+    controller.redirect_to controller.main_app.root_path, alert: "Not authorized"
+  end
+end
+```
+
+## Instrumentation
+
+rails_orbit automatically subscribes to these ActiveSupport notifications:
+
+| Source | Events Captured |
+|--------|----------------|
+| solid_queue | enqueued, performed (with duration), failed, retried, discarded |
+| solid_cache | read hit, read miss, write, delete, fetch hit |
+| solid_errors | error recorded (with exception class) |
+
+All writes happen in a background thread. If the write queue is full, events are discarded rather than blocking your app.
+
+## Data Retention
+
+Schedule the built-in retention job to keep your database lean:
+
+```yaml
+# config/recurring.yml (solid_queue)
+rails_orbit_retention:
+  class: "RailsOrbit::RetentionJob"
+  schedule: "0 2 * * *"
+```
+
+This deletes metrics older than `retention_days` (default: 7).
+
+## Kamal Integration
+
+Optional SSH-based container stats polling. Disabled by default.
+
+```ruby
+# Gemfile
+gem "sshkit", "~> 1.21"
+```
+
+```ruby
+RailsOrbit.configure do |config|
+  config.kamal_enabled      = true
+  config.kamal_ssh_key_path = Rails.root.join(".kamal", "id_ed25519")
+end
+```
+
+Reads `config/deploy.yml` to discover servers. Collects CPU and memory stats from Docker containers every 30 seconds.
+
+**Security:**
+- SSH key path must be set explicitly — never auto-discovered
+- Never commit SSH keys to your repository
+- Only enable in production environments
+
+## Contributing
+
+```bash
+git clone https://github.com/dev-ham/rails_orbit.git
+cd rails_orbit
+bundle install
+bundle exec rspec
+```
+
+Tests run against a dummy Rails app in `spec/dummy/`.
+
+1. Fork the repo
+2. Create a branch (`git checkout -b feature/my-feature`)
+3. Run tests: `bundle exec rspec`
+4. Commit and push
+5. Open a Pull Request
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/app/assets/javascripts/rails_orbit/application.js

@@ -0,0 +1,232 @@
+(function() {
+  "use strict";
+
+  // ── Poll Controller ───────────────────────────────────────────────────────
+
+  function OrbitPollController(element) {
+    this.element  = element;
+    this.url      = element.dataset.orbitPollUrlValue;
+    this.interval = parseInt(element.dataset.orbitPollIntervalValue) || 5000;
+    this.timer    = null;
+  }
+
+  OrbitPollController.prototype.start = function() {
+    if (!this.url) return;
+    this.poll();
+    this.timer = setInterval(this.poll.bind(this), this.interval);
+  };
+
+  OrbitPollController.prototype.stop = function() {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+  };
+
+  OrbitPollController.prototype.poll = function() {
+    var self = this;
+    fetch(this.url, { headers: { "Accept": "text/vnd.turbo-stream.html" } })
+      .then(function(r) { return r.ok ? r.text() : null; })
+      .then(function(html) {
+        if (!html) return;
+        if (typeof Turbo !== "undefined" && Turbo.renderStreamMessage) {
+          Turbo.renderStreamMessage(html);
+        } else {
+          self.fallbackUpdate(html);
+        }
+        self.refreshTimestamp();
+      })
+      .catch(function() {});
+  };
+
+  OrbitPollController.prototype.fallbackUpdate = function(html) {
+    var doc = new DOMParser().parseFromString(html, "text/html");
+    doc.querySelectorAll("turbo-stream").forEach(function(stream) {
+      var target = document.getElementById(stream.getAttribute("target"));
+      if (!target) return;
+      var tpl = stream.querySelector("template");
+      if (!tpl) return;
+      var action = stream.getAttribute("action");
+      if (action === "update" || action === "replace") target.innerHTML = tpl.innerHTML;
+    });
+  };
+
+  OrbitPollController.prototype.refreshTimestamp = function() {
+    var el = document.getElementById("orbit-last-updated");
+    if (!el) return;
+    el.dataset.time = new Date().toISOString();
+    el.textContent  = "Updated just now";
+  };
+
+  // ── Timestamp Ticker ──────────────────────────────────────────────────────
+
+  function startTimestampTicker() {
+    setInterval(function() {
+      var el = document.getElementById("orbit-last-updated");
+      if (!el || !el.dataset.time) return;
+      var s = Math.floor((Date.now() - new Date(el.dataset.time).getTime()) / 1000);
+      if (s < 5)       el.textContent = "Updated just now";
+      else if (s < 60) el.textContent = "Updated " + s + "s ago";
+      else             el.textContent = "Updated " + Math.floor(s / 60) + "m ago";
+    }, 5000);
+  }
+
+  // ── Interactive SVG Chart ─────────────────────────────────────────────────
+
+  function OrbitChart(container) {
+    this.container = container;
+    this.data      = JSON.parse(container.dataset.chart || "[]");
+    this.unit      = container.dataset.unit || "";
+    this.color     = container.dataset.color || "var(--orbit-primary)";
+    this.gradId    = container.dataset.gradientId || ("orbit-grad-" + Math.random().toString(36).slice(2, 8));
+
+    if (this.data.length === 0) return;
+    this.render();
+  }
+
+  OrbitChart.prototype.render = function() {
+    var W = 700, H = 90, PAD_TOP = 5, PAD_BOT = 5;
+    var data  = this.data;
+    var vals  = data.map(function(d) { return d.v; });
+    var maxV  = Math.max.apply(null, vals) || 1;
+    var minV  = Math.min.apply(null, vals);
+    var range = maxV - minV || 1;
+    var stepX = data.length > 1 ? W / (data.length - 1) : W;
+    var self  = this;
+
+    function yPos(v) {
+      return PAD_TOP + ((maxV - v) / range) * (H - PAD_TOP - PAD_BOT);
+    }
+
+    var points = data.map(function(d, i) {
+      return { x: (i * stepX).toFixed(1), y: yPos(d.v).toFixed(1) };
+    });
+
+    var polyline = points.map(function(p) { return p.x + "," + p.y; }).join(" ");
+    var polygon  = "0," + H + " " + polyline + " " + W + "," + H;
+
+    var svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.setAttribute("viewBox", "0 0 " + W + " " + (H + 2));
+    svg.setAttribute("preserveAspectRatio", "none");
+    svg.setAttribute("class", "orbit-chart");
+
+    svg.innerHTML =
+      '<defs><linearGradient id="' + this.gradId + '" x1="0" y1="0" x2="0" y2="1">' +
+      '<stop offset="0%" stop-color="' + this.color + '" stop-opacity="0.25"/>' +
+      '<stop offset="100%" stop-color="' + this.color + '" stop-opacity="0.02"/>' +
+      '</linearGradient></defs>' +
+      '<polygon points="' + polygon + '" fill="url(#' + this.gradId + ')"/>' +
+      '<polyline points="' + polyline + '" fill="none" stroke="' + this.color + '" stroke-width="1.5" stroke-linejoin="round"/>';
+
+    var hitZones = document.createElementNS("http://www.w3.org/2000/svg", "g");
+    hitZones.setAttribute("class", "orbit-chart__hitzone");
+
+    for (var i = 0; i < points.length; i++) {
+      var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+      var x0 = i === 0 ? 0 : parseFloat(points[i].x) - stepX / 2;
+      rect.setAttribute("x", x0);
+      rect.setAttribute("y", 0);
+      rect.setAttribute("width", stepX);
+      rect.setAttribute("height", H);
+      rect.setAttribute("fill", "transparent");
+      rect.setAttribute("data-idx", i);
+      hitZones.appendChild(rect);
+    }
+    svg.appendChild(hitZones);
+
+    var dot = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+    dot.setAttribute("r", "3");
+    dot.setAttribute("fill", this.color);
+    dot.setAttribute("class", "orbit-chart__dot");
+    dot.style.display = "none";
+    svg.appendChild(dot);
+
+    var vLine = document.createElementNS("http://www.w3.org/2000/svg", "line");
+    vLine.setAttribute("y1", "0");
+    vLine.setAttribute("y2", H);
+    vLine.setAttribute("stroke", "var(--orbit-border-hover)");
+    vLine.setAttribute("stroke-width", "1");
+    vLine.setAttribute("stroke-dasharray", "2,2");
+    vLine.setAttribute("class", "orbit-chart__vline");
+    vLine.style.display = "none";
+    svg.appendChild(vLine);
+
+    var tooltip = document.createElement("div");
+    tooltip.className = "orbit-chart__tooltip";
+    tooltip.style.display = "none";
+
+    var wrap = document.createElement("div");
+    wrap.className = "orbit-chart-wrap";
+    wrap.appendChild(svg);
+    wrap.appendChild(tooltip);
+
+    var labels = document.createElement("div");
+    labels.className = "orbit-chart__labels";
+    labels.innerHTML =
+      '<span class="orbit-chart__label">' + minV.toFixed(1) + this.unit + '</span>' +
+      '<span class="orbit-chart__label orbit-chart__label--current">' +
+        data[data.length - 1].v.toFixed(1) + this.unit + ' now</span>' +
+      '<span class="orbit-chart__label">' + maxV.toFixed(1) + this.unit + ' peak</span>';
+    wrap.appendChild(labels);
+
+    this.container.innerHTML = "";
+    this.container.appendChild(wrap);
+
+    svg.addEventListener("mousemove", function(e) {
+      var rect = svg.getBoundingClientRect();
+      var mx = (e.clientX - rect.left) / rect.width * W;
+      var idx = Math.round(mx / stepX);
+      if (idx < 0) idx = 0;
+      if (idx >= data.length) idx = data.length - 1;
+
+      var pt = points[idx];
+      dot.setAttribute("cx", pt.x);
+      dot.setAttribute("cy", pt.y);
+      dot.style.display = "";
+
+      vLine.setAttribute("x1", pt.x);
+      vLine.setAttribute("x2", pt.x);
+      vLine.style.display = "";
+
+      var d = data[idx];
+      tooltip.textContent = self.formatTime(d.t) + "  " + d.v.toFixed(1) + self.unit;
+      tooltip.style.display = "";
+
+      var pctX = parseFloat(pt.x) / W * 100;
+      tooltip.style.left = pctX + "%";
+      tooltip.style.transform = pctX > 80 ? "translateX(-100%)" : (pctX < 20 ? "translateX(0)" : "translateX(-50%)");
+    });
+
+    svg.addEventListener("mouseleave", function() {
+      dot.style.display = "none";
+      vLine.style.display = "none";
+      tooltip.style.display = "none";
+    });
+  };
+
+  OrbitChart.prototype.formatTime = function(ts) {
+    if (!ts) return "";
+    var d = new Date(ts.replace(" ", "T") + (ts.indexOf("Z") === -1 ? "Z" : ""));
+    if (isNaN(d.getTime())) return ts;
+    var h = d.getHours().toString().padStart(2, "0");
+    var m = d.getMinutes().toString().padStart(2, "0");
+    var mon = d.toLocaleString("en", { month: "short" });
+    var day = d.getDate();
+    return mon + " " + day + " " + h + ":" + m;
+  };
+
+  // ── Init ──────────────────────────────────────────────────────────────────
+
+  function initAll() {
+    document.querySelectorAll("[data-controller='orbit-poll']").forEach(function(el) {
+      new OrbitPollController(el).start();
+    });
+    document.querySelectorAll(".orbit-chart-interactive").forEach(function(el) {
+      new OrbitChart(el);
+    });
+    startTimestampTicker();
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initAll);
+  } else {
+    initAll();
+  }
+})();