syntropy 0.33.0 → 0.34.0

data/lib/syntropy/app.rb

@@ -11,35 +11,52 @@ require 'syntropy/routing_tree'
 require 'syntropy/mime_types'
 
 module Syntropy
+  # The App implements a Syntropy application. It is responsible for handling
+  # incoming HTTP requests, routing them to the correct handler, and maintaining
+  # application state.
   class App
     class << self
+      # Creates an app instance based on the given environment hash.
+      #
+      # @param env [Hash] environment hash
+      # @return [Syntropy::App]
       def load(env)
         site_file_app(env) || default_app(env)
       end
 
       private
 
-      # for apps with a _site.rb file
+      # Creates a multi-hostname app if a _site.rb file is detected.
+      #
+      # @param env [Hash] environment hash
+      # @return [Syntropy::App]
       def site_file_app(env)
-        fn = File.join(env[:root_dir], '_site.rb')
+        fn = File.join(env[:app_root], '_site.rb')
         return nil if !File.file?(fn)
 
         loader = Syntropy::ModuleLoader.new(env)
         loader.load('_site')
       end
 
-      # default app
+      # Creates a normal Syntropy app.
+      #
+      # @param env [Hash] environment hash
+      # @return [Syntropy::App]
       def default_app(env)
         new(**env)
       end
     end
 
-    attr_reader :module_loader, :routing_tree, :root_dir, :mount_path, :env
+    attr_reader :module_loader, :routing_tree, :app_root, :mount_path, :env
     attr_accessor :raise_on_internal_server_error
 
+    # Initializes the app instance.
+    #
+    # @param env [Hash] environment hash
+    # @return [void]
     def initialize(**env)
       @machine = env[:machine]
-      @root_dir = File.expand_path(env[:root_dir])
+      @app_root = File.expand_path(env[:app_root])
       @mount_path = env[:mount_path]
       @env = env
       @logger = env[:logger]
@@ -77,12 +94,14 @@ module Syntropy
       proc = route[:proc] ||= compute_route_proc(route)
       proc.(req)
     rescue ScriptError, StandardError => e
-      @logger&.error(
-        message: "Error while serving request: #{e.message}",
-        method: req.method,
-        path: path,
-        error: e
-      ) if Error.log_error?(e)
+      if Error.log_error?(e)
+        @logger&.error(
+          message: "Error while serving request: #{e.message}",
+          method: req.method,
+          path: path,
+          error: e
+        )
+      end
       error_handler = get_error_handler(route)
       error_handler.(req, e)
     end
@@ -102,21 +121,6 @@ module Syntropy
       route
     end
 
-    def setup_db(db_path:, schema_root: '_schema')
-      @env[:db_path] = db_path
-      @env[:schema_root] = schema_root
-
-      class << self
-        def connection_pool
-          @connection_pool ||= DB::ConnectionPool.new(@machine, @env[:db_path], 4)
-        end
-
-        def schema
-          @schema ||= DB::Schema.new(module_loader: @module_loader, schema_root: @env[:schema_root])
-        end
-      end
-    end
-
     private
 
     # Handles a not found error, taking into account hooks up the tree from the
@@ -134,7 +138,10 @@ module Syntropy
       end
     end
 
-    # Returns the find
+    # Finds the first up-tree route entry for the given path.
+    #
+    # @param path [String] path
+    # @return [Hash] route entry
     def find_first_uptree_route(path)
       route = @router_proc.(path, {})
       if !route && path != '/'
@@ -149,7 +156,7 @@ module Syntropy
     # @return [void]
     def setup_routing_tree
       @routing_tree = Syntropy::RoutingTree.new(
-        root_dir: @root_dir, mount_path: @mount_path, **@env
+        app_root: @app_root, mount_path: @mount_path, **@env
       )
       mount_builtin_applet if @env[:builtin_applet_path]
       @router_proc = @routing_tree.router_proc
@@ -164,6 +171,10 @@ module Syntropy
       @routing_tree.mount_applet(path, @builtin_applet)
     end
 
