paper_view 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b12547320bb6d8dd78354092beee8c80f6fe2936e7476ef766791c7fdd2caa2
-  data.tar.gz: 35aef5e07fbf35d80559c57e961ad7b388aaee2de8ca7d16e0f6c8279f48d096
+  metadata.gz: e5b8c10c7eacd5de4647ef283af9a141770cdee45592572ea0c5b690991f3990
+  data.tar.gz: c245d622bd0061bba67a1ef574938d83c83c01717688efd8ecede618bcb02b43
 SHA512:
-  metadata.gz: 5771770579c64ff7442fbbfdea10a9b071917e45c2e0ecda1cd8fa8e30d8c461eaa21ffa85bf81fa389a9e507ac7bebcf831cdc3a41990224aa69ae45eb201ef
-  data.tar.gz: e4129deda604f38f7c862ebf8afa45e1b4b2bc18930ed747f647170e76b3dda48080562940041990939bc056e67b3bf8400d71cc7cac2325710dadbebfe75f45
+  metadata.gz: baaecb34237b30125aa4cb6d082241336ec38cb8ec76e7292e15f4d0185ba26c56ad0e32a99b925fd96350064e18ae408d2b7e2ed7ce4271d1c25e9f954b6dca
+  data.tar.gz: d15fdc166fe827652b429666ef5fe1ea4eb8189edf33a0a7428eff19bd95c5ecf8ea8e1eeafb066a28b0bde9cebcbcdad2f4c82e012b96a391c1aa9431f9ee6d

data/README.md

