syntropy 0.32.0 → 0.34.0

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

@@ -3,20 +3,160 @@
 require 'syntropy'
 require 'syntropy/request/mock_adapter'
 require 'minitest'
+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
+
+    # 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(
+          ':method' => 'GET',
+          ':path'   => path
+        )
+      )
+    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(
+        headers.merge(
+          {
+            ':method' => 'POST',
+            ':path'   => path
+          }
+        ),
+        body
+      )
+    end
+
+    # 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
+
+    # 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(
+        **@@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
+      @test_harness = nil
+    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=)
 
@@ -28,32 +168,52 @@ module Syntropy
       end
     end
 
-
     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
@@ -64,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
@@ -74,4 +238,6 @@ module Syntropy
       m[1]
     end
   end
+
+  Request.include TestRequestExtensions
 end

data/lib/syntropy/utils.rb

@@ -1,52 +1,87 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module Syntropy
   # Utilities for use in modules
   module Utilities
-    # Returns a request handler that routes request according to
+    def tmp_path(prefix = 'syntropy')
+      "/tmp/#{prefix}-#{SecureRandom.hex(16)}"
+    end
+
+    # Returns a request handler that routes request according to the host
+    # header. Looks for site directories (named by host name) in the app's root
+    # directory. A map may be given in order to provide additional hostnames to
+    # site directories.
+    #
+    # @param env [Hash] app environment hash
+    # @param map [Hash, nil] additional hostname map
+    # @return [Proc] router proc
     def route_by_host(env, map = nil)
-      root = env[:root_dir]
-      sites = Dir[File.join(root, '*')]
-              .reject { File.basename(it) =~ /^_/ }
-              .select { File.directory?(it) }
-              .each_with_object({}) { |fn, h|
-                name = File.basename(fn)
-                h[name] = Syntropy::App.new(**env.merge(root_dir: fn))
-              }
-
-      # copy over map refs
+      sites = find_hostname_sites(env)
+
+      # add map refs
       map&.each { |k, v| sites[k] = sites[v] }
 
-      #
       lambda { |req|
         site = sites[req.host]
         site ? site.call(req) : req.respond(nil, ':status' => HTTP::BAD_REQUEST)
       }
     end
 
+    # Returns a list of parsed markdown pages at the given path.
+    #
+    # @param env [Hash] app environment hash
+    # @param ref [String] directory path
+    # @return [Array<Hash>] array of page entries
     def page_list(env, ref)
-      full_path = File.join(env[:root_dir], ref)
+      full_path = File.join(env[:app_root], ref)
       raise 'Not a directory' if !File.directory?(full_path)
 
       Dir[File.join(full_path, '*.md')].sort.map {
-        atts, markdown = Syntropy.parse_markdown_file(it, env)
+        atts, markdown = Syntropy::Markdown.parse(it, env)
         { atts:, markdown: }
       }
     end
 
-    def app(**env)
-      Syntropy::App.new(**env)
+    # Instantiates a Syntropy app for the given environment hash.
+    #
+    # @return [Syntropy::App]
+    def app(**)
+      Syntropy::App.new(**)
     end
 
-    BUILTIN_APPLET_ROOT_DIR = File.expand_path(File.join(__dir__, 'applets/builtin'))
+    BUILTIN_APPLET_app_root = File.expand_path(File.join(__dir__, 'applets/builtin'))
+
+    # Creates a builtin applet with the given environment hash. By default the
+    # builtin applet is mounted at /.syntropy.
+    #
+    # @param env [Hash] app environment
+    # @param mount_path [String] mount path for the builtin applet
+    # @return [Syntropy::App] applet
     def builtin_applet(env, mount_path: '/.syntropy')
       app(
         machine:    env[:machine],
-        root_dir:   BUILTIN_APPLET_ROOT_DIR,
+        app_root:   BUILTIN_APPLET_app_root,
         mount_path: mount_path,
         builtin_applet_path: nil,
         watch_files: nil
       )
     end
