better_structure_sql 0.1.0

data/app/controllers/better_structure_sql/schema_versions_controller.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  # Controller for browsing and downloading stored schema versions
+  #
+  # Provides web UI actions for listing, viewing, and downloading schema
+  # versions stored in the database. Implements memory-efficient streaming
+  # for large files and multi-file ZIP archive support.
+  #
+  # @see SchemaVersion
+  class SchemaVersionsController < ApplicationController
+    # Maximum file size to load into memory (2MB)
+    MAX_MEMORY_SIZE = 2.megabytes
+    # Maximum file size to display in browser (200KB)
+    MAX_DISPLAY_SIZE = 200.kilobytes
+
+    # Lists stored schema versions with pagination
+    #
+    # Loads only metadata (no content or zip_archive) for performance.
+    # Displays up to 100 most recent versions ordered by creation date.
+    #
+    # @return [void]
+    # GET /better_structure_sql/schema_versions
+    def index
+      # Load only metadata for listing (no content or zip_archive)
+      @schema_versions = SchemaVersion
+                         .select(:id, :pg_version, :format_type, :output_mode, :created_at,
+                                 :content_size, :file_count)
+                         .order(created_at: :desc)
+                         .limit(100)
+    end
+
+    # Displays details of a specific schema version
+    #
+    # Loads metadata first for performance. For small single-file versions
+    # (under 200KB), loads content for inline display. For multi-file versions,
+    # extracts and parses the embedded manifest JSON.
+    #
+    # @return [void]
+    # @raise [ActiveRecord::RecordNotFound] if schema version not found
+    # GET /better_structure_sql/schema_versions/:id
+    def show
+      # Load metadata first
+      @schema_version = SchemaVersion
+                        .select(:id, :pg_version, :format_type, :output_mode, :created_at,
+                                :content_size, :line_count, :file_count)
+                        .find(params[:id])
+
+      # Only load content for small single-file versions
+      if @schema_version.output_mode == 'single_file' && @schema_version.content_size <= MAX_DISPLAY_SIZE
+        @schema_version = SchemaVersion.find(params[:id]) # Load with content
+      elsif @schema_version.output_mode == 'multi_file'
+        # Load content to extract manifest
+        full_version = SchemaVersion.select(:id, :content).find(params[:id])
+        @manifest = extract_manifest_from_content(full_version.content)
+      end
+    rescue ActiveRecord::RecordNotFound
+      render plain: 'Schema version not found', status: :not_found
+    end
+
+    # Downloads raw content of a schema version as plain text
+    #
+    # Streams large files (>2MB) in chunks to avoid memory issues.
+    # Smaller files are sent directly using send_data.
+    #
+    # @return [void]
+    # @raise [ActiveRecord::RecordNotFound] if schema version not found
+    # GET /better_structure_sql/schema_versions/:id/raw
+    def raw
+      version = SchemaVersion.select(:id, :format_type, :content_size).find(params[:id])
+
+      filename = "schema_version_#{version.id}_#{version.format_type}.txt"
+
+      # For large files, stream from database to avoid loading into memory
+      if version.content_size > MAX_MEMORY_SIZE
+        stream_large_file(version.id, filename)
+      else
+        # For smaller files, use regular send_data
+        content = SchemaVersion.find(version.id).content
+        send_data content,
+                  filename: filename,
+                  type: 'text/plain',
+                  disposition: 'attachment'
+      end
+    rescue ActiveRecord::RecordNotFound
+      render plain: 'Schema version not found', status: :not_found
+    end
+
+    # Downloads schema version in appropriate format
+    #
+    # Multi-file versions with ZIP archives are sent as .zip files.
+    # Single-file versions are sent as .sql or .rb files based on format_type.
+    #
+    # @return [void]
+    # @raise [ActiveRecord::RecordNotFound] if schema version not found
+    # GET /better_structure_sql/schema_versions/:id/download
+    def download
+      version = SchemaVersion.find(params[:id])
+
+      if version.multi_file? && version.zip_archive?
+        send_zip_download(version)
+      else
+        send_file_download(version)
+      end
+    rescue ActiveRecord::RecordNotFound
+      render plain: 'Schema version not found', status: :not_found
+    end
+
+    private
+
+    # Sends ZIP archive download for multi-file schema versions
+    #
+    # Validates ZIP archive before sending to prevent corrupted downloads.
+    # Filename includes version ID and timestamp.
+    #
+    # @param version [SchemaVersion] the schema version to download
+    # @return [void]
+    def send_zip_download(version)
+      # Validate ZIP
+      BetterStructureSql::ZipGenerator.validate_zip!(version.zip_archive)
+
+      filename = "schema_version_#{version.id}_#{version.created_at.to_i}.zip"
+
+      send_data version.zip_archive,
+                filename: filename,
+                type: 'application/zip',
+                disposition: 'attachment'
+    end
+
+    # Sends single-file schema version download
+    #
+    # Streams large files (>2MB) to avoid memory issues. Filename is
+    # structure.sql or structure.rb based on format_type.
+    #
+    # @param version [SchemaVersion] the schema version to download
+    # @return [void]
+    def send_file_download(version)
+      extension = version.format_type == 'rb' ? 'rb' : 'sql'
+      filename = "structure.#{extension}"
+
+      # Handle large files with streaming
+      if version.content_size > MAX_MEMORY_SIZE
+        stream_large_content(version, filename)
+      else
+        send_data version.content,
+                  filename: filename,
+                  type: 'text/plain',
+                  disposition: 'attachment'
+      end
+    end
+
+    # Streams large content in 64KB chunks to avoid memory issues
+    #
+    # Sets response headers for streaming and disables proxy buffering.
+    # Fetches content from database and yields chunks via Enumerator.
+    #
+    # @param version [SchemaVersion] the schema version to stream
+    # @param filename [String] the filename for Content-Disposition header
+    # @return [void]
+    def stream_large_content(version, filename)
+      response.headers['Content-Type'] = 'text/plain'
+      response.headers['Content-Disposition'] = "attachment; filename=\"#{filename}\""
+      response.headers['X-Accel-Buffering'] = 'no'
+
+      self.response_body = Enumerator.new do |yielder|
+        content = SchemaVersion.connection.select_value(
+          "SELECT content FROM #{SchemaVersion.table_name} WHERE id = #{version.id}"
+        )
+
+        chunk_size = 64.kilobytes
+        offset = 0
+        while offset < content.bytesize
+          yielder << content.byteslice(offset, chunk_size)
+          offset += chunk_size
+        end
+      end
+    end
+
+    # Extracts embedded manifest JSON from multi-file schema content
+    #
+    # Manifest is stored between MANIFEST_JSON_START and MANIFEST_JSON_END markers
+    # as SQL comments. Parses and returns the manifest hash.
+    #
+    # @param content [String] the schema content containing embedded manifest
+    # @return [Hash, nil] parsed manifest hash or nil if not found/invalid
+    def extract_manifest_from_content(content)
+      # Manifest is embedded in content between MANIFEST_JSON_START and MANIFEST_JSON_END markers
+      return nil unless content.include?('MANIFEST_JSON_START')
+
+      # Extract JSON from between markers, removing comment prefixes
+      start_marker = '-- MANIFEST_JSON_START'
+      end_marker = '-- MANIFEST_JSON_END'
+
+      start_pos = content.index(start_marker)
+      end_pos = content.index(end_marker)
+
+      return nil unless start_pos && end_pos
+
+      manifest_section = content[(start_pos + start_marker.length)..(end_pos - 1)]
+      manifest_json = manifest_section.lines
+                                      .map { |line| line.sub(/^--\s?/, '') }
+                                      .join
+
+      JSON.parse(manifest_json)
+    rescue JSON::ParserError => e
+      Rails.logger.debug { "Failed to parse manifest: #{e.message}" }
+      nil
+    end
+
+    # Streams large file content from database in chunks
+    #
+    # Sets appropriate headers for streaming downloads and disables proxy buffering.
+    # Fetches content from database and streams in 64KB chunks via Enumerator.
+    #
+    # @param version_id [Integer] the schema version ID
+    # @param filename [String] the filename for Content-Disposition header
+    # @return [void]
+    def stream_large_file(version_id, filename)
+      # Set headers for streaming
+      response.headers['Content-Type'] = 'text/plain'
+      response.headers['Content-Disposition'] = "attachment; filename=\"#{filename}\""
+      response.headers['Cache-Control'] = 'no-cache'
+      response.headers['X-Accel-Buffering'] = 'no' # Disable proxy buffering
+
+      # Stream the content in chunks
+      self.response_body = Enumerator.new do |yielder|
+        # Fetch content in a streaming fashion from database
+        SchemaVersion.connection.select_value(
+          "SELECT content FROM #{SchemaVersion.table_name} WHERE id = #{version_id}"
+        ).tap do |content|
+          # Stream in 64KB chunks
+          chunk_size = 64.kilobytes
+          offset = 0
+
+          while offset < content.bytesize
+            yielder << content.byteslice(offset, chunk_size)
+            offset += chunk_size
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/better_structure_sql/schema_versions_helper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  # View helper methods for schema versions display
+  #
+  # Provides formatting methods for rendering schema version attributes
+  # in the web UI, including badges and icons for output modes and format types.
+  module SchemaVersionsHelper
+    # Formats output mode as a Bootstrap badge with icon
+    #
+    # @param mode [String] the output mode ('multi_file' or 'single_file')
+    # @return [String] HTML-safe badge element with icon
+    def format_output_mode(mode)
+      case mode
+      when 'multi_file'
+        content_tag(:span, class: 'badge bg-info') do
+          concat content_tag(:i, '', class: 'bi bi-folder')
+          concat ' Multi-File'
+        end
+      when 'single_file'
+        content_tag(:span, class: 'badge bg-secondary') do
+          concat content_tag(:i, '', class: 'bi bi-file-earmark')
+          concat ' Single File'
+        end
+      else
+        content_tag(:span, 'Unknown', class: 'badge bg-warning')
+      end
+    end
+
+    # Formats format type as a Bootstrap badge with icon
+    #
+    # SQL format uses blue badge with SQL icon, Ruby format uses green
+    # badge with Ruby icon.
+    #
+    # @param format_type [String] the format type ('sql' or 'rb')
+    # @return [String] HTML-safe badge element with icon
+    def format_type_badge(format_type)
+      bg_class = format_type == 'sql' ? 'bg-primary' : 'bg-success'
+      icon_class = format_type == 'sql' ? 'bi-filetype-sql' : 'bi-filetype-rb'
+      content_tag(:span, class: "badge #{bg_class}") do
+        concat content_tag(:i, '', class: "bi #{icon_class}")
+        concat " #{format_type.upcase}"
+      end
+    end
+  end
+end

