pressroom 0.1.0

data/lib/pressroom/blocks/schema.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Pressroom
+  module Blocks
+    # Declarative description of one block's data payload.
+    #
+    # The schema exists for security first and validation second: it records
+    # which fields carry HTML from Editor.js inline tools, so the renderer
+    # knows exactly what to run through the sanitizer and what to escape.
+    class Schema
+      Field = Struct.new(:name, :type, :required, :default, :options, :schema,
+                         keyword_init: true)
+
+      SCALAR_TYPES = %i[string html integer boolean enum].freeze
+
+      # Guards against a hand-crafted document nesting a list deep enough
+      # to exhaust the stack during coercion or rendering.
+      MAX_TREE_DEPTH = 8
+
+      def self.build(&block)
+        schema = new
+        schema.instance_eval(&block) if block
+        schema
+      end
+
+      attr_reader :fields
+
+      def initialize
+        @fields = {}
+      end
+
+      def string(name, required: false, default: nil)
+        add(name, :string, required, default)
+      end
+
+      def html(name, required: false, default: nil)
+        add(name, :html, required, default)
+      end
+
+      def integer(name, required: false, default: nil)
+        add(name, :integer, required, default)
+      end
+
+      def boolean(name, required: false, default: false)
+        add(name, :boolean, required, default)
+      end
+
+      # +in:+ is a Ruby keyword and cannot be a parameter name, so it is
+      # collected through the options hash.
+      def enum(name, required: false, default: nil, **options)
+        values = Array(options.fetch(:in)).map(&:to_s)
+        add(name, :enum, required, default, { values: values })
+      end
+
+      def array(name, of:, required: false, default: nil)
+        add(name, :array, required, default || [], { of: of.to_sym })
+      end
+
+      def nested(name, required: false, &block)
+        add(name, :nested, required, nil, {}, Schema.build(&block))
+      end
+
+      # A recursive list, as produced by @editorjs/list 2.x:
+      #   [{ "content" => "a", "items" => [{ "content" => "a1", "items" => [] }] }]
+      #
+      # Plain strings are accepted too, so documents written by the 1.x
+      # tool keep rendering after an upgrade.
+      def tree(name, content: :html, required: false)
+        add(name, :tree, required, [], { content: content.to_sym })
+      end
+
+      # Names of fields whose values must be sanitized before rendering.
+      def html_fields
+        fields.each_value.filter_map do |field|
+          next field.name if field.type == :html
+          next field.name if field.type == :array && field.options[:of] == :html
+          next field.name if field.type == :tree && field.options[:content] == :html
+
+          nil
+        end
+      end
+
+      # Applies the sanitizer to every field that can carry markup.
+      #
+      # This lives on the schema rather than the renderer because only the
+      # schema knows the shape of each field: a flat string, an array, a
+      # nested object, or a recursive tree.
+      def sanitize(data, sanitizer)
+        result = data.dup
+
+        fields.each do |name, field|
+          case field.type
+          when :html
+            result[name] = sanitizer.sanitize(result[name])
+          when :array
+            next unless field.options[:of] == :html
+
+            result[name] = Array(result[name]).map { |item| sanitizer.sanitize(item) }
+          when :tree
+            next unless field.options[:content] == :html
+
+            result[name] = sanitize_tree(Array(result[name]), sanitizer)
+          when :nested
+            result[name] = field.schema.sanitize(result[name] || {}, sanitizer)
+          end
+        end
+
+        result
+      end
+
+      # Returns [normalized_data, errors]. Never raises: a malformed payload
+      # degrades to defaults so that one bad article cannot take a page down.
+      def coerce(data)
+        data = data.is_a?(Hash) ? stringify(data) : {}
+        errors = []
+        result = {}
+
+        fields.each do |name, field|
+          if !data.key?(name) || data[name].nil?
+            errors << "#{name} is required" if field.required
+            result[name] = dup_default(field)
+            next
+          end
+
+          value, error = cast(field, data[name])
+          errors << "#{name}: #{error}" if error
+          result[name] = error ? dup_default(field) : value
+        end
+
+        [result, errors]
+      end
+
+      private
+
+      def add(name, type, required, default, options = {}, schema = nil)
+        key = name.to_s
+        fields[key] = Field.new(name: key, type: type, required: required,
+                                default: default, options: options, schema: schema)
+        key
+      end
+
+      def stringify(hash)
+        hash.each_with_object({}) { |(k, v), memo| memo[k.to_s] = v }
+      end
+
+      def dup_default(field)
+        default = field.default
+        default.respond_to?(:dup) && !default.frozen? ? default.dup : default
+      end
+
+      def cast(field, value)
+        case field.type
+        when :string, :html
+          [value.to_s, nil]
+        when :integer
+          [Integer(value), nil]
+        when :boolean
+          [cast_boolean(value), nil]
+        when :enum
+          cast_enum(field, value)
+        when :array
+          cast_array(field, value)
+        when :tree
+          cast_tree(field, value)
+        when :nested
+          cast_nested(field, value)
+        else
+          [nil, "unknown field type #{field.type}"]
+        end
+      rescue ArgumentError, TypeError
+        [nil, "cannot be cast to #{field.type}"]
+      end
+
+      def cast_boolean(value)
+        return false if value == false || value.nil?
+        return false if value.to_s.strip.downcase == "false"
+        return false if value.to_s.strip == "0"
+        return false if value.to_s.strip.empty?
+
+        true
+      end
+
+      def cast_enum(field, value)
+        candidate = value.to_s
+        return [candidate, nil] if field.options[:values].include?(candidate)
+
+        [nil, "must be one of #{field.options[:values].join(', ')}"]
+      end
+
+      def cast_array(field, value)
+        return [nil, "must be an array"] unless value.is_a?(Array)
+
+        element = Field.new(name: field.name, type: field.options[:of],
+                            required: false, default: nil, options: {})
+        [value.map { |item| cast(element, item).first }, nil]
+      end
+
+      def cast_nested(field, value)
+        return [nil, "must be an object"] unless value.is_a?(Hash)
+
+        nested_data, nested_errors = field.schema.coerce(value)
+        [nested_data, nested_errors.empty? ? nil : nested_errors.join("; ")]
+      end
+
+      def cast_tree(field, value)
+        return [nil, "must be an array"] unless value.is_a?(Array)
+
+        [build_tree(field, value, 0), nil]
+      end
+
+      def build_tree(field, items, depth)
+        return [] if depth >= MAX_TREE_DEPTH
+
+        items.filter_map do |item|
+          node = normalize_tree_node(item)
+          next nil if node.nil?
+
+          content, = cast(content_field(field), node[:content])
+          { "content" => content.to_s,
+            "items" => build_tree(field, Array(node[:children]), depth + 1) }
+        end
+      end
+
+      def normalize_tree_node(item)
+        case item
+        when Hash
+          { content: item["content"] || item[:content],
+            children: item["items"] || item[:items] }
+        when nil then nil
+        else { content: item, children: [] }
+        end
+      end
+
+      def content_field(field)
+        Field.new(name: field.name, type: field.options[:content],
+                  required: false, default: nil, options: {})
+      end
+
+      def sanitize_tree(items, sanitizer)
+        items.map do |item|
+          { "content" => sanitizer.sanitize(item["content"]),
+            "items" => sanitize_tree(Array(item["items"]), sanitizer) }
+        end
+      end
+    end
+  end
+end

