syntropy 0.32.0 → 0.34.0

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

@@ -23,12 +23,11 @@ module Syntropy
 
         @done = nil
         @response_headers = nil
+        @response_cookies = nil
       end
 
       def run
         loop do
-          @done = nil
-          @response_headers = nil
           persist = serve_request
           break if !persist
         end
@@ -47,6 +46,9 @@ module Syntropy
       # object and handing it off to the app handler. Returns true if the
       # connection should be persisted.
       def serve_request
+        @done = nil
+        @response_headers = nil
+        @response_cookies = nil
         @closed = nil
         headers = @io.http_read_request_headers
         return false if !headers
@@ -130,13 +132,10 @@ module Syntropy
         @response_headers ? @response_headers.merge!(headers) : @response_headers = headers
       end
 
-      def set_cookie(*cookies)
-        existing_cookies = @response_headers && @response_headers['Set-Cookie']
-        if existing_cookies
-          @response_headers['Set-Cookie'] = existing_cookies + cookies
-        else
-          set_response_headers('Set-Cookie' => cookies)
-        end
+      DELETE_COOKIE = "; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; Max-Age=0; HttpOnly"
+
+      def set_cookie(key, value)
+        (@response_cookies ||= {})[key] = value || DELETE_COOKIE
       end
 
       SEND_FLAGS = UM::MSG_NOSIGNAL | UM::MSG_WAITALL
@@ -152,11 +151,11 @@ module Syntropy
       # @param body [String] response body
       # @param headers
       def respond(request, body, headers)
+        add_set_cookie_headers if @response_cookies
         headers = @response_headers.merge(headers) if @response_headers
 
         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
 
@@ -315,6 +311,12 @@ module Syntropy
           lines << "#{key}: #{value}\r\n"
         end
       end
+
+      def add_set_cookie_headers
+        @response_headers ||= {}
+        sc = (@response_headers['Set-Cookie'] ||= [])
+        @response_cookies.each { |k, v| sc << "#{k}=#{v}" }
+      end
     end
   end
 end

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

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
@@ -39,11 +39,12 @@ module Syntropy
     # @return [any] export value
     def load(ref, raise_on_missing: true)
       ref = "/#{ref}" if ref !~ /^\//
+      if !(entry = @modules[ref])
+        entry = load_module(ref, raise_on_missing:)
+        return if !entry
 
-      entry = load_module(ref, raise_on_missing:)
-      return if !entry
-
-      @modules[ref] ||= entry
+        @modules[ref] = entry
+      end
       entry[:export_value]
     end
 
@@ -54,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
@@ -88,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
@@ -117,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
 
@@ -141,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(\+)?$/
 
@@ -221,7 +229,7 @@ module Syntropy
     # #collection_module!
     #
     # @return [bool]
-    def is_collection_module?
+    def collection_module?
       @collection_module_p
     end
 
@@ -257,6 +265,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 =~ /^\//
@@ -273,7 +285,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
@@ -285,10 +297,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
   }