studio-engine 0.98.0 → 0.99.0

data/lib/studio/knowledge_preview.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+module Studio
+  # What /admin/knowledge/:id shows of a document without a download: a
+  # workbook or CSV as tables, a PDF or image inline, text as text.
+  #
+  # NOT required by lib/studio.rb. Studio::KnowledgeDoc requires it on first
+  # use, and the spreadsheet reader (nokogiri, zlib) and `csv` load later
+  # still, on the first file of that kind, so an app that never draws the
+  # knowledge routes pays nothing for it.
+  #
+  # Everything here is read-only and answers with a Result, never an
+  # exception: a file this cannot show, for any reason, is a Result of kind
+  # :fallback carrying one plain sentence, and the page offers the download
+  # link beside it.
+  #
+  # THE CAPS, all in one place:
+  #
+  #   SPREADSHEET_MAX_BYTES  an .xlsx larger than this is not opened at all.
+  #   INFLATE_BUDGET         what a whole workbook may inflate to, every part
+  #                          read counted, a part read twice counted twice.
+  #   SPREADSHEET_DEADLINE_SECONDS
+  #                          wall-clock time one workbook read may take.
+  #   MAX_PARSED_TEXT_BYTES  text the XML parser may hand the reader across a
+  #                          workbook, kept or not.
+  #   XmlGuard::MAX_TOKEN_BYTES, MAX_OPEN_TAG_BYTES, MAX_ASIDE_BYTES,
+  #   MAX_NAMESPACE_DECLARATIONS, MAX_DEPTH
+  #                          what the XML parser is ever GIVEN, enforced on the
+  #                          byte stream below it: no DTD, UTF-8 only, and no
+  #                          text node, set of open start tags, or pile of
+  #                          comments large enough for the parser to spend a
+  #                          gigabyte on before a single node comes out.
+  #   MAX_ROWS, MAX_COLUMNS  what one sheet (or CSV) shows; the rest is named
+  #                          in a notice, never silently dropped.
+  #   MAX_SHEETS             tabs rendered; further sheets are counted.
+  #   MAX_CELLS              filled cells across one workbook.
+  #   MAX_CELL_CHARS         text kept for one cell (Excel's own limit); a
+  #                          longer value is cut and marked.
+  #   MAX_TEXT_BYTES         cell text across one workbook, counted once per
+  #                          cell that shows it.
+  #   MAX_GRID_CELLS         cells rendered across one workbook, empty ones
+  #                          included.
+  #                          The sheet that spends the last of any of these
+  #                          three is cut there and says so; the sheets after
+  #                          it are counted, not rendered.
+  #   NumberFormat::MAX_CODE_LENGTH, MAX_DECIMALS
+  #                          a number format longer than Excel allows is
+  #                          ignored, and no number renders past thirty
+  #                          decimals.
+  #   DELIMITED_HEAD_BYTES   a CSV is read only this far, so one of any size
+  #                          previews its first rows.
+  #   TEXT_HEAD_BYTES        likewise for text.
+  #   INLINE_MAX_BYTES       a PDF or image past this is not embedded.
+  module KnowledgePreview
+    class Error < StandardError; end
+    # The file is not what its name says, or is damaged. The message completes
+    # "This file could not be previewed: ...".
+    class Unreadable < Error; end
+    class TooLarge < Error; end
+
+    MEGABYTE = 1_048_576
+    SPREADSHEET_MAX_BYTES = 20 * MEGABYTE
+    INFLATE_BUDGET        = 64 * MEGABYTE
+    SPREADSHEET_DEADLINE_SECONDS = 10
+    MAX_PARSED_TEXT_BYTES = 16 * MEGABYTE
+    MAX_ROWS              = 500
+    MAX_COLUMNS           = 50
+    MAX_SHEETS            = 20
+    MAX_CELLS             = 50_000
+    MAX_CELL_CHARS        = 32_767
+    MAX_TEXT_BYTES        = 2 * MEGABYTE
+    MAX_GRID_CELLS        = 100_000
+    DELIMITED_HEAD_BYTES  = 1 * MEGABYTE
+    TEXT_HEAD_BYTES       = 256 * 1024
+    INLINE_MAX_BYTES      = 100 * MEGABYTE
+
+    XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+
+    KIND_BY_EXTENSION = {
+      ".xlsx" => :spreadsheet, ".xlsm" => :spreadsheet,
+      ".csv" => :delimited, ".tsv" => :delimited,
+      ".pdf" => :pdf,
+      ".png" => :image, ".jpg" => :image, ".jpeg" => :image, ".gif" => :image, ".webp" => :image,
+      ".txt" => :text, ".md" => :text, ".markdown" => :text, ".log" => :text,
+      ".json" => :text, ".vtt" => :text, ".srt" => :text
+    }.freeze
+
+    KIND_BY_MIME = {
+      XLSX_MIME => :spreadsheet,
+      "text/csv" => :delimited, "text/tab-separated-values" => :delimited,
+      "application/pdf" => :pdf,
+      "image/png" => :image, "image/jpeg" => :image, "image/gif" => :image, "image/webp" => :image,
+      "application/json" => :text
+    }.freeze
+
+    # The content type an inline object is SERVED as. Chosen here, from the
+    # kind, and never copied from the stored mime type: a file uploaded as
+    # text/html under a .pdf name must reach the browser as a (broken) PDF,
+    # not as a page. SVG is absent on purpose; it is a document that can
+    # carry script, and it takes the download link.
+    INLINE_TYPE_BY_EXTENSION = {
+      ".pdf" => "application/pdf",
+      ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg",
+      ".gif" => "image/gif", ".webp" => "image/webp"
+    }.freeze
+
+    Cell  = Struct.new(:text, :numeric)
+    # rows is a rectangle of Cell-or-nil. row_limit is the row count the
+    # truncation notice names.
+    Sheet = Struct.new(:name, :rows, :truncated_rows, :truncated_columns, :hidden, :row_limit,
+                       keyword_init: true)
+
+    # kind: :table, :pdf, :image, :text or :fallback.
+    # error: the unexpected exception behind a fallback, for the caller to
+    # log; nil when the fallback is an ordinary refusal.
+    Result = Struct.new(:kind, :sheets, :omitted_sheets, :text, :truncated, :url, :reason, :error,
+                        keyword_init: true) do
+      def fallback? = kind == :fallback
+    end
+
+    NUMERIC_TEXT = /\A\(?[-+$€£]?\s?\d[\d,]*(\.\d+)?%?\)?\z/
+
+    class << self
+      # :spreadsheet, :delimited, :pdf, :image, :text, or nil for a file with
+      # no inline preview. The extension decides when it is one this knows;
+      # the stored mime type is the browser's guess at upload and is consulted
+      # only for a name that says nothing.
+      def kind_for(filename:, mime_type: nil)
+        extension = File.extname(filename.to_s).downcase
+        return KIND_BY_EXTENSION[extension] if KIND_BY_EXTENSION.key?(extension)
+
+        mime = mime_type.to_s.split(";").first.to_s.strip.downcase
+        KIND_BY_MIME[mime] || (mime.start_with?("text/") ? :text : nil)
+      end
+
+      def inline_content_type(filename:, mime_type: nil)
+        by_name = INLINE_TYPE_BY_EXTENSION[File.extname(filename.to_s).downcase]
+        return by_name if by_name
+
+        mime = mime_type.to_s.split(";").first.to_s.strip.downcase
+        INLINE_TYPE_BY_EXTENSION.value?(mime) ? mime : nil
+      end
+
+      # 0 -> "A", 25 -> "Z", 26 -> "AA": the heading a spreadsheet gives a column.
+      def column_letter(index)
+        letters = +""
+        number = index + 1
+        while number.positive?
+          number, remainder = (number - 1).divmod(26)
+          letters.prepend((65 + remainder).chr)
+        end
+        letters
+      end
+
+      # The preview for a Studio::KnowledgeDoc. Reads the bucket (or, for a
+      # PDF or image, only signs a URL), so call it off the page's own render
+      # path. `storage` answers download(key:, max_bytes:) and defaults to
+      # Studio::S3, named only when a read is about to happen.
+      def for(doc, storage: nil)
+        return fallback("No file is attached.") unless doc.file?
+
+        kind = kind_for(filename: doc.filename, mime_type: doc.mime_type)
+        case kind
+        when :spreadsheet then spreadsheet(doc, storage)
+        when :delimited   then delimited(doc, storage)
+        when :text        then text(doc, storage)
+        when :pdf, :image then inline(doc, kind)
+        else fallback(no_preview_reason(doc))
+        end
+      rescue TooLarge => e
+        fallback("This file is too large to preview: #{e.message}.")
+      rescue Unreadable => e
+        fallback("This file could not be previewed: #{e.message}.")
+      rescue StandardError, LoadError => e
+        # Storage down, an object missing, a defect in a reader, or a library
+        # the host's bundle lacks. The page must still render; the caller logs
+        # what happened.
+        fallback("The preview could not be built.", error: e)
+      end
+
+      # --- readers, usable without a document ---------------------------------
+
+      def read_spreadsheet(bytes, **overrides)
+        require_relative "knowledge_preview/xlsx"
+        Xlsx.read(bytes, max_rows: MAX_ROWS, max_columns: MAX_COLUMNS, max_sheets: MAX_SHEETS,
+                         max_cells: MAX_CELLS, max_cell_chars: MAX_CELL_CHARS, max_text_bytes: MAX_TEXT_BYTES,
+                         max_grid_cells: MAX_GRID_CELLS, max_parsed_text_bytes: MAX_PARSED_TEXT_BYTES,
+                         inflate_budget: INFLATE_BUDGET, deadline_seconds: SPREADSHEET_DEADLINE_SECONDS,
+                         **overrides)
+      rescue Error
+        raise
+      rescue StandardError => e
+        # A hostile or half-written workbook can trip the reader anywhere;
+        # every such trip is the file's fault until shown otherwise.
+        raise Unreadable, "its contents are damaged (#{e.class})"
+      end
+
+      # `partial` says the bytes are only the head of a longer file, so the
+      # last line may be cut and is dropped.
+      def read_delimited(bytes, separator: ",", partial: false)
+        require "csv"
+        text = decode(bytes, partial: partial)
+        raise Unreadable, "it is empty" if text.strip.empty?
+
+        text = text[0..text.rindex("\n")] if partial && text.include?("\n")
+        rows = []
+        truncated_rows = partial
+        truncated_columns = false
+        begin
+          CSV.new(text, col_sep: separator, liberal_parsing: true).each do |row|
+            if rows.size >= MAX_ROWS
+              truncated_rows = true
+              break
+            end
+            truncated_columns = true if row.size > MAX_COLUMNS
+            rows << row.first(MAX_COLUMNS)
+          end
+        rescue CSV::MalformedCSVError
+          # Rows read before the bad line still show; with none, it is not CSV.
+          raise Unreadable, "it is not valid CSV" if rows.empty?
+
+          truncated_rows = true
+        end
+
+        width = rows.map(&:size).max.to_i
+        cells = rows.map do |row|
+          Array.new(width) do |index|
+            value = row[index].to_s
+            value.empty? ? nil : Cell.new(value, value.match?(NUMERIC_TEXT))
+          end
+        end
+        Sheet.new(name: nil, rows: cells, truncated_rows: truncated_rows,
+                  truncated_columns: truncated_columns, hidden: false, row_limit: cells.size)
+      end
+
+      # Bytes to UTF-8 text. UTF-8 first; a UTF-16 byte-order mark is honoured;
+      # anything else is read as Windows-1252, which is what a CSV exported by
+      # desktop accounting software usually is. NUL bytes mean it is not text.
+      def decode(bytes, partial: false)
+        raw = bytes.to_s.b
+        if raw.start_with?("\xFF\xFE".b, "\xFE\xFF".b)
+          encoding = raw.start_with?("\xFF\xFE".b) ? Encoding::UTF_16LE : Encoding::UTF_16BE
+          body = raw.byteslice(2..)
+          body = body.byteslice(0, body.bytesize - 1) if body.bytesize.odd?
+          return body.force_encoding(encoding).encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        end
+        raise Unreadable, "it does not look like text" if raw.include?("\x00".b)
+
+        raw = raw.byteslice(3..) if raw.start_with?("\xEF\xBB\xBF".b)
+        utf8 = raw.dup.force_encoding(Encoding::UTF_8)
+        return utf8 if utf8.valid_encoding?
+
+        if partial
+          # A head read can end inside a multi-byte character.
+          1.upto(3) do |trim|
+            shorter = raw.byteslice(0, [raw.bytesize - trim, 0].max).force_encoding(Encoding::UTF_8)
+            return shorter if shorter.valid_encoding?
+          end
+        end
+        raw.force_encoding(Encoding::Windows_1252).encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      end
+
+      private
+
+      def fallback(reason, error: nil)
+        Result.new(kind: :fallback, reason: reason, error: error)
+      end
+
+      def no_preview_reason(doc)
+        extension = File.extname(doc.filename.to_s).downcase
+        extension.empty? ? "There is no inline preview for this kind of file." : "There is no inline preview for #{extension} files."
+      end
+
+      def megabytes(bytes)
+        "#{(bytes.to_f / MEGABYTE).round(1).to_s.delete_suffix('.0')} MB"
+      end
+
+      def spreadsheet(doc, storage)
+        refuse_over!(doc, SPREADSHEET_MAX_BYTES)
+        # One byte past the cap: the recorded byte_size can be absent or
+        # stale, and this is the read that cannot be.
+        bytes = (storage || Studio::S3).download(key: doc.s3_key, max_bytes: SPREADSHEET_MAX_BYTES + 1)
+        raise TooLarge, "spreadsheet previews stop at #{megabytes(SPREADSHEET_MAX_BYTES)}" if bytes.bytesize > SPREADSHEET_MAX_BYTES
+
+        workbook = read_spreadsheet(bytes)
+        Result.new(kind: :table, sheets: workbook.sheets, omitted_sheets: workbook.omitted_sheets)
+      end
+
+      def delimited(doc, storage)
+        bytes = (storage || Studio::S3).download(key: doc.s3_key, max_bytes: DELIMITED_HEAD_BYTES + 1)
+        partial = bytes.bytesize > DELIMITED_HEAD_BYTES
+        tabbed = File.extname(doc.filename.to_s).casecmp?(".tsv") ||
+                 doc.mime_type.to_s.start_with?("text/tab-separated-values")
+        sheet = read_delimited(bytes.byteslice(0, DELIMITED_HEAD_BYTES), separator: tabbed ? "\t" : ",", partial: partial)
+        Result.new(kind: :table, sheets: [sheet], omitted_sheets: 0)
+      end
+
+      def text(doc, storage)
+        bytes = (storage || Studio::S3).download(key: doc.s3_key, max_bytes: TEXT_HEAD_BYTES + 1)
+        partial = bytes.bytesize > TEXT_HEAD_BYTES
+        Result.new(kind: :text, text: decode(bytes.byteslice(0, TEXT_HEAD_BYTES), partial: partial), truncated: partial)
+      end
+
+      def inline(doc, kind)
+        refuse_over!(doc, INLINE_MAX_BYTES)
+        content_type = inline_content_type(filename: doc.filename, mime_type: doc.mime_type)
+        # Without a type of our choosing the URL would be signed to serve the
+        # STORED type, which is the one thing this path exists to prevent.
+        raise Unreadable, "its type cannot be shown inline" if content_type.nil?
+
+        Result.new(kind: kind, url: doc.signed_url(inline_as: content_type))
+      end
+
+      def refuse_over!(doc, cap)
+        size = doc.byte_size.to_i
+        return unless size > cap
+
+        raise TooLarge, "it is #{megabytes(size)} and previews of this kind stop at #{megabytes(cap)}"
+      end
+    end
+  end
+end

