syntropy 0.37.0 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb6c66cfca4b2d7be9060c5571028b5356950fb34f8fba634b0d43b97169cd48
-  data.tar.gz: 447b2442d22332e0642869e01eee03889d8c85ba31e58909d603382be51f4c7d
+  metadata.gz: 85989e43beae58a319d108e1c8cf42f8265fdfaa0675c0fa2b0b8c8df5dbfbd1
+  data.tar.gz: cd2dd5db7add2b3e3aa74f2a3fa02da3c1896b808a46be16b088e264875aec10
 SHA512:
-  metadata.gz: 19d092f17b75b7cc3290cb2802f46bd19efbb30855f3acf78e1cfc2f88084e0c0dca68bbfcd661545bd50def484cc9526d8a2f4057c9a6da8d6639c95b2cd8c4
-  data.tar.gz: 34d839e355da94f8993ffefa1a48c9bebfecb6da9c6b43cfe7f934d4fe8a804889d2a7a75874f0107b3226bd6a880037466610f4cffd87d48bdab2f19c5e0545
+  metadata.gz: 3cd0fb5d085456bc8d51db049fecaf11f000071cde6b19dd224c7ec422e1fb749be3ba92dfd5b8a43e3e95313f99b1ffed5f926ca37abd5377e2badd249576f3
+  data.tar.gz: c3a2b789fe2c9cfbff79b2245381f3ee76bad2e905e3f8408df2666af1495b51f93988d7085c1957330b194237f366e0999b43eb25b8e0e42954f07146aaa5cb

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 0.38.0 2026-06-13
+
+- Reimplement controller extensions: `dispatch_by_host`,
+  `dispatch_by_http_method`
+- Fix middleware composition
+- Add CLI command shortcuts
+- Rename `Syntropy::Module` to `Syntropy::ModuleContext`
+
 # 0.37.0 2026-06-07
 
 - Call `IO#clear` before closing server connection

data/Gemfile

@@ -1,3 +1,7 @@
 source 'https://gem.coop'
 
 gemspec
+
+group :development do
+  gem 'roda'
+end

data/TODO.md

@@ -1,5 +1,9 @@
 ## Immediate
 
+- [ ] Controllers
+  - [ ] Streamline names of ready-made control methods:
+    - [ ] dispatch_json_rpc
+
 - [ ] Collection - treat directories and files as collections of data.
 
   Kind of similar to the routing tree, but instead of routes it just takes a

data/bin/syntropy

@@ -1,13 +1,23 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require_relative '../cmd/_banner'
-
 def cmd_fn(cmd)= File.join(__dir__, "../cmd/#{cmd}.rb")
 
 cmd = ARGV.shift || 'help'
 cmd = 'help' if cmd !~ /^[a-z]+$/
 
+SHORTCUTS = {
+  'c' => 'console',
+  'n' => 'new',
+  's' => 'serve',
+  't' => 'test',
+  'v' => 'version'
+}
+
+if (target_cmd = SHORTCUTS[cmd])
+  cmd = target_cmd
+end
+
 fn = cmd_fn(cmd)
 fn = cmd_fn('help') if !File.file?(fn)
 

data/cmd/help.rb

@@ -5,8 +5,12 @@ HELP = <<~MSG
 
   Available commands:
 
+    console   Start an IRB session
+    help      Show this message
+    new       Create a new Syntropy app
     serve     Start a Syntropy server
     test      Run tests
+    version   Show version information
 MSG
 
 $stdout << HELP

data/cmd/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'syntropy/version'
+require 'uringmachine/version'
+require_relative './_banner'
+
+VERSION = <<~MSG
+      Syntropy version #{Syntropy::VERSION}
+  UringMachine version #{UringMachine::VERSION}
+          Ruby version #{RUBY_VERSION}
+MSG
+
+$stdout << SYNTROPY_BANNER
+$stdout << VERSION

data/examples/blog/app/posts/[id]/edit.rb

@@ -1,7 +1,7 @@
 @posts = import '/_lib/posts'
 @layout = import '/_layout/default'
 
