tnw 0.1.0

data/app/views/tnw/dashboard/index.html.erb

@@ -0,0 +1,62 @@
+<main>
+  <header class="tnw-page-header">
+    <div>
+      <p class="tnw-eyebrow">The Night Watch</p>
+      <h1>Server health</h1>
+    </div>
+    <span class="tnw-server-count"><%= pluralize(@server_metrics.size, "server") %></span>
+  </header>
+
+  <% if @server_metrics.empty? %>
+    <section class="tnw-empty-state">
+      <h2>No servers registered</h2>
+    </section>
+  <% else %>
+    <section class="tnw-server-grid">
+      <% @server_metrics.each do |server_metrics| %>
+        <% sample = server_metrics.sample %>
+        <article class="tnw-server" data-status="<%= server_metrics.status %>">
+          <header class="tnw-server-header">
+            <div>
+              <h2><%= server_metrics.server.display_name %></h2>
+              <p><%= server_metrics.server.identifier %></p>
+            </div>
+            <span class="tnw-status"><%= server_metrics.status_label %></span>
+          </header>
+
+          <dl class="tnw-metrics">
+            <div>
+              <dt>CPU</dt>
+              <dd><%= metric_percentage(sample&.cpu_percent) %></dd>
+            </div>
+            <div>
+              <dt>Memory used</dt>
+              <dd><%= metric_bytes(sample&.memory_used_bytes) %></dd>
+            </div>
+            <div>
+              <dt>Disk used</dt>
+              <dd><%= metric_bytes(sample&.disk_used_bytes) %></dd>
+            </div>
+            <div>
+              <dt>Load 1m</dt>
+              <dd><%= metric_decimal(sample&.load_1m) %></dd>
+            </div>
+          </dl>
+
+          <footer class="tnw-server-footer">
+            <% if sample %>
+              Last received <time datetime="<%= sample.received_at.iso8601 %>"><%= time_ago_in_words(sample.received_at) %> ago</time>
+            <% else %>
+              Waiting for first sample
+            <% end %>
+            <% if server_metrics.server.last_ingestion_error_code.present? %>
+              <span>Error: <%= server_metrics.server.last_ingestion_error_code.humanize %></span>
+            <% elsif sample&.parse_errors&.any? %>
+              <span>Partial: <%= sample.parse_errors.map(&:humanize).join(", ") %></span>
+            <% end %>
+          </footer>
+        </article>
+      <% end %>
+    </section>
+  <% end %>
+</main>

data/config/routes.rb

@@ -0,0 +1,6 @@
+Tnw::Engine.routes.draw do
+  root "dashboard#index"
+  namespace :internal do
+    resources :metric_samples, only: :create
+  end
+end

data/db/migrate/20260711000001_create_tnw_servers.rb

@@ -0,0 +1,15 @@
+class CreateTnwServers < ActiveRecord::Migration[8.1]
+  def change
+    create_table :tnw_servers do |t|
+      t.string :identifier, null: false
+      t.string :name
+      t.boolean :enabled, null: false, default: true
+      t.string :last_ingestion_status
+      t.string :last_ingestion_error_code
+      t.datetime :last_ingestion_at
+      t.timestamps
+    end
+
+    add_index :tnw_servers, :identifier, unique: true
+  end
+end

data/db/migrate/20260711000002_create_tnw_metric_samples.rb