data/lib/pressroom/blocks/text_extractor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Pressroom
+  module Blocks
+    # Produces plain text for the host application's search index.
+    #
+    # Never raises: it runs inside a save callback, and a block type the
+    # registry has not seen must not prevent an author from saving a draft.
+    class TextExtractor
+      def initialize(registry:)
+        @registry = registry
+      end
+
+      def extract(document)
+        blocks_of(document)
+          .filter_map { |block| text_for_block(block) }
+          .join(" ")
+          .gsub(/\s+/, " ")
+          .strip
+      end
+
+      private
+
+      def blocks_of(document)
+        case document
+        when Array then document.select { |item| item.is_a?(Hash) }
+        when Hash  then Array(document["blocks"] || document[:blocks])
+                          .select { |item| item.is_a?(Hash) }
+        else []
+        end
+      end
+
+      def text_for_block(block)
+        type = (block["type"] || block[:type]).to_s
+        definition = @registry.fetch(type)
+        return nil unless definition
+
+        data, = definition.schema.coerce(block["data"] || block[:data])
+        text = definition.text_for(data).to_s.strip
+        text.empty? ? nil : text
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/pressroom/built_in_blocks.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Pressroom
+  # The seven core block types. Anything richer -- tables, checklists,
+  # embeds, attachments -- belongs in the host application or in a
+  # companion gem, not here: every built-in block is support surface
+  # forever.
+  module BuiltInBlocks
+    module_function
+
+    def register!(registry)
+      paragraph(registry)
+      header(registry)
+      list(registry)
+      quote(registry)
+      code(registry)
+      image(registry)
+      delimiter(registry)
+    end
+
+    def paragraph(registry)
+      registry.register(:paragraph) do |b|
+        b.tool "Paragraph"
+        b.partial "pressroom/blocks/paragraph"
+        b.schema { html :text }
+      end
+    end
+
+    def header(registry)
+      registry.register(:header) do |b|
+        b.tool "Header", config: { levels: [2, 3, 4], defaultLevel: 2 }
+        b.partial "pressroom/blocks/header"
+        b.schema do
+          html :text
+          integer :level, default: 2
+        end
+      end
+    end
+
+    def list(registry)
+      registry.register(:list) do |b|
+        b.tool "List"
+        b.partial "pressroom/blocks/list"
+        b.schema do
+          enum :style, in: %w[ordered unordered], default: "unordered"
+          tree :items, content: :html
+        end
+      end
+    end
+
+    def quote(registry)
+      registry.register(:quote) do |b|
+        b.tool "Quote"
+        b.partial "pressroom/blocks/quote"
+        b.schema do
+          html :text
+          html :caption
+          enum :alignment, in: %w[left center], default: "left"
+        end
+      end
+    end
+
+    def code(registry)
+      registry.register(:code) do |b|
+        b.tool "CodeTool"
+        b.partial "pressroom/blocks/code"
+        # Deliberately a string, not html: code is escaped, never sanitized.
+        b.schema { string :code }
+      end
+    end
+
+    def image(registry)
+      registry.register(:image) do |b|
+        b.tool "ImageTool"
+        b.partial "pressroom/blocks/image"
+        b.schema do
+          nested :file do
+            string :url
+          end
+          html :caption
+          boolean :withBorder
+          boolean :stretched
+          boolean :withBackground
+        end
+        b.searchable { |data| data["caption"] }
+      end
+    end
+
+    def delimiter(registry)
+      registry.register(:delimiter) do |b|
+        b.tool "Delimiter"
+        b.partial "pressroom/blocks/delimiter"
+        b.schema { }
+      end
+    end
+  end
+end