data/lib/studio/s3.rb

@@ -18,8 +18,32 @@ module Studio
         public_url? ? url(key: key) : nil
       end
 
-      def download(key:)
-        client.get_object(bucket: bucket, key: full_key(key)).body.read
+      # max_bytes reads only the head of the object (a ranged GET), which is
+      # how a preview looks at the first megabyte of a file of any size and
+      # how a caller enforces a size cap without trusting a recorded length.
+      # A ranged read of an EMPTY object is a 416 (InvalidRange) on S3; that
+      # is answered as the empty string it means. Tested against a stubbed
+      # client only: no live store, R2 included, has been asked.
+      def download(key:, max_bytes: nil)
+        # 0 or a negative would build "bytes=0--1", which a store may read as
+        # no range at all and answer with the whole object.
+        unless max_bytes.nil? || (max_bytes.is_a?(Integer) && max_bytes.positive?)
+          raise ArgumentError, "max_bytes must be a positive Integer, got #{max_bytes.inspect}"
+        end
+
+        opts = { bucket: bucket, key: full_key(key) }
+        opts[:range] = "bytes=0-#{max_bytes - 1}" if max_bytes
+        s3 = client
+        # The rescue names an SDK constant, so it wraps only what runs after
+        # the client (which loads the SDK) exists: an unconfigured app must
+        # raise NotConfigured from `bucket` above, not a NameError from here.
+        begin
+          s3.get_object(**opts).body.read
+        rescue Aws::S3::Errors::InvalidRange
+          raise unless max_bytes
+
+          "".b
+        end
       end
 
       # The PUBLIC URL of an object. On AWS (no endpoint) it is the bucket's