+    # Sets and returns the not found proc for the given route entry.
+    #
+    # @param route [Hash] route entry
+    # @return [Proc] not found proc
     def route_not_found_proc(route)
       route[:not_found_proc] ||= compose_up_tree_hooks(route, ->(req) {
         raise Syntropy::Error.not_found('Not found')
@@ -233,7 +244,7 @@ module Syntropy
       req.validate_cache(**cache_opts) {
         req.respond(target[:content], 'Content-Type' => target[:mime_type])
       }
-    rescue => e
+    rescue StandardError => e
       p e
       p e.backtrace
       exit!
@@ -299,7 +310,7 @@ module Syntropy
     # @param route [Hash] route entry
     # @return [String] rendered HTML
     def render_markdown(route)
-      atts, md = Syntropy.parse_markdown_file(route[:target][:fn], @env)
+      atts, md = Syntropy::Markdown.parse(route[:target][:fn], @env)
 
       layout = compute_markdown_layout(route, atts)
       Papercraft.html(layout, md:, **atts)
@@ -337,7 +348,7 @@ module Syntropy
           }
           body {
             markdown md
-            auto_refresh! if @env[:dev_mode]
+            auto_refresh! if Syntropy.dev_mode
           }
         }
       }
@@ -482,6 +493,9 @@ module Syntropy
       req.respond(msg, ':status' => status) rescue nil
     }
 
+    # Returns the default error handler for the app.
+    #
+    # @return [Proc] error handler
     def default_error_handler
       @default_error_handler ||= begin
         if @builtin_applet
@@ -507,7 +521,7 @@ module Syntropy
         @machine.sleep 0.1
         route_count = @routing_tree.static_map.size + @routing_tree.dynamic_map.size
         @logger&.info(
-          message: "Serving from #{@root_dir} (#{route_count} routes found)"
+          message: "Serving from #{@app_root} (#{route_count} routes found)"
         )
 
         file_watcher_loop if @env[:watch_files]
@@ -519,18 +533,12 @@ module Syntropy
     #
     # @return [void]
     def file_watcher_loop