data/lib/pressroom/configuration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Pressroom
+  # Host-application settings. Every value has a safe default; the one
+  # deliberate exception is +authenticate_with+, which defaults to nil so
+  # that an unconfigured admin refuses access instead of granting it.
+  class Configuration
+    DEFAULT_SANITIZER_TAGS = %w[b strong i em u s mark code br a].freeze
+    DEFAULT_SANITIZER_ATTRIBUTES = %w[href target rel class].freeze
+
+    # Drops unknown characters instead of replacing them with "?", so that
+    # a fully non-Latin title yields an empty string the slug generator can
+    # detect and fall back from. See Pressroom::Transliteration for why this
+    # does not simply call I18n.transliterate.
+    DEFAULT_TRANSLITERATOR = lambda do |string, locale|
+      Pressroom::Transliteration.call(string, locale)
+    end
+
+    attr_accessor :parent_controller, :author_class,
+                  :author_name_method, :comments, :transliteration_locale,
+                  :transliterator, :sanitizer_tags, :sanitizer_attributes,
+                  :unknown_block_strategy, :admin_per_page,
+                  :image_content_types, :max_image_bytes
+
+    attr_writer :authenticate_with
+
+    def initialize
+      @parent_controller       = "ApplicationController"
+      @authenticate_with       = nil
+      @author_class            = nil
+      @author_name_method      = :name
+      @comments                = false
+      @transliteration_locale  = nil
+      @transliterator          = DEFAULT_TRANSLITERATOR
+      @sanitizer_tags          = DEFAULT_SANITIZER_TAGS.dup
+      @sanitizer_attributes    = DEFAULT_SANITIZER_ATTRIBUTES.dup
+      @unknown_block_strategy  = nil
+      @admin_per_page          = 25
+      @image_content_types     = %w[image/png image/jpeg image/gif image/webp]
+      @max_image_bytes         = 5 * 1024 * 1024
+    end
+
+    # Reader and block-form writer in one, so both spellings work:
+    #
+    #   config.authenticate_with { redirect_to main_app.root_path unless ... }
+    #   config.authenticate_with = ->(*) { ... }
+    def authenticate_with(&block)
+      @authenticate_with = block if block
+      @authenticate_with
+    end
+
+    # Explicit configuration wins; otherwise fail loudly where a developer
+    # will see it and degrade quietly where users would.
+    def resolved_unknown_block_strategy
+      return unknown_block_strategy if unknown_block_strategy
+
+      defined?(Rails) && Rails.env.local? ? :raise : :skip
+    end
+
+    def author_class_object
+      author_class&.constantize
+    end
+  end
+end