@@ -43,9 +67,20 @@ module Studio
         endpoint.nil? || !Studio.s3_public_url.to_s.empty?
       end
 
-      def signed_url(key:, expires_in: 3600)
+      # response_content_disposition and response_content_type are SIGNED into
+      # the URL and override the headers the object is served with. That is
+      # S3's documented behaviour and part of the S3 compatibility Cloudflare
+      # documents for R2. What the tests here prove is the SIGNING, against an
+      # R2-style endpoint; that R2 serves the overridden headers has not been
+      # verified against a live bucket. "inline" plus a content type the
+      # caller chose is how a private PDF or image is shown in the page
+      # without the stored content type deciding how the browser treats it.
+      def signed_url(key:, expires_in: 3600, response_content_disposition: nil, response_content_type: nil)
         require "aws-sdk-s3"
-        Aws::S3::Presigner.new(client: client).presigned_url(:get_object, bucket: bucket, key: full_key(key), expires_in: expires_in)
+        params = { bucket: bucket, key: full_key(key), expires_in: expires_in }
+        params[:response_content_disposition] = response_content_disposition if response_content_disposition
+        params[:response_content_type] = response_content_type if response_content_type
+        Aws::S3::Presigner.new(client: client).presigned_url(:get_object, **params)
       end
 
       def exists?(key:)

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.98.0"
+  VERSION = "0.99.0"
 end

