syntropy 0.39.0 → 0.41.0

data/lib/syntropy/markdown.rb

@@ -12,6 +12,7 @@ module Syntropy
       symbolize_names: true
     }.freeze
 
+    # Implements a Markdown file controller.
     class Controller
       def initialize(env, atts, md)
         @env = env
@@ -20,6 +21,9 @@ module Syntropy
         @module_loader = env[:module_loader]
       end
 
+      # Returns the controller proc.
+      #
+      # @return [Proc] controller proc
       def to_proc
         ->(req) {
           case req.method
@@ -37,6 +41,10 @@ module Syntropy
 
       private
 
+      # Process any Papercraft embeds in the markdown file by rendering them
+      # into the markdown code.
+      #
+      # @return [String] Markdown with rendered embeds
       def process_md_embeds
         return @md if @embedded_templates&.empty?
 
@@ -48,23 +56,40 @@ module Syntropy
         }
       end
 
-      def prepare_snippet_template(snippet, location = nil)
+      # Prepares a snippet template by writing it to a temporary file and
+      # instance_eval'ing the code, returning a Papercraft template.
+      #
+      # @param snippet [String] Papercraft snippet
+      # @param _location [String] currently not used
+      # @return [Proc] Papercraft template
+      def prepare_snippet_template(snippet, _location = nil)
         fn = "/tmp/snippet-#{SecureRandom.hex(8)}.rb"
         src = "->() do\n#{snippet}\nend"
         IO.write(fn, src)
         instance_eval src, fn
       end
 
+      # Renders the given markdown to HTML.
+      #
+      # @param md [String] markdown
+      # @return [String] HTML
       def render(md)
         @template ||= make_template
         Papercraft.html(@template, md: md, **@atts)
       end
 
+      # Makes a Markdown rendering template based on the corresponding layout.
+      #
+      # @return [Proc] Papercraft template
       def make_template
         layout = make_layout
         Papercraft.apply(layout) { |md:, **| markdown(md) }
       end
 
+      # Makes a layout template by loading the layout module. If no layout
+      # module was specified, returns the default layout.
+      #
+      # @return [Proc] Layout template
       def make_layout
         return default_layout if !@atts[:layout]
         raise Error, 'Missing module loader' if !@module_loader
@@ -72,6 +97,9 @@ module Syntropy
         @module_loader.load("_layout/#{@atts[:layout]}")
       end
 