data/app/views/better_structure_sql/schema_versions/index.html.erb

@@ -0,0 +1,110 @@
+<div class="row">
+  <div class="col-12">
+    <div class="d-flex justify-content-between align-items-center mb-4">
+      <h1 class="h2">
+        <i class="bi bi-database-fill-gear text-primary"></i>
+        Schema Versions
+      </h1>
+      <div class="text-muted">
+        <i class="bi bi-info-circle"></i>
+        Total: <%= @schema_versions.count %>
+      </div>
+    </div>
+
+    <% if @schema_versions.empty? %>
+      <div class="empty-state">
+        <i class="bi bi-inbox" style="font-size: 4rem;"></i>
+        <h3 class="mt-3">No Schema Versions Yet</h3>
+        <p class="text-muted">
+          Schema versions will appear here after running:<br>
+          <code>rails db:schema:dump</code> (with versioning enabled)
+        </p>
+      </div>
+    <% else %>
+      <div class="card shadow-sm">
+        <div class="table-responsive">
+          <table class="table table-hover table-striped mb-0">
+            <thead class="table-light">
+              <tr>
+                <th scope="col" class="text-center" style="width: 80px;">ID</th>
+                <th scope="col" style="width: 120px;">Format</th>
+                <th scope="col" style="width: 150px;">Mode</th>
+                <th scope="col" style="width: 180px;">PostgreSQL</th>
+                <th scope="col">Created At</th>
+                <th scope="col" style="width: 100px;">Files</th>
+                <th scope="col" style="width: 120px;">Size</th>
+                <th scope="col" class="text-end" style="width: 200px;">Actions</th>
+              </tr>
+            </thead>
+            <tbody>
+              <% @schema_versions.each do |version| %>
+                <tr>
+                  <td class="text-center fw-bold text-muted">
+                    #<%= version.id %>
+                  </td>
+                  <td>
+                    <%= format_type_badge(version.format_type) %>
+                  </td>
+                  <td>
+                    <%= format_output_mode(version.output_mode) %>
+                  </td>
+                  <td>
+                    <span class="text-muted">
+                      <i class="bi bi-server"></i>
+                      <%= version.pg_version %>
+                    </span>
+                  </td>
+                  <td>
+                    <i class="bi bi-calendar-event"></i>
+                    <%= version.created_at.strftime('%Y-%m-%d %H:%M:%S') %>
+                    <small class="text-muted d-block">
+                      <%= time_ago_in_words(version.created_at) %> ago
+                    </small>
+                  </td>
+                  <td>
+                    <% if version.file_count %>
+                      <span class="badge bg-light text-dark">
+                        <%= version.file_count %> files
+                      </span>
+                    <% else %>
+                      <span class="text-muted">1 file</span>
+                    <% end %>
+                  </td>
+                  <td>
+                    <span class="badge bg-secondary">
+                      <%= version.formatted_size %>
+                    </span>
+                  </td>
+                  <td class="text-end">
+                    <div class="btn-group btn-group-sm" role="group">
+                      <a href="<%= better_structure_sql.schema_version_path(version) %>"
+                         class="btn btn-outline-primary"
+                         title="View details">
+                        <i class="bi bi-eye"></i>
+                        View
+                      </a>
+                      <a href="<%= better_structure_sql.download_schema_version_path(version) %>"
+                         class="btn btn-outline-success"
+                         title="Download"
+                         data-turbo="false">
+                        <i class="bi bi-download"></i>
+                        Download
+                      </a>
+                    </div>
+                  </td>
+                </tr>
+              <% end %>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <% if @schema_versions.count >= 100 %>
+        <div class="alert alert-info mt-3">
+          <i class="bi bi-info-circle"></i>
+          Showing the 100 most recent versions. Older versions are still stored in the database.
+        </div>
+      <% end %>
+    <% end %>
+  </div>
+</div>