-export http_methods
+export dispatch_by_http_method
 
 def get(req)
   id = req.route_params['id'].to_i

data/examples/blog/app/posts/[id]/index.rb

@@ -1,7 +1,7 @@
 @posts = import '/_lib/posts'
 @layout = import '/_layout/default'
 
-export http_methods
+export dispatch_by_http_method
 
 def get(req)
   id = req.route_params['id'].to_i

data/examples/blog/app/posts/index.rb

@@ -1,7 +1,7 @@
 @posts = import '_lib/posts'
 @layout = import '_layout/default'
 
-export http_methods
+export dispatch_by_http_method
 
 def get(req)
   posts = @posts.get_all

data/examples/blog/app/posts/new.rb

@@ -1,7 +1,7 @@
 @posts = import '/_lib/posts'
 @layout = import '/_layout/default'
 
-export http_methods
+export dispatch_by_http_method
 
 def get(req)
   req.respond_html(

data/lib/syntropy/app.rb

@@ -9,6 +9,7 @@ require 'syntropy/errors'
 require 'syntropy/module_loader'
 require 'syntropy/routing_tree'
 require 'syntropy/mime_types'
+require 'syntropy/controller_extensions'
 
 module Syntropy
   # The App implements a Syntropy application. It is responsible for handling
@@ -34,7 +35,7 @@ module Syntropy
         fn = File.join(env[:app_root], '_site.rb')
         return nil if !File.file?(fn)
 
-        loader = Syntropy::ModuleLoader.new(env)
+        loader = Syntropy::ModuleLoader.new(env, extensions: ControllerExtensions)
         loader.load('_site')
       end
 
@@ -61,7 +62,10 @@ module Syntropy
       @env = env
       @logger = env[:logger]
 
-      @module_loader = Syntropy::ModuleLoader.new(app: self, **env)
+      @module_loader = Syntropy::ModuleLoader.new(
+        env.merge(app: self),
+        extensions: ControllerExtensions
+      )
       setup_routing_tree
       start
     end

data/lib/syntropy/controller_extensions.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Syntropy
+  # Utilities for use in modules
+  module ControllerExtensions
+    # Returns a unique temporary path
+    #
+    # @param prefix [String] temp file prefix
+    # @return [String]
+    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 dir [String, nil] relative directory path for host sites
+    # @param map [Hash, nil] hash mapping host names to relative site directory
+    # @return [Proc] router proc
+    def dispatch_by_host(dir = nil, map = nil)
+      raise Syntropy::Error, 'Must provide dir and/or map' if !dir && !map
+
+      site_map = {}
+      setup_directory_sites(dir, site_map) if dir
+      setup_mapped_sites(map, site_map) if map
+
+      ->(req) do
+        site = site_map[req.host]
+        site ? site.call(req) : req.respond(nil, ':status' => HTTP::BAD_REQUEST)
+      end
+    end
+
+    # Returns a request handler that handles requests by calling the appropriate
+    # module method (e.g. get, post, etc.)
+    #
+    # @return [Proc]
+    def dispatch_by_http_method
+      ->(req) do
+        route_by_http_method(req)
+      end
+    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[:app_root], ref)
+      raise 'Not a directory' if !File.directory?(full_path)
+
+      Dir[File.join(full_path, '*.md')].sort.map {
+        atts, markdown = Syntropy::Markdown.parse(it, env)
+        { atts:, markdown: }
+      }
+    end
+
+    # Instantiates a Syntropy app for the given environment hash.
+    #
+    # @return [Syntropy::App]
+    def app(**)
+      Syntropy::App.new(**)
+    end
+
+    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],
+        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, adds
+    # entries to the given site map.
+    #
+    # @param dir [String] relative or absolute path
+    # @param site_map [Hash] site map
+    # @return [void]
+    def setup_directory_sites(ref, site_map)
+      app_root = @app ? @app.app_root : @env[:app_root]
+      ref = normalize_import_ref(ref)
+
+      Dir[File.join(app_root, ref, '*')]
+        .select { File.directory?(it) && File.basename(it) !~ /^_/ }
+        .each { |entry| site_map[File.basename(entry)] = make_app(entry) }
+    end
+
+    # converts the given map entries by adding entries to the given site map.
+    #
+    # @param map [Hash] ref map
+    # @param site_map [Hash] site map
+    # @return [void]
+    def setup_mapped_sites(map, site_map)
+      app_root = @app ? @app.app_root : @env[:app_root]
+      map.each do |name, ref|
+        ref = File.join(File.dirname(@ref), ref) if ref !~ /^\//
+        site_root = File.join(app_root, ref)
+        site_map[name] = make_app(site_root)
+      end
+    end
+
+    # Creates an app loaded from the given root directory, with the present
+    # mount path.
+    def make_app(site_root)
+      mount_path = @ref == '/_site' ? '/' : @ref
+      env = @env.merge(app_root: site_root, mount_path:)
+      Syntropy::App.new(**env)
+    end
+
+    # Handles the given request by calling the module method corresponding to
+    # the request's HTTP method. If no method is found, raises a
+    # method_not_allowed error.
+    def route_by_http_method(req)
+      sym = req.method.to_sym
+      raise Syntropy::Error.method_not_allowed if !respond_to?(sym)
+
+      send(sym, req)
+    end
+  end
+end

