plum-cms 0.2.0 → 0.2.2

data/docs/static-caching.md

@@ -0,0 +1,163 @@
+# Static Page Caching
+
+Plum ships a full-page static cache: the first request for a public page
+renders through Liquid as normal, and the complete HTML response is written to
+disk. Subsequent requests are served from that file without touching the
+database or the template engine. When content changes, the affected site's
+cache is deleted and pages lazily re-render on their next visit.
+
+This is a cache on the one true render path — not a static site generator.
+There is no build step, no dependency graph to get wrong, and the control
+panel always shows live data.
+
+**It is off by default and must be turned on explicitly.** Read "Should you
+enable this?" below before flipping it on — the wrong setting on the wrong
+deployment topology causes a specific, silent content bug (stale pages served
+forever), not a crash you'd notice.
+
+## Should you enable this?
+
+Ask one question: **does your app run on more than one server/dyno/instance
+at the same time?**
+
+| Your deployment | Enable it? | Why |
+|---|---|---|
+| Single VPS/Droplet/EC2 box (Plum's standalone SQLite mode) | **Yes** | This is the shape it was designed for. One disk, one cache, invalidation always reaches it. Free page-load speed and DB-load reduction. |
+| Docker Compose on one host, one app container | **Yes** | Still one filesystem for the app process. |
+| Heroku with 1 dyno, Render with 1 instance | **Yes, cautiously** | Correct today, but re-check this the moment you scale to 2 dynos — nothing will warn you when you cross that line. |
+| Heroku/Render/Fly with **2+ dynos or instances**, or any horizontally-scaled/load-balanced deployment | **No** | See "Why this fails on multiple nodes" below. Use a CDN in front of the app instead (see that section). |
+| Plum mounted inside a larger host app (embedded/SaaS mode, e.g. many customer sites behind one Rails app) | **Depends entirely on the host app's node count** — almost always multi-node in practice, so usually **No** | The host app's deployment shape governs, not Plum's. |
+| Not sure / evaluating locally | **Leave it off** | It has zero effect on correctness either way in dev; there's no reason to enable it before you know your production topology. |
+
+If you're unsure, leave it off. The cost of leaving it off is slower page
+responses and more DB load. The cost of turning it on wrongly is **visitors
+silently seeing outdated or wrong content**, which is worse and harder to
+debug — nothing errors, nothing logs, pages simply disagree depending on
+which server answered the request.
+
+### Why this fails on multiple nodes
+
+The cache is plain files on the server's own local disk. Invalidation works
+by *deleting those files* when content changes. On one server, that's
+airtight: the file that would be stale no longer exists, so the next request
+always re-renders fresh.
+
+With two or more servers, each has its **own separate disk**. An editor
+publishes a change; the request that triggers invalidation lands on
+whichever server handled that specific HTTP request — say, server A. Server A
+deletes its cached file. Server B's copy of that same file is untouched.
+Visitors routed to server B by the load balancer keep seeing the old page
+**indefinitely** — not for a few seconds until some TTL expires, but forever,
+until something else happens to touch that page on server B too.
+
+This is why there is deliberately no "auto-detect production and turn it on"
+behavior. A setting that's silently wrong 100% of the time on a common
+deployment shape (small teams scaling from 1 to 2 dynos is one of the most
+ordinary things that happens to a growing app) is worse than a setting you
+have to think about once.
+
+### If you're on a multi-node platform and still want caching
+
+Don't use the disk store. Put a CDN (Cloudflare, CloudFront, Fastly) in front
+of the app and let *it* hold the cached pages — a CDN has exactly one shared
+cache, not one per node, so the invalidation problem above doesn't exist. You
+still get the "no build step, one render path" benefit described above; only
+the storage layer changes. See "Serving cached files from the web server"
+below for the shape this takes; a first-class CDN/surrogate-key purge backend
+driven by the same capture/invalidation hooks used here is on the roadmap.
+
+## How it works
+
+1. `Plum::StaticCache::Middleware` checks every `GET` request with no query
+   string. If a cached file exists for the request host + path, it is served
+   immediately (`X-Plum-Static-Cache: hit`).
+2. On a miss, the request renders normally. `Plum::PagesController` and
+   `Plum::ThemeAssetsController` mark their successful responses, and the
+   middleware writes the body to
+   `storage/plum_static_cache/{host}/{path}/index.html`
+   (theme assets keep their real filename and extension).
+3. Content models flush their site's cache directory in an `after_commit`
+   hook (`Plum::StaticCacheInvalidation`). Flushing deletes files; it never
+   generates anything, so over-flushing is cheap and always correct — this is
+   what makes it safe on one server and unsafe across many, per above.
+
+Requests with query strings (search, pagination, UTM-tagged links) are never
+cached and never served from the cache. The control panel, API, and form
+endpoints are untouched.
+
+## Configuration
+
+```ruby
+Plum.configure do |config|
+  # Explicit opt-in. Off by default. Read "Should you enable this?" above
+  # before setting this to true.
+  config.static_cache_enabled = true
+
+  # Where cache files live. Default: Rails.root/storage/plum_static_cache
+  config.static_cache_path = "/var/www/site-cache"
+end
+```
+
+There is no environment-based default (no "automatically on in production")
+— it must be set explicitly, on purpose, by someone who has confirmed the
+deployment is single-node. This is a deliberate change: earlier versions of
+this feature turned on automatically in `production`, which was correct for
+the single-VPS case this was designed around but silently wrong the moment an
+app scaled to multiple nodes. Explicit opt-in means the person flipping the
+switch is the person who knows the deployment topology.
+
+Cache directories are keyed by request host. A site with a `domain` set
+flushes `{domain}` and `www.{domain}`; sites without a domain flush the whole
+cache root.
+
+Administrators can clear a site's cache manually from the dashboard
+("Clear page cache").
+
+## Serving cached files from the web server (full measure)
+
+The middleware already skips the database and rendering, but nginx or Caddy
+can serve the files without invoking Ruby at all:
+
+```nginx
+server {
+  server_name example.com;
+  root /path/to/app/storage/plum_static_cache/$host;
+
+  location / {
+    try_files $uri $uri/index.html @rails;
+  }
+
+  location @rails {
+    proxy_pass http://app_upstream;
+    proxy_set_header Host $host;
+  }
+}
+```
+
+Anything not in the cache (first hits, search, forms, the control panel)
+falls through to Rails. Because invalidation deletes files, the web server
+can never serve a stale page that Plum knows is stale.
+
+The same layout works for pushing to object storage: sync the cache directory
+to S3/CloudFront and invalidate on deploy, or point a CDN at the app origin
+and let the middleware serve as the fast backend.
+
+## Forms and CSRF
+
+Cached pages cannot carry per-session CSRF tokens, so public `{% form %}`
+submissions use a hidden honeypot field (`form_submission[website]`) instead.
+Submissions with a filled honeypot are silently accepted-and-dropped. The
+control panel keeps standard Rails CSRF protection — only the public form
+endpoint opts out.
+
+This also means rendering a public page no longer writes a session cookie,
+which is what makes responses safely shareable between visitors — and is true
+regardless of whether the cache itself is enabled.
+
+## What stays dynamic
+
+- `/search` (query-dependent)
+- Collection pagination beyond page 1 (`?page=2`)
+- Form submission POSTs
+- The JSON content API
+- The entire control panel

data/lib/generators/plum/install/templates/plum_initializer.rb

@@ -12,6 +12,14 @@ Plum.configure do |config|
     Plum::Engine.root.join("app/themes")
   ]
 