data/app/views/better_structure_sql/schema_versions/show.html.erb

@@ -0,0 +1,186 @@
+<div class="row">
+  <div class="col-12">
+    <!-- Header with Back Button -->
+    <div class="d-flex justify-content-between align-items-center mb-4">
+      <h1 class="h2">
+        <i class="bi bi-file-earmark-code text-primary"></i>
+        Schema Version #<%= @schema_version.id %>
+      </h1>
+      <a href="<%= better_structure_sql.schema_versions_path %>" class="btn btn-outline-secondary">
+        <i class="bi bi-arrow-left"></i>
+        Back to List
+      </a>
+    </div>
+
+    <!-- Metadata Card -->
+    <div class="card metadata-card shadow-sm mb-4">
+      <div class="card-body">
+        <div class="row">
+          <div class="col-md-3">
+            <h6 class="text-muted mb-1">
+              <i class="bi bi-hash"></i>
+              Version ID
+            </h6>
+            <p class="mb-0 fw-bold">#<%= @schema_version.id %></p>
+          </div>
+          <div class="col-md-3">
+            <h6 class="text-muted mb-1">
+              <i class="bi bi-filetype-sql"></i>
+              Format
+            </h6>
+            <p class="mb-0">
+              <%= format_type_badge(@schema_version.format_type) %>
+            </p>
+          </div>
+          <div class="col-md-3">
+            <h6 class="text-muted mb-1">
+              <i class="bi bi-folder"></i>
+              Output Mode
+            </h6>
+            <p class="mb-0">
+              <%= format_output_mode(@schema_version.output_mode) %>
+            </p>
+          </div>
+          <div class="col-md-3">
+            <h6 class="text-muted mb-1">
+              <i class="bi bi-server"></i>
+              PostgreSQL Version
+            </h6>
+            <p class="mb-0"><%= @schema_version.pg_version %></p>
+          </div>
+        </div>
+
+        <div class="row mt-3">
+          <div class="col-md-3">
+            <h6 class="text-muted mb-1">
+              <i class="bi bi-calendar-event"></i>
+              Created
+            </h6>
+            <p class="mb-0">
+              <%= @schema_version.created_at.strftime('%Y-%m-%d %H:%M:%S') %>
+              <small class="text-muted d-block">
+                <%= time_ago_in_words(@schema_version.created_at) %> ago
+              </small>
+            </p>
+          </div>
+          <div class="col-md-3">
+            <h6 class="text-muted mb-1">
+              <i class="bi bi-file-earmark-bar-graph"></i>
+              Size
+            </h6>
+            <p class="mb-0">
+              <span class="badge bg-secondary"><%= @schema_version.formatted_size %></span>
+            </p>
+          </div>
+          <div class="col-md-3">
+            <h6 class="text-muted mb-1">
+              <i class="bi bi-info-circle"></i>
+              Lines
+            </h6>
+            <p class="mb-0"><%= number_with_delimiter(@schema_version.line_count) %> lines</p>
+          </div>
+          <div class="col-md-3">
+            <h6 class="text-muted mb-1">
+              <i class="bi bi-files"></i>
+              Files
+            </h6>
+            <p class="mb-0">
+              <% if @schema_version.file_count %>
+                <span class="badge bg-light text-dark"><%= @schema_version.file_count %> files</span>
+              <% else %>
+                <span class="text-muted">1 file</span>
+              <% end %>
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Actions -->
+    <div class="mb-3">
+      <a href="<%= better_structure_sql.download_schema_version_path(@schema_version) %>"
+         class="btn btn-primary btn-lg"
+         data-turbo="false">
+        <% if @schema_version.multi_file? %>
+          <i class="bi bi-file-zip"></i>
+          Download ZIP Archive
+        <% else %>
+          <i class="bi bi-download"></i>
+          Download File
+        <% end %>
+      </a>
+      <% if @schema_version.respond_to?(:content) && @schema_version.content.present? %>
+        <button type="button" class="btn btn-outline-secondary btn-lg" onclick="copyToClipboard()">
+          <i class="bi bi-clipboard"></i>
+          Copy to Clipboard
+        </button>
+      <% end %>
+    </div>
+
+    <!-- Multi-file Info -->
+    <% if @schema_version.multi_file? && @manifest %>
+      <div class="alert alert-info mb-4">
+        <h6 class="alert-heading">
+          <i class="bi bi-info-circle"></i>
+          Multi-File Schema
+        </h6>
+        <p class="mb-2">This schema was generated in multi-file format with <%= @schema_version.file_count %> files across organized directories.</p>
+        <% if @manifest['directories'] %>
+          <p class="mb-0 small">
+            <strong>Directories:</strong>
+            <%= @manifest['directories'].keys.sort.join(', ') %>
+          </p>
+        <% end %>
+      </div>
+    <% end %>
+
+    <!-- Schema Content -->
+    <div class="card shadow-sm">
+      <div class="card-header bg-light">
+        <h5 class="card-title mb-0">
+          <i class="bi bi-code-square"></i>
+          Schema Content
+          <% if @schema_version.multi_file? %>
+            <small class="text-muted">(combined from all files)</small>
+          <% end %>
+        </h5>
+      </div>
+      <div class="card-body p-0">
+        <% if @schema_version.respond_to?(:content) && @schema_version.content.present? %>
+          <pre class="code-block m-0" id="schema-content"><%= @schema_version.content %></pre>
+        <% else %>
+          <div class="alert alert-warning m-3">
+            <i class="bi bi-exclamation-triangle"></i>
+            <strong>File too large to display</strong>
+            <p class="mb-0 mt-2">
+              This schema file is too large to display in the browser (limit: 200 KB).
+              Please use the "Download" button above to download and view it locally.
+            </p>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+</div>
+
+<script>
+  function copyToClipboard() {
+    const content = document.getElementById('schema-content').textContent;
+    navigator.clipboard.writeText(content).then(function() {
+      // Show success feedback
+      const btn = event.target.closest('button');
+      const originalHTML = btn.innerHTML;
+      btn.innerHTML = '<i class="bi bi-check-lg"></i> Copied!';
+      btn.classList.remove('btn-outline-secondary');
+      btn.classList.add('btn-success');
+
+      setTimeout(function() {
+        btn.innerHTML = originalHTML;
+        btn.classList.remove('btn-success');
+        btn.classList.add('btn-outline-secondary');
+      }, 2000);
+    }, function(err) {
+      alert('Failed to copy to clipboard: ' + err);
+    });
+  }
+</script>