vigiles 0.1.0.pre.beta2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d020325255cc9a0513dbc92c0460fce06536b59a18c0fbe7c3d5b549f40aa0d2
+  data.tar.gz: '0096c987ef42a2b552667ed494c8a20601ff8355e647048169a5445afc33d337'
+SHA512:
+  metadata.gz: 84fde40e68c78440e04b7aebb79a07d0876d8b5c5c24b5499cfcc2915a3e34776450602d0531474c3588e631090f4acce3baeef6c2fef760d8d3b75678e3d059
+  data.tar.gz: 29f49773ea835792322a44e8620320d2be31fdcdce3cd286e317a30a57348aa6b1b3c61c75e2016803b5fbdb5bdba6882dad5c647446bbec4c992b7bf375d8f2

data/.rubocop.yml

@@ -0,0 +1,26 @@
+require:
+  - rubocop-rake
+  - rubocop-minitest
+  - rubocop-sorbet
+
+AllCops:
+  TargetRubyVersion: 2.7
+  Exclude:
+    - "**/generators/**/*"
+    - "**/sorbet/**/*"
+    - "**/bin/**/*"
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/AccessModifierDeclarations:
+  Enabled: true
+  EnforcedStyle: inline
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-03-05
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Yaw Boakye
+
+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,14 @@
+# Vigiles
+
+Sometimes it helps to be able to examine, in totality, the request your
+Rails application received, and the specific response it elicited. Very handy
+when you're debugging. Also very handy when your engineers have to assist
+non-technical customer support staff. That aside, it's generally a great
+visualization of the black box abstraction, where your entire application is
+seen as one logical function, taking input (request) and producing output
+(response).
+
+At the moment, this gem is unable to conduct you on your research journey from a
+given request to its response: you'd have to call on your logs and other
+observability systems you've engaged. But it's easy—rather,
+possible—to see how we can bring this in house, with a little tracing.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/core_ext/object.rb

@@ -0,0 +1,7 @@
+# typed: strict
+# frozen_string_literal: true
+
+class Object
+  extend T::Sig
+  extend T::Helpers
+end

data/lib/core_ext.rb

@@ -0,0 +1,4 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative "core_ext/object"

data/lib/generators/templates/archive_conversation_migration.rb.erb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class CreateVigilesArchiveConversationsTable < ActiveRecord::Migration<%= migration_version %>
+
+  def change
+    create_table :vigiles_archive_conversations do |t|
+      t.text     :request_content_type, null: false
+      t.text     :request_user_agent,   null: false
+      t.datetime :request_timestamp,    null: false
+      t.inet     :request_remote_ip,    null: false
+      t.text     :request_protocol,     null: false
+      t.jsonb    :request_headers,      null: false, default: {}
+
+      # if the request doesn't origin from an identifiable origin,
+      # like a website, this value is typically nil. in which case
+      # we can substitute with `request_user_agent`.
+      t.text     :request_origin
+      t.jsonb    :request_payload,      null: false, default: {}
+      t.text     :request_method,       null: false
+      t.text     :request_path,         null: false
+      t.text     :request_url,          null: false
+      t.text     :request_id,           null: false
+
+      t.text     :response_content_type, null: false
+      t.jsonb    :response_headers,      null: false
+      t.jsonb    :response_payload,      null: false
+      t.integer  :response_status,       null: false
+
+      # conversation `metadata` holds all other information that might be
+      # useful when inspecting the conversation. for example, metadata
+      # could hold user information (id, rate limiting usage, etc), or
+      # the (rack) environment within which rails handled the request.
+      t.jsonb :metadata, null: false, default: {}
+
+      # `extras` are added here as convenience. it's a grab bag of all
+      # data that wouldn't cleanly fit in any of the above columns. it's
+      # also a mixed bag of request and response data.
+      t.jsonb :extras, null: false, default: {}
+    end
+  end
+end

data/lib/generators/templates/initializer.rb

@@ -0,0 +1,6 @@
+# typed: false
+# frozen_string_literal: true
+
+Vigiles.configure do |spec|
+
+end

data/lib/generators/vigiles/initializer_generator.rb

@@ -0,0 +1,22 @@
+# typed: false
+# frozen_string_literal: true
+
+module Vigiles
+  module Generators
+    class InitializerGenerator < ::Rails::Generators::Base
+      desc <<~DOC.squish
+        This generator creates the vigiles initializer file at the
+        `config/initializers/vigiles.rb` path and sets up a sane
+        default configuration.
+      DOC
+
+      source_root File.expand_path("../templates", __dir__)
+
+      def copy_initializer_file
+        copy_file \
+          "initializer.rb",
+          "config/initializers/vigiles.rb"
+      end
+    end
+  end
+end