data/lib/syntropy/module_loader.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'papercraft'
+require 'syntropy/errors'
 
 module Syntropy
   # The ModuleLoader class implemenets a module loader. It handles loading of
@@ -25,12 +26,14 @@ module Syntropy
     # Instantiates a module loader
     #
     # @param env [Hash] environment hash
+    # @param extensions [Module, Array<Module>] extension module(s)
     # @return [void]
-    def initialize(env)
+    def initialize(env, extensions: nil)
       @env = env
       @app_root = env[:app_root]
       @modules = {} # maps ref to module entry
       @fn_map = {} # maps filename to ref
+      @extensions = extensions
     end
 
     # Loads a module (if not already loaded) and returns its export value.
@@ -131,7 +134,7 @@ module Syntropy
       @fn_map[fn] = ref
       code = IO.read(fn)
       env = @env.merge(module_loader: self, ref: clean_ref(ref))
-      mod = Syntropy::Module.load(env, code, fn)
+      mod = Syntropy::ModuleContext.load(env, code, fn, @extensions)
       add_dependencies(ref, mod.__dependencies__)
       export_value = transform_module_export_value(
         mod.__export_value__, fn, raise_on_missing:
@@ -150,10 +153,10 @@ module Syntropy
     # @param ref [String] input ref
     # @return [String] clean ref
     def clean_ref(ref)
-      return '/' if ref =~ /^index(\+)?$/
+      return '/' if ref =~ /^index[+]?$/
 
-      clean = ref.gsub(/\/index(?:\+)?$/, '')
-      clean == '' ? '/' : clean
+      clean = ref.gsub(/\/index[+]?$/, '')
+      (clean == '') ? '/' : clean
     end
 
     # Transforms the given export value. If the value is nil, an exception is
@@ -173,9 +176,9 @@ module Syntropy
     end
   end
 
-  # The Syntropy::Module class implements a reloadable module. A module is a
-  # `.rb` source file that implements a route endpoint, a template, utility
-  # methods or any other functionality needed by the web app.
+  # The Syntropy::ModuleContext class provides a context for loading a module. A
+  # module is a `.rb` source file that implements a route endpoint, a template,
+  # utility methods or any other functionality needed by the web app.
   #
   # The following instance variables are available to modules:
   #
@@ -189,35 +192,45 @@ module Syntropy
   # In addition, the module code also has access to the `MODULE` constant which
   # is set to `self`, and may be used to refer to various methods defined in the
   # module.
-  class Module
+  class ModuleContext
     # Loads a module, returning the module instance
-    def self.load(env, code, fn)
-      m = new(**env)
-      m.instance_eval(code, fn)
+    # @param env [Hash] app environment
+    # @param code [String] module source code
+    # @param fn [String] module file name
+    # @param extensions [Module, Array<Module>] extension module(s)
+    # @return [Syntropy::ModuleContext] created module context
+    def self.load(env, code, fn, extensions)
+      mod = new(env)
+      apply_extensions(mod, extensions)
+      mod.instance_eval(code, fn)
       env[:logger]&.info(message: "Loaded module at #{fn}")
-      m
-    rescue SyntaxError => e
+      mod
+    rescue StandardError, SyntaxError => e
       env[:logger]&.error(message: "Error while loading module at #{fn}", error: e)
-      STDERR.puts("\n#{e.message}") if !Syntropy.test_mode
+      e.is_a?(SyntaxError) ? handle_syntax_error(env, e) : (raise e)
+    end
 
-      if (m = e.message.match(/^(.+)\: syntax/))
-        location = m[1]
-        e2 = SyntaxError.new("Syntax errors found in module #{env[:ref]}")
-        e2.set_backtrace([location] + e.backtrace)
-        raise e2
+    # Applies the given extension(s) to the given module context.
+    #
+    # @param mod [Syntropy::ModuleContext] module context
+    # @param extensions [Module, Array<Module>] extension module(s)
+    def self.apply_extensions(mod, extensions)
+      case extensions
+      when Array
+        extensions.each { mod.extend(it) }
+      when Module
+        mod.extend(extensions)
+      when nil # return
       else
-        raise e
+        raise Syntropy::Error, "Invalid module extensions: #{extensions.inspect}"
       end
-    rescue => e
-      env[:logger]&.error(message: "Error while loading module at #{fn}", error: e)
-      raise e
     end
 
     # Initializes a module with the given environment hash.
     #
     # @param env [Hash] environment hash
     # @return [void]
-    def initialize(**env)
+    def initialize(env)
       @env = env
       @machine = env[:machine]
       @module_loader = env[:module_loader]
@@ -329,22 +342,15 @@ module Syntropy
       Syntropy::App.new(**env)
     end
 
-    # Returns a request handler that handles requests by calling the appropriate
-    # module method (e.g. get, post, etc.)
-    #
-    # @return [Proc]
-    def http_methods
-      ->(req) { route_by_http_method(req) }
-    end
-
-    # Handles the given request by calling the module method corresponding to
-    # the request's HTTP method. If no method is found, raises a
-    # method_not_allowed error.
-    def route_by_http_method(req)
-      sym = req.method.to_sym
-      raise Syntropy::Error.method_not_allowed if !respond_to?(sym)
+    def handle_syntax_error(env, e)
+      $stderr.puts("\n#{e.message}") if !Syntropy.test_mode
+      m = e.message.match(/^(.+): syntax/)
+      raise e if !m
 
-      send(sym, req)
+      location = m[1]
+      e2 = SyntaxError.new("Syntax errors found in module #{env[:ref]}")
+      e2.set_backtrace([location] + e.backtrace)
+      raise e2
     end
   end
 end

data/lib/syntropy/routing_tree.rb

@@ -339,8 +339,8 @@ module Syntropy
           target: { kind:, fn: },
           # In case we're at the tree root, we need to copy over the hook and
           # error refs.
-          hook: !parent[:parent] && parent[:hook],
-          error: !parent[:parent] && parent[:error]
+          hook: parent[:hook],
+          error: parent[:error]
         }
       end
       nil