+      # Creates a default layout template.
+      #
+      # @return [Proc] Default layout template
       def default_layout
         ->(**atts) {
           html5 {
@@ -101,26 +129,26 @@ module Syntropy
         parse_md(atts, md)
       end
 
+      # Parses the markdown content, returning the attributes and cleaned up
+      # markdown.
+      #
+      # @param atts [Hash] attributes hash
+      # @param md [String] markdown file
+      # @return [Array<atts, md>] Array containing attributes and clean markdown
       def parse_md(atts, md)
-        html = parse_content(atts, md)
-        [atts, html]
+        md = parse_content(atts, md)
+        [atts, md]
       end
 
+      # Creates a Markdown file contoroller for the given environment,
+      # attributes and markdown.
+      #
+      # @param env [Hash]  app environment
+      # @param atts [Hash] markdown file attributes
+      # @param md [String] markdown
+      # @return [Markdown::Controller] controller instance
       def make_controller(env, atts, md)
         Controller.new(env, atts, md).to_proc
-        # layout = setup_layout_template(env, atts)
-        
-        # ->(req) {
-        #   case req.method
-        #   when 'head'
-        #     req.respond_html(nil)
-        #   when 'get'
-        #     html = render_md(env, atts, md)
-        #     req.respond_html(html)
-        #   else
-        #     req.respond(nil, ':status' => HTTP::METHOD_NOT_ALLOWED)
-        #   end
-        # }
       end
 
       private
@@ -165,10 +193,6 @@ module Syntropy
           path.gsub(/#{app_root}/, '').gsub(/\.md$/, '')
         end
       end
-
-      def render_md(env, atts, md)
-        
-      end
     end
   end
 end

data/lib/syntropy/module_loader.rb

@@ -44,11 +44,11 @@ module Syntropy
     #
     # @param ref [String] module reference
     # @return [any] export value
-    def load(ref, raise_on_missing: true)
+    def load(ref, raise_on_missing_export: true)
       lock do
         ref = "/#{ref}" if ref !~ /^\//
         if !(entry = @modules[ref])
-          entry = load_module(ref, raise_on_missing:)
+          entry = load_module(ref, raise_on_missing_export:)
           return if !entry
 
           @modules[ref] = entry
@@ -86,6 +86,8 @@ module Syntropy
     private
 
     # Synchronizes access to the module loader state
+    #
+    # @return [any] block return value
     def lock
       return yield if @lock_holder == Fiber.current
 
@@ -142,20 +144,25 @@ module Syntropy
     #
     # @param ref [String] module reference
     # @return [Hash] module entry
-    def load_module(ref, raise_on_missing: true)
+    def load_module(ref, raise_on_missing_export: true)
       ref = "/#{ref}" if ref !~ /^\//
       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
+        raise Syntropy::Error, "File not found #{fn}" if raise_on_missing_export
 
         return
       end
 
       raise Syntropy::Error, "Circular dependency detected" if @loading.include?(ref)
-      do_load_module(ref, fn, raise_on_missing:)
+      do_load_module(ref, fn, raise_on_missing_export:)
     end
 
-    def do_load_module(ref, fn, raise_on_missing:)
+    # Loads a module.
+    #
+    # @param ref [String] module reference
+    # @param fn [String] module filename
+    # @param raise_on_missing_export [bool] whether to raise on missing export
+    def do_load_module(ref, fn, raise_on_missing_export:)
       @loading << ref
       @fn_map[fn] = ref
       code = read_file(fn)
@@ -163,7 +170,7 @@ module Syntropy
       mod = Syntropy::ModuleContext.new(env, code, fn, @extensions)
       add_dependencies(ref, mod.__dependencies__)
       export_value = transform_module_export_value(
-        mod.__export_value__, fn, raise_on_missing:
+        mod, fn, raise_on_missing_export:
       )
       @env[:logger]&.info(message: "Loaded module at #{fn}")
 
@@ -180,6 +187,10 @@ module Syntropy
       @loading.delete(ref)
     end
 
+    # Returns a file's content.
+    #
+    # @param fn [String] filename
+    # @return [String] file content
     def read_file(fn)
       @machine.open(fn, UM::O_RDONLY) { |fd|
         buf = +''
@@ -199,22 +210,24 @@ module Syntropy
       (clean == '') ? '/' : clean
     end
 
-    # Transforms the given export value. If the value is nil, an exception is
-    # raised.
+    # Transforms the given module's export value. If the value is nil, an
+    # exception is raised.
     #
-    # @param export_value [any] module's export value
+    # @param mod [Syntropy::ModuleContext] module context
     # @return [any] transformed value
-    def transform_module_export_value(export_value, fn, raise_on_missing:)
-      case export_value
+    def transform_module_export_value(mod, fn, raise_on_missing_export:)
+      case (value = mod.__export_value__)
       when nil
-        raise Syntropy::Error, "No export found in #{fn}" if raise_on_missing
+        mod
       when String
-        ->(req) { req.respond(export_value) }
+        ->(req) { req.respond(value) }
       else
-        export_value
+        value
       end
     end
 
+    # Handles a syntax error encountered while loading a module by generating a
+    # new exception with a backtrace including the syntax error location.
     def handle_syntax_error(fn, e)
       $stderr.puts("\n#{e.message}") if !Syntropy.test_mode
       m = e.message.match(/^(.+): syntax/)
@@ -249,7 +262,7 @@ module Syntropy
     # @param env [Hash] environment hash
     # @param code [String] module source code
     # @param fn [String] module filename
-    # @param extensions [Array<Module>, Module] 
+    # @param extensions [Array<Module>, Module]
     # @return [void]
     def initialize(env, code, fn, extensions)
       @env = env

data/lib/syntropy/request/request_info.rb

@@ -234,7 +234,7 @@ module Syntropy
     # @return [String]
     def rel(rel_path)
       File.expand_path(File.join(path, rel_path))
-    end 
+    end
 
     private
 

data/lib/syntropy/request/response.rb

@@ -11,6 +11,10 @@ module Syntropy
   module ResponseMethods
     WEBSOCKET_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
 
+    # Upgrades a request to  the WebSocket protocol.
+    #
+    # @param custom_headers [Hash, nil] additional response headers
+    # @return [void]
     def upgrade_to_websocket(custom_headers = nil)
       key = "#{headers['sec-websocket-key']}#{WEBSOCKET_GUID}"
       upgrade_headers = {
@@ -22,21 +26,42 @@ module Syntropy
       adapter.websocket_connection(self)
     end
 
+    # Responds with a redirect to the given URL. If a relative path is provided
+    # as the URL, the absolute URL path will be calculated relative to the
+    # current request's path.
+    #
+    # @param url [String] redirect URL
+    # @param status [Integer] HTTP status code
+    # @return [void]
     def redirect(url, status = HTTP::FOUND)
       url = File.expand_path(File.join(path, url)) if url =~ /^\./
       respond(nil, ':status' => status, 'Location' => url)
     end
 
+    # Redirects to the same URL, except with HTTPS.
+    #
+    # @param status [Integer] HTTP status code
+    # @return [void]
     def redirect_to_https(status = HTTP::MOVED_PERMANENTLY)
       secure_uri = "https://#{host}#{uri}"
       redirect(secure_uri, status)
     end
 
+    # Redirect to the same path and query, on a different host.
+    #
+    # @param new_host [String] new host name
+    # @param status [Integer] HTTP status code
+    # @return [void]
     def redirect_to_host(new_host, status = HTTP::FOUND)
       secure_uri = "//#{new_host}#{uri}"
       redirect(secure_uri, status)
     end
 
+    # Serves a static file as a response, with cache headers.
+    #
+    # @param path [String] file path
+    # @param opts [Hash] options
+    # @return [void]
     def serve_file(path, opts = {})
       full_path = file_full_path(path, opts)
       stat = File.stat(full_path)
@@ -59,6 +84,12 @@ module Syntropy
       respond(nil, ':status' => HTTP::NOT_FOUND)
     end
 
+    # Validates a static file cache against the request cache headers. Returns
+    # true if cache headers are valid.
+    #
+    # @param etag [String] ETag
+    # @param last_modified [String] last-modified value
+    # @return [bool] are cache headers valid
     def validate_static_file_cache(etag, last_modified)
       if (none_match = headers['if-none-match'])
         return true if none_match == etag
@@ -70,6 +101,11 @@ module Syntropy
       false
     end
 
+    # Returns a fully qualified file path based on the given options.
+    #
+    # @param path [String] file path
+    # @param opts [Hash] options hash
+    # @return [String] qualified file path
     def file_full_path(path, opts)
       if (base_path = opts[:base_path])
         File.join(opts[:base_path], path)
@@ -78,10 +114,13 @@ module Syntropy
       end
     end
 
-    def serve_io(io, opts)
-      respond(io.read, opts[:headers] || {})
-    end
-
+    # Renders a static file response.
+    #
+    # @param path [String] file path
+    # @param etag [String] ETag
+    # @param last_modified [String] last-modified value
+    # @param opts [Hash] options
+    # @return [void]
     def respond_with_static_file(path, etag, last_modified, opts)
       cache_headers = (etag || last_modified) ? {
         'etag' => etag,
@@ -91,14 +130,29 @@ module Syntropy
       adapter.respond_with_static_file(self, path, opts, cache_headers)
     end
 
+    # Set additional response headers.
+    #
+    # @param headers [Hash] response headers
+    # @return [void]
     def set_response_headers(headers)
       adapter.set_response_headers(headers)
     end
 
-    def set_cookie(k, v)
-      adapter.set_cookie(k, v)
+    # Sets a response cookie.
+    #
+    # @param key [String] cookie name
+    # @param value [String] cookie value
+    # @return [void]
+    def set_cookie(key, value)
+      adapter.set_cookie(key, value)
     end
 
+    # Upgrades the connection to the given protocol, yielding the connection to
+    # the given block.
+    #
+    # @param protocol [String] upgraded protocol
+    # @param custom_headers [Hash, nil] additional response headers
+    # @return [void]
     def upgrade(protocol, custom_headers = nil, &block)
       upgrade_headers = {
         ':status' => HTTP::SWITCHING_PROTOCOLS,
@@ -169,6 +223,11 @@ module Syntropy
       end
     end
 
+    # Renders an HTML repsonse with HTML content type.
+    #
+    # @param html [String] HTML response body
+    # @param headers [Hash] additional response headers
+    # @return [void]
     def respond_html(html, **headers)
       respond(
         html,
@@ -177,6 +236,11 @@ module Syntropy
       )
     end
 
+    # Renders a JSON repsonse with JSON content type.
+    #
+    # @param obj [any] obj to render into JSON
+    # @param headers [Hash] additional response headers
+    # @return [void]
     def respond_json(obj, **headers)
       respond(
         JSON.dump(obj),
@@ -185,6 +249,11 @@ module Syntropy
       )
     end
 
+    # Renders a nicely-formatted JSON repsonse with JSON content type.
+    #
+    # @param obj [any] obj to render into JSON
+    # @param headers [Hash] additional response headers
+    # @return [void]
     def json_pretty_response(obj, **headers)
       respond(
         JSON.pretty_generate(obj),

data/lib/syntropy/request/validation.rb

@@ -18,6 +18,12 @@ module Syntropy
       raise Syntropy::Error.method_not_allowed
     end
 
+    # Validates the request's content-type against the given accepted content
+    # types. If the content type does not match the given accepted list, raises
+    # an error.
+    #
+    # @param accepted [Array<String>] array of accepted content types
+    # @return [String] accepted content type
     def validate_content_type(*accepted)
       ct = content_type
       return ct if accepted.include?(ct)

data/lib/syntropy/storage/connection_pool.rb

@@ -8,6 +8,12 @@ module Syntropy
     class ConnectionPool
       attr_reader :count
 
+      # Initializes the connection pool.
+      #
+      # @param machine [UringMachine] machine instance
+      # @param fn [String] database filename
+      # @param max_conn [Integer] maximum number of connections
+      # @return [void]
       def initialize(machine, fn, max_conn)
         @machine = machine
         @fn = fn
@@ -17,6 +23,11 @@ module Syntropy
         @key = :"connection_pool_#{object_id}"
       end
 
+      # Checks out a database connection, passing it to the given block. This
+      # method is reentrant - called from the same fiber, it will yield the same
+      # database connection.
+      #
+      # @return [Extralite::Database] database connection
       def with_db
         if (db = Thread.current[@key])
           @machine.snooze
@@ -33,14 +44,27 @@ module Syntropy
         end
       end
 
+      # Performs the given query by acquiring a database connection and running
+      # the query.
+      #
+      # @param sql [String] SQL query
+      # @return [Array<Hash>] result rows
       def query(sql, *, **, &)
         with_db { it.query(sql, *, **, &) }
       end
 
+      # Executes the given query by acquiring a database connection and running
+      # the query.
+      #
+      # @param sql [String] SQL query
+      # @return [Integer] number of changed rows
       def execute(sql, *, **)
         with_db { it.execute(sql, *, **) }
       end
 
+      # Closes the connection pool by removing all connections.
+      #
+      # @return [void]
       def close
         while @queue.count > 0
           db = @machine.shift(@queue)
@@ -51,16 +75,26 @@ module Syntropy
 
       private
 
+      # Checks out a connection from the pool.
+      #
+      # @return [Extralite::Database] database connection
       def checkout
         return make_db_instance if @queue.count == 0 && @count < @max_conn
 
         @machine.shift(@queue)
       end
 
+      # Checks in a connection to the pool.
+      #
+      # @param db [Extralite::Database] database connection
+      # @return [void]
       def checkin(db)
         @machine.push(@queue, db)
       end
 
+      # Creates a database connection.
+      #
+      # @return [Extralite::Database] database connection
       def make_db_instance
         Extralite::Database.new(@fn, wal: true).tap do
           @count += 1

data/lib/syntropy/test.rb

@@ -19,7 +19,7 @@ module Syntropy
       def global_env
         @@global_env
       end
-    
+
       # Gets/sets app environment for tests
       attr_accessor :env
     end
@@ -38,8 +38,8 @@ module Syntropy
     #
     # @param ref [String] module reference
     # @return [any] module
-    def load_module(ref, raise_on_missing: true)
-      app.module_loader.load(ref, raise_on_missing:)
+    def load_module(ref, raise_on_missing_export: true)
+      app.module_loader.load(ref, raise_on_missing_export:)
     end
 
     # Makes an HTTP request to the test app.
@@ -145,7 +145,7 @@ module Syntropy
       )
       @test_harness = Syntropy::TestHarness.new(@app)
 
-      @db = load_module('/_lib/storage', raise_on_missing: false)
+      @db = load_module('/_lib/storage', raise_on_missing_export: false)
       @db&.migrate! if @db.respond_to?(:migrate!)
     end
 

data/lib/syntropy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Syntropy
-  VERSION = '0.39.0'
+  VERSION = '0.41.0'
 end

data/lib/syntropy.rb

@@ -72,6 +72,12 @@ module Syntropy
       end
     end
 
+    # Loads the app config module based on the environment's config root and
+    # mode: (test, dev, production). The module's exported value is assigned to
+    # env[:config].
+    #
+    # @param env [Hash] app environment
+    # @return [void]
     def load_config(env)
       return if !env[:config_root]
 
@@ -81,7 +87,7 @@ module Syntropy
         machine: UM.new(size: 8)
       )
       loader = ModuleLoader.new(loader_env)
-      if (config = loader.load(env[:mode], raise_on_missing: false))
+      if (config = loader.load(env[:mode], raise_on_missing_export: false))
         env[:config] = config
       end
     end

data/syntropy.gemspec

@@ -21,9 +21,9 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 3.4'
   s.executables = ['syntropy']
 
-  s.add_dependency 'extralite',     '~>2.14'
-  s.add_dependency 'papercraft',    '~>3.2.0'
-  s.add_dependency 'uringmachine',  '~>1.0.2'
+  s.add_dependency 'extralite',     '~>3.0.1'
+  s.add_dependency 'papercraft',    '~>3.2.2'
+  s.add_dependency 'uringmachine',  '~>1.0.4'
 
   s.add_dependency 'json'
   s.add_dependency 'base64'
@@ -31,6 +31,6 @@ Gem::Specification.new do |s|
   s.add_dependency 'irb'
   s.add_dependency 'minitest'
 
-  s.add_development_dependency 'rake',      '~>13.3.1'
+  s.add_development_dependency 'rake'
   s.add_development_dependency 'solargraph'
 end

data/test/test_markdown.rb

@@ -60,7 +60,7 @@ class MarkdownControllerTest < Minitest::Test
     @controller = nil
     @test_harness = Syntropy::TestHarness.new(->(req) { @controller.(req) })
   end
-  
+
   def test_markdown_renderer_no_layout
     md = <<~MD
       foo *bar*
@@ -230,8 +230,8 @@ class MarkdownControllerTest < Minitest::Test
     md = <<~MD
       ```ruby
       # render: true
-      @env[:count] ||= 0
-      h3 (@env[:count] += 1)
+      @count ||= 0
+      h3 (@count += 1)
       ```
       bar
     MD

data/test/test_module_loader.rb

@@ -16,7 +16,10 @@ class ModuleLoaderTest < Minitest::Test
     assert_equal 42, mod.bar
 
     assert_raises(Syntropy::Error) { @loader.load('_lib/missing-module') }
-    assert_raises(Syntropy::Error) { @loader.load('_lib/missing-export') }
+
+    mod = @loader.load('_lib/missing-export')
+    assert_kind_of Syntropy::ModuleContext, mod
+    assert_equal :bar, mod.call
 
     mod = @loader.load('_lib/callable')
     assert_kind_of Syntropy::ModuleContext, mod