impression 0.11 → 0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7a6bc0c67e0c2488971f3277d47a40c44b482dd76e2456c4a1769d7cfd176a0
-  data.tar.gz: aef9442c29716d60f20bb41e0fe7f518599352bacebff8c489d13b8e21046908
+  metadata.gz: e9b79a3bb3823fad2c5c7ad2ed7f187c2c398dea84c62d9d0fdbd481238f499a
+  data.tar.gz: 6cd1d41db73b992ee6f2027220440871d6512811f23b810ba064733a0538e7d4
 SHA512:
-  metadata.gz: 8e26204c6147d8f10ba10e0d84c89d2d13b92795eee2aec72650dca37a6e069c2806a004491a5507f6fd32d540213b2dfae353b45e827febc71d3e19f2d5fb94
-  data.tar.gz: 808dc2e16f4b58f74a82570b84e589da05649f9e78d4997e3c90e68c11537c636b3f93d9b32bd1b01add73617bfa921fba240f3e774978a9d898fdab834b1bfa
+  metadata.gz: 734ab33bb5056e06076403fc774a13851953edec042b915826577aaa810c8e9d39c1a242b95836b5b6dcb61404d0fd1e8ab3afaf0cd095105a14d5ccd1bab9ea
+  data.tar.gz: df49438b49021b4d42de855f72b2342ecfe9416a2ea118feb8d09580d8ac4c0bb3f10b87d25edc020cdf37be8a91a5d0d4f85119b3a7bf3e3d3186b917477594

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.12 2022-02-16
+
+- Implement `RackApp` resource class (#16)
+
 ## 0.11 2022-02-10
 
 - Update Tipi

data/Gemfile

@@ -1,8 +1,3 @@
 source 'https://rubygems.org'
 
 gemspec
-
-# %w{polyphony tipi qeweney papercraft}.each do |dep|
-#   dir = "../#{dep}"
-#   gem(dep, path: dir) if File.directory?(dir)
-# end

data/Gemfile.lock

@@ -1,11 +1,11 @@
 PATH
   remote: .
   specs:
-    impression (0.11)
+    impression (0.12)
       modulation (~> 1.1)
-      papercraft (~> 0.19)
+      papercraft (~> 0.23)
       polyphony (~> 0.77)
-      qeweney (~> 0.17)
+      qeweney (~> 0.18)
       tipi (~> 0.50)
 
 GEM
@@ -16,7 +16,7 @@ GEM
     docile (1.4.0)
     escape_utils (1.2.1)
     ever (0.1)
-    extralite (1.11)
+    extralite (1.12)
     faraday (1.9.3)
       faraday-em_http (~> 1.0)
       faraday-em_synchrony (~> 1.0)
@@ -50,15 +50,15 @@ GEM
     localhost (1.1.9)
     minitest (5.11.3)
     modulation (1.1)
-    msgpack (1.4.4)
+    msgpack (1.4.5)
     multipart-post (2.1.1)
-    papercraft (0.19)
+    papercraft (0.23)
       escape_utils (~> 1.2.1)
       kramdown (~> 2.3.1)
       kramdown-parser-gfm (~> 1.1.0)
       rouge (~> 3.27.0)
     polyphony (0.77)
-    qeweney (0.17)
+    qeweney (0.18)
       escape_utils (~> 1.2.1)
     rack (2.2.3)
     rake (12.3.3)

data/README.md

@@ -19,20 +19,90 @@
 ## What is Impression
 
 > Impression is still in a very early stage of development. Things might not
-> correctly, or not at all.
+> work correctly.
 
 Impression is a modern web framework for Ruby. Unlike other web framework,
 Impression does not impose any rigid structure or paradigm, but instead provides
-a set of tools letting you build any kind of web app, by freely mixing different
-kinds of web resources, be they static files, structured templates, Jamstack
-sites, or dynamic APIs.
+a minimalistic set of tools, letting you build any kind of web app, by freely
+mixing different kinds of web resources, be they static files, structured
+templates, Jamstack sites, or dynamic APIs.
 
-In Impression, resources can be composed into a hierarchical tree, allowing
-combining of multiple web apps, or web subsystems, into a single URL hierarchy.
+## Resources
+
+The main abstraction in Impression is the resource - which represents an web
+endpoint that is mounted at a specific location in the URL namespace, and
+responds to requests. Resources can be nested in order to create arbitrarily
+complex routing trees. Impression provides multiple resource types, each
+customized for a specific use case, be it a JSON API, a set of MVC-style
+controllers, or a Markdown-based blog with static content.
+
+Finally, any kind of resource can be used as an Impression app. Routing is
+performed automatically according to the resource tree, starting from the root
+resource.
+
+## The request-response cycle
+
+The handling of incoming HTTP requests is done in two stages. First the request
+is routed to the corresponding resource, which then handles the request by
+generating a response.
+
+HTTP requests and responses use the
+[Qeweney](https://github.com/digital-fabric/qeweney) API.
+
+## Resource types
+
+Impression provides the following resources:
+
+- `Resource` - a generic resource.
+- `FileTree` - a resource serving static files from the given directory.
+- `App` - a resource serving static files, markdown files with layouts and Ruby
+  modules from the given directory.
+- `RackApp` - a resource serving the given Rack app.
+
+## Setting up a basic resource
+
+To setup a generic resource, call `Impression.resource` and provide a request
+handler:
+
+```
+app = Impression.resource { |req| req.respond('Hello, world!') }
+```
+
+## Running your app with Tipi
 
 Impression is made for running on top of
-[Tipi](https://github.com/digital-fabric/tipi), a new all-in-one web server for
-Ruby.
+[Tipi](https://github.com/digital-fabric/tipi). Your Tipi app file would like
+something like the following:
+
+```ruby
+# app.rb
+app = Impression.resource { |req| req.respond('Hello, world!') }
+Tipi.run(&app)
+```
+
+You can then start Tipi by running `tipi run app.rb`.
+
+## Running your app with a Rack app server
+
+You can also run your app on any Rack app server, using something like the
+following:
+
+```ruby
+app = Impression.resource { |req| req.respond('Hello, world!') }
+run Qeweney.rack(&app)
+```
+
+## Creating a routing map with resources
+
+A resource can be mounted at any point in the app's URL space. Resources can be
+nested within other resources by passing a `parent:` argument when creating a
+resource:
+
+```ruby
+app = Impression.app { |req| req.respond('Homepage') }
+greeter = Impression.resource(parent: app, path: 'greeter')
+static = Impression.file_tree(parent: app, path: 'static', directory: __dir__)
+```
 
 ## I want to know more
 

data/impression.gemspec

@@ -22,9 +22,9 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency      'polyphony',            '~>0.77'
   s.add_runtime_dependency      'tipi',                 '~>0.50'
-  s.add_runtime_dependency      'qeweney',              '~>0.17'
+  s.add_runtime_dependency      'qeweney',              '~>0.18'
   
-  s.add_runtime_dependency      'papercraft',           '~>0.19'
+  s.add_runtime_dependency      'papercraft',           '~>0.23'
   s.add_runtime_dependency      'modulation',           '~>1.1'
 
   

data/lib/impression/app.rb

@@ -1,9 +1,277 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+require 'date'
+require 'yaml'
+require 'modulation'
+require 'papercraft'
+
+require_relative './resource'
+require_relative './file_tree'
+
 module Impression
-  class App < Resource
-    def initialize(path: '/', **opts)
-      super(path: path, **opts)
+
+  # `App` implements a resource that maps to a generic app directory.
+  class App < FileTree
+    def initialize(**props)
+      super
+      @layouts = {}
+    end
+
+    # Returns a list of pages found in the given directory (relative to the base
+    # directory). Each entry containins the absolute file path, the pretty URL,
+    # the possible date parsed from the file name, and any other front matter
+    # attributes (for .md files). This method will detect only pages with the
+    # extensions .html, .md, .rb. The returned entries are sorted by file path.
+    #
+    # @param dir [String] relative directory
+    # @return [Array<Hash>] array of page entries
+    def page_list(dir)
+      base = File.join(@directory, dir)
+      Dir.glob('*.{html,md}', base: base)
+        .map { |fn| get_path_info(File.join(dir, fn)) }# page_entry(fn, dir) }
+        .sort_by { |i| i[:path] }
+    end
+
+    private
+
+    DATE_REGEXP = /(\d{4}\-\d{2}\-\d{2})/.freeze
+    FRONT_MATTER_REGEXP = /\A(---\s*\n.*?\n?)^((---|\.\.\.)\s*$\n?)/m.freeze
+    MD_EXT_REGEXP = /\.md$/.freeze
+    PAGE_EXT_REGEXP = /^(.+)\.(md|html|rb)$/.freeze
+    INDEX_PAGE_REGEXP = /^(.+)?\/index$/.freeze
+
+    YAML_OPTS = {
+      permitted_classes: [Date],
+      symbolize_names: true
+    }.freeze
+
+    # Returns the path info for the given file path.
+    #
+    # @param path [String] file path
+    # @return [Hash] path info
+    def file_info(path)
+      info = super
+      case info[:ext]
+      when '.md'
+        atts, content = parse_markdown_file(path)
+        info = info.merge(atts)
+        info[:html_content] = Papercraft.markdown(content)
+        info[:kind] = :markdown
+      when '.rb'
+        info[:module] = import(path)
+        info[:kind] = :module
+      end
+      if (m = path.match(DATE_REGEXP))
+        info[:date] ||= Date.parse(m[1])
+      end
+  
+      info
+    end
+
+    # Returns the pretty URL for the given relative path. For pages, the
+    # extension is removed. For index pages, the index suffix is removed.
+    #
+    # @param relative_path [String] relative path
+    # @return [String] pretty URL
+    def pretty_url(relative_path)
+      if (m = relative_path.match(PAGE_EXT_REGEXP))
+        relative_path = m[1]
+      end
+      if (m = relative_path.match(INDEX_PAGE_REGEXP))
+        relative_path = m[1] || '/'
+      end
+      relative_path == '/' ? absolute_path : File.join(absolute_path, relative_path)
+    end
+
+    # Renders a response according to the given path info.
+    # 
+    # @param req [Qeweney::Request] request
+    # @param path_info [Hash] path info
+    # @return [void]
+    def render_from_path_info(req, path_info)
+      case (kind = path_info[:kind])
+      when :not_found
+        mod_path_info = up_tree_resource_module_path_info(req, path_info)
+        if mod_path_info
+          render_module(req, mod_path_info)
+        else
+          req.respond(nil, ':status' => Qeweney::Status::NOT_FOUND)
+        end
+      when :module
+        render_module(req, path_info)
+      when :markdown
+        render_markdown_file(req, path_info)
+      when :file
+        render_file(req, path_info)
+      else
+        raise "Invalid path info kind #{kind.inspect}"
+      end
+    end
+
+    # Returns the path info for an up-tree resource module, or false if not
+    # found. the :up_tree_resource_module_path_info KV can be either:
+    # - nil (default): up tree module search has not been performed.
+    # - false: no up tree module was found.
+    # - module path info: up tree module info (subsequent requests will be
+    #   directly routed to the module).
+    #
+    # @param req [Qeweney::Request] request
+    # @param path_info [Hash] path info
+    # @return [Hash, false] up-tree resource module path info
+    def up_tree_resource_module_path_info(req, path_info)
+      if path_info[:up_tree_resource_module_path_info].nil?
+        if (mod_path_info = find_up_tree_resource_module(req, path_info))
+          path_info[:up_tree_resource_module_path_info] = mod_path_info
+          return mod_path_info;
+        else
+          path_info[:up_tree_resource_module_path_info] = false
+          return false
+        end
+      end
+      path_info[:up_tree_resource_module_path_info]
+    end
+
+    # Performs a recursive search for an up-tree resource module from the given
+    # path info. If a resource module is found up the tree, its path_info is
+    # returned, otherwise returns nil.
+    # 
+    # @param req [Qeweney::Request] request
+    # @param path_info [Hash] path info
+    # @return [Hash, nil] up-tree resource module path info
+    def find_up_tree_resource_module(req, path_info)
+      relative_path = req.resource_relative_path
+
+      while relative_path != path
+        up_tree_path = File.expand_path('..', relative_path)
+        return nil if up_tree_path == relative_path
+
+        up_tree_path_info = get_path_info(up_tree_path)
+        case up_tree_path_info[:kind]
+        when :not_found
+          relative_path = up_tree_path
+          next
+        when :module
+          return up_tree_path_info
+        else
+          return nil
+        end
+      end
+      nil
+    end
+
+    # Renders a file response for the given request and the given path info,
+    # according to the file type.
+    #
+    # @param req [Qeweney::Request] request
+    # @param path_info [Hash] path info
+    # @return [void]
+    # def render_file(req, path_info)
+    #   case path_info[:kind]
+    #   else
+    #     req.serve_file(path_info[:path])
+    #   end
+    # end
+
+    # Renders a module. If the module is a Resource, it is mounted, and then the
+    # request is rerouted from the new resource and rendered. If the module is a
+    # Proc or a Papercraft::Template, it is rendered as such. Otherwise, an
+    # error is raised.
+    #
+    # @param req [Qeweney::Request] request
+    # @param path_info [Hash] path info
+    # @return [void]
+    def render_module(req, path_info)
+      # p render_module: path_info
+      case (mod = path_info[:module])
+      when Module
+        resource = mod.resource
+        resource.remount(self, path_info[:url])
+        # p path_info_url: path_info[:url], relative_path: req.resource_relative_path
+        relative_url = path_info[:url].gsub(/^#{path}/, '')
+        # p relative_url: relative_url
+        req.recalc_resource_relative_path(relative_url)
+        # p resource_relative_path: req.resource_relative_path
+        resource.route(req).call(req)
+      when Impression::Resource
+        mod.remount(self, path_info[:url])
+        req.recalc_resource_relative_path(path_info[:url])
+        mod.route(req).call(req)
+      when Proc, Papercraft::Template
+        render_papercraft_module(req, mod)
+      else
+        raise "Unsupported module type #{mod.class}"
+      end
+    end
+
+    # Renders a Papercraft module.
+    #
+    # @param mod [Module] Papercraft module
+    # @param path_info [Hash] path info
+    # @return [void]
+    def render_papercraft_module(req, mod)
+      template = Papercraft.html(mod)
+      body = template.render(request: req, resource: self)
+      req.respond(body, 'Content-Type' => template.mime_type)
+    end
+
+    # Renders a markdown file using a layout.
+    #
+    # @param req [Qeweney::Request] reqest
+    # @param path_info [Hash] path info
+    # @return [void]
+    def render_markdown_file(req, path_info)
+      layout = get_layout(path_info[:layout])
+
+      html = layout.render(request: req, resource: self, **path_info) {
+        emit path_info[:html_content]
+      }
+      req.respond(html, 'Content-Type' => layout.mime_type)
+    end
+
+    # Returns a layout component based on the given name. The given name
+    # defaults to 'default' if nil.
+    #
+    # @param layout [String, nil] layout name
+    # @return [Papercraft::Template] layout component
+    def get_layout(layout)
+      layout ||= 'default'
+      path = File.join(@directory, "_layouts/#{layout}.rb")
+      raise "Layout not found #{path}" unless File.file?(path)
+      
+      import path
+    end
+  
+    # Parses the markdown file at the given path.
+    #
+    # @param path [String] file path
+    # @return [Array] an tuple containing properties<Hash>, contents<String>
+    def parse_markdown_file(path)
+      content = IO.read(path) || ''
+      atts = {}
+
+      # Parse date from file name
+      if (m = path.match(DATE_REGEXP))
+        atts[:date] ||= Date.parse(m[1])
+      end
+
+      if (m = content.match(FRONT_MATTER_REGEXP))
+        front_matter = m[1]
+        content = m.post_match
+        
+        yaml = YAML.safe_load(front_matter, **YAML_OPTS)
+        atts = atts.merge(yaml)
+      end
+        
+      [atts, content]
+    end
+
+    # Returns the supported path extensions used for searching for files based
+    # on pretty URLs.
+    #
+    # @return [Array] list of supported path extensions
+    def supported_path_extensions
+      [:html, :rb, :md]
     end
   end
 end

data/lib/impression/file_tree.rb

@@ -14,8 +14,8 @@ module Impression
     #
     # @param directory [String] static directory path
     # @return [void]
-    def initialize(directory:, **props)
-      super(**props)
+    def initialize(directory: nil, **props, &block)
+      super(**props, &block)
       @directory = directory
       @path_info_cache = {}
     end
@@ -25,6 +25,8 @@ module Impression
     # @param req [Qeweney::Request] request
     # @return [void]
     def call(req)
+      return super if @directory.nil?
+
       path_info = get_path_info(req.resource_relative_path)
       render_from_path_info(req, path_info)
     end

data/lib/impression/rack_app.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tipi'
+require_relative './resource'
+
+module Impression
+
+  # The `RackApp` class represents Rack apps as resources.
+  class RackApp < Resource
+    def initialize(app: nil, **props, &block)
+      raise "No Rack app given" unless app || block
+
+      # We pass nil as the block, otherwise the block will pass to
+      # Resource#initialize, which will cause #call to be overidden.
+      super(**props, &nil) 
+      @handler = Tipi::RackAdapter.run(app || block)
+    end
+
+    def call(req)
+      if @path != '/'
+        req.rewrite!(@path, '/')
+      end
+      @handler.(req)
+    end
+  end
+end

data/lib/impression/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Impression
-  VERSION = '0.11'
+  VERSION = '0.12'
 end

data/lib/impression.rb

@@ -3,12 +3,10 @@
 require 'polyphony'
 
 require_relative './impression/request_extensions'
-# require_relative './impression/file_watcher'
-
 require_relative './impression/resource'
 require_relative './impression/file_tree'
-require_relative './impression/jamstack'
 require_relative './impression/app'
+require_relative './impression/rack_app'
 
 # The Impression module contains convenience methods for creating resources.
 module Impression
@@ -26,17 +24,31 @@ module Impression
 
   # Creates a new `Impression::FileTree` instance with the given parameters.
   #
-  # @param **props [Hash] properties
+  # @param path [String] resource path (defaults to `"/"`)
+  # @param **props [Hash] other resource properties
+  # @param &block [Proc] optional block for overriding default request handler
   # @return [Impression::FileTree] new resource
-  def self.file_tree(path: '/', **props)
-    FileTree.new(path: path, **props)
+  def self.file_tree(path: '/', **props, &block)
+    FileTree.new(path: path, **props, &block)
+  end
+
+  # Creates a new `Impression::App` instance with the given parameters.
+  #
+  # @param path [String] resource path (defaults to `"/"`)
+  # @param **props [Hash] other resource properties
+  # @param &block [Proc] optional block for overriding default request handler
+  # @return [Impression::App] new resource
+  def self.app(path: '/', **props, &block)
+    App.new(path: path, **props, &block)
   end
 
-  # Creates a new `Impression::Jamstack` instance with the given parameters.
+  # Creates a new `Impression::RackApp` instance with the given parameters.
   #
-  # @param **props [Hash] properties
-  # @return [Impression::Jamstack] new resource
-  def self.jamstack(path: '/', **props)
-    Jamstack.new(path: path, **props)
+  # @param path [String] resource path (defaults to `"/"`)
+  # @param **props [Hash] other resource properties
+  # @param &block [Proc] Rack app proc (can also be passed using the `app:` parameter)
+  # @return [Impression::RackApp] new resource
+  def self.rack_app(path: '/', **props, &block)
+    RackApp.new(path: path, **props, &block)
   end
 end

data/test/{jamstack → app}/resources/recurse.rb

@@ -3,7 +3,7 @@
 export :resource
 
 def resource
-  Impression.jamstack(
+  Impression.app(
     directory: File.expand_path('..', __dir__)
   )
 end