syntropy 0.33.0 → 0.34.1

data/lib/syntropy/markdown.rb

@@ -3,39 +3,68 @@
 require 'yaml'
 
 module Syntropy
-  DATE_REGEXP = /(\d{4}-\d{2}-\d{2})/
-  FRONT_MATTER_REGEXP = /\A(---\s*\n.*?\n?)^((---|\.\.\.)\s*$\n?)/m
-  YAML_OPTS = {
-    permitted_classes: [Date],
-    symbolize_names: true
-  }
-
-  # Parses the markdown file at the given path.
-  #
-  # @param path [String] file path
-  # @return [Array] an tuple containing properties<Hash>, contents<String>
-  def self.parse_markdown_file(path, env)
-    content = IO.read(path) || ''
-    atts = {}
-
-    # Parse date from file name
-    m = path.match(DATE_REGEXP)
-    atts[:date] ||= Date.parse(m[1]) if m
-
-    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
+  # Markdown parsing.
+  module Markdown
+    FRONT_MATTER_REGEXP = /\A(---\s*\n.*?\n?)^((---|\.\.\.)\s*$\n?)/m
+    YAML_OPTS = {
+      permitted_classes: [Date],
+      symbolize_names: true
+    }.freeze
 
-    if env[:root_dir]
-      atts[:url] = path
-                   .gsub(/#{env[:root_dir]}/, '')
-                   .gsub(/\.md$/, '')
-    end
+    class << self
+      # Parses the markdown file at the given path.
+      #
+      # @param path [String] file path
+      # @return [Array] an tuple containing properties<Hash>, contents<String>
+      def parse(path, env)
+        content = IO.read(path) || ''
+        atts = {}
+
+        parse_date(path, atts)
+        content = parse_content(content, atts)
+        atts[:url] = path_to_url(path, env[:app_root]) if env[:app_root]
+
+        [atts, content]
+      end
+
+      private
 
-    [atts, content]
+      # Parses date information from the given path.
+      #
+      # @param path [String] file path
+      # @param atts [Hash] file attributes
+      # @return [void]
+      def parse_date(path, atts)
+        # Parse date from file name
+        if (m = path.match(/(\d{4}-\d{2}-\d{2})/))
+          atts[:date] ||= Date.parse(m[1])
+        end
+      end
+
+      # Parses the markdown content and front matter attributes from the given content.
+      #
+      # @param content [String] file content
+      # @param atts [Hash] file attributes
+      # @return [String] parsed markdown content
+      def parse_content(content, atts)
+        if (m = content.match(FRONT_MATTER_REGEXP))
+          front_matter = m[1]
+          content = m.post_match
+
+          yaml = YAML.safe_load(front_matter, **YAML_OPTS)
+          atts.merge!(yaml)
+        end
+        content
+      end
+
+      # Converts the markdown file path to URL
+      #
+      # @param path [String] file path
+      # @param app_root [String] app root directory
+      # @return [String] url
+      def path_to_url(path, app_root)
+        path.gsub(/#{app_root}/, '').gsub(/\.md$/, '')
+      end
+    end
   end
 end

data/lib/syntropy/mime_types.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Syntropy
-  # File extension to MIME type mapping
+  # The MimeTypes module maps file extensions to MIME types.
   module MimeTypes
     TYPES = {
       'html'  => 'text/html',
@@ -21,16 +21,20 @@ module Syntropy
 
     EXT_REGEXP = /\.?([^\.]+)$/.freeze
 
-    def self.[](ref)
-      case ref
+    # Returns the mime type for the given file extension.
+    #
+    # @param ext [String, Symbol] file extension
+    # @return [String, nil] MIME type
+    def self.[](ext)
+      case ext
       when Symbol
-        TYPES[ref.to_s]
+        TYPES[ext.to_s]
       when EXT_REGEXP
         TYPES[Regexp.last_match(1)]
       when ''
         nil
       else
-        raise "Invalid argument #{ref.inspect}"
+        raise "Invalid argument #{ext.inspect}"
       end
     end
   end

data/lib/syntropy/module_loader.rb

@@ -28,7 +28,7 @@ module Syntropy
     # @return [void]
     def initialize(env)
       @env = env
-      @root_dir = env[:root_dir]
+      @app_root = env[:app_root]
       @modules = {} # maps ref to module entry
       @fn_map = {} # maps filename to ref
     end
@@ -55,8 +55,8 @@ module Syntropy
     # @param dir [String] relative module directory
     # @return [Array<String>] list of modules
     def list(dir)
-      fns = Dir[File.join(@root_dir, dir, '*.rb')]
-      fns.map { it.match(/^#{@root_dir}\/(.+)\.rb$/)[1] }.sort
+      fns = Dir[File.join(@app_root, dir, '*.rb')]
+      fns.map { it.match(/^#{@app_root}\/(.+)\.rb$/)[1] }.sort
     end
 
     # Invalidates a module by its filename, normally following a change to the
@@ -89,10 +89,13 @@ module Syntropy
       entry[:reverse_deps].each { invalidate_ref(it) }
     end
 
+    # Invalidates a collection module.
+    #
+    # @return [void]
     def invalidate_collection_modules
       refs = []
       @modules.each do |ref, entry|
-        refs << ref if entry[:module].is_collection_module?
+        refs << ref if entry[:module].collection_module?
       end
       refs.each { invalidate_ref(it) }
     end
@@ -118,7 +121,7 @@ module Syntropy
     # @return [Hash] module entry
     def load_module(ref, raise_on_missing: true)
       ref = "/#{ref}" if ref !~ /^\//
-      fn = File.expand_path(File.join(@root_dir, "#{ref}.rb"))
+      fn = File.expand_path(File.join(@app_root, "#{ref}.rb"))
       if !File.file?(fn)
         raise Syntropy::Error, "File not found #{fn}" if raise_on_missing
 
@@ -142,6 +145,10 @@ module Syntropy
       }
     end
 
+    # Cleans up a module reference specifier, turning /index into /
+    #
+    # @param ref [String] input ref
+    # @return [String] clean ref
     def clean_ref(ref)
       return '/' if ref =~ /^index(\+)?$/
 
@@ -191,6 +198,17 @@ module Syntropy
       m.instance_eval(code, fn)
       env[:logger]&.info(message: "Loaded module at #{fn}")
       m
+    rescue SyntaxError => e
+      STDERR.puts("\n#{e.message}")
+
+      if (m = e.message.match(/^(.+)\: syntax/))
+        location = m[1]
+        e2 = SyntaxError.new("Syntax errors found in module #{env[:ref]}")
+        e2.set_backtrace([location] + e.backtrace)
+        raise e2
+      else
+        raise e
+      end
     end
 
     # Initializes a module with the given environment hash.
@@ -222,7 +240,7 @@ module Syntropy
     # #collection_module!
     #
     # @return [bool]
-    def is_collection_module?
+    def collection_module?
       @collection_module_p
     end
 
@@ -258,6 +276,10 @@ module Syntropy
       self
     end
 
+    # Normalize an import reference, turning a relative path into an absolute one.
+    #
+    # @param ref [String] input ref
+    # @return [String] normalized ref
     def normalize_import_ref(ref)
       base = @ref == '' ? '/' : @ref
       if ref =~ /^\//
@@ -274,7 +296,7 @@ module Syntropy
     # @return [Papercraft::Template] template
     def template(proc = nil, &block)
       proc ||= block
-      raise "No template block/proc given" if !proc
+      raise 'No template block/proc given' if !proc
 
       Papercraft::Template.new(proc)
     end
@@ -286,10 +308,10 @@ module Syntropy
     # @return [Papercraft::Template] template
     def template_xml(proc = nil, &block)
       proc ||= block
-      raise "No template block/proc given" if !proc
+      raise 'No template block/proc given' if !proc
 
       Papercraft::Template.new(proc, mode: :xml)
-    rescue => e
+    rescue StandardError => e
       p e
       p e.backtrace
       raise

data/lib/syntropy/papercraft_extensions.rb

@@ -4,12 +4,12 @@ require 'papercraft'
 
 Papercraft.extension(
   'auto_refresh!': ->(loc = '/.syntropy') {
-    if $syntropy_dev_mode
+    if Syntropy.dev_mode
       script(src: File.join(loc, 'auto_refresh/watch.js'), type: 'module')
     end
   },
   'debug_template!': ->(loc = '/.syntropy') {
-    if $syntropy_dev_mode
+    if Syntropy.dev_mode
       script(src: File.join(loc, 'debug/debug.js'), type: 'module')
     end
   }

data/lib/syntropy/request/mock_adapter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Syntropy
+  # Implements a mock adapter for testing
   class MockAdapter
     attr_reader :response_body, :response_headers, :calls
 
@@ -19,14 +20,13 @@ module Syntropy
     end
 
     def initialize(request_body)
-      case request_body
-      when Array
-        @request_body_chunks = request_body
-      when nil
-        @request_body_chunks = []
-      else
-        @request_body_chunks = [request_body]
-      end
+      @request_body_chunks =
+        case request_body
+        when Array then request_body
+        when nil   then []
+        else            [request_body]
+        end
+
       @calls = []
     end
 
@@ -47,6 +47,8 @@ module Syntropy
       response_headers[':status'] || HTTP::OK
     end
 
+    def respond_to_missing?(sym) = true
+
     def method_missing(sym, *args)
       calls << [sym, *args]
     end

data/lib/syntropy/request/request_info.rb

@@ -3,36 +3,61 @@
 require 'uri'
 
 module Syntropy
+  # Request information extension methods.
   module RequestInfoMethods
+    # Returns the request host.
+    #
+    # @return [String, nil]
     def host
       @headers['host'] || @headers[':authority']
     end
     alias_method :authority, :host
 
+    # Returns the connection header value.
+    #
+    # @return [String, nil]
     def connection
       @headers['connection']
     end
 
+    # Returns the upgrade protocol.
+    #
+    # @return [String, nil]
     def upgrade_protocol
       connection == 'upgrade' && @headers['upgrade']&.downcase
     end
 
+    # Returns the websocket version.
+    #
+    # @return [String, nil]
     def websocket_version
       headers['sec-websocket-version'].to_i
     end
 
+    # Returns the protocol.
+    #
+    # @return [String, nil]
     def protocol
       @protocol ||= @adapter.protocol
     end
 
+    # Returns the HTTP method in lower case.
+    #
+    # @return [String]
     def method
       @method ||= @headers[':method'].downcase
     end
 
+    # Returns the request scheme.
+    #
+    # @return [String, nil]
     def scheme
       @scheme ||= @headers[':scheme']
     end
 
+    # Returns the request content type.
+    #
+    # @return [String, nil]
     def content_type
       ct = @headers['content-type']
       return nil if !ct
@@ -59,22 +84,37 @@ module Syntropy
       self
     end
 
+    # Returns the parsed request URI.
+    #
+    # @return [URI::Generic]
     def uri
       @uri ||= URI.parse(@headers[':path'] || '')
     end
 
+    # Returns the parsed full request URI.
+    #
+    # @return [URI::HTTP]
     def full_uri
       @full_uri = "#{scheme}://#{host}#{uri}"
     end
 
+    # Returns the request path.
+    #
+    # @return [String]
     def path
       @path ||= uri.path
     end
 
+    # Returns the request (unparsed) query string.
+    #
+    # @return [String, nil]
     def query_string
       @query_string ||= uri.query
     end
 
+    # Returns the parsed query hash.
+    #
+    # @return [Hash]
     def query
       return @query if @query
 
@@ -83,6 +123,10 @@ module Syntropy
 
     QUERY_KV_REGEXP = /([^=]+)(?:=(.*))?/
 
+    # Converts a query string into a query hash
+    #
+    # @param query [String]
+    # @return [Hash]
     def parse_query(query)
       query.split('&').each_with_object({}) do |kv, h|
         k, v = kv.match(QUERY_KV_REGEXP)[1..2]
@@ -90,10 +134,16 @@ module Syntropy
       end
     end
 
+    # Returns the request ID.
+    #
+    # @return [String, nil]
     def request_id
       @headers['x-request-id']
     end
 
+    # Returns the forwarded for value.
+    #
+    # @return [String, nil]
     def forwarded_for
       @headers['x-forwarded-for']
     end
@@ -107,6 +157,9 @@ module Syntropy
       encoding.split(',').map { |i| i.strip }
     end
 
+    # Returns the parsed cookie values.
+    #
+    # @return [String, nil]
     def cookies
       @cookies ||= parse_cookies(headers['cookie'])
     end
@@ -114,6 +167,10 @@ module Syntropy
     COOKIE_RE = /^([^=]+)=(.*)$/.freeze
     SEMICOLON = ';'
 
+    # Parses the cookie string.
+    #
+    # @param cookies [String]
+    # @return [Hash]
     def parse_cookies(cookies)
       return {} unless cookies
 
@@ -139,6 +196,9 @@ module Syntropy
       raise Syntropy::Error.new('Invalid form data', HTTP::BAD_REQUEST)
     end
 
+    # Returns true if the user-agent is a browser.
+    #
+    # @return [bool]
     def browser?
       user_agent = headers['user-agent']
       user_agent && user_agent =~ /^Mozilla\//
@@ -156,6 +216,9 @@ module Syntropy
       @accept_parts.include?(mime_type)
     end
 
+    # Returns the bearer token.
+    #
+    # @return [String, nil]
     def auth_bearer_token
       auth = headers['authorization']
       if auth && (m = auth.match(/Bearer\s+([^\w]+)/))
@@ -167,12 +230,22 @@ module Syntropy
 
     private
 
+    # Parses an accept string into an array of accepted MIME types.
+    #
+    # @param accept [string]
+    # @return [Array<String>]
     def parse_accept_parts(accept)
       accept.split(',').map { it.match(/^\s*([^\s;]+)/)[1] }
     end
   end
 
+  # Request info class methods
   module RequestInfoClassMethods
+    # Parses form data into a hash
+    #
+    # @param body [String]
+    # @param headers [Hash]
+    # @return [Hash]
     def parse_form_data(body, headers)
       case (content_type = headers['content-type'])
       when /^multipart\/form\-data; boundary=([^\s]+)/
@@ -185,6 +258,11 @@ module Syntropy
       end
     end
 
+    # Parses a multipart form body.
+    #
+    # @param body [String]
+    # @param boundary [String]
+    # @return [Hash]
     def parse_multipart_form_data(body, boundary)
       parts = body.split(boundary)
       raise BadRequestError, 'Invalid form data' if parts.size < 2
@@ -197,6 +275,11 @@ module Syntropy
       end
     end
 
+    # Parses a multipart form data part.
+    #
+    # @param body [String]
+    # @param hash [Hash] output hash
+    # @return [void]
     def parse_multipart_form_data_part(part, hash)
       body, headers = parse_multipart_form_data_part_headers(part)
       disposition = headers['content-disposition'] || ''
@@ -211,6 +294,10 @@ module Syntropy
       end
     end
 
+    # Parses a multipart form data part headers.
+    #
+    # @param part [String]
+    # @return [Hash]
     def parse_multipart_form_data_part_headers(part)
       headers = {}
       while true
@@ -234,6 +321,10 @@ module Syntropy
     MAX_PARAMETER_NAME_SIZE = 256
     MAX_PARAMETER_VALUE_SIZE = 2**20 # 1MB
 
+    # Parses a URL-encoded form.
+    #
+    # @param body [String]
+    # @return [Hash]
     def parse_urlencoded_form_data(body)
       return {} unless body
 

data/lib/syntropy/request/response.rb

@@ -7,18 +7,7 @@ require_relative '../http/status'
 require_relative '../mime_types'
 
 module Syntropy
-  module StaticFileCaching
-    class << self
-      def file_stat_to_etag(stat)
-        "#{stat.mtime.to_i.to_s(36)}#{stat.size.to_s(36)}"
-      end
-
-      def file_stat_to_last_modified(stat)
-        stat.mtime.httpdate
-      end
-    end
-  end
-
+  # Response methods.
   module ResponseMethods
     WEBSOCKET_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
 

data/lib/syntropy/request/validation.rb

@@ -3,6 +3,7 @@
 require 'uri'
 
 module Syntropy
+  # Request validation methods.
   module RequestValidationMethods
 
     # Checks the request's HTTP method against the given accepted values. If not