syntropy 0.33.0 → 0.34.0

data/lib/syntropy/routing_tree.rb

@@ -5,7 +5,7 @@ module Syntropy
   # static files, markdown files, ruby modules, parametric routes, subtree routes,
   # nested middleware and error handlers.
   #
-  # A RoutingTree instance takes the given directory (root_dir) and constructs a
+  # A RoutingTree instance takes the given directory (app_root) and constructs a
   # tree of route entries corresponding to the directory's contents. Finally, it
   # generates an optimized router proc, which is used by the application to return
   # a route entry for each incoming HTTP request.
@@ -41,15 +41,15 @@ module Syntropy
   #   allows you to prevent access through the HTTP server to protected or
   #   internal modules or files.
   class RoutingTree
-    attr_reader :root_dir, :mount_path, :static_map, :dynamic_map, :root
+    attr_reader :app_root, :mount_path, :static_map, :dynamic_map, :root
 
     # Initializes a new RoutingTree instance and computes the routing tree
     #
-    # @param root_dir [String] root directory of file tree
+    # @param app_root [String] root directory of file tree
     # @param mount_path [String] base URL path
     # @return [void]
-    def initialize(root_dir:, mount_path:, **env)
-      @root_dir = root_dir
+    def initialize(app_root:, mount_path:, **env)
+      @app_root = app_root
       @mount_path = mount_path
       @static_map = {}
       @dynamic_map = {}
@@ -72,7 +72,7 @@ module Syntropy
     # @param fn [String] file path
     # @return [String] clean path
     def compute_clean_url_path(fn)
-      rel_path = fn.sub(@root_dir, '')
+      rel_path = fn.sub(@app_root, '')
       case rel_path
       when /^(.*)\/index\.(md|rb|html)$/
         Regexp.last_match(1).then { it == '' ? '/' : it }
@@ -88,7 +88,7 @@ module Syntropy
     # @param fn [String] filename
     # @return [String] relative path
     def fn_to_rel_path(fn)