data/lib/generators/vigiles/install_generator.rb

@@ -0,0 +1,25 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative "initializer_generator"
+
+module Vigiles
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      SUB_GENERATORS = Set.new(
+        %w[
+          vigiles:initializer
+          vigiles:migration
+        ]
+      ).freeze
+
+      source_root File.expand_path("../templates", __dir__)
+
+      def install_vigiles
+        SUB_GENERATORS.each do |generator_task|
+          invoke generator_task
+        end
+      end
+    end
+  end
+end

data/lib/generators/vigiles/migration_generator.rb

@@ -0,0 +1,32 @@
+# typed: false
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Vigiles
+  module Generators
+    class MigrationGenerator < ::Rails::Generators::Base
+      desc <<~DOC.squish
+      DOC
+
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("../templates", __dir__)
+
+      def install
+        migration_template(
+          "archive_conversation_migration.rb.erb",
+          "db/migrate/create_vigiles_archive_conversations_table.rb",
+          migration_version:
+        )
+      end
+
+      def migration_version = "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+    end
+  end
+end

data/lib/vigiles/archive/conversation.rb

@@ -0,0 +1,12 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "active_record"
+
+module Vigiles
+  module Archive
+    class Conversation < ::ActiveRecord::Base
+      self.table_name = "vigiles_archive_conversations"
+    end
+  end
+end

data/lib/vigiles/archive/extras.rb

@@ -0,0 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Vigiles
+  module Archive
+    class Extras < T::Struct;
+      const :request_env, T.untyped
+
+      def self.from(request_env)
+        Extras.new(request_env:)
+      end
+    end
+  end
+end

data/lib/vigiles/archive/metadata.rb

@@ -0,0 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Vigiles
+  module Archive
+    class Metadata < T::Struct
+      const :request_env, T.untyped
+
+      def self.from(request_env)
+        Metadata.new(request_env:)
+      end
+    end
+  end
+end

data/lib/vigiles/archive/request.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "uri"
+
+module Vigiles
+  module Archive
+    extend T::Sig
+
+    class Request < T::Struct
+      const :content_type, String
+      const :http_method,  Types::HttpMethod
+      const :user_agent,   String
+      const :timestamp,    DateTime
+      const :remote_ip,    IPAddr
+      const :protocol,     String
+      const :headers,      Types::Headers
+      const :origin,       String
+      const :payload,      Types::Payload
+      const :path,         String
+      const :url,          T.any(URI::HTTPS, URI::HTTP)
+      const :id,           String
+
+      sig { params(request: ActionDispatch::Request).returns(Request) }
+      def self.from(request)
+        Request.new(
+          content_type: request.content_type,
+          user_agent: request.user_agent,
+          timestamp: DateTime.now,
+          remote_ip: IPAddr.new(request.remote_ip),
+          protocol: request.protocol,
+          headers: {},
+          origin: request.origin || "n/a",
+          payload: request.body.read,
+          http_method: Types::HttpMethod.deserialize(request.method),
+          path: request.path,
+          url: URI.parse(request.url),
+          id: request.request_id
+        )
+      end
+    end
+  end
+end

data/lib/vigiles/archive/response.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Vigiles
+  module Archive
+    class Response < T::Struct
+      const :content_type, String
+      const :headers,      Types::Headers
+      const :payload,      Types::Payload
+      const :status,       Integer
+
+      sig { params(response: ActionDispatch::Response).returns(Response) }
+      def self.from(response)
+        Response.new(
+          content_type: response.content_type,
+          headers: response.headers.as_json,
+          payload: response.body,
+          status: response.status
+        )
+      end
+    end
+  end
+end

data/lib/vigiles/archive.rb