@@ -0,0 +1,33 @@
+class CreateTnwMetricSamples < ActiveRecord::Migration[8.1]
+  def change
+    create_table :tnw_metric_samples do |t|
+      t.references :server, null: false, foreign_key: { to_table: :tnw_servers }
+      t.datetime :collected_at, null: false
+      t.datetime :received_at, null: false
+      t.decimal :cpu_percent, precision: 5, scale: 2
+      t.decimal :load_1m, precision: 10, scale: 3
+      t.decimal :load_5m, precision: 10, scale: 3
+      t.decimal :load_15m, precision: 10, scale: 3
+      t.bigint :memory_total_bytes
+      t.bigint :memory_used_bytes
+      t.bigint :memory_available_bytes
+      t.bigint :disk_total_bytes
+      t.bigint :disk_used_bytes
+      t.bigint :disk_available_bytes
+      t.string :disk_mount
+      t.string :collector_name, null: false
+      t.string :collector_version, null: false
+      t.string :parser_version, null: false
+      t.string :source_ip
+      t.string :sample_uid, null: false
+      t.json :parse_errors, null: false, default: []
+      t.json :validation_errors, null: false, default: []
+      t.timestamps
+    end
+
+    add_index :tnw_metric_samples, %i[server_id collected_at]
+    add_index :tnw_metric_samples, %i[server_id sample_uid], unique: true
+    add_index :tnw_metric_samples, :collected_at
+    add_index :tnw_metric_samples, :received_at
+  end
+end

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

@@ -0,0 +1,44 @@
+require "rails/generators"
+
+module Tnw
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "tnw.rb", "config/initializers/tnw.rb"
+      end
+
+      def mount_engine
+        routes_path = destination_root_path.join("config/routes.rb")
+        return if routes_path.exist? && routes_path.read.include?("mount Tnw::Engine")
+
+        route 'mount Tnw::Engine => "/tnw"'
+      end
+
+      def copy_migrations
+        migration_sources.each_with_index do |source, index|
+          migration_name = File.basename(source).sub(/\A\d+_/, "")
+          next if migration_installed?(migration_name)
+
+          timestamp = (Time.now.utc + index.seconds).strftime("%Y%m%d%H%M%S")
+          copy_file source, "db/migrate/#{timestamp}_#{migration_name}"
+        end
+      end
+
+      private
+
+      def migration_sources
+        Dir[Tnw::Engine.root.join("db/migrate/*.rb")].sort
+      end
+
+      def migration_installed?(migration_name)
+        Dir[destination_root_path.join("db/migrate/*_#{migration_name}")].any?
+      end
+
+      def destination_root_path
+        Pathname(destination_root)
+      end
+    end
+  end
+end

data/lib/generators/tnw/install/templates/tnw.rb

@@ -0,0 +1,12 @@
+Tnw.configure do |config|
+  # Required outside development. Connect this to the host application's
+  # existing administrator authentication method.
+  # config.authenticate_with do |controller|
+  #   controller.authenticate_admin!
+  # end
+
+  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

data/lib/tasks/tnw_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :tnw do
+#   # Task goes here
+# end

data/lib/tnw/configuration.rb