@@ -1,7 +1,9 @@
 # PaperView
 
 A lightweight, mountable dashboard for [paper_trail](https://github.com/paper-trail-gem/paper_trail).
-Browse the `versions` table and read, in one chronological timeline, what actually changed.   
+Browse the `versions` table and read, in a chronological timeline, what actually changed.   
+
+![preview](https://res.cloudinary.com/dlvuixik3/image/upload/v1789159753/paper_view_preview_aclugn.png)
 
 ## Installation
 
@@ -18,7 +20,7 @@ gem "paper_view"
 # config/routes.rb
 Rails.application.routes.draw do
   authenticate :user, ->(user) { user.admin? } do
-    mount PaperView::Engine => "/paper_view"
+    mount PaperView::Engine => "/versions"
   end
 end
 ```
@@ -45,6 +47,10 @@ PaperView.setup do |config|
 
   config.per_page = 25
 
+  # The exact columns to show as metadata. Defaults to every column that
+  # paper_trail does not write itself, so usually nothing has to be set here.
+  # config.metadata_columns = %w[ip user_agent]
+
   # Any model with the paper_trail column layout works here.
   # Required interface: id, item_type, item_id, event, whodunnit, created_at, object_changes
   config.version_class_name = "PaperTrail::Version"
@@ -52,3 +58,29 @@ end
 ```
 
 Visit `/paper_view`.
+
+## Metadata
+
+paper_trail can store [extra columns](https://github.com/paper-trail-gem/paper_trail#4c-storing-metadata) on a
+version, either through `has_paper_trail meta: { ... }` or through `controller_info`:
+
+```ruby
+class Post < ApplicationRecord
+  has_paper_trail meta: {author_id: :author_id}
+end
+```
+
+Every column of the `versions` table counts as metadata, except the ones paper_trail writes itself:
+`id`, `item_type`, `item_subtype`, `item_id`, `event`, `whodunnit`, `object`, `object_changes`,
+`created_at`, `updated_at` and `transaction_id`.
+
+Set `config.metadata_columns` to the exact list you want if your table carries columns you would
+rather not see — anything left out of that list is then hidden.
+
+## PaperTrail setup
+
+To work properly, PaperView requires an `object_changes` column in your `versions` table. This can be added by running the installation generator with the `--with-changes` option. This can be done even if you already have a `versions` table; it will generate a migration that adds the `object_changes` column to your existing `versions` table:
+
+```bash
+rails generate paper_trail:install --with-changes
+```

data/app/controllers/paper_view/stats_controller.rb

@@ -0,0 +1,12 @@
+module PaperView
+  class StatsController < ApplicationController
+    def show
+      # First request shows skeletons.
+      # Second request comes with load_content param
+      return unless params[:load_content]
+
+      @stats = TableStats.new
+      render partial: "stats", locals: {stats: @stats}, layout: false if request.xhr?
+    end
+  end
+end

data/app/helpers/paper_view/application_helper.rb

@@ -14,6 +14,16 @@ module PaperView
       tag.time(time.strftime(PaperView.config.time_format), datetime: time.iso8601, title: time.iso8601)
     end
 
+    def paper_view_bytes(bytes)
+      return EMPTY if bytes.nil?
+
+      number_to_human_size(bytes, precision: 3, significant: true, strip_insignificant_zeros: true)
+    end
+
+    def paper_view_percentage(share)
+      number_to_percentage(share * 100, precision: 1, significant: false, strip_insignificant_zeros: false)
+    end
+
     def paper_view_item_path(version)
       versions_path(item_type: version.item_type, item_id: version.item_id)
     end
@@ -27,6 +37,22 @@ module PaperView
       safe_join(paper_view_filter_params.except(*excluded).map { |name, value| hidden_field_tag(name, value, id: nil) })
     end
 
+    def paper_view_nav_class(active)
+      active ? "pv-header__link pv-header__link--active" : "pv-header__link"
+    end
+
+    def paper_view_turbo_script_tag
+      return unless PaperView.config.turbo
+
+      javascript_include_tag(turbo_asset_path(digest: PaperView::TurboAsset::DIGEST), type: "module", nonce: true)
+    end
+
+    # A Turbo visit from the host app would swap our markup and styles into its document.
+    # Our own Turbo announces itself, so every other visit is sent through a full reload.
+    def paper_view_full_reload_required?
+      request.headers["X-PaperView-Turbo"].blank?
+    end
+
     def paper_view_nonce_attribute
       nonce = content_security_policy_nonce
       return unless nonce

data/app/models/paper_view/metadata.rb

@@ -0,0 +1,73 @@
+module PaperView
+  class Metadata
+    include Enumerable
+
+    # Everything paper_trail itself writes. Whatever else the table carries was put
+    # there by `has_paper_trail meta:` or `controller_info`, which is the metadata.
+    PAPER_TRAIL_COLUMNS = %w[
+      id item_type item_subtype item_id event whodunnit
+      object object_changes created_at updated_at transaction_id
+    ].freeze
+
+    VISIBLE = 2
+
+    Entry = Struct.new(:name, :value) do
+      def text
+        AttributeChange.display(value)
+      end
+    end
+
+    def self.for(version)
+      new(version, columns(version))
+    end
+
+    def self.columns(version)
+      configured = PaperView.config.metadata_columns
+      return Array(configured).map(&:to_s) if configured
+
+      table_columns(version) - PAPER_TRAIL_COLUMNS
+    end
+
+    def self.table_columns(version)
+      version.class.respond_to?(:column_names) ? version.class.column_names.map(&:to_s) : []
+    end
+
+    attr_reader :entries
+
+    def initialize(version, columns)
+      @entries = columns.filter_map do |name|
+        value = read(version, name)
+        Entry.new(name, value) unless blank?(value)
+      end
+    end
+
+    def each(&block)
+      entries.each(&block)
+    end
+
+    def empty?
+      entries.empty?
+    end
+
+    def visible
+      entries.first(VISIBLE)
+    end
+
+    def hidden
+      entries.drop(VISIBLE)
+    end
+
+    private
+
+    def read(version, name)
+      version.public_send(name) if version.respond_to?(name)
+    rescue
+      nil
+    end
+
+    def blank?(value)
+      return true if value.nil?
+      value.respond_to?(:empty?) ? value.empty? : false
+    end
+  end
+end

data/app/models/paper_view/payload_sizes.rb

@@ -0,0 +1,107 @@
+module PaperView
+  # Estimates how many bytes of payload each item type keeps in the versions table.
+  #
+  # Both paths read a bounded slice instead of the whole table: PostgreSQL samples pages
+  # from across the table, every other adapter reads the newest rows.
+  class PayloadSizes
+    COLUMNS = %w[object object_changes].freeze
+    SAMPLE_PAGES = 4_000
+    SAMPLE_ROWS = 5_000
+    # Fixed so that the same pages come back every time: an estimate that changes
+    # on every refresh reads like a bug, and a new sample is no more true than the last.
+    SAMPLE_SEED = 1
+
+    def initialize(versions_table)
+      @versions_table = versions_table
+    end
+
+    def measurable?
+      average_bytes.any?
+    end
+
+    def average_bytes
+      return @average_bytes if defined?(@average_bytes)
+      return @average_bytes = {} if columns.empty?
+
+      @average_bytes = averages(versions_table.postgresql? ? page_sample : head_sample)
+    rescue ActiveRecord::StatementInvalid
+      @average_bytes = {}
+    end
+
+    private
+
+    attr_reader :versions_table
+
+    def columns
+      @columns ||= COLUMNS & version_class.column_names
+    end
+
+    # Item types too rare to land in the sample fall back to the overall average, so that
+    # their bytes still count towards the total instead of quietly going missing.
+    def averages(sample)
+      rows = sample.sum { |_, count, _| count }
+      return {} if rows.zero?
+
+      overall = sample.sum { |_, _, bytes| bytes } / rows
+      sample.each_with_object(Hash.new(overall)) { |(item_type, count, bytes), averages| averages[item_type] = bytes / count }
+    end
+
+    def page_sample
+      select_sample(<<~SQL)
+        SELECT #{item_type_column}, COUNT(*), COALESCE(SUM(#{payload_size}), 0)
+        FROM #{version_class.quoted_table_name} TABLESAMPLE SYSTEM (#{sample_percent}) REPEATABLE (#{SAMPLE_SEED})
+        GROUP BY #{item_type_column}
+      SQL
+    end
+
+    # Payloads grow as models gain columns, so the newest rows are the ones that
+    # say what the table weighs now.
+    def head_sample
+      newest = version_class.select(item_type_column, Arel.sql("#{payload_size} AS pv_bytes")).limit(SAMPLE_ROWS)
+      newest = newest.order(version_class.primary_key => :desc) if version_class.primary_key
+
+      select_sample(<<~SQL)
+        SELECT #{item_type_column}, COUNT(*), COALESCE(SUM(pv_bytes), 0)
+        FROM (#{newest.to_sql}) pv_sample
+        GROUP BY #{item_type_column}
+      SQL
+    end
+
+    def select_sample(sql)
+      connection.select_rows(sql, "PaperView Payload Sample").map { |item_type, count, bytes| [item_type, count.to_i, bytes.to_f] }
+    end
+
+    # A fixed percentage reads more the bigger the table gets, which is backwards for a
+    # page nobody wants to wait on. Aim at a page count and let the percentage follow.
+    def sample_percent
+      pages = versions_table.heap_pages
+      return 100 if pages <= SAMPLE_PAGES
+
+      (SAMPLE_PAGES * 100.0 / pages).ceil(4)
+    end
+
+    def payload_size
+      @payload_size ||= columns.map { |column| "COALESCE(#{byte_length(connection.quote_column_name(column))}, 0)" }.join(" + ")
+    end
+
+    # Reports the stored size, so a compressed or out-of-line payload is counted as it sits on disk.
+    def byte_length(column)
+      return "pg_column_size(#{column})" if versions_table.postgresql?
+      return "LENGTH(CAST(#{column} AS BLOB))" if versions_table.sqlite?
+
+      "LENGTH(#{column})"
+    end
+
+    def item_type_column
+      connection.quote_column_name("item_type")
+    end
+
+    def version_class
+      PaperView.version_class
+    end
+
+    def connection
+      version_class.connection
+    end
+  end
+end

data/app/models/paper_view/table_stats.rb

@@ -0,0 +1,62 @@
+module PaperView
+  class TableStats
+    Row = Struct.new(:item_type, :count, :average_bytes) do
+      def estimated_bytes
+        return nil if average_bytes.nil?
+
+        (average_bytes * count).round
+      end
+
+      def share(total)
+        return 0.0 if total.nil? || total.zero?
+
+        estimated_bytes.to_i / total.to_f
+      end
+    end
+
+    def rows
+      @rows ||= counts.map { |item_type, count| Row.new(item_type, count, payload_sizes.average_bytes[item_type]) }
+        .sort_by { |row| [-row.estimated_bytes.to_i, -row.count] }
+    end
+
+    def empty?
+      rows.empty?
+    end
+
+    def total_count
+      @total_count ||= rows.sum(&:count)
+    end
+
+    def estimated_total_bytes
+      return nil unless measurable?
+
+      @estimated_total_bytes ||= rows.sum { |row| row.estimated_bytes.to_i }
+    end
+
+    def disk_size
+      versions_table.disk_size
+    end
+
+    private
+
+    def measurable?
+      payload_sizes.measurable?
+    end
+
+    def counts
+      @counts ||= version_class.group(:item_type).count
+    end
+
+    def payload_sizes
+      @payload_sizes ||= PayloadSizes.new(versions_table)
+    end
+
+    def versions_table
+      @versions_table ||= VersionsTable.new
+    end
+
+    def version_class
+      PaperView.version_class
+    end
+  end
+end

data/app/models/paper_view/timeline.rb

@@ -23,12 +23,12 @@ module PaperView
       @items ||= rows.map(&:item_key).uniq
     end
 
-    def stream?
+    def multi_item_view?
       items.size != 1
     end
 
     def title
-      stream? ? "All changes" : rows.first.item_label
+      multi_item_view? ? "All changes" : rows.first.item_label
     end
 
     def selected

data/app/models/paper_view/version_row.rb

@@ -34,6 +34,10 @@ module PaperView
       [version.item_type, version.item_id]
     end
 
+    def metadata
+      @metadata ||= Metadata.for(version)
+    end
+
     def burst?
       burst_size > 1
     end
@@ -42,17 +46,37 @@ module PaperView
       "#{burst_size} versions within 1s"
     end
 
+    def created?
+      event == "create"
+    end
+
     def destroyed?
       event == "destroy"
     end
 
+    def snapshot?
+      created? || destroyed?
+    end
+
+    def change_label
+      noun = case event
+      when "create" then "initial value"
+      when "destroy" then "final value"
+      else "changed field"
+      end
+
+      "#{change_set.size} #{noun.pluralize(change_set.size)}"
+    end
+
     def lines
-      leaves.first(MAX_LINES)
+      snapshot? ? [] : leaves.first(MAX_LINES)
     end
 
     def footnotes
       notes = []
       notes << "payload not deserializable" if change_set.unreadable?
+      return notes if snapshot?
+
       notes << "..." if overflow_count.positive?
       notes << "no attribute changes recorded" if leaves.empty? && !change_set.unreadable?
       notes
@@ -81,14 +105,12 @@ module PaperView
         version = #{PaperView.config.version_class_name}.find(#{id})
         item    = version.reify          # the deleted record
 
-        item.attributes                  # columns added since are nil here
-
-        # item.save!                     # re-create the record
+        # item.save!                     # re-create the record; columns added since are nil
       RUBY
     end
 
     def leaves
-      @leaves ||= destroyed? ? [LeafChange.new("record", item_label, nil)] : change_set.flat_map(&:leaves)
+      @leaves ||= change_set.flat_map(&:leaves)
     end
 
     def overflow_count

data/app/models/paper_view/versions_table.rb

@@ -1,5 +1,7 @@
 module PaperView
   class VersionsTable
+    DiskSize = Struct.new(:table, :indexes)
+
     def item_types
       return distinct_scan unless postgresql? && item_type_indexed?
 
@@ -12,6 +14,35 @@ module PaperView
       @item_type_indexed = connection.indexes(version_class.table_name).any? { |index| Array(index.columns).first == "item_type" }
     end
 
+    def disk_size
+      return @disk_size if defined?(@disk_size)
+
+      sql = disk_size_sql
+      row = sql && connection.select_rows(sql).first
+      @disk_size = row && DiskSize.new(*row.map(&:to_i))
+    rescue ActiveRecord::StatementInvalid
+      @disk_size = nil
+    end
+
+    def heap_pages
+      connection.select_value(<<~SQL).to_i
+        #{partition_tree_cte}
+        SELECT COALESCE(SUM(pg_relation_size(oid)), 0) / current_setting('block_size')::bigint FROM pv_tree
+      SQL
+    end
+
+    def postgresql?
+      connection.adapter_name.match?(/postgres/i)
+    end
+
+    def mysql?
+      connection.adapter_name.match?(/mysql|trilogy|maria/i)
+    end
+
+    def sqlite?
+      connection.adapter_name.match?(/sqlite/i)
+    end
+
     private
 
     def version_class
@@ -22,14 +53,39 @@ module PaperView
       version_class.connection
     end
 
-    def postgresql?
-      connection.adapter_name.match?(/postgres/i)
-    end
-
     def distinct_scan
       version_class.distinct.order(:item_type).pluck(:item_type)
     end
 
+    def disk_size_sql
+      if postgresql?
+        <<~SQL
+          #{partition_tree_cte}
+          SELECT COALESCE(SUM(pg_table_size(oid)), 0), COALESCE(SUM(pg_indexes_size(oid)), 0) FROM pv_tree
+        SQL
+      elsif mysql?
+        <<~SQL
+          SELECT data_length, index_length
+          FROM information_schema.tables
+          WHERE table_schema = DATABASE() AND table_name = #{connection.quote(version_class.table_name)}
+        SQL
+      end
+    end
+
+    # A partitioned table keeps no rows of its own, so every size it reports is zero
+    # until the partitions underneath it are counted too.
+    def partition_tree_cte
+      relation = "#{connection.quote(version_class.quoted_table_name)}::regclass"
+
+      <<~SQL
+        WITH RECURSIVE pv_tree AS (
+          SELECT #{relation} AS oid
+          UNION ALL
+          SELECT partition.inhrelid FROM pg_inherits partition JOIN pv_tree ON partition.inhparent = pv_tree.oid
+        )
+      SQL
+    end
+
     # A plain DISTINCT reads every row. This walks the item_type index
     # and jumps straight from one item_type to the next one.
     def skip_scan_sql

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

@@ -4,25 +4,33 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="turbo-visit-control" content="reload">
+    <% if paper_view_full_reload_required? %>
+      <meta name="turbo-visit-control" content="reload">
+    <% end %>
+    <meta name="turbo-cache-control" content="no-preview">
     <meta name="robots" content="noindex, nofollow">
 
     <title>PaperView</title>
-    <%= tag.link rel: "icon", href: 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 0 100 100"><text y=".90em" font-size="90">👀</text></svg>' %>
+    <%= tag.link rel: "icon", href: 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 0 100 100"><text y=".90em" font-size="90">📝</text></svg>' %>
     <%= csrf_meta_tags %>
     <%= csp_meta_tag %>
     <%= render "paper_view/shared/styles" %>
+    <%= paper_view_turbo_script_tag %>
   </head>
 
   <body>
     <header class="pv-header">
       <%= link_to root_path, class: "pv-header__brand" do %>
-        <span class="pv-header__dot"></span>
         PaperView
       <% end %>
 
+      <nav class="pv-header__nav">
+        <%= link_to "Versions", root_path, class: paper_view_nav_class(controller_name == "versions") %>
+        <%= link_to "Stats", stats_path, class: paper_view_nav_class(controller_name == "stats") %>
+      </nav>
+
       <% if main_app.respond_to?(:root_path) %>
-        <span class="pv-header__meta"><%= link_to "← Back to app", main_app.root_path %></span>
+        <span class="pv-header__meta"><%= link_to "← Back to app", main_app.root_path, data: {turbo: false} %></span>
       <% end %>
     </header>