data/lib/pressroom/engine.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pressroom
+  class Engine < ::Rails::Engine
+    isolate_namespace Pressroom
+
+    # Registration happens once at boot, not in to_prepare: the registry is
+    # not reloadable, and re-registering would raise on a code reload.
+    initializer "pressroom.blocks" do
+      Pressroom::BuiltInBlocks.register!(Pressroom.registry)
+    end
+
+    initializer "pressroom.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include Pressroom::BlocksHelper
+      end
+    end
+
+    initializer "pressroom.assets" do |app|
+      next unless app.config.respond_to?(:assets)
+
+      app.config.assets.paths << root.join("app/assets/javascripts")
+      app.config.assets.paths << root.join("app/assets/stylesheets")
+    end
+
+    initializer "pressroom.importmap", before: "importmap" do |app|
+      next unless app.config.respond_to?(:importmap)
+
+      app.config.importmap.paths << root.join("config/importmap.rb")
+      app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+    end
+  end
+end

data/lib/pressroom/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pressroom
+  class Error < StandardError; end
+
+  # Raised when the host application has not configured a required hook.
+  class ConfigurationError < Error; end
+
+  # Raised when a stored block has no matching definition in the registry.
+  class UnknownBlockError < Error; end
+end

data/lib/pressroom/feed.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rss"
+
+module Pressroom
+  # Builds RSS 2.0 and Atom 1.0 documents from a collection of posts.
+  #
+  # The gem does not own public routes, so the caller supplies a block that
+  # turns a post into its public URL.
+  class Feed
+    def initialize(posts, title:, url:, description:, author: nil, &link_builder)
+      @posts = posts
+      @title = title
+      @url = url
+      @description = description
+      @author = author || title
+      @link_builder = link_builder || ->(post) { "#{url}/#{post.slug}" }
+    end
+
+    def to_rss
+      RSS::Maker.make("2.0") do |maker|
+        maker.channel.title = @title
+        maker.channel.link = @url
+        maker.channel.description = @description
+        maker.channel.updated = updated_at.to_s
+
+        add_items(maker)
+      end.to_s
+    end
+
+    def to_atom
+      RSS::Maker.make("atom") do |maker|
+        maker.channel.id = @url
+        maker.channel.title = @title
+        maker.channel.link = @url
+        maker.channel.description = @description
+        maker.channel.author = @author
+        maker.channel.updated = updated_at.to_s
+
+        add_items(maker)
+      end.to_s
+    end
+
+    private
+
+    def add_items(maker)
+      @posts.each do |post|
+        link = @link_builder.call(post)
+
+        maker.items.new_item do |item|
+          item.id = link
+          item.title = post.title
+          item.link = link
+          item.description = post.excerpt.to_s
+          item.updated = timestamp_for(post).to_s
+          item.pubDate = timestamp_for(post).to_s
+        end
+      end
+    end
+
+    def timestamp_for(post)
+      post.published_at || post.updated_at || Time.current
+    end
+
+    def updated_at
+      @posts.filter_map { |post| timestamp_for(post) }.max || Time.current
+    end
+  end
+end