@@ -0,0 +1,72 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "action_dispatch"
+
+module Vigiles
+  module Archive
+    extend T::Sig
+
+    Types       = Vigiles::Types
+    ContentType = Types::ContentType
+
+    sig { params(ad_response: ActionDispatch::Response).returns(T.nilable(Conversation)) }
+    def self.record_conversation(ad_response)
+        # preferring to call `response.request` instead of preparing a new
+        # request (via `ActionDispatch::Request.new(env)` and passing it
+        # as an argument to this method because we can always recover the
+        # specific request that elicited a given response, according to
+        # https://github.com/rails/rails/blob/cacb8475a9d4373c0db437e7be4905685f03cefa/actionpack/lib/action_dispatch/http/response.rb#L53
+      ad_request = ad_response.request
+      response   = Response.from(ad_response)
+      metadata   = Metadata.from(ad_request.env)
+      request    = Request.from(ad_request)
+      extras     = Extras.from(ad_request.env)
+
+      case (content_type = request.content_type)
+      when ContentType::ApplicationJson.serialize then record_json_conversation(request:, response:, metadata:, extras:)
+      when ContentType::TextHtml.serialize        then record_html_conversation(request:, response:, metadata:, extras:)
+      else record_conversation_with_unknown_content_type(request:)
+      end
+    end
+
+    sig do
+      params(
+        request: Request,
+        response: Response,
+        metadata: Metadata,
+        extras: Extras
+      )
+        .returns(T.nilable(Conversation))
+    end
+    private_class_method def self.record_json_conversation(request:, response:, metadata:, extras:)
+      Conversation.create!(
+        request_content_type: request.content_type,
+        request_user_agent: request.user_agent,
+        request_timestamp: request.timestamp,
+        request_remote_ip: request.remote_ip,
+        request_protocol: request.protocol,
+        request_headers: request.headers,
+        request_origin: request.origin,
+        request_payload: request.payload,
+        request_method: request.http_method.serialize,
+        request_path: request.path,
+        request_url: request.url,
+        request_id: request.id,
+        response_content_type: response.content_type,
+        response_headers: response.headers,
+        response_payload: JSON.load(response.payload),
+        response_status: response.status
+      )
+    rescue => e
+    end
+    private_class_method def self.record_html_conversation(request:, response:, metadata:, extras:); end
+    private_class_method def self.record_conversation_with_unknown_content_type(
+      request:,
+      response:,
+      metadata:,
+      extras:
+    )
+    end
+  end
+end

data/lib/vigiles/middleware/record_conversation.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "rack"
+
+module Vigiles
+  module Middleware
+    class RecordConversation
+      class Options < T::Struct
+        const :logger, T.untyped
+
+        sig { returns(Options) }
+        def self.defaults
+          Options.new(
+            logger: Rails.logger
+          )
+        end
+      end
+
+      sig { params(app: T.untyped, options: Options).void }
+      def initialize(app, options = Options.defaults)
+        @app    = app
+        @logger = options.logger
+      end
+
+      sig { params(env: T.untyped).returns(T.untyped) }
+      def call(env)
+        record_conversation do
+          @app.call(env)
+        end
+      end
+
+      private def record_conversation(&blk)
+        rack_response = blk.call
+        _, _, body    = rack_response
+        response      = body.instance_variable_get(:@response)
+
+        convo = Vigiles.maybe_record_conversation(response)
+        @logger.info "conversation recorded: conversation_id=#{convo&.id}" if convo
+
+        rack_response
+      ensure
+        rack_response
+      end
+    end
+  end
+end

data/lib/vigiles/spec.rb

@@ -0,0 +1,9 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Vigiles
+  class Spec < T::Struct
+    sig { returns(Spec) }
+    def self.make_default_spec; end
+  end
+end

data/lib/vigiles/types.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Vigiles
+  module Types
+    extend T::Sig
+
+    class ContentType < T::Enum
+      enums do
+        ApplicationJson = new("application/json")
+        TextHtml        = new("text/html")
+        Unknown         = new
+      end
+    end
+
+    class HttpMethod < T::Enum
+      enums do
+        OPTIONS = new("OPTIONS")
+        DELETE  = new("DELETE")
+        POST    = new("POST")
+        HEAD    = new("HEAD")
+        GET     = new("GET")
+        PUT     = new("PUT")
+      end
+    end
+
+    Headers     = T.type_alias { T::Hash[String, T.untyped] }
+    JsonPayload = T.type_alias { T::Hash[T.untyped, T.untyped] }
+    HtmlPayload = String
+    Payload     = T.type_alias { T.any(JsonPayload, HtmlPayload) }
+  end
+end

data/lib/vigiles/version.rb

@@ -0,0 +1,6 @@
+# typed: false
+# frozen_string_literal: true
+
+module Vigiles
+  VERSION = "0.1.0-beta2"
+end

data/lib/vigiles.rb