@@ -0,0 +1,95 @@
+require "active_support/core_ext/numeric/time"
+
+module Tnw
+  class Configuration
+    attr_reader :metrics_sample_interval,
+      :metrics_retention,
+      :metrics_ingestion_token,
+      :metrics_accepted_clock_skew,
+      :authentication_handler,
+      :basic_auth_username,
+      :basic_auth_password
+
+    def initialize
+      @metrics_sample_interval = 5.seconds
+      @metrics_retention = 7.days
+      @metrics_ingestion_token = nil
+      @metrics_accepted_clock_skew = 30.seconds
+      @authentication_handler = nil
+      @basic_auth_username = nil
+      @basic_auth_password = nil
+    end
+
+    def metrics_sample_interval=(interval)
+      @metrics_sample_interval = positive_duration!(interval, :metrics_sample_interval)
+    end
+
+    def metrics_retention=(retention)
+      @metrics_retention = positive_duration!(retention, :metrics_retention)
+    end
+
+    def metrics_ingestion_token=(token)
+      unless token.nil? || (token.is_a?(String) && !token.strip.empty?)
+        raise ArgumentError, "metrics_ingestion_token must be a non-blank String or nil"
+      end
+
+      @metrics_ingestion_token = token
+    end
+
+    def metrics_accepted_clock_skew=(clock_skew)
+      @metrics_accepted_clock_skew = positive_duration!(clock_skew, :metrics_accepted_clock_skew)
+    end
+
+    def authenticate_with(&block)
+      raise ArgumentError, "authenticate_with requires a block" unless block
+
+      @authentication_handler = block
+    end
+
+    def basic_auth_username=(username)
+      @basic_auth_username = optional_non_blank_string!(username, :basic_auth_username)
+    end
+
+    def basic_auth_password=(password)
+      @basic_auth_password = optional_non_blank_string!(password, :basic_auth_password)
+    end
+
+    def basic_auth_configured?
+      basic_auth_username && basic_auth_password
+    end
+
+    def inspect
+      token = metrics_ingestion_token.nil? ? nil : "[FILTERED]"
+      password = basic_auth_password.nil? ? nil : "[FILTERED]"
+
+      "#<#{self.class.name} " \
+        "metrics_sample_interval=#{metrics_sample_interval.inspect} " \
+        "metrics_retention=#{metrics_retention.inspect} " \
+        "metrics_ingestion_token=#{token.inspect} " \
+        "metrics_accepted_clock_skew=#{metrics_accepted_clock_skew.inspect} " \
+        "authentication_handler=#{authentication_handler.inspect} " \
+        "basic_auth_username=#{basic_auth_username.inspect} " \
+        "basic_auth_password=#{password.inspect}>"
+    end
+
+    private
+
+    def positive_duration!(value, name)
+      seconds = value.respond_to?(:in_seconds) ? value.in_seconds : value
+
+      unless seconds.is_a?(Numeric) && seconds.positive? && seconds.finite?
+        raise ArgumentError, "#{name} must be positive"
+      end
+
+      value
+    end
+
+    def optional_non_blank_string!(value, name)
+      unless value.nil? || (value.is_a?(String) && !value.strip.empty?)
+        raise ArgumentError, "#{name} must be a non-blank String or nil"
+      end
+
+      value
+    end
+  end
+end

data/lib/tnw/engine.rb

@@ -0,0 +1,5 @@
+module Tnw
+  class Engine < ::Rails::Engine
+    isolate_namespace Tnw
+  end
+end

data/lib/tnw/metrics/ingestion_error.rb

@@ -0,0 +1,12 @@
+module Tnw
+  module Metrics
+    class IngestionError < StandardError
+      attr_reader :code
+
+      def initialize(code, message)
+        @code = code.to_s
+        super(message)
+      end
+    end
+  end
+end

data/lib/tnw/metrics/parse_error.rb

@@ -0,0 +1,6 @@
+module Tnw
+  module Metrics
+    class ParseError < StandardError
+    end
+  end
+end

data/lib/tnw/metrics/parsers/df.rb

@@ -0,0 +1,37 @@
+module Tnw
+  module Metrics
+    module Parsers
+      class Df
+        BLOCK_BYTES = 1024
+
+        def self.parse(output, mount: "/")
+          rows = output.lines.drop(1).filter_map do |line|
+            fields = line.strip.split(/\s+/, 6)
+            fields if fields.length == 6
+          end
+          row = rows.find { |fields| fields.fetch(5) == mount }
+          raise ParseError, "df output is missing mount #{mount}" unless row
+
+          total = blocks_to_bytes(row.fetch(1))
+          used = blocks_to_bytes(row.fetch(2))
+          available = blocks_to_bytes(row.fetch(3))
+
+          {
+            total_bytes: total,
+            used_bytes: used,
+            available_bytes: available,
+            mount: row.fetch(5)
+          }
+        end
+
+        def self.blocks_to_bytes(value)
+          Integer(value, 10) * BLOCK_BYTES
+        rescue ArgumentError
+          raise ParseError, "df output contains an invalid block count"
+        end
+
+        private_class_method :blocks_to_bytes
+      end
+    end
+  end
+end

data/lib/tnw/metrics/parsers/proc_loadavg.rb

@@ -0,0 +1,20 @@
+module Tnw
+  module Metrics
+    module Parsers
+      class ProcLoadavg
+        def self.parse(output)
+          values = output.split.first(3)
+          raise ParseError, "/proc/loadavg has too few values" if values.length < 3
+
+          {
+            one: Float(values.fetch(0)),
+            five: Float(values.fetch(1)),
+            fifteen: Float(values.fetch(2))
+          }
+        rescue ArgumentError
+          raise ParseError, "/proc/loadavg contains an invalid value"
+        end
+      end
+    end
+  end
+end