data/lib/studio.rb

@@ -1453,8 +1453,8 @@ module Studio
       end
 
       # Knowledge layer — /admin/knowledge (Studio::KnowledgeDoc): folder/flat
-      # document browser, upload-to-inbox intake, per-agent access map, and
-      # 15-minute presigned downloads. Opt-in (default off) like every route
+      # document browser, upload-to-inbox intake, per-agent access map,
+      # 15-minute presigned downloads, and the inline document preview. Opt-in (default off) like every route
       # surface, so no app grows an admin page it never asked for.
       if Studio.draw_knowledge_routes
         get   "admin/knowledge",     to: "studio/knowledge_docs#index", as: :admin_knowledge
@@ -1471,6 +1471,9 @@ module Studio
         patch "admin/knowledge/:id", to: "studio/knowledge_docs#update"
         get   "admin/knowledge/:id/download", to: "studio/knowledge_docs#download",
               as: :admin_knowledge_doc_download
+        # The inline preview the show page lazy-loads (Studio::KnowledgePreview).
+        get   "admin/knowledge/:id/preview", to: "studio/knowledge_docs#preview",
+              as: :admin_knowledge_doc_preview
       end
 
       # Solana / Phantom wallet sign-in (nonce challenge + signature verify),

data/studio-engine.gemspec

