binocs 0.1.0

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

@@ -0,0 +1,67 @@
+/*
+ * Binocs - Request Monitor Styles
+ * Base styles - Tailwind is loaded via CDN in layout
+ */
+
+/* Additional custom styles */
+.binocs-container {
+  font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+
+/* Scrollbar styling for dark theme */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: #1e293b;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #475569;
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #64748b;
+}
+
+/* Code/Pre styling */
+pre {
+  white-space: pre-wrap;
+  word-wrap: break-word;
+}
+
+/* Animation for new requests */
+@keyframes highlight-new {
+  0% {
+    background-color: rgba(99, 102, 241, 0.2);
+  }
+  100% {
+    background-color: transparent;
+  }
+}
+
+.turbo-stream-prepend {
+  animation: highlight-new 2s ease-out;
+}
+
+/* Form input styling */
+input[type="text"],
+select {
+  background-color: #334155;
+  border-color: #475569;
+  color: #f8fafc;
+}
+
+input[type="text"]:focus,
+select:focus {
+  border-color: #6366f1;
+  outline: none;
+  box-shadow: 0 0 0 2px rgba(99, 102, 241, 0.2);
+}
+
+input[type="text"]::placeholder {
+  color: #94a3b8;
+}

data/app/channels/binocs/application_cable/channel.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Binocs
+  module ApplicationCable
+    class Channel < ActionCable::Channel::Base
+    end
+  end
+end

data/app/channels/binocs/application_cable/connection.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Binocs
+  module ApplicationCable
+    class Connection < ActionCable::Connection::Base
+    end
+  end
+end

data/app/channels/binocs/requests_channel.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Binocs
+  class RequestsChannel < ApplicationCable::Channel
+    def subscribed
+      stream_from "binocs_requests"
+    end
+
+    def unsubscribed
+      # Cleanup when channel is unsubscribed
+    end
+  end
+end

data/app/controllers/binocs/application_controller.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Binocs
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+    layout "binocs/application"
+
+    before_action :verify_access
+    before_action :authenticate_binocs_user
+
+    private
+
+    def verify_access
+      if Rails.env.production?
+        render plain: "Binocs is not available in production.", status: :forbidden
+        return
+      end
+
+      return unless Binocs.configuration.basic_auth_enabled?
+
+      authenticate_or_request_with_http_basic("Binocs") do |username, password|
+        ActiveSupport::SecurityUtils.secure_compare(username, Binocs.configuration.basic_auth_username) &
+          ActiveSupport::SecurityUtils.secure_compare(password, Binocs.configuration.basic_auth_password)
+      end
+    end
+
+    def authenticate_binocs_user
+      auth_method = Binocs.configuration.authentication_method
+      return unless auth_method
+
+      # Store the current URL for redirect after login (Devise integration)
+      store_location_for_binocs
+
+      case auth_method
+      when Symbol
+        # Call the method by name (e.g., :authenticate_user!)
+        send(auth_method)
+      when Proc
+        # Call the proc with the controller instance
+        instance_exec(&auth_method)
+      when String
+        # Call the method by name as string
+        send(auth_method.to_sym)
+      end
+    end
+
+    def store_location_for_binocs
+      # Determine the Devise scope from the authentication method
+      auth_method = Binocs.configuration.authentication_method.to_s
+      match = auth_method.match(/authenticate_(\w+)!/)
+      scope = match ? match[1] : 'user'
+
+      # Check if user is already signed in (don't overwrite return URL)
+      signed_in_method = "#{scope}_signed_in?"
+      return if respond_to?(signed_in_method, true) && send(signed_in_method)
+
+      # Store directly in session using Devise's expected key format
+      # Devise looks for session["#{scope}_return_to"] after sign in
+      session["#{scope}_return_to"] = request.fullpath
+    end
+  end
+end