data/lib/tnw/metrics/parsers/proc_meminfo.rb

@@ -0,0 +1,37 @@
+module Tnw
+  module Metrics
+    module Parsers
+      class ProcMeminfo
+        KIBIBYTE = 1024
+
+        def self.parse(output)
+          values = output.each_line.to_h do |line|
+            key, value = line.split(":", 2)
+            [ key, value.to_s.split.first ]
+          end
+
+          total = kibibytes(values, "MemTotal")
+          available = kibibytes(values, "MemAvailable")
+          raise ParseError, "/proc/meminfo reports available memory above total memory" if available > total
+
+          {
+            total_bytes: total,
+            used_bytes: total - available,
+            available_bytes: available
+          }
+        end
+
+        def self.kibibytes(values, key)
+          value = values[key]
+          raise ParseError, "/proc/meminfo is missing #{key}" unless value
+
+          Integer(value, 10) * KIBIBYTE
+        rescue ArgumentError
+          raise ParseError, "/proc/meminfo contains an invalid #{key} value"
+        end
+
+        private_class_method :kibibytes
+      end
+    end
+  end
+end

data/lib/tnw/metrics/parsers/proc_stat.rb

@@ -0,0 +1,37 @@
+module Tnw
+  module Metrics
+    module Parsers
+      class ProcStat
+        CPU_COUNTER_COUNT = 8
+
+        def self.parse(previous:, current:)
+          previous_counters = counters(previous)
+          current_counters = counters(current)
+          deltas = current_counters.zip(previous_counters).map { |after, before| after - before }
+
+          raise ParseError, "/proc/stat counters moved backwards" if deltas.any?(&:negative?)
+
+          total_delta = deltas.sum
+          raise ParseError, "/proc/stat contains no elapsed CPU time" unless total_delta.positive?
+
+          idle_delta = deltas.fetch(3) + deltas.fetch(4)
+          { percent: ((total_delta - idle_delta) * 100.0 / total_delta).round(2) }
+        end
+
+        def self.counters(output)
+          line = output.each_line.find { |candidate| candidate.start_with?("cpu ") }
+          raise ParseError, "/proc/stat is missing the aggregate cpu row" unless line
+
+          values = line.split.drop(1).first(CPU_COUNTER_COUNT)
+          raise ParseError, "/proc/stat has too few CPU counters" if values.length < CPU_COUNTER_COUNT
+
+          values.map { |value| Integer(value, 10) }
+        rescue ArgumentError
+          raise ParseError, "/proc/stat contains an invalid CPU counter"
+        end
+
+        private_class_method :counters
+      end
+    end
+  end
+end

data/lib/tnw/metrics/replay_guard.rb

@@ -0,0 +1,17 @@
+module Tnw
+  module Metrics
+    class ReplayGuard
+      def self.verify!(server:, sample_uid:)
+        if sample_uid.blank?
+          raise IngestionError.new(:missing_sample_uid, "Metric sample id is missing")
+        end
+
+        if server.metric_samples.exists?(sample_uid: sample_uid)
+          raise IngestionError.new(:replayed_sample, "Metric sample has already been accepted")
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/tnw/metrics/request_verifier.rb