@@ -0,0 +1,41 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "sorbet-runtime"
+require_relative "core_ext"
+
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.ignore("#{__dir__}/generators")
+loader.ignore("#{__dir__}/core_ext.rb")
+loader.ignore("#{__dir__}/core_ext")
+loader.setup
+
+module Vigiles
+  extend T::Sig
+
+  sig { params(response: ActionDispatch::Response).returns(T.nilable(Archive::Conversation)) }
+  def self.maybe_record_conversation(response)
+    return unless should_record?(response)
+
+    Archive.record_conversation(response)
+  end
+
+  sig { params(blk: T.untyped).void }
+  def self.configure(&blk)
+    default_spec = Vigiles::Spec.default_specification
+    blk.call(default_spec)
+  end
+
+  sig { params(request: ActionDispatch::Request).returns(T::Boolean) }
+  private_class_method def self.content_type_match?(request)
+    !request.nil?
+  end
+
+  sig { params(response: ActionDispatch::Response).returns(T::Boolean) }
+  private_class_method def self.should_record?(response)
+    request = response.request
+
+    content_type_match?(request)
+  end
+end

data/sorbet/config

@@ -0,0 +1,4 @@
+--dir
+.
+--ignore=tmp/
+--ignore=vendor/

data/sorbet/rbi/annotations/.gitattributes

@@ -0,0 +1 @@
+**/*.rbi linguist-vendored=true

data/sorbet/rbi/annotations/activemodel.rbi

@@ -0,0 +1,89 @@
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This file was pulled from a central RBI files repository.
+# Please run `bin/tapioca annotations` to update it.
+
+class ActiveModel::Errors
+  Elem = type_member { { fixed: ActiveModel::Error } }
+
+  sig { params(attribute: T.any(Symbol, String)).returns(T::Array[String]) }
+  def [](attribute); end
+
+  sig { params(attribute: T.any(Symbol, String), type: T.untyped, options: T.untyped).returns(ActiveModel::Error) }
+  def add(attribute, type = :invalid, **options); end
+
+  sig { params(attribute: T.any(Symbol, String), type: T.untyped, options: T.untyped).returns(T::Boolean) }
+  def added?(attribute, type = :invalid, options = {}); end
+
+  sig { params(options: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
+  def as_json(options = nil); end
+
+  sig { returns(T::Array[Symbol]) }
+  def attribute_names; end
+
+  sig { params(attribute: T.any(Symbol, String), type: T.untyped, options: T.untyped).returns(T.nilable(T::Array[String])) }
+  def delete(attribute, type = nil, **options); end
+
+  sig { returns(T::Hash[Symbol, T::Array[T::Hash[Symbol, T.untyped]]]) }
+  def details; end
+
+  sig { returns(T::Array[Elem]) }
+  def errors; end
+
+  sig { params(attribute: T.any(Symbol, String), message: String).returns(String) }
+  def full_message(attribute, message); end
+
+  sig { returns(T::Array[String]) }
+  def full_messages; end
+
+  sig { params(attribute: T.any(Symbol, String)).returns(T::Array[String]) }
+  def full_messages_for(attribute); end
+
+  sig { params(attribute: T.any(Symbol, String), type: T.untyped, options: T.untyped).returns(String) }
+  def generate_message(attribute, type = :invalid, options = {}); end
+
+  sig { returns(T::Hash[Symbol, T::Array[ActiveModel::Error]]) }
+  def group_by_attribute; end
+
+  sig { params(attribute: T.any(Symbol, String)).returns(T::Boolean) }
+  def has_key?(attribute); end
+
+  sig { params(error: ActiveModel::Error, override_options: T.untyped).returns(T::Array[ActiveModel::Error]) }
+  def import(error, override_options = {}); end
+
+  sig { params(attribute: T.any(Symbol, String)).returns(T::Boolean) }
+  def include?(attribute); end
+
+  sig { params(attribute: T.any(Symbol, String)).returns(T::Boolean) }
+  def key?(attribute); end
+
+  sig { params(other: T.untyped).returns(T::Array[ActiveModel::Error]) }
+  def merge!(other); end
+
+  sig { returns(T::Hash[Symbol, T::Array[String]]) }
+  def messages; end
+
+  sig { params(attribute: T.any(Symbol, String)).returns(T::Array[String]) }
+  def messages_for(attribute); end
+
+  sig { returns(T::Array[Elem]) }
+  def objects; end
+
+  sig { params(attribute: T.any(Symbol, String), type: T.untyped).returns(T::Boolean) }
+  def of_kind?(attribute, type = :invalid); end
+
+  sig { returns(T::Array[String]) }
+  def to_a; end
+
+  sig { params(full_messages: T.untyped).returns(T::Hash[Symbol, T::Array[String]]) }
+  def to_hash(full_messages = false); end
+
+  sig { params(attribute: T.any(Symbol, String), type: T.untyped, options: T.untyped).returns(T::Array[ActiveModel::Error]) }
+  def where(attribute, type = nil, **options); end
+end
+
+module ActiveModel::Validations
+  sig { returns(ActiveModel::Errors) }
+  def errors; end
+end