@@ -458,9 +458,9 @@ module Syntropy
         emit_router_proc_prelude(buffer)
         segment_idx = 1
         if @root[:path] != '/'
-          root_parts = @root[:path].split('/')
-          segment_idx = root_parts.size
-          emit_root_validate_guard(buffer:, root_parts:)
+          root_segments = @root[:path].split('/')
+          segment_idx = root_segments.size
+          emit_root_validate_guard(buffer:, root_segments:)
         end
 
         visit_routing_tree_entry(buffer:, entry: @root, segment_idx:)
@@ -492,18 +492,18 @@ module Syntropy
     def emit_router_proc_prelude(buffer)
       emit_code_line(buffer, '->(path, params) {')
       emit_code_line(buffer, '  entry = @static_map[path]; return entry if entry')
-      emit_code_line(buffer, '  parts = path.split("/")')
+      emit_code_line(buffer, '  segments = path.split("/")')
     end
 
     # Emits root path validation guard code.
     #
     # @param buffer [String] output buffer
-    # @param root_parts [Array<String>] root path parts
+    # @param root_segments [Array<String>] root path segments
     # @return [void]
-    def emit_root_validate_guard(buffer:, root_parts:)
+    def emit_root_validate_guard(buffer:, root_segments:)
       validate_parts = []