data/app/controllers/binocs/requests_controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Binocs
+  class RequestsController < ApplicationController
+    before_action :set_request, only: [:show, :destroy]
+
+    def index
+      @requests = Request.recent
+      @requests = apply_filters(@requests)
+      @requests = @requests.page(params[:page]).per(50) if @requests.respond_to?(:page)
+      @requests = @requests.limit(50) unless @requests.respond_to?(:page)
+
+      @stats = {
+        total: Request.count,
+        today: Request.today.count,
+        avg_duration: Request.average_duration,
+        error_rate: Request.error_rate
+      }
+
+      respond_to do |format|
+        format.html
+        format.turbo_stream
+      end
+    end
+
+    def show
+      respond_to do |format|
+        format.html
+        format.turbo_stream
+      end
+    end
+
+    def destroy
+      @request.destroy
+
+      respond_to do |format|
+        format.html { redirect_to requests_path, notice: "Request deleted." }
+        format.turbo_stream { render turbo_stream: turbo_stream.remove(@request) }
+      end
+    end
+
+    def clear
+      Request.delete_all
+
+      respond_to do |format|
+        format.html { redirect_to requests_path, notice: "All requests cleared." }
+        format.turbo_stream { render turbo_stream: turbo_stream.replace("requests-list", partial: "binocs/requests/empty_list") }
+      end
+    end
+
+    private
+
+    def set_request
+      @request = Request.find_by!(uuid: params[:id])
+    rescue ActiveRecord::RecordNotFound
+      redirect_to requests_path, alert: "Request not found."
+    end
+
+    def apply_filters(scope)
+      scope = scope.by_method(params[:method]) if params[:method].present?
+      scope = scope.by_status_range(params[:status]) if params[:status].present?
+      scope = scope.search(params[:search]) if params[:search].present?
+      scope = scope.by_controller(params[:controller_name]) if params[:controller_name].present?
+      scope = scope.with_exception if params[:has_exception] == "1"
+      scope = scope.slow(params[:slow_threshold].to_i) if params[:slow_threshold].present?
+      scope
+    end
+  end
+end

data/app/helpers/binocs/application_helper.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Binocs
+  module ApplicationHelper
+    def method_badge_class(method)
+      case method.to_s.upcase
+      when "GET"
+        "bg-green-900/50 text-green-300"
+      when "POST"
+        "bg-blue-900/50 text-blue-300"
+      when "PUT", "PATCH"
+        "bg-yellow-900/50 text-yellow-300"
+      when "DELETE"
+        "bg-red-900/50 text-red-300"
+      else
+        "bg-slate-700 text-slate-300"
+      end
+    end
+
+    def status_badge_class(status)
+      return "bg-slate-700 text-slate-300" if status.nil?
+
+      case status
+      when 200..299
+        "bg-green-900/50 text-green-300"
+      when 300..399
+        "bg-blue-900/50 text-blue-300"
+      when 400..499
+        "bg-yellow-900/50 text-yellow-300"
+      when 500..599
+        "bg-red-900/50 text-red-300"
+      else
+        "bg-slate-700 text-slate-300"
+      end
+    end
+
+    def format_value(value)
+      case value
+      when Hash, Array
+        JSON.pretty_generate(value)
+      when nil
+        "null"
+      else
+        value.to_s
+      end
+    rescue
+      value.to_s
+    end
+
+    def format_body(body)
+      return body if body.nil?
+
+      begin
+        parsed = JSON.parse(body)
+        JSON.pretty_generate(parsed)
+      rescue JSON::ParserError
+        body
+      end
+    end
+  end
+end