@@ -0,0 +1,59 @@
+require "openssl"
+
+module Tnw
+  module Metrics
+    class RequestVerifier
+      def self.signature(raw_body:, timestamp:, secret:)
+        OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
+      end
+
+      def initialize(raw_body:, timestamp:, signature:, now: Time.current, configuration: Tnw.configuration)
+        @raw_body = raw_body
+        @timestamp = timestamp
+        @signature = signature
+        @now = now
+        @configuration = configuration
+      end
+
+      def verify!
+        secret = @configuration.metrics_ingestion_token
+        raise IngestionError.new(:not_configured, "Metric ingestion is not configured") unless secret
+        raise IngestionError.new(:missing_authentication, "Metric authentication is missing") if authentication_missing?
+
+        signed_at = parse_timestamp
+        verify_freshness!(signed_at)
+        verify_signature!(secret)
+
+        true
+      end
+
+      private
+
+      def authentication_missing?
+        @timestamp.blank? || @signature.blank?
+      end
+
+      def parse_timestamp
+        Time.at(Integer(@timestamp, 10)).utc
+      rescue ArgumentError, TypeError, RangeError
+        raise IngestionError.new(:invalid_timestamp, "Metric timestamp is invalid")
+      end
+
+      def verify_freshness!(signed_at)
+        skew = @configuration.metrics_accepted_clock_skew.in_seconds
+        return if (@now.to_f - signed_at.to_f).abs <= skew
+
+        raise IngestionError.new(:stale_timestamp, "Metric timestamp is outside the accepted clock skew")
+      end
+
+      def verify_signature!(secret)
+        expected = self.class.signature(raw_body: @raw_body, timestamp: @timestamp, secret: secret)
+        valid = @signature.bytesize == expected.bytesize &&
+          ActiveSupport::SecurityUtils.secure_compare(@signature, expected)
+        return if valid
+
+        raise IngestionError.new(:invalid_signature, "Metric signature is invalid")
+      end
+    end
+  end
+end

data/lib/tnw/metrics.rb

@@ -0,0 +1,14 @@
+require "tnw/metrics/parse_error"
+require "tnw/metrics/ingestion_error"
+require "tnw/metrics/request_verifier"
+require "tnw/metrics/replay_guard"
+require "tnw/metrics/parsers/proc_stat"
+require "tnw/metrics/parsers/proc_meminfo"
+require "tnw/metrics/parsers/df"
+require "tnw/metrics/parsers/proc_loadavg"
+
+module Tnw
+  module Metrics
+    PARSER_VERSION = "1"
+  end
+end

data/lib/tnw/version.rb

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

data/lib/tnw.rb

@@ -0,0 +1,21 @@
+require "tnw/version"
+require "tnw/configuration"
+require "tnw/metrics"
+require "tnw/engine"
+
+module Tnw
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: tnw
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Catalin Ionescu
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: The Night Watch is a mountable Rails engine for inspecting and operating
+  a Kamal-backed Rails application.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/tnw/application.css
+- app/controllers/tnw/application_controller.rb
+- app/controllers/tnw/dashboard_controller.rb
+- app/controllers/tnw/internal/metric_samples_controller.rb
+- app/helpers/tnw/application_helper.rb
+- app/jobs/tnw/application_job.rb
+- app/jobs/tnw/metrics/retention_job.rb
+- app/models/tnw/application_record.rb
+- app/models/tnw/metric_sample.rb
+- app/models/tnw/server.rb
+- app/presenters/tnw/server_metric_status.rb
+- app/services/tnw/metric_samples/ingest.rb
+- app/views/layouts/tnw/application.html.erb
+- app/views/tnw/dashboard/index.html.erb
+- config/routes.rb
+- db/migrate/20260711000001_create_tnw_servers.rb
+- db/migrate/20260711000002_create_tnw_metric_samples.rb
+- lib/generators/tnw/install/install_generator.rb
+- lib/generators/tnw/install/templates/tnw.rb
+- lib/tasks/tnw_tasks.rake
+- lib/tnw.rb
+- lib/tnw/configuration.rb
+- lib/tnw/engine.rb
+- lib/tnw/metrics.rb
+- lib/tnw/metrics/ingestion_error.rb
+- lib/tnw/metrics/parse_error.rb
+- lib/tnw/metrics/parsers/df.rb
+- lib/tnw/metrics/parsers/proc_loadavg.rb
+- lib/tnw/metrics/parsers/proc_meminfo.rb
+- lib/tnw/metrics/parsers/proc_stat.rb
+- lib/tnw/metrics/replay_guard.rb
+- lib/tnw/metrics/request_verifier.rb
+- lib/tnw/version.rb
+homepage: https://github.com/cionescu/tnw
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/cionescu/tnw
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A protected operational UI for Kamal-backed Rails applications.
+test_files: []