@@ -40,6 +40,10 @@ Gem::Specification.new do |spec|
   spec.add_dependency "solid_queue", ">= 1.0", "< 2.0"
   spec.add_dependency "aws-sdk-s3", "~> 1.218"
   spec.add_dependency "mini_magick", "~> 5.0"
+  # The knowledge layer's CSV preview (Studio::KnowledgePreview) requires it,
+  # lazily. csv left Ruby's default gems in 3.4, and a bundled app can then
+  # load it only if its lockfile names it; not every consumer's does.
+  spec.add_dependency "csv", ">= 3.0"
   spec.add_dependency "resend", "~> 1.1"
   # Realtime: the redis cable/cache/Sidekiq adapter (Studio::Redis) + Turbo Streams
   # broadcasting (Studio::Cable). `redis` is the dependency whose ABSENCE

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.98.0
+  version: 0.99.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -112,6 +112,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: resend
   requirement: !ruby/object:Gem::Requirement
@@ -564,9 +578,14 @@ files:
 - app/views/studio/knowledge_docs/_chip_styles.html.erb
 - app/views/studio/knowledge_docs/_coverage_table.html.erb
 - app/views/studio/knowledge_docs/_doc_row.html.erb
+- app/views/studio/knowledge_docs/_preview.html.erb
+- app/views/studio/knowledge_docs/_preview_fallback.html.erb
+- app/views/studio/knowledge_docs/_preview_sheet.html.erb
+- app/views/studio/knowledge_docs/_preview_styles.html.erb
 - app/views/studio/knowledge_docs/_upload_form.html.erb
 - app/views/studio/knowledge_docs/coverage.html.erb
 - app/views/studio/knowledge_docs/index.html.erb
+- app/views/studio/knowledge_docs/preview.html.erb
 - app/views/studio/knowledge_docs/show.html.erb
 - app/views/studio/links/confirm.html.erb
 - app/views/studio/local_emails/index.html.erb
@@ -715,6 +734,11 @@ files:
 - lib/studio/ip_locations.rb
 - lib/studio/js_identifier.rb
 - lib/studio/js_literal.rb
+- lib/studio/knowledge_preview.rb
+- lib/studio/knowledge_preview/number_format.rb
+- lib/studio/knowledge_preview/xlsx.rb
+- lib/studio/knowledge_preview/xml_guard.rb
+- lib/studio/knowledge_preview/zip.rb
 - lib/studio/knowledge_recording.rb
 - lib/studio/knowledge_transcript.rb
 - lib/studio/link_preview.rb