data/app/models/binocs/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Binocs
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/binocs/request.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Binocs
+  class Request < ApplicationRecord
+    self.table_name = "binocs_requests"
+
+    serialize :params, coder: JSON
+    serialize :request_headers, coder: JSON
+    serialize :response_headers, coder: JSON
+    serialize :logs, coder: JSON
+    serialize :exception, coder: JSON
+
+    validates :uuid, presence: true, uniqueness: true
+    validates :method, presence: true
+    validates :path, presence: true
+
+    # Scopes for filtering
+    scope :by_method, ->(method) { where(method: method.upcase) if method.present? }
+    scope :by_status, ->(status) { where(status_code: status) if status.present? }
+    scope :by_status_range, ->(range) {
+      case range
+      when "2xx" then where(status_code: 200..299)
+      when "3xx" then where(status_code: 300..399)
+      when "4xx" then where(status_code: 400..499)
+      when "5xx" then where(status_code: 500..599)
+      end
+    }
+    scope :by_path, ->(path) { where("path LIKE ?", "%#{path}%") if path.present? }
+    scope :by_controller, ->(controller) { where(controller_name: controller) if controller.present? }
+    scope :by_action, ->(action) { where(action_name: action) if action.present? }
+    scope :with_exception, -> { where.not(exception: nil) }
+    scope :without_exception, -> { where(exception: nil) }
+    scope :slow, ->(threshold_ms = 1000) { where("duration_ms > ?", threshold_ms) }
+    scope :by_ip, ->(ip) { where(ip_address: ip) if ip.present? }
+    scope :recent, -> { order(created_at: :desc) }
+    scope :today, -> { where("created_at >= ?", Time.current.beginning_of_day) }
+    scope :last_hour, -> { where("created_at >= ?", 1.hour.ago) }
+    scope :search, ->(query) {
+      return all if query.blank?
+
+      where("path LIKE :q OR controller_name LIKE :q OR action_name LIKE :q", q: "%#{query}%")
+    }
+
+    # Instance methods
+
+    # Alias for 'method' to avoid conflict with Object#method
+    def http_method
+      read_attribute(:method)
+    end
+
+    def success?
+      status_code.present? && status_code >= 200 && status_code < 300
+    end
+
+    def redirect?
+      status_code.present? && status_code >= 300 && status_code < 400
+    end
+
+    def client_error?
+      status_code.present? && status_code >= 400 && status_code < 500
+    end
+
+    def server_error?
+      status_code.present? && status_code >= 500
+    end
+
+    def has_exception?
+      exception.present?
+    end
+
+    def status_class
+      return "error" if server_error? || has_exception?
+      return "warning" if client_error?
+      return "redirect" if redirect?
+
+      "success"
+    end
+
+    def method_class
+      case method.upcase
+      when "GET" then "method-get"
+      when "POST" then "method-post"
+      when "PUT", "PATCH" then "method-put"
+      when "DELETE" then "method-delete"
+      else "method-other"
+      end
+    end
+
+    def formatted_duration
+      return "N/A" unless duration_ms
+
+      if duration_ms < 1
+        "< 1ms"
+      elsif duration_ms < 1000
+        "#{duration_ms.round(1)}ms"
+      else
+        "#{(duration_ms / 1000).round(2)}s"
+      end
+    end
+
+    def formatted_memory_delta
+      return "N/A" unless memory_delta
+
+      if memory_delta.abs < 1024
+        "#{memory_delta} B"
+      elsif memory_delta.abs < 1024 * 1024
+        "#{(memory_delta / 1024.0).round(2)} KB"
+      else
+        "#{(memory_delta / (1024.0 * 1024)).round(2)} MB"
+      end
+    end
+
+    def short_path
+      return path if path.length <= 50
+
+      "#{path[0, 47]}..."
+    end
+
+    def full_url
+      # Construct URL from host header if available
+      host = request_headers&.dig('Host') || request_headers&.dig('host') || 'localhost'
+      scheme = request_headers&.dig('X-Forwarded-Proto') || 'http'
+      "#{scheme}://#{host}#{path}"
+    end
+
+    def controller_action
+      return nil unless controller_name && action_name
+
+      "#{controller_name}##{action_name}"
+    end
+
+    def swagger_url
+      # Convert path to Swagger UI deep link format: #/{tagName}/{operationId}
+      swagger_path, tag = find_swagger_path_and_tag
+
+      # Generate operationId: method + path with non-alphanumeric chars replaced
+      # /v1/companies/{company_uuid}/invitations -> v1_companies__company_uuid__invitations
+      operation_id = "#{method.downcase}#{swagger_path.gsub(/[^a-zA-Z0-9]/, '_')}"
+
+      "/api-docs/index.html#/#{ERB::Util.url_encode(tag)}/#{operation_id}"
+    end
+
+    def find_swagger_path_and_tag
+      spec_path = Rails.root.join("swagger/v1/swagger.yaml")
+      return [path, default_tag] unless File.exist?(spec_path)
+
+      spec = YAML.load_file(spec_path)
+
+      # Find matching swagger path by converting UUIDs to param placeholders
+      spec["paths"]&.each do |swagger_path, methods|
+        # Create regex from swagger path: /v1/channels/{channel_uuid} -> /v1/channels/[^/]+
+        pattern = swagger_path.gsub(/\{[^}]+\}/, "[^/]+")
+        regex = /\A#{pattern}\z/
+
+        if path.match?(regex) && methods[method.downcase]
+          tag = methods.dig(method.downcase, "tags")&.first || default_tag
+          return [swagger_path, tag]
+        end
+      end
+
+      [path, default_tag]
+    rescue => e
+      Rails.logger.debug "[Binocs] Failed to find swagger path: #{e.message}"
+      [path, default_tag]
+    end
+
+    def default_tag
+      # Fallback: derive tag from controller name
+      # V1::CompaniesController -> "Companies"
+      return "default" unless controller_name
+
+      controller_name.demodulize.sub(/Controller$/, "").titleize
+    end
+
+    # Class methods for statistics
+    def self.average_duration
+      average(:duration_ms)&.round(2)
+    end
+
+    def self.error_rate
+      return 0 if count.zero?
+
+      ((with_exception.count + by_status_range("5xx").count).to_f / count * 100).round(2)
+    end
+
+    def self.methods_breakdown
+      group(:method).count
+    end
+
+    def self.status_breakdown
+      group(:status_code).count
+    end
+
+    def self.controllers_list
+      distinct.pluck(:controller_name).compact.sort
+    end
+  end
+end