+  # Static page caching serves rendered pages from disk instead of hitting
+  # the database/Liquid on every request — a big win on a single server, but
+  # only correct on a single server. See docs/static-caching.md before
+  # enabling this on a multi-node/PaaS deployment (Heroku, Render, etc. with
+  # 2+ dynos or instances).
+  #
+  # config.static_cache_enabled = true
+
   # White-label the control panel:
   #
   # config.cp_name = "My Brand"

data/lib/plum/configuration.rb

@@ -6,7 +6,8 @@ module Plum
                   :mailer_sender, :cp_name, :cp_subtitle, :cp_logo_path,
                   :cp_accent_color, :cp_sidebar_bg, :cp_sidebar_header_bg, :cp_sidebar_text, :cp_sidebar_muted,
                   :cp_back_url, :cp_back_label,
-                  :powered_by_name, :powered_by_url
+                  :powered_by_name, :powered_by_url,
+                  :static_cache_enabled, :static_cache_path, :config_path
     attr_writer :theme_paths
     attr_reader :content_sources
 
@@ -25,6 +26,16 @@ module Plum
       @cp_back_label = "← Back"
       @powered_by_name = "Plum"
       @powered_by_url = "https://plumcms.com"
+      # Explicit opt-in — see docs/static-caching.md before enabling. Off by
+      # default because it's only correct on a single-server deployment;
+      # silently corrupts pages (stale content served forever from whichever
+      # node didn't get the invalidation) on multi-node platforms like
+      # Heroku/Render with 2+ dynos.
+      @static_cache_enabled = false
+      @static_cache_path = nil
+      # Directory for config-as-code YAML (content types, fieldsets).
+      # nil = default to Rails.root/plum when the tasks are invoked.
+      @config_path = nil
       @content_sources = ContentSourceRegistry.new
       @current_site_resolver = ->(_controller) { Plum::Site.first_or_create_standalone! }
       @current_user_resolver = lambda { |controller|

data/lib/plum/engine.rb

@@ -1,4 +1,6 @@
 require_relative "configuration"
+require_relative "static_cache"
+require_relative "static_cache/middleware"
 
 module Plum
   class Engine < ::Rails::Engine
@@ -6,9 +8,16 @@ module Plum
     config.paths["config/routes.rb"] = "config/plum_routes.rb"
     config.paths["db/migrate"] = [ "db/engine_migrate" ]
 
+    initializer "plum.static_cache" do |app|
+      # Always installed; it no-ops per request unless StaticCache.enabled?
+      app.middleware.use Plum::StaticCache::Middleware
+    end
+
     initializer "plum.assets" do |app|
       app.config.assets.paths << root.join("app/assets/javascripts")
-      app.config.assets.paths << root.join("app/javascript/controllers/plum")
+      # Importmap exposes these files as `plum/*`, so Propshaft must resolve
+      # them relative to the parent controllers directory.
+      app.config.assets.paths << root.join("app/javascript/controllers")
       app.config.assets.paths << root.join("vendor/javascript")
 
       lexxy_spec = Gem.loaded_specs["lexxy"]

data/lib/plum/static_cache/middleware.rb

@@ -0,0 +1,61 @@
+require_relative "../static_cache"
+
+module Plum
+  module StaticCache
+    # Serves cached pages before the request reaches Rails and captures
+    # renders on the way out. Controllers opt responses in by setting the
+    # X-Plum-Static-Cache header to "store" (see PagesController); everything
+    # else passes through untouched.
+    class Middleware
+      MARKER = StaticCache::MARKER_HEADER.downcase
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        if StaticCache.enabled? && cacheable_request?(env) && (file = StaticCache.read(env["HTTP_HOST"], env["PATH_INFO"]))
+          return serve(file, env)
+        end
+
+        status, headers, body = @app.call(env)
+        maybe_store(env, status, headers, body)
+      end
+
+      private
+
+      def cacheable_request?(env)
+        return false unless env["REQUEST_METHOD"] == "GET" || env["REQUEST_METHOD"] == "HEAD"
+
+        env["QUERY_STRING"].to_s.empty?
+      end
+
+      def serve(file, env)
+        body = env["REQUEST_METHOD"] == "HEAD" ? [] : [ file.binread ]
+        headers = {
+          "content-type" => StaticCache.content_type_for(file),
+          "content-length" => file.size.to_s,
+          MARKER => "hit"
+        }
+        [ 200, headers, body ]
+      end
+
+      def maybe_store(env, status, headers, body)
+        # The marker is internal — strip it even when the response isn't stored.
+        marker = headers.delete(MARKER) || headers.delete(StaticCache::MARKER_HEADER)
+        return [ status, headers, body ] unless marker == "store" && StaticCache.enabled? && cacheable_request?(env)
+        return [ status, headers, body ] unless status == 200 && env["REQUEST_METHOD"] == "GET"
+        return [ status, headers, body ] if headers["set-cookie"].present? || headers["Set-Cookie"].present?
+
+        chunks = []
+        body.each { |chunk| chunks << chunk.to_s }
+        body.close if body.respond_to?(:close)
+        full_body = chunks.join
+
+        StaticCache.store(env["HTTP_HOST"], env["PATH_INFO"], full_body)
+        headers[MARKER] = "miss"
+        [ status, headers, [ full_body ] ]
+      end
+    end
+  end
+end

data/lib/plum/static_cache.rb

@@ -0,0 +1,103 @@
+require "rack/mime"
+
+module Plum
+  # Full-page static cache. Rendered public pages are written to disk keyed by
+  # host + path; subsequent requests are served from the file without touching
+  # the database or Liquid. A web server can serve the same files directly
+  # (nginx try_files) for the "full measure" where Rails never sees the hit.
+  #
+  # Cache entries are invalidated by deletion (see StaticCacheInvalidation) —
+  # the next request re-renders and re-stores the page. Over-flushing is cheap,
+  # so anything ambiguous flushes the whole site.
+  module StaticCache
+    MARKER_HEADER = "X-Plum-Static-Cache".freeze
+
+    class << self
+      # Explicit opt-in only — see docs/static-caching.md. There is
+      # deliberately no "auto-on in production" mode: this cache is only
+      # correct on a single-server deployment, and defaulting it on would
+      # silently corrupt pages the moment an app scales to 2+ nodes.
+      def enabled?
+        !!Plum.configuration.static_cache_enabled
+      end
+
+      def cache_root
+        Pathname(Plum.configuration.static_cache_path || Rails.root.join("storage", "plum_static_cache"))
+      end
+
+      # Pages are stored as {host}/{path}/index.html so a web server can map
+      # URLs to files directly. Paths with a file extension (theme assets) are
+      # stored verbatim.
+      def file_path(host, path)
+        key = normalized_path(path)
+        return nil unless key
+
+        base = cache_root.join(sanitized_host(host))
+        full = File.extname(key).present? ? base.join(key) : base.join(key, "index.html")
+        full = Pathname(File.expand_path(full))
+        return nil unless full.to_s.start_with?(cache_root.to_s + File::SEPARATOR)
+
+        full
+      end
+
+      def read(host, path)
+        file = file_path(host, path)
+        file if file&.file?
+      end
+
+      def store(host, path, body)
+        file = file_path(host, path)
+        return unless file
+
+        file.dirname.mkpath
+        tmp = file.sub_ext(".tmp-#{Process.pid}-#{Thread.current.object_id}")
+        tmp.binwrite(body)
+        File.rename(tmp, file)
+        file
+      rescue SystemCallError => e
+        Rails.logger.error("[Plum] static cache write failed for #{path}: #{e.message}")
+        nil
+      end
+
+      def flush_site!(site)
+        return flush_all! if site.nil? || site.domain.blank?
+
+        [ site.domain, "www.#{site.domain}" ].each do |host|
+          dir = cache_root.join(sanitized_host(host))
+          FileUtils.rm_rf(dir) if dir.to_s.start_with?(cache_root.to_s) && dir.exist?
+        end
+      end
+
+      def flush_all!
+        return unless cache_root.exist?
+
+        cache_root.children.each { |child| FileUtils.rm_rf(child) }
+      end
+
+      def content_type_for(file)
+        Rack::Mime.mime_type(File.extname(file.to_s), "text/html")
+      end
+
+      private
+
+      def sanitized_host(host)
+        cleaned = host.to_s.downcase.gsub(/[^a-z0-9.\-]/, "")
+        cleaned.presence || "_default"
+      end
+
+      # Rejects anything that could escape the cache directory and normalizes
+      # "/" and "/about/" style paths to a shared key.
+      def normalized_path(path)
+        decoded = begin
+          URI.decode_www_form_component(path.to_s)
+        rescue ArgumentError
+          return nil
+        end
+        return nil if decoded.include?("..") || decoded.include?("\0")
+
+        trimmed = decoded.delete_prefix("/").chomp("/")
+        trimmed.presence || "_root"
+      end
+    end
+  end
+end

data/lib/plum/version.rb

@@ -1,6 +1,6 @@
 module Plum
   module Version
-    STRING = "0.2.0"
+    STRING = "0.2.2"
   end
 
   VERSION = Version::STRING

data/lib/tasks/plum_config.rake

@@ -0,0 +1,48 @@
+# This repo is both the engine and an app, so Rails loads lib/tasks twice
+# (engine railtie + application). Rake appends actions on re-definition, which
+# would run every task body twice — guard against the second load.
+unless Rake::Task.task_defined?("plum:config:export")
+  namespace :plum do
+    namespace :config do
+      def plum_config_site
+        site = ENV["SITE_ID"].present? ? Plum::Site.find(ENV["SITE_ID"]) : Plum::Site.first
+        abort "No Plum site exists" unless site
+        site
+      end
+
+      def plum_config_dir
+        ENV["DIR"].presence || Plum.configuration.config_path || Rails.root.join("plum")
+      end
+
+      desc "Write the content model (content types, fieldsets) to YAML files (SITE_ID optional; DIR defaults to plum/)"
+      task export: :environment do
+        files = Plum::ConfigSync.export(site: plum_config_site, dir: plum_config_dir)
+        puts "Exported #{files.length} config files to #{plum_config_dir}"
+      end
+
+      desc "Apply YAML config files to the database (SITE_ID optional; PRUNE=1 deletes types absent from files; FORCE=1 allows deleting types with entries)"
+      task sync: :environment do
+        result = Plum::ConfigSync.apply(
+          site: plum_config_site,
+          dir: plum_config_dir,
+          prune: ENV["PRUNE"].present?,
+          force: ENV["FORCE"].present?
+        )
+        puts "Config sync: #{result.summary}"
+      rescue Plum::ConfigSync::UnsafePruneError => e
+        abort e.message
+      end
+
+      desc "Fail if the database content model has drifted from the YAML files (for CI)"
+      task check: :environment do
+        drift = Plum::ConfigSync.check(site: plum_config_site, dir: plum_config_dir)
+        if drift.any?
+          drift.each { |line| puts "DRIFT #{line}" }
+          abort "Content model has drifted from config files (#{drift.length} differences)"
+        else
+          puts "Content model matches config files"
+        end
+      end
+    end
+  end
+end

data/lib/tasks/plum_portability.rake

@@ -0,0 +1,62 @@
+# This repo is both the engine and an app, so Rails loads lib/tasks twice
+# (engine railtie + application). Rake appends actions on re-definition, which
+# would run every task body twice — guard against the second load.
+unless Rake::Task.task_defined?("plum:site:export")
+  namespace :plum do
+    namespace :site do
+      desc "Export a complete Plum site archive (SITE_ID or first site; ARCHIVE required)"
+      task export: :environment do
+        path = ENV.fetch("ARCHIVE") { abort "ARCHIVE is required" }
+        site = ENV["SITE_ID"].present? ? Plum::Site.find(ENV["SITE_ID"]) : Plum::Site.first
+        abort "No Plum site exists" unless site
+
+        archive = Plum::SiteArchive.dump(site: site, path: path)
+        puts "Exported #{site.name} to #{archive}"
+      end
+
+      desc "Import a Plum site archive as a new site (ARCHIVE required; NAME and DOMAIN optional)"
+      task import: :environment do
+        path = ENV.fetch("ARCHIVE") { abort "ARCHIVE is required" }
+        site = Plum::SiteArchive.load(path: path, name: ENV["NAME"], domain: ENV["DOMAIN"])
+        puts "Imported #{site.name} as site #{site.id}"
+      end
+    end
+
+    namespace :site do
+      desc "Replace the local site with an archive — the 'pull' refresh (ARCHIVE required; SITE_ID optional; FORCE=1 required in production)"
+      task replace: :environment do
+        path = ENV.fetch("ARCHIVE") { abort "ARCHIVE is required" }
+        if Rails.env.production? && ENV["FORCE"].blank?
+          abort "Refusing to replace a site in production (set FORCE=1 to override)"
+        end
+
+        old_site = ENV["SITE_ID"].present? ? Plum::Site.find(ENV["SITE_ID"]) : Plum::Site.first
+        old_name = old_site&.name
+
+        site = ActiveRecord::Base.transaction do
+          old_site&.destroy!
+          Plum::SiteArchive.load(path: path, name: ENV["NAME"], domain: ENV["DOMAIN"])
+        end
+
+        puts old_name ? "Replaced #{old_name} with #{site.name} (site #{site.id})" : "Imported #{site.name} as site #{site.id}"
+      end
+    end
+
+    namespace :backup do
+      desc "Create a timestamped Plum site backup (SITE_ID optional; DIRECTORY defaults to backups/plum)"
+      task create: :environment do
+        site = ENV["SITE_ID"].present? ? Plum::Site.find(ENV["SITE_ID"]) : Plum::Site.first
+        abort "No Plum site exists" unless site
+        directory = Rails.root.join(ENV.fetch("DIRECTORY", "backups/plum"))
+        filename = "plum-site-#{site.id}-#{Time.current.utc.strftime('%Y%m%d%H%M%S')}.plum.zip"
+        archive = Plum::SiteArchive.dump(site: site, path: directory.join(filename))
+        puts "Backed up #{site.name} to #{archive}"
+      end
+
+      desc "Restore a Plum backup as a new site (ARCHIVE required; NAME and DOMAIN optional)"
+      task restore: :environment do
+        Rake::Task["plum:site:import"].invoke
+      end
+    end
+  end
+end

data/lib/tasks/plum_styles.rake

@@ -1,12 +1,17 @@
-require "fileutils"
+# This repo is both the engine and an app, so Rails loads lib/tasks twice
+# (engine railtie + application). Rake appends actions on re-definition, which
+# would run every task body twice — guard against the second load.
+unless Rake::Task.task_defined?("plum:build_styles")
+  require "fileutils"
 
-namespace :plum do
-  desc "Build Tailwind and copy the result into Plum's packaged stylesheet"
-  task build_styles: :environment do
-    system(Rails.root.join("bin/rails").to_s, "tailwindcss:build", exception: true)
-    source = Rails.root.join("app/assets/builds/tailwind.css")
-    destination = Rails.root.join("app/assets/stylesheets/plum/control_panel.css")
-    FileUtils.cp(source, destination)
-    puts "Packaged #{destination.relative_path_from(Rails.root)}"
+  namespace :plum do
+    desc "Build Tailwind and copy the result into Plum's packaged stylesheet"
+    task build_styles: :environment do
+      system(Rails.root.join("bin/rails").to_s, "tailwindcss:build", exception: true)
+      source = Rails.root.join("app/assets/builds/tailwind.css")
+      destination = Rails.root.join("app/assets/stylesheets/plum/control_panel.css")
+      FileUtils.cp(source, destination)
+      puts "Packaged #{destination.relative_path_from(Rails.root)}"
+    end
   end
 end