+
+    private
+
+    # Finds sites in the root directory for the given environment hash.
+    #
+    # @param env [Hash] app environment hash
+    # @return [Hash] hash mapping hostname to app
+    def find_hostname_sites(env)
+      Dir[File.join(env[:app_root], '*')]
+        .select { File.directory?(it) && File.basename(it) !~ /^_/ }
+        .each_with_object({}) { |fn, h|
+          name = File.basename(fn)
+          h[name] = Syntropy::App.new(**env.merge(app_root: fn))
+        }
+    end
   end
 end

data/lib/syntropy/version.rb

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

data/lib/syntropy.rb

@@ -2,6 +2,7 @@
 
 require 'uringmachine'
 require 'papercraft'
+require 'yaml'
 
 require 'syntropy/request'
 require 'syntropy/logger'
@@ -21,20 +22,31 @@ require 'syntropy/side_run'
 require 'syntropy/utils'
 require 'syntropy/version'
 
+# Syntropy is a web framework for building web apps in Ruby. Syntropy uses
+# UringMachine for I/O and concurrency, and provides a comprehensive and
+# flexible solution for writing web apps with minimal boilerplate.
 module Syntropy
   extend Utilities
 
   class << self
-    attr_accessor :machine
+    attr_accessor :machine, :dev_mode
 
+    # Runs the given block on a separate thread. Use this method for running
+    # code that is not fiber-aware (i.e. does not use UringMachine).
+    #
+    # @return [any] operation return value
     def side_run(&block)
       raise 'Syntropy.machine not set' if !@machine
 
       SideRun.call(@machine, &block)
     end
-  end
 
-  class << self
+    # Runs a web app with the given environment hash. The given block is either
+    # an instance of Syntropy::App, or a Proc/callable that takes a request as
+    # argument.
+    #
+    # @param env [Hash] environment
+    # @return [void]
     def run(env = {}, &app)
       if @in_run
         @env = env
@@ -47,7 +59,14 @@ module Syntropy
         @in_run = true
         machine = env[:machine] || UM.new
 
-        env[:logger]&.info(message: "Running Syntropy #{Syntropy::VERSION}, UringMachine #{UM::VERSION}, Ruby #{RUBY_VERSION}")
+        if (logger = env[:logger])
+          logger.info(
+            message: "Syntropy #{Syntropy::VERSION}, UringMachine #{UM::VERSION}, Ruby #{RUBY_VERSION}"
+          )
+          logger.info(
+            message: "Running in #{env[:mode]} mode"
+          )
+        end
 
         server = HTTP::Server.new(machine, env, &app)
 
@@ -58,23 +77,38 @@ module Syntropy
       end
     end
 
-    def env(env = nil, &app)
-      return @env if !env && !app
+    def load_config(env)
+      return if !env[:config_root]
+
+      loader_env = env.merge(
+        app_root: env[:config_root],
+        logger: nil
+      )
+      loader = ModuleLoader.new(loader_env)
+      config = loader.load(env[:mode])
 
-      @env = env || {}
-      @env[:app] = app if app
+      env[:config] = config
     end
 
     private
 
+    # Sets up asynchronous SIGINT handling.
+    #
+    # @param machine [UringMachine] machine instance
+    # @param fiber [Fiber] fiber to terminate on SIGINT
+    # @return [void]
     def setup_signal_handling(machine, fiber)
       queue = UM::Queue.new
       trap('SIGINT') { machine.push(queue, :SIGINT) }
       machine.spin { watch_for_int_signal(machine, queue, fiber) }
     end
 
-    # waits for signal from queue, then terminates given fiber
-    # to be done
+    # Waits for signal from queue, then terminates the given fiber.
+    #
+    # @param machine [UringMachine] machine instance
+    # @param queue [UringMachine::Queue] queue to wait on
+    # @param fiber [Fiber] fiber to terminate
+    # @return [void]
     def watch_for_int_signal(machine, queue, fiber)
       machine.shift(queue)
       machine.schedule(fiber, UM::Terminate.new)