data/app/views/binocs/requests/_empty_list.html.erb

@@ -0,0 +1,9 @@
+<div class="px-4 py-12 text-center">
+  <svg class="mx-auto h-12 w-12 text-slate-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"></path>
+  </svg>
+  <h3 class="mt-2 text-sm font-medium text-white">No requests</h3>
+  <p class="mt-1 text-sm text-slate-400">
+    Make some requests to your application and they'll appear here in real-time.
+  </p>
+</div>

data/app/views/binocs/requests/_request.html.erb

@@ -0,0 +1,61 @@
+<%= turbo_frame_tag dom_id(request) do %>
+  <%= link_to binocs.request_path(request.uuid), class: "block hover:bg-slate-700/50 transition-colors duration-150", data: { turbo_frame: "_top" } do %>
+    <div class="px-4 py-3 pr-6">
+      <div class="flex items-center justify-between">
+        <div class="flex items-center space-x-4 min-w-0">
+          <!-- Method Badge -->
+          <span class="inline-flex items-center rounded px-2 py-1 text-xs font-medium <%= method_badge_class(request.method) %>">
+            <%= request.method %>
+          </span>
+
+          <!-- Status Badge -->
+          <span class="inline-flex items-center rounded px-2 py-1 text-xs font-medium <%= status_badge_class(request.status_code) %>">
+            <%= request.status_code %>
+          </span>
+
+          <!-- Path -->
+          <span class="text-sm text-white truncate" title="<%= request.path %>">
+            <%= request.short_path %>
+          </span>
+
+          <!-- Controller#Action -->
+          <% if request.controller_action %>
+            <span class="text-xs text-slate-400">
+              <%= request.controller_action %>
+            </span>
+          <% end %>
+
+          <!-- Exception Indicator -->
+          <% if request.has_exception? %>
+            <span class="inline-flex items-center rounded-full bg-red-900/50 px-2 py-1 text-xs font-medium text-red-300">
+              <svg class="w-3 h-3 mr-1" fill="currentColor" viewBox="0 0 20 20">
+                <path fill-rule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7 4a1 1 0 11-2 0 1 1 0 012 0zm-1-9a1 1 0 00-1 1v4a1 1 0 102 0V6a1 1 0 00-1-1z" clip-rule="evenodd"></path>
+              </svg>
+              Exception
+            </span>
+          <% end %>
+        </div>
+
+        <div class="flex items-center space-x-4 text-sm text-slate-400 flex-shrink-0 pl-4">
+          <!-- Duration -->
+          <span title="Duration" class="whitespace-nowrap">
+            <svg class="w-4 h-4 inline-block mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z"></path>
+            </svg>
+            <%= request.formatted_duration %>
+          </span>
+
+          <!-- IP Address -->
+          <span title="IP Address" class="hidden lg:inline whitespace-nowrap">
+            <%= request.ip_address %>
+          </span>
+
+          <!-- Timestamp -->
+          <span title="<%= request.created_at %>" class="whitespace-nowrap">
+            <%= time_ago_in_words(request.created_at) %> ago
+          </span>
+        </div>
+      </div>
+    </div>
+  <% end %>
+<% end %>