-      @machine.file_watch(@root_dir, UM::IN_CREATE | UM::IN_DELETE | UM::IN_CLOSE_WRITE) { |e|
+      @machine.file_watch(@app_root, UM::IN_CREATE | UM::IN_DELETE | UM::IN_CLOSE_WRITE) { |e|
         fn = e[:fn]
         @logger&.info(message: 'File change detected', fn: fn)
         @module_loader.invalidate_fn(fn)
         debounce_file_change
       }
-
-      # Syntropy.file_watch(@machine, @root_dir, period: period) do |event, fn|
-      #   @logger&.info(message: 'File change detected', fn: fn)
-      #   @module_loader.invalidate_fn(fn)
-      #   debounce_file_change
-      # end
     rescue Exception => e
       p e
       p e.backtrace
@@ -564,7 +572,7 @@ module Syntropy
 
       watcher_mod = watcher_route[:proc]
       watcher_mod.signal!
-    rescue => e
+    rescue StandardError => e
       @logger&.error(
         message: 'Unexpected error while signalling auto refresh watcher',
         error: e

data/lib/syntropy/applets/builtin/auto_refresh/watch.sse.rb

@@ -36,7 +36,7 @@ rescue Timeout::Error
   req.send_chunk("retry: 0\n\n", done: true) rescue nil
 rescue SystemCallError
   # ignore
-rescue => e
+rescue StandardError => e
   @logger&.error(
     message: 'Unexpected error encountered while serving auto refresh watcher',
     error: e

data/lib/syntropy/db/schema.rb

@@ -53,7 +53,7 @@ module Syntropy
         connection_pool.with_db do |db|
           current_version = get_schema_version(db)
           migrations_keys = @migrations.keys.sort
-          migrations_keys.select { it > current_version } if current_version
+          migrations_keys.select! { it > current_version } if current_version
 
           migrations_keys.each do |key|
             db.transaction do

data/lib/syntropy/db/store.rb

@@ -2,6 +2,8 @@
 
 module Syntropy
   module DB
+    # The Store class represents a data store based on one or more tables, and
+    # connected to a database connection pool.
     class Store
       def initialize(connection_pool)
         @connection_pool = connection_pool

data/lib/syntropy/errors.rb

@@ -43,8 +43,6 @@ module Syntropy
     # @return [Syntropy::Error]
     def self.teapot(msg = 'I\'m a teapot') = new(msg, HTTP::TEAPOT)
 
-    attr_reader :http_status
-
     # Initializes a Syntropy error with the given HTTP status and message.
     #
     # @param http_status [Integer, String] HTTP status
@@ -70,21 +68,27 @@ module Syntropy
     end
   end
 
+  # ProtocolError is raised when an HTTP protocol error is encountered.
   class ProtocolError < Error
     def http_status
       HTTP::BAD_REQUEST
     end
   end
 
+  # UnsupportedHTTPVersionError is raised when an invalid protocol specified in
+  # a request's request line.
   class UnsupportedHTTPVersionError < ProtocolError
     def http_status
       HTTP::HTTP_VERSION_NOT_SUPPORTED
     end
   end
 
+  # BadRequestError is raised when a request contains invalid information.
   class BadRequestError < Error
   end
 
+  # InvalidRequestContentTypeError is raised when a request has an invalid
+  # content type.
   class InvalidRequestContentTypeError < Error
     def http_status
       HTTP::UNSUPPORTED_MEDIA_TYPE

data/lib/syntropy/http/client.rb

@@ -5,6 +5,7 @@ require 'uri'
 
 module Syntropy
   module HTTP
+    # HTTP Client class.
     class Client
       def initialize(machine)
         @machine = machine

data/lib/syntropy/http/server_connection.rb

@@ -156,7 +156,6 @@ module Syntropy
 
         formatted_headers = format_headers(headers, body)
         @response_headers = headers
-        request&.tx_incr(formatted_headers.bytesize + (body ? body.bytesize : 0))
         if body
           chunk_prelude = "#{body.bytesize.to_s(16)}\r\n"
           @machine.sendv(@fd, formatted_headers, chunk_prelude, body, CHUNKED_ENCODING_POSTLUDE)
@@ -175,7 +174,6 @@ module Syntropy
       # @return [void]
       def send_headers(request, headers, empty_response: false)
         formatted_headers = format_headers(headers, !empty_response)
-        request.tx_incr(formatted_headers.bytesize)
         @machine.send(@fd, formatted_headers, formatted_headers.bytesize, SEND_FLAGS)
         @response_headers = headers
       end
@@ -193,7 +191,6 @@ module Syntropy
         data << EMPTY_CHUNK if done
         return if data.empty?
 
-        request.tx_incr(data.bytesize)
         @machine.send(@fd, data, data.bytesize, SEND_FLAGS)
         return if @done || !done
 
@@ -205,7 +202,6 @@ module Syntropy
       # default headers are sent using #send_headers.
       # @return [void]
       def finish(request)
-        request.tx_incr(EMPTY_CHUNK_LEN)
         @machine.send(@fd, EMPTY_CHUNK, EMPTY_CHUNK_LEN, SEND_FLAGS)
         return if @done
 

data/lib/syntropy/json_api.rb

@@ -4,11 +4,20 @@ require 'syntropy/errors'
 require 'json'
 
 module Syntropy
+  # JSONAPI is a controller that implements a JSON API.
   class JSONAPI
+    # Initializes the controller.
+    #
+    # @param env [Hash] app environment
+    # @return [void]
     def initialize(env)
       @env = env
     end
 
+    # Processes the given request.
+    #
+    # @param req [Syntropy::Request]
+    # @return [void]
     def call(req)
       response, status = __invoke__(req)
       req.respond(
@@ -20,6 +29,9 @@ module Syntropy
 
     private
 
+    # Processes the request by invoking the corresponding object method.
+    #
+    # @param req [Syntropy::Request]
     def __invoke__(req)
       q = req.validate_param(:q, String).to_sym
       response = case req.method
@@ -31,7 +43,7 @@ module Syntropy
         raise Syntropy::Error.method_not_allowed
       end
       [{ status: 'OK', response: response }, HTTP::OK]
-    rescue => e
+    rescue StandardError => e
       if !e.is_a?(Syntropy::Error)
         p e
         p e.backtrace
@@ -39,6 +51,11 @@ module Syntropy
       __error_response__(e)
     end
 
+    # Processes a GET request.
+    #
+    # @param sym [Symbol] object method
+    # @param req [Syntropy::Request] request
+    # @return [any] method call return value
     def __invoke_get__(sym,  req)
       return send(sym, req) if respond_to?(sym)
 
@@ -46,6 +63,11 @@ module Syntropy
       raise err
     end
 
+    # Processes a POST request.
+    #
+    # @param sym [Symbol] object method
+    # @param req [Syntropy::Request] request
+    # @return [any] method call return value
     def __invoke_post__(sym, req)
       sym_post = :"#{sym}!"
       return send(sym_post, req) if respond_to?(sym_post)
@@ -54,6 +76,10 @@ module Syntropy
       raise err
     end
 
+    # Generates an error response in case of exception.
+    #
+    # @param err [Exception] raised Exception
+    # @return [Hash] error response
     def __error_response__(err)
       http_status = err.respond_to?(:http_status) ? err.http_status : HTTP::INTERNAL_SERVER_ERROR
       error_name = err.class.name.split('::').last

data/lib/syntropy/logger.rb

@@ -3,29 +3,51 @@
 require 'json'
 
 module Syntropy
+  # The Logger class implements a logger with support for structured logging.
   class Logger
+    # Initializes the logger.
+    #
+    # @param machine [UringMachine] machine instance
+    # @param fd [Integer] file descriptor for writing log messages
+    # @param opts [Hash] logger options
+    # @return [void]
     def initialize(machine, fd = $stdout.fileno, **opts)
       @machine = machine
       @fd = fd
       @opts = opts
     end
 
+    # Logs an INFO entry.
+    #
+    # @param o [Hash] log entry
+    # @return [void]
     def info(o)
       call(:INFO, o)
     end
 
+    # Logs an WARN entry.
+    #
+    # @param o [Hash] log entry
+    # @return [void]
     def warn(o)
       call(:WARN, o)
     end
 
+    # Logs an ERROR entry.
+    #
+    # @param o [Hash] log entry
+    # @return [void]
     def error(o)
       call(:ERROR, o)
     end
 
     private
 
-    # @param level <Symbol> log level
-    # @param o <Hash> hash
+    # Writes a log entry.
+    #
+    # @param level [Symbol] log level
+    # @param o [Hash] entry
+    # @return [void]
     def call(level, o)
       emit(make_entry(level, o))
     rescue StandardError => e
@@ -35,10 +57,20 @@ module Syntropy
       exit
     end
 
+    # Emits an entry to the associated output.
+    #
+    # @param entry [Hash] log entry
+    # @return [void]
     def emit(entry)
       @machine.write_async(@fd, "#{entry.to_json}\n")
     end
 
+    # Transforms raw entry into a log entry. Additional information is added
+    # dependending on the kind of entry.
+    #
+    # @param level [Symbol] log level
+    # @param o [Hash] raw entry
+    # @return [Hash] log entry
     def make_entry(level, o)
       if o[:request]
         make_request_entry(level, o)
@@ -49,52 +81,74 @@ module Syntropy
       end
     end
 
+    # Makes an error log entry.
+    #
+    # @param level [Symbol] log level
+    # @param o [Hash] input entry
+    # @return [Hash] output entry
     def make_error_entry(level, o)
       err = o[:error]
+      t = Time.now
       {
-        level: level.to_s,
-        ts: (t = Time.now; t.to_i),
-        ts_s: t.iso8601
-      }
-      .merge(o)
-      .merge(
+        level:  level.to_s,
+        ts:     t.to_i,
+        ts_s:   t.iso8601
+      }.merge(o).merge(
         error: "#{err.class}: #{err.message}",
         backtrace: err.backtrace
       )
     end
 
+    # Makes a request log entry.
+    #
+    # @param level [Symbol] log level
+    # @param o [Hash] input entry
+    # @return [Hash] output entry
     def make_request_entry(level, o)
       request = o[:request]
       request_headers = request.headers
       response_headers = o[:response_headers]
       elapsed = monotonic_clock - request.start_stamp
+      t = Time.now
       {
-        level: level.to_s,
-        ts: (t = Time.now; t.to_i),
-        ts_s: t.iso8601,
-        message: o[:message] || 'HTTP request done',
-        client_ip: request.forwarded_for || '?',
-        http_method: request_headers[':method'].upcase,
-        user_agent: request_headers['user-agent'],
-        uri: full_uri(request_headers),
-        status: response_headers[':status'] || '200',
-        elapsed: elapsed
+        level:        level.to_s,
+        ts:           t.to_i,
+        ts_s:         t.iso8601,
+        message:      o[:message] || 'HTTP request done',
+        client_ip:    request.forwarded_for || '?',
+        http_method:  request_headers[':method'].upcase,
+        user_agent:   request_headers['user-agent'],
+        uri:          full_uri(request_headers),
+        status:       response_headers[':status'] || '200',
+        elapsed:      elapsed
       }
     end
 
-    def monotonic_clock
-      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
-    end
-
+    # Makes a request log entry.
+    #
+    # @param level [Symbol] log level
+    # @param o [Hash] input entry
+    # @return [Hash] output entry
     def make_hash_entry(level, hash)
+      t = Time.now
       {
-        level: level.to_s,
-        ts: (t = Time.now; t.to_i),
-        ts_s: t.iso8601
-      }
-      .merge(hash)
+        level:  level.to_s,
+        ts:     t.to_i,
+        ts_s:   t.iso8601
+      }.merge(hash)
+    end
+
+    # Returns the monotonic clock.
+    #
+    # @return [Float]
+    def monotonic_clock
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
     end
 
+    # Returns the full request URI for the given request headers.
+    #
+    # @param headers [Hash] request headers
+    # @return [String] request URI
     def full_uri(headers)
       format(
         '%<scheme>s://%<host>s%<path>s',

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