syntropy 0.33.0 → 0.34.1

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

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.33.0'
+  VERSION = '0.34.1'
 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)

data/test/bm_router_proc.rb

@@ -138,8 +138,8 @@ def make_tmp_file_tree(dir, spec)
   dir
 end
 
-ROOT_DIR = "/tmp/#{__FILE__.gsub('/', '-')}-#{SecureRandom.hex}"
-make_tmp_file_tree(ROOT_DIR, {
+app_root = "/tmp/#{__FILE__.gsub('/', '-')}-#{SecureRandom.hex}"
+make_tmp_file_tree(app_root, {
   'index.rb': "export ->(req) { req.redirect('/hello') }",
   'hello': {
     'index.rb': "export ->(req) { req.respond('Hello!', 'Content-Type' => 'text/html') }",
@@ -149,7 +149,7 @@ make_tmp_file_tree(ROOT_DIR, {
 
 machine = UM.new
 syntropy_app = Syntropy::App.new(
-  root_dir: ROOT_DIR,
+  app_root: app_root,
   mount_path: '/',
   machine: machine
 )
@@ -185,7 +185,7 @@ BM.run do
     def setup
       machine = UM.new
       syntropy_app = Syntropy::App.new(
-        root_dir: ROOT_DIR,
+        app_root: app_root,
         mount_path: '/',
         # watch_files: 0.05,
         machine: machine

data/test/fixtures/app/class_instance.rb

@@ -0,0 +1,5 @@
+class Foo
+  def bar; :baz; end
+end
+
+export Foo.new

data/test/fixtures/app/http.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+export ->(req) {
+  req.respond('hi', ':status' => HTTP::TEAPOT)
+}

data/test/fixtures/app/post_ct.rb

@@ -0,0 +1,5 @@
+export http_methods
+
+def post(req)
+  req.respond("#{req.content_type}:#{req.read}")
+end

data/test/fixtures/app/singleton.rb

@@ -0,0 +1,3 @@
+class Bar; end
+
+export self

data/test/test_app.rb

@@ -5,7 +5,7 @@ require_relative 'helper'
 class AppTest < Minitest::Test
   HTTP = Syntropy::HTTP
 
-  APP_ROOT = File.join(__dir__, 'app')
+  APP_ROOT = File.join(__dir__, 'fixtures/app')
 
   def setup
     @machine = UM.new
@@ -14,7 +14,7 @@ class AppTest < Minitest::Test
     @tmp_fn = File.join(APP_ROOT, 'tmp.rb')
 
     @app = Syntropy::App.new(
-      root_dir: APP_ROOT,
+      app_root: APP_ROOT,
       mount_path: '/test',
       watch_files: 0.05,
       machine: @machine
@@ -133,6 +133,9 @@ class AppTest < Minitest::Test
 
     req = @test_harness.request(':method' => 'DELETE', ':path' => '/test/by_method')
     assert_equal HTTP::METHOD_NOT_ALLOWED, req.response_status
+
+    req = @test_harness.request(':method' => 'GET', ':path' => '/test/http')
+    assert_equal HTTP::TEAPOT, req.response_status
   end
 
   def test_automatic_redirect_on_trailing_slash
@@ -183,13 +186,13 @@ end
 class CustomAppTest < Minitest::Test
   HTTP = Syntropy::HTTP
 
-  APP_ROOT = File.join(__dir__, 'app_custom')
+  APP_ROOT = File.join(__dir__, 'fixtures/app_custom')
 
   def setup
     @machine = UM.new
     @app = Syntropy::App.load(
       machine: @machine,
-      root_dir: APP_ROOT,
+      app_root: APP_ROOT,
       mount_path: '/'
     )
     @test_harness = Syntropy::TestHarness.new(@app)
@@ -205,13 +208,13 @@ end
 class MultiSiteAppTest < Minitest::Test
   HTTP = Syntropy::HTTP
 
-  APP_ROOT = File.join(__dir__, 'app_multi_site')
+  APP_ROOT = File.join(__dir__, 'fixtures/app_multi_site')
 
   def setup
     @machine = UM.new
     @app = Syntropy::App.load(
       machine: @machine,
-      root_dir: APP_ROOT,
+      app_root: APP_ROOT,
       mount_path: '/'
     )
     @test_harness = Syntropy::TestHarness.new(@app)
@@ -233,7 +236,7 @@ end
 class AppAPITest < Minitest::Test
   HTTP = Syntropy::HTTP
 
-  APP_ROOT = File.join(__dir__, 'app')
+  APP_ROOT = File.join(__dir__, 'fixtures/app')
 
   def setup
     @machine = UM.new
@@ -242,7 +245,7 @@ class AppAPITest < Minitest::Test
     @tmp_fn = File.join(APP_ROOT, 'tmp.rb')
 
     @app = Syntropy::App.new(
-      root_dir: APP_ROOT,
+      app_root: APP_ROOT,
       mount_path: '/test',
       watch_files: 0.05,
       machine: @machine
@@ -297,7 +300,7 @@ end
 class AppDependenciesTest < Minitest::Test
   HTTP = Syntropy::HTTP
 
-  APP_ROOT = File.join(__dir__, 'app')
+  APP_ROOT = File.join(__dir__, 'fixtures/app')
 
   def test_app_dependencies
     foo = { foo: 'foo' }
@@ -309,7 +312,7 @@ class AppDependenciesTest < Minitest::Test
     @tmp_fn = File.join(APP_ROOT, 'tmp.rb')
 
     @app = Syntropy::App.new(
-      root_dir: APP_ROOT,
+      app_root: APP_ROOT,
       mount_path: '/test',
       machine: @machine,
       foo: foo,
@@ -322,45 +325,3 @@ class AppDependenciesTest < Minitest::Test
     assert_equal HTTP::OK, req.response_status
   end
 end
-
-class AppDBSetupDBTest < Minitest::Test
-  HTTP = Syntropy::HTTP
-
-  APP_ROOT = File.join(__dir__, 'app_with_schema')
-
-  def test_app_setup_db
-    machine = UM.new
-
-    app = Syntropy::App.new(
-      root_dir: APP_ROOT,
-      mount_path: '/test',
-      machine: machine
-    )
-
-    assert_equal false, app.respond_to?(:connection_pool)
-    assert_equal false, app.respond_to?(:schema)
-
-    fn = "/tmp/#{rand(100000)}.db"
-
-    app.setup_db(
-      db_path:      fn,
-      schema_root:  '_schema'
-    )
-
-    assert_equal true, app.respond_to?(:connection_pool)
-    assert_equal fn, app.connection_pool.with_db { it.filename }
-
-    assert_equal true, app.respond_to?(:schema)
-    app.schema.apply(app.connection_pool)
-    assert_equal '2026-05-30-bar', app.schema.current_version(app.connection_pool)
-
-    assert_equal [
-      {
-        id: 1,
-        title: 'foo',
-        body: 'baz'
-      }
-    ], app.connection_pool.query('select id, title, body from posts')
-
-  end
-end

data/test/test_caching.rb

@@ -6,7 +6,7 @@ require 'digest/sha1'
 class CachingTest < Minitest::Test
   HTTP = Syntropy::HTTP
 
-  APP_ROOT = File.join(__dir__, 'app')
+  APP_ROOT = File.join(__dir__, 'fixtures/app')
 
   def make_socket_pair
     port = SecureRandom.random_number(10000..40000)
@@ -32,7 +32,7 @@ class CachingTest < Minitest::Test
 
     @env = {
       machine: @machine,
-      root_dir: APP_ROOT,
+      app_root: APP_ROOT,
       mount_path: '/test',
       watch_files: 0.05
     }

data/test/test_db_schema.rb

@@ -77,7 +77,7 @@ class DBSchemaTest < Minitest::Test
 
   def test_schema_from_module_files
     module_loader = Syntropy::ModuleLoader.new({
-      root_dir: File.join(__dir__, 'schema')
+      app_root: File.join(__dir__, 'fixtures/schema')
     })
     schema = Syntropy::DB::Schema.new(module_loader:, schema_root: '/')
 

data/test/test_http_server_connection.rb

@@ -454,7 +454,7 @@ class HTTPServerConnectionTest < Minitest::Test
     write_client_side("GET / HTTP/1.1\r\n\r\n")
     @machine.spin do
       @connection.serve_request
-    rescue => e
+    rescue StandardError => e
       p e
       p e.backtrace
     end
@@ -479,7 +479,7 @@ class HTTPServerConnectionTest < Minitest::Test
 
     @hook = ->(req) do
       req.respond_with_static_file(fn, nil, nil, nil)
-    rescue => e
+    rescue StandardError => e
       p e
       p e.backtrace
     end
@@ -490,7 +490,7 @@ class HTTPServerConnectionTest < Minitest::Test
     write_client_side("GET / HTTP/1.1\r\n\r\n")
     @machine.spin do
       @connection.serve_request
-    rescue => e
+    rescue StandardError => e
       p e
       p e.backtrace
     end