-      fn.sub(/^#{Regexp.escape(@root_dir)}\//, '').sub(/\.[^\.]+$/, '')
+      fn.sub(/^#{Regexp.escape(@app_root)}\//, '').sub(/\.[^\.]+$/, '')
     end
 
     # Mounts the given applet on the routng tree at the given (absolute) mount
@@ -142,7 +142,7 @@ module Syntropy
     #
     # @return [Hash] root entry
     def compute_tree
-      compute_route_directory(dir: @root_dir, rel_path: '/', parent: nil)
+      compute_route_directory(dir: @app_root, rel_path: '/', parent: nil)
     end
 
     # Converts the given absolute path to a relative one (relative to the
@@ -233,7 +233,7 @@ module Syntropy
     # @return [String, nil] file path if found
     def find_aux_module_entry(dir, name)
       fn = File.join(dir, name)
-      File.file?(fn) ? ({ kind: :module,  fn: }) : nil
+      File.file?(fn) ? { kind: :module,  fn: } : nil
     end
 
     # Returns a hash mapping file/dir names to route entries.
@@ -247,10 +247,10 @@ module Syntropy
 
         rel_path = compute_clean_url_path(fn)
         child = if File.file?(fn)
-          compute_route_file(fn:, rel_path:, parent:)
-        elsif File.directory?(fn)
-          compute_route_directory(dir: fn, rel_path:, parent:)
-        end
+                  compute_route_file(fn:, rel_path:, parent:)
+                elsif File.directory?(fn)
+                  compute_route_directory(dir: fn, rel_path:, parent:)
+                end
         map[child_key(child)] = child if child
       }
     end
@@ -317,7 +317,6 @@ module Syntropy
       set_index_route_target(parent:, path:, kind:, fn:, handle_subtree:)
     end
 
-
     # Sets an index route target for the given parent entry. Index files are
     # applied as targets to the immediate containing directory. HTML index files
     # are considered static and therefore not added to the routing tree.
@@ -329,7 +328,7 @@ module Syntropy
     # @param handle_subtree [bool] whether the target handles the subtree
     # @return [nil] (prevents addition of an index route)
     def set_index_route_target(parent:, path:, kind:, fn:, handle_subtree: nil)
-      if is_parametric_route?(parent) || handle_subtree
+      if parametric_route?(parent) || handle_subtree
         @dynamic_map[path] = parent
         parent[:target] = { kind:, fn: }
         parent[:handle_subtree] = handle_subtree
@@ -383,7 +382,7 @@ module Syntropy
     # @param entry [Hash] route entry
     def make_route_entry(entry)
       path = entry[:path]
-      if is_parametric_route?(entry) || entry[:handle_subtree]
+      if parametric_route?(entry) || entry[:handle_subtree]
         @dynamic_map[path] = entry
       else
         entry[:static] = true
@@ -394,8 +393,8 @@ module Syntropy
     # returns true if the route or any of its ancestors are parametric.
     #
     # @param entry [Hash] route entry
-    def is_parametric_route?(entry)
-      entry[:param] || (entry[:parent] && is_parametric_route?(entry[:parent]))
+    def parametric_route?(entry)
+      entry[:param] || (entry[:parent] && parametric_route?(entry[:parent]))
     end
 
     # Converts a relative URL path to absolute URL path.
@@ -468,7 +467,7 @@ module Syntropy
         emit_router_proc_postlude(buffer, default_route_path: wildcard_root && @root[:path])
       end
 
-      buffer#.tap { puts '*' * 40; puts it; puts }
+      buffer # .tap { puts '*' * 40; puts it; puts }
     end
 
     # Emits optimized code for a childless wildcard router.
@@ -540,7 +539,7 @@ module Syntropy
         return
       end
 
-      if is_void_route?(entry)
+      if void_route?(entry)
         parent = entry[:parent]
         parametric_sibling = parent && parent[:children] && parent[:children]['[]']
         if parametric_sibling
@@ -580,7 +579,7 @@ module Syntropy
     # @param entry [Hash] route entry
     # @return [Hash, nil] route target if exists
     def find_target_in_subtree(entry)
-      entry[:children]&.values&.each { |e|
+      entry[:children]&.each_value { |e|
         target = e[:target] || find_target_in_subtree(e)
         return target if target
       }
@@ -593,14 +592,14 @@ module Syntropy
     #
     # @param entry [Hash] route entry
     # @return [bool]
-    def is_void_route?(entry)
+    def void_route?(entry)
       return false if entry[:param] || entry[:target]
+      return true if entry[:static]
 
-      if entry[:children]
-        return true if !entry[:children]['[]'] && entry[:children]&.values&.all? { is_void_route?(it) }
-      else
-        return true if entry[:static]
-      end
+      children = entry[:children]
+      return false if !children
+
+      return true if !children['[]'] && children.values.all? { void_route?(it) }
 
       false
     end
@@ -640,7 +639,7 @@ module Syntropy
 
         elsif has_children
           # otherwise look at the next segment
-          next if is_void_route?(child_entry) && !param_entry
+          next if void_route?(child_entry) && !param_entry
 
           when_buffer = +''
           visit_routing_tree_entry(buffer: when_buffer, entry: child_entry, indent: indent + 1, segment_idx: segment_idx + 1)

data/lib/syntropy/session.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'securerandom'
+
+module Syntropy
+  # A Session object serves as storage for data associated with the user's
+  # browser session, such as flash data (for communicating notices and alerts).
+  # The session is modeled as a key-value store, where keys are strings, and
+  # values can be any value that can be represented in JSON, including arrays
+  # and hashes.
+  #
+  # The session data is stored as an HTTP cookie.
+  class Session
+    # Initializes the session.
+    #
+    # @param request [Syntropy::Request] associated request
+    # @return [void]
+    def initialize(request)
+      @request = request
+      @data = nil
+    end
+
+    # Returns the value associated with the given key.
+    #
+    # @param key [String]
+    # @return [any] value
+    def [](key)
+      @data ||= load
+      @data[key]
+    end
+
+    # Sets the value for the given key and updates the response session cookie.
+    #
+    # @param key [String]
+    # @param value [any]
+    # @return [void]
+    def []=(key, value)
+      @data ||= load
+      @data[key] = value
+      save(@data)
+    end
+
+    # Deletes the given key-value pair and updates the response session cookie.
+    #
+    # @param key [String]
+    # @return [any] deleted value
+    def delete(key)
+      @data ||= load
+      value = @data.delete(key)
+      save(@data.empty? ? nil : @data)
+      value
+    end
+
+    # Discards the session data, updating the response session cookie by
+    # emptying it.
+    #
+    # @return [void]
+    def discard
+      save(nil)
+    end
+
+    # Returns the flash storage for the session.
+    #
+    # @return [Syntropy::Session::Flash]
+    def flash
+      @data ||= load
+      @flash ||= Flash.new(self)
+    end
+
+    private
+
+    # Loads session data from the request session cookie.
+    #
+    # @return [Hash] session data
+    def load
+      data = @request.cookies['__syntropy_session__']
+      return {} if !data
+
+      JSON.parse(Base64.decode64(data))
+    rescue JSON::ParserError
+      {}
+    ensure
+      @loaded = true
+    end
+
+    # Saves session data to the response session cookie.
+    #
+    # @param data [Hash] session data
+    # @return [void]
+    def save(data)
+      cookie = data ? "#{Base64.strict_encode64(JSON.dump(data))}; Path=/; HttpOnly" : nil
+      @request.set_cookie('__syntropy_session__', cookie)
+    end
+  end
+
+  # NowFlash holds flash data for the current request.
+  class NowFlash
+    def initialize
+      @data = {}
+    end
+
+    # Returns the value for the given key.
+    #
+    # @param key [Symbol]
+    # @return [any] flash value
+    def [](key)
+      @data[key.to_s]
+    end
+
+    # Sets the value for the given key.
+    #
+    # @param key [Symbol]
+    # @param value [any]
+    # @return [any] value
+    def []=(key, value)
+      @data[key.to_s] = value
+    end
+
+    # Iterates through the flash storage, yielding each key-value pair to the
+    # given block.
+    #
+    # @return [void]
+    def each(&block)
+      @data.each { |k, v| block.(k.to_sym, v) }
+    end
+  end
+
+  # Flash acts as a special storage mechanism for transient information that
+  # can be passsed between consecutive requests in the same session. Flash
+  # values can be set in order to be retrieved in the next response. Reading
+  # from flash storage will return data that was set in the previous request.
+  # Data written to the flash storage will only be available to the next
+  # request. You can also set flash data that will be available to the current
+  # request by using Flash#now.
+  #
+  # In order to keep the read flash data (set in the previous request) and
+  # make it available to the next request, use Flash#keep.
+  class Flash
+    # Initializes the flash storage.
+    #
+    # @return [void]
+    def initialize(session)
+      @session = session
+      @current_flash_data = @session['_flash']
+      @session.delete('_flash') if @current_flash_data
+      @current_flash_data ||= {}
+      @future_flash_data = {}
+      @now_flash_data = NowFlash.new
+    end
+
+    # Reads data from flash storage for the given key. The value would have
+    # been set in the previous request.
+    #
+    # @param key [Symbol]
+    # @return [any] value
+    def [](key)
+      key = key.to_s
+      @now_flash_data[key] || @current_flash_data[key]
+    end
+
+    # Sets the flash storage value for the given key. The value would be
+    # available to the next request.
+    #
+    # @param key [Symbol]
+    # @param value [any]
+    # @return [void]
+    def []=(key, value)
+      key = key.to_s
+      @future_flash_data[key] = value
+      @session['_flash'] = @future_flash_data
+    end
+
+    # Iterates through the flash storage, passing each key-value pair to the
+    # given block.
+    #
+    # @return [void]
+    def each(&block)
+      @current_flash_data.each_pair { |k, v| block.(k.to_sym, v) }
+    end
+
+    # Persists any flash data set in the previous request to the next request.
+    #
+    # @return [void]
+    def keep
+      @future_flash_data = @current_flash_data.merge!(@future_flash_data)
+      @session['_flash'] = @future_flash_data
+    end
+
+    # Returns the flash storage for the current request.
+    #
+    # @return [Syntropy::NowFlash]
+    def now
+      @now_flash_data
+    end
+  end
+end

data/lib/syntropy/side_run.rb

@@ -3,8 +3,16 @@
 require 'etc'
 
 module Syntropy
+  # SideRun implements running an operation on a separate thread.
   module SideRun
     class << self
+      # Runs the given block on a separate thread, using UringMachine to wait
+      # for the operation to complete. If the operation results in a raised
+      # exception, that exception will be reraised in the context of the waiting
+      # fiber.
+      #
+      # @param machine [UringMachine] machine instance
+      # @return [any] operation return value
       def call(machine, &block)
         setup if !@queue
 
@@ -15,6 +23,11 @@ module Syntropy
         result.is_a?(Exception) ? (raise result) : result
       end
 
+      private
+
+      # Sets up a thread pool for side-running operations.
+      #
+      # @return [void]
       def setup
         @queue = UM::Queue.new
         count = (Etc.nprocessors - 1).clamp(2..6)
@@ -23,9 +36,13 @@ module Syntropy
         }
       end
 
+      # Runs worker loop for running side-run operations.
+      #
+      # @param queue [UringMachine::Queue] queue for pulling operations
+      # @return [void]
       def side_run_worker(queue)
         machine = UM.new
-        loop { handle_request(machine, queue) }
+        loop { run_op(machine, queue) }
       rescue UM::Terminate
         # # We can also add a timeout here
         # t0 = Time.now
@@ -34,7 +51,13 @@ module Syntropy
         # end
       end
 
-      def handle_request(machine, queue)
+      # Pulls an operation from the given queue and runs it, pushing its return
+      # value to the corresponding mailbox.
+      #
+      # @param machine [UringMachine] machine instance
+      # @param queue [UringMachine::Queue] op queue
+      # @return [void]
+      def run_op(machine, queue)
         response_mailbox, closure = machine.shift(queue)
         result = closure.call
         machine.push(response_mailbox, result)

data/lib/syntropy/test.rb

@@ -7,27 +7,49 @@ require 'json'
 require 'uri'
 
 module Syntropy
+  # Test provides a class for testing a Syntropy app, based on Minitest.
   class Test < Minitest::Test
     HTTP = Syntropy::HTTP
 
+    # Sets the app environment for all Syntropy tests.
+    #
+    # @param env [Hash] app environment hash
+    # @return [void]
     def self.env=(env)
       @@env = env
     end
 
     attr_reader :machine, :app
 
+    # Returns the test environment.
+    #
+    # @return [Hash] test app environment
     def env
       @@env
     end
 
-    def load_module(ref)
-      app.module_loader.load(ref)
+    # Loads and returns a module with the given reference.
+    #
+    # @param ref [String] module reference
+    # @return [any] module
+    def load_module(ref, raise_on_missing: true)
+      app.module_loader.load(ref, raise_on_missing:)
     end
 
+    # Makes an HTTP request to the test app.
+    #
+    # @param headers [Hash] request headers
+    # @param body [String, nil] request body
+    # @return [Syntropy::Request]
     def http_request(headers, body = nil)
       @test_harness.request(headers, body)
     end
 
+    # Makes an HTTP GET request to the test app.
+    #
+    # @param path [String] request path
+    # @param headers [Hash] request headers
+    # @return [Syntropy::Request]
     def get(path, **headers)
       http_request(
         headers.merge(
@@ -37,6 +59,13 @@ module Syntropy
       )
     end
 
+    # Makes an HTTP POST request to the test app.
+    #
+    # @param path [String] request path
+    # @param content_type [String, nil] content MIME type
+    # @param body [String] request body
+    # @param headers [Hash] request headers
+    # @return [Syntropy::Request]
     def post(path, content_type, body, **headers)
       headers = headers.merge('content-type' => content_type) if content_type
       http_request(
@@ -50,26 +79,52 @@ module Syntropy
       )
     end
 
-    def post_json(path, obj, **)
-      post(path, 'application/json', JSON.dump(obj), **)
+    # Makes an HTTP POST request to the test app with a "application/json"
+    # content type. The given object is converted to JSON and sent as the
+    # request body.
+    #
+    # @param path [String] request path
+    # @param data [any] data
+    # @return [Syntropy::Request]
+    def post_json(path, data, **)
+      post(path, 'application/json', JSON.dump(data), **)
     end
 
-    def post_form(path, form, **)
-      post(path, 'application/x-www-form-urlencoded', URI.encode_www_form(form), **)
+    # Makes an HTTP POST request to the test app with a
+    # "application/x-www-form-urlencoded" content type. The given data is
+    # converted to URL Encoded form format and sent as the request body.
+    #
+    # @param path [String] request path
+    # @param data [Hash] form data
+    # @return [Syntropy::Request]
+    def post_form(path, data, **)
+      post(path, 'application/x-www-form-urlencoded', URI.encode_www_form(data), **)
     end
 
+    # Sets up a test instance.
+    #
+    # @return [void]
     def setup
       raise 'Environment not set' if !@@env
 
+      Syntropy.load_config(@@env)
+
       @machine = UM.new
       @app = Syntropy::App.new(
-        root_dir: @@env[:root_dir],
-        mount_path: '/',
-        machine: @machine
+        **@@env.merge(
+          machine: @machine,
+          test_mode: true
+        )
       )
       @test_harness = Syntropy::TestHarness.new(@app)
+
+      @db = load_module('/_lib/database', raise_on_missing: false)
+      @db&.migrate!
     end
 
+    # Cleans up a test instance.
+    #
+    # @return [void]
     def teardown
       @machine = nil
       @app = nil
@@ -77,18 +132,31 @@ module Syntropy
     end
   end
 
+  # TestHarness provides glue code for performing HTTP requests against a
+  # Syntropy app.
   class TestHarness
+    # Initializes the test harness with the given app.
+    #
+    # @param app [Syntropy::App]
+    # @return [void]
     def initialize(app)
       @app = app
       @app.raise_internal_server_error = true if @app.respond_to?(:raise_internal_server_error=)
     end
 
+    # Perfrms a request against the associated app.
+    #
+    # @param headers [Hash] request headers
+    # @param body [String, nil] request body
+    # @return [Syntropy::Request]
     def request(headers, body = nil)
       req = mock_req(headers, body)
       @app.call(req)
       req
     end
 
+    # Temporarily disables raising an exception in case of an internal server
+    # error while running the given block.
     def no_raise_internal_server_error
       return yield if !@app.respond_to?(:raise_internal_server_error=)
 
@@ -102,29 +170,50 @@ module Syntropy
 
     private
 
+    # Creates a Syntropy request running on a mock adapter.
+    #
+    # @param headers [Hash] request headers
+    # @param body [String, nil] request body
+    # @return [Syntropy::Request]
     def mock_req(headers, body = nil)
       Syntropy::MockAdapter.mock(headers, body)
     end
   end
 
-  class Request
+  # Extensions to Syntropy::Request for testing.
+  module TestRequestExtensions
+    # Returns the response headers.
+    #
+    # @return [Hash]
     def response_headers
       adapter.response_headers
     end
 
+    # Returns the response status
+    #
+    # @return [Integer]
     def response_status
       adapter.status
     end
 
+    # Returns the response body
+    #
+    # @return [String, nil]
     def response_body
       adapter.response_body
     end
 
+    # Parses the response body from JSON.
+    #
+    # @return [any] parsed JSON object
     def response_json
       raise if response_content_type != 'application/json'
       JSON.parse(response_body)
     end
 
+    # Returns the response content MIME type.
+    #
+    # @return [String, nil]
     def response_content_type
       ct = response_headers['Content-Type']
       return nil if !ct
@@ -135,6 +224,10 @@ module Syntropy
       m[1]
     end
 
+    # Returns the cookie value for the given cookie name from the response.
+    #
+    # @param name [String, Symbol] cookie name
+    # @return [String, nil] cookie value
     def response_cookie(name)
       sc = response_headers['Set-Cookie']
       return nil if !sc
@@ -145,4 +238,6 @@ module Syntropy
       m[1]
     end
   end
+
+  Request.include TestRequestExtensions
 end