-      (1...root_parts.size).each do |i|
-        validate_parts << "(parts[#{i}] != #{root_parts[i].inspect})"
+      (1...root_segments.size).each do |i|
+        validate_parts << "(segments[#{i}] != #{root_segments[i].inspect})"
       end
       emit_code_line(buffer, "  return nil if #{validate_parts.join(' || ')}")
     end
@@ -568,7 +568,7 @@ module Syntropy
 
       # Get next segment
       if !case_buffer.empty?
-        emit_code_line(buffer, "#{ws}case (p = parts[#{segment_idx}])")
+        emit_code_line(buffer, "#{ws}case (s = segments[#{segment_idx}])")
         buffer << case_buffer
         emit_code_line(buffer, "#{ws}end")
       end
@@ -630,7 +630,7 @@ module Syntropy
           next if child_entry[:static]
 
           emit_code_line(buffer, "#{ws}when #{k.inspect}")
-          if_clause = child_entry[:handle_subtree] ? '' : " if !parts[#{segment_idx + 1}]"
+          if_clause = child_entry[:handle_subtree] ? '' : " if !segments[#{segment_idx + 1}]"
 
           child_path = child_entry[:path]
           route_value = "@dynamic_map[#{child_path.inspect}]"
@@ -657,12 +657,12 @@ module Syntropy
       # parametric route
       if param_entry
         if when_count == 0
-          emit_code_line(buffer, "#{ws}when p")
+          emit_code_line(buffer, "#{ws}when s")
         else
           emit_code_line(buffer, "#{ws}else")
         end
 
-        emit_code_line(buffer, "#{ws}  params[#{param_entry[:param].inspect}] = p")
+        emit_code_line(buffer, "#{ws}  params[#{param_entry[:param].inspect}] = s")
         visit_routing_tree_entry(buffer:, entry: param_entry, indent: indent + 1, segment_idx: segment_idx + 1)
       # wildcard route
       elsif entry[:handle_subtree]

data/lib/syntropy/test.rb

@@ -11,12 +11,9 @@ module Syntropy
   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
+    class << self
+      # Gets/sets app environment for tests
+      attr_accessor :env
     end
 
     attr_reader :machine, :app
@@ -25,7 +22,7 @@ module Syntropy
     #
     # @return [Hash] test app environment
     def env
-      @@env
+      self.class.env
     end
 
     # Loads and returns a module with the given reference.
@@ -101,17 +98,38 @@ module Syntropy
       post(path, 'application/x-www-form-urlencoded', URI.encode_www_form(data), **)
     end
 
+    # Makes an HTTP PATCH 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 patch(path, content_type, body, **headers)
+      headers = headers.merge('content-type' => content_type) if content_type
+      http_request(
+        headers.merge(
+          {
+            ':method' => 'PATCH',
+            ':path'   => path
+          }
+        ),
+        body
+      )
+    end
+
     # Sets up a test instance.
     #
     # @return [void]
     def setup
-      raise 'Environment not set' if !@@env
+      env = self.class.env
+      raise 'Environment not set' if !env
 
-      Syntropy.load_config(@@env)
+      Syntropy.load_config(env)
 
       @machine = UM.new
       @app = Syntropy::App.new(
-        **@@env.merge(
+        **env.merge(
           machine: @machine,
           test_mode: true
         )

data/lib/syntropy/version.rb

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

data/lib/syntropy.rb

@@ -17,15 +17,12 @@ require 'syntropy/papercraft_extensions'
 require 'syntropy/routing_tree'
 require 'syntropy/json_api'
 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, :dev_mode, :test_mode