tnw 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6a4787102291111902c43e70fbf3f0edf7e076ae38f4b3bae52b35f2e829b829
+  data.tar.gz: 4ba3be9e039f8bc95f151b725347c8cc6957462d8c236a09e0e90effac593a7c
+SHA512:
+  metadata.gz: 0c3fb1cbe3664a48895adddc93f79234b52024a4cdc3abe0cea9af9665857ec6b31a88f288d05abdb43ad401c3847a78640b321a63b87c37c021d9984328fb76
+  data.tar.gz: 82f3e5b0f288e73e08dc52221af4a46a1a5d4937d79e78731373c06e42cf6cfc70ebd353bcd58928dee9e6c61b1e42a0a71745a0856997883d68afae3be7bb64

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Catalin Ionescu
+
+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,56 @@
+# The Night Watch
+
+The Night Watch (`tnw`) is a mountable Rails engine for inspecting and operating a Kamal-backed Rails application from a protected web UI.
+
+The project is under active development. The engine and dummy host application are scaffolded; operational features are not available yet.
+
+## Installation
+
+Add the gem to the host application's `Gemfile`:
+
+```ruby
+gem "tnw"
+```
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+mount Tnw::Engine => "/tnw"
+```
+
+The install generator creates the initializer, mounts the engine, and copies its migrations:
+
+```bash
+bin/rails generate tnw:install
+bin/rails db:migrate
+```
+
+Configure either the host authentication callback shown in the generated initializer or basic auth credentials. Outside development, the dashboard fails closed when neither mode is complete.
+
+Configure server metrics from a host-app initializer:
+
+```ruby
+Tnw.configure do |config|
+  config.metrics_sample_interval = 5.seconds
+  config.metrics_retention = 7.days
+  config.metrics_ingestion_token = ENV["TNW_METRICS_INGESTION_TOKEN"]
+  config.metrics_accepted_clock_skew = 30.seconds
+end
+```
+
+Metric ingestion fails closed when the ingestion token is missing.
+
+Host collector installation is documented in [the server stats installation guide](https://github.com/cionescu/TNW/blob/main/docs/server-stats-install.md).
+
+## Development
+
+The generated dummy Rails application lives in `test/dummy`.
+
+```bash
+bundle install
+bin/rails test
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/tnw/application.css

@@ -0,0 +1,183 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */
+
+.tnw {
+  margin: 0;
+  background: #f5f6f7;
+  color: #17202a;
+  font-family: ui-sans-serif, system-ui, sans-serif;
+}
+
+.tnw main {
+  width: min(1120px, calc(100% - 32px));
+  margin: 0 auto;
+  padding: 32px 0;
+}
+
+.tnw-page-header,
+.tnw-server-header,
+.tnw-server-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.tnw-page-header {
+  margin-bottom: 24px;
+}
+
+.tnw h1,
+.tnw h2,
+.tnw p,
+.tnw dl {
+  margin: 0;
+}
+
+.tnw h1 {
+  font-size: 28px;
+  line-height: 1.2;
+}
+
+.tnw h2 {
+  font-size: 17px;
+  line-height: 1.3;
+}
+
+.tnw-eyebrow,
+.tnw-server-header p,
+.tnw-server-footer {
+  color: #65717d;
+  font-size: 13px;
+}
+
+.tnw-eyebrow {
+  margin-bottom: 4px;
+  font-weight: 700;
+}
+
+.tnw-server-count,
+.tnw-status {
+  border: 1px solid #cbd2d9;
+  border-radius: 4px;
+  background: #fff;
+  padding: 5px 8px;
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.tnw-server-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 440px), 1fr));
+  gap: 16px;
+}
+
+.tnw-server,
+.tnw-empty-state {
+  border: 1px solid #d7dce1;
+  border-radius: 6px;
+  background: #fff;
+}
+
+.tnw-server {
+  overflow: hidden;
+}
+
+.tnw-server-header,
+.tnw-server-footer {
+  padding: 14px 16px;
+}
+
+.tnw-server[data-status="healthy"] .tnw-status {
+  border-color: #86b89a;
+  background: #edf8f1;
+  color: #205c38;
+}
+
+.tnw-server[data-status="stale"] .tnw-status,
+.tnw-server[data-status="partial"] .tnw-status,
+.tnw-server[data-status="never_received"] .tnw-status {
+  border-color: #d6b46b;
+  background: #fff8e6;
+  color: #73510b;
+}
+
+.tnw-server[data-status="rejected"] .tnw-status,
+.tnw-server[data-status="disabled"] .tnw-status {
+  border-color: #d79595;
+  background: #fff0f0;
+  color: #812a2a;
+}
+
+.tnw-metrics {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  border-top: 1px solid #e5e8eb;
+  border-bottom: 1px solid #e5e8eb;
+}
+
+.tnw-metrics div {
+  min-width: 0;
+  padding: 14px 12px;
+  border-right: 1px solid #e5e8eb;
+}
+
+.tnw-metrics div:last-child {
+  border-right: 0;
+}
+
+.tnw-metrics dt {
+  color: #65717d;
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.tnw-metrics dd {
+  margin: 5px 0 0;
+  overflow-wrap: anywhere;
+  font-size: 16px;
+  font-weight: 700;
+}
+
+.tnw-server-footer {
+  align-items: flex-start;
+  flex-wrap: wrap;
+}
+
+.tnw-empty-state {
+  padding: 32px;
+  text-align: center;
+}
+
+@media (max-width: 620px) {
+  .tnw main {
+    width: min(100% - 20px, 1120px);
+    padding: 20px 0;
+  }
+
+  .tnw-metrics {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .tnw-metrics div:nth-child(2) {
+    border-right: 0;
+  }
+
+  .tnw-metrics div:nth-child(-n+2) {
+    border-bottom: 1px solid #e5e8eb;
+  }
+}

data/app/controllers/tnw/application_controller.rb

@@ -0,0 +1,32 @@
+module Tnw
+  class ApplicationController < ActionController::Base
+    before_action :authenticate_tnw_operator!
+
+    private
+
+    def authenticate_tnw_operator!
+      configuration = Tnw.configuration
+
+      if configuration.authentication_handler
+        authenticate_with_host!(configuration.authentication_handler)
+      elsif configuration.basic_auth_configured?
+        authenticate_with_basic_auth!(configuration)
+      elsif !Rails.env.development?
+        render plain: "The Night Watch authentication is not configured.", status: :service_unavailable
+      end
+    end
+
+    def authenticate_with_host!(handler)
+      allowed = handler.call(self)
+      head :forbidden unless allowed || performed?
+    end
+
+    def authenticate_with_basic_auth!(configuration)
+      authenticate_or_request_with_http_basic("The Night Watch") do |username, password|
+        username_valid = ActiveSupport::SecurityUtils.secure_compare(username, configuration.basic_auth_username)
+        password_valid = ActiveSupport::SecurityUtils.secure_compare(password, configuration.basic_auth_password)
+        username_valid & password_valid
+      end
+    end
+  end
+end

data/app/controllers/tnw/dashboard_controller.rb

@@ -0,0 +1,14 @@
+module Tnw
+  class DashboardController < ApplicationController
+    def index
+      servers = Tnw::Server.order(:name, :identifier)
+      latest_samples = Tnw::MetricSample
+        .where(id: Tnw::MetricSample.select("MAX(id)").group(:server_id))
+        .index_by(&:server_id)
+
+      @server_metrics = servers.map do |server|
+        Tnw::ServerMetricStatus.new(server: server, sample: latest_samples[server.id])
+      end
+    end
+  end
+end

data/app/controllers/tnw/internal/metric_samples_controller.rb

@@ -0,0 +1,62 @@
+module Tnw
+  module Internal
+    class MetricSamplesController < ActionController::API
+      MAX_PAYLOAD_BYTES = 64.kilobytes
+
+      rescue_from JSON::ParserError, with: :render_invalid_json
+      rescue_from Tnw::Metrics::IngestionError, with: :render_ingestion_error
+
+      def create
+        raise_payload_too_large! if request.content_length.to_i > MAX_PAYLOAD_BYTES
+
+        raw_body = request.raw_post
+        raise_payload_too_large! if raw_body.bytesize > MAX_PAYLOAD_BYTES
+
+        verify_request!(raw_body)
+        sample = Tnw::MetricSamples::Ingest.new(
+          payload: JSON.parse(raw_body),
+          source_ip: request.remote_ip
+        ).call
+
+        render json: { status: "accepted", sample_id: sample.id }, status: :created
+      end
+
+      private
+
+      def verify_request!(raw_body)
+        Tnw::Metrics::RequestVerifier.new(
+          raw_body: raw_body,
+          timestamp: request.headers["X-TNW-Timestamp"],
+          signature: request.headers["X-TNW-Signature"]
+        ).verify!
+      end
+
+      def raise_payload_too_large!
+        raise Tnw::Metrics::IngestionError.new(:payload_too_large, "Metric payload is too large")
+      end
+
+      def render_invalid_json
+        render json: { error: "invalid_json" }, status: :bad_request
+      end
+
+      def render_ingestion_error(error)
+        render json: { error: error.code }, status: status_for(error.code)
+      end
+
+      def status_for(code)
+        case code
+        when "not_configured"
+          :service_unavailable
+        when "missing_authentication", "invalid_signature", "invalid_timestamp", "stale_timestamp"
+          :unauthorized
+        when "payload_too_large"
+          :content_too_large
+        when "replayed_sample"
+          :conflict
+        else
+          :unprocessable_content
+        end
+      end
+    end
+  end
+end

data/app/helpers/tnw/application_helper.rb

@@ -0,0 +1,21 @@
+module Tnw
+  module ApplicationHelper
+    def metric_percentage(value)
+      return "Unavailable" if value.nil?
+
+      number_to_percentage(value, precision: 1)
+    end
+
+    def metric_bytes(value)
+      return "Unavailable" if value.nil?
+
+      number_to_human_size(value, precision: 3)
+    end
+
+    def metric_decimal(value)
+      return "Unavailable" if value.nil?
+
+      number_with_precision(value, precision: 2)
+    end
+  end
+end

data/app/jobs/tnw/application_job.rb

@@ -0,0 +1,4 @@
+module Tnw
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/tnw/metrics/retention_job.rb

@@ -0,0 +1,10 @@
+module Tnw
+  module Metrics
+    class RetentionJob < ApplicationJob
+      def perform(now: Time.current)
+        cutoff = now - Tnw.configuration.metrics_retention
+        Tnw::MetricSample.where(collected_at: ...cutoff).delete_all
+      end
+    end
+  end
+end

data/app/models/tnw/application_record.rb

@@ -0,0 +1,5 @@
+module Tnw
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/tnw/metric_sample.rb

@@ -0,0 +1,16 @@
+module Tnw
+  class MetricSample < ApplicationRecord
+    belongs_to :server
+
+    validates :collected_at, :received_at, :collector_name, :collector_version, :parser_version, :sample_uid,
+      presence: true
+    validates :sample_uid, uniqueness: { scope: :server_id }
+    validates :cpu_percent, numericality: { in: 0..100 }, allow_nil: true
+    validates :load_1m, :load_5m, :load_15m, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+    validates :memory_total_bytes, :memory_used_bytes, :memory_available_bytes,
+      :disk_total_bytes, :disk_used_bytes, :disk_available_bytes,
+      numericality: { only_integer: true, greater_than_or_equal_to: 0 }, allow_nil: true
+
+    scope :chronological, -> { order(:collected_at) }
+  end
+end

data/app/models/tnw/server.rb

@@ -0,0 +1,16 @@
+module Tnw
+  class Server < ApplicationRecord
+    INGESTION_STATUSES = %w[accepted rejected].freeze
+
+    has_many :metric_samples, dependent: :delete_all
+
+    validates :identifier, presence: true, uniqueness: true
+    validates :last_ingestion_status, inclusion: { in: INGESTION_STATUSES }, allow_nil: true
+
+    scope :enabled, -> { where(enabled: true) }
+
+    def display_name
+      name.presence || identifier
+    end
+  end
+end

data/app/presenters/tnw/server_metric_status.rb

@@ -0,0 +1,32 @@
+module Tnw
+  class ServerMetricStatus
+    attr_reader :server, :sample
+
+    def initialize(server:, sample:, now: Time.current, configuration: Tnw.configuration)
+      @server = server
+      @sample = sample
+      @now = now
+      @configuration = configuration
+    end
+
+    def status
+      return :disabled unless server.enabled?
+      return :rejected if server.last_ingestion_status == "rejected"
+      return :never_received unless sample
+      return :stale if stale?
+      return :partial if sample.parse_errors.any?
+
+      :healthy
+    end
+
+    def status_label
+      status.to_s.humanize
+    end
+
+    private
+
+    def stale?
+      sample.received_at < @now - (@configuration.metrics_sample_interval * 3)
+    end
+  end
+end

data/app/services/tnw/metric_samples/ingest.rb

@@ -0,0 +1,160 @@
+require "time"
+
+module Tnw
+  module MetricSamples
+    class Ingest
+      ERROR_CODE_PATTERN = /\A[a-z0-9_.-]+\z/
+      MAX_ERROR_CODES = 10
+      MAX_ERROR_CODE_LENGTH = 100
+
+      def initialize(payload:, source_ip:, now: Time.current)
+        @payload = payload
+        @source_ip = source_ip
+        @now = now
+        @server = nil
+      end
+
+      def call
+        validate_payload_shape!
+        @server = find_server!
+        sample_attributes = build_sample_attributes
+
+        @server.with_lock do
+          Tnw::Metrics::ReplayGuard.verify!(server: @server, sample_uid: sample_attributes[:sample_uid])
+          sample = @server.metric_samples.create!(sample_attributes)
+          mark_server!(:accepted)
+          sample
+        end
+      rescue ActiveRecord::RecordInvalid => error
+        ingestion_error = Tnw::Metrics::IngestionError.new(
+          :invalid_payload,
+          error.record.errors.full_messages.to_sentence
+        )
+        mark_server!(:rejected, ingestion_error.code) if @server
+        raise ingestion_error
+      rescue ActiveRecord::RecordNotUnique
+        ingestion_error = Tnw::Metrics::IngestionError.new(
+          :replayed_sample,
+          "Metric sample has already been accepted"
+        )
+        mark_server!(:rejected, ingestion_error.code) if @server
+        raise ingestion_error
+      rescue Tnw::Metrics::IngestionError => error
+        mark_server!(:rejected, error.code) if @server
+        raise
+      end
+
+      private
+
+      def validate_payload_shape!
+        return if @payload.is_a?(Hash) && @payload["metrics"].is_a?(Hash)
+
+        raise Tnw::Metrics::IngestionError.new(:invalid_payload, "Metric payload must contain a metrics object")
+      end
+
+      def find_server!
+        identifier = required_string!("server_id")
+        server = Tnw::Server.find_by(identifier: identifier)
+        raise Tnw::Metrics::IngestionError.new(:unknown_server, "Metric server is not registered") unless server
+        raise Tnw::Metrics::IngestionError.new(:disabled_server, "Metric server is disabled") unless server.enabled?
+
+        server
+      end
+
+      def build_sample_attributes
+        metrics = @payload.fetch("metrics")
+        {
+          collected_at: collected_at,
+          received_at: @now,
+          cpu_percent: optional_float(metrics.dig("cpu", "percent")),
+          load_1m: optional_float(metrics.dig("load", "one")),
+          load_5m: optional_float(metrics.dig("load", "five")),
+          load_15m: optional_float(metrics.dig("load", "fifteen")),
+          memory_total_bytes: optional_integer(metrics.dig("memory", "total_bytes")),
+          memory_used_bytes: optional_integer(metrics.dig("memory", "used_bytes")),
+          memory_available_bytes: optional_integer(metrics.dig("memory", "available_bytes")),
+          disk_total_bytes: optional_integer(metrics.dig("disk", "total_bytes")),
+          disk_used_bytes: optional_integer(metrics.dig("disk", "used_bytes")),
+          disk_available_bytes: optional_integer(metrics.dig("disk", "available_bytes")),
+          disk_mount: optional_string(metrics.dig("disk", "mount")),
+          collector_name: required_string!("collector_name"),
+          collector_version: required_string!("collector_version"),
+          parser_version: required_string!("parser_version"),
+          source_ip: @source_ip,
+          sample_uid: required_string!("sample_uid"),
+          parse_errors: parse_error_codes
+        }
+      rescue TypeError
+        raise Tnw::Metrics::IngestionError.new(:invalid_payload, "Metric groups must be objects")
+      end
+
+      def collected_at
+        value = Time.iso8601(required_string!("collected_at"))
+        skew = Tnw.configuration.metrics_accepted_clock_skew.in_seconds
+        if (@now.to_f - value.to_f).abs > skew
+          raise Tnw::Metrics::IngestionError.new(:stale_sample, "Metric sample time is outside the accepted clock skew")
+        end
+
+        value
+      rescue ArgumentError
+        raise Tnw::Metrics::IngestionError.new(:invalid_payload, "collected_at must be an ISO 8601 timestamp")
+      end
+
+      def required_string!(key)
+        value = @payload[key]
+        return value if value.is_a?(String) && !value.strip.empty? && value.bytesize <= 255
+
+        raise Tnw::Metrics::IngestionError.new(:invalid_payload, "#{key} must be a non-blank string")
+      end
+
+      def optional_string(value)
+        return if value.nil?
+        return value if value.is_a?(String) && value.bytesize <= 255
+
+        raise Tnw::Metrics::IngestionError.new(:invalid_payload, "Metric string value is invalid")
+      end
+
+      def optional_float(value)
+        return if value.nil?
+
+        number = Float(value)
+        return number if number.finite?
+
+        raise ArgumentError
+      rescue ArgumentError, TypeError
+        raise Tnw::Metrics::IngestionError.new(:invalid_payload, "Metric numeric value is invalid")
+      end
+
+      def optional_integer(value)
+        return if value.nil?
+
+        Integer(value)
+      rescue ArgumentError, TypeError
+        raise Tnw::Metrics::IngestionError.new(:invalid_payload, "Metric byte value is invalid")
+      end
+
+      def parse_error_codes
+        values = @payload.fetch("parse_errors", [])
+        unless values.is_a?(Array) && values.length <= MAX_ERROR_CODES
+          raise Tnw::Metrics::IngestionError.new(:invalid_payload, "parse_errors must be a bounded array")
+        end
+
+        values.map do |value|
+          valid = value.is_a?(String) && value.length <= MAX_ERROR_CODE_LENGTH && value.match?(ERROR_CODE_PATTERN)
+          raise Tnw::Metrics::IngestionError.new(:invalid_payload, "parse_errors contains an invalid code") unless valid
+
+          value
+        end
+      end
+
+      def mark_server!(status, error_code = nil)
+        @server.update_columns(
+          last_ingestion_status: status,
+          last_ingestion_error_code: error_code,
+          last_ingestion_at: @now,
+          updated_at: @now
+        )
+      end
+    end
+  end
+end

data/app/views/layouts/tnw/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>The Night Watch</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag "tnw/application", media: "all" %>
+</head>
+<body class="tnw">
+  <%= yield %>
+</body>
+</html>