syntropy 0.5 → 0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f125135bc3ed83c1050467241f48caf366600fead1d75db79455038e42e311a
-  data.tar.gz: ee9bd2bbf906eea9c90481ecdf643126285f65f63fe66a3f2b4f3050893e7c28
+  metadata.gz: b86a65bfeb990aa38b76b5bb6487210887e7103bab652e40c3790d68c1ab48df
+  data.tar.gz: 89397a9faf63d2a07c69ab69f93048cb92c82014e30d7ca6ed9399671c17bb48
 SHA512:
-  metadata.gz: 0bdce31c490701521d73829c02e1193fcd0da399b1e6186066ad5d6ecfa067dc143941300bf670fa4b447d5d5c177e903fa273d9d6d5bbfa2319ec0c74fd2678
-  data.tar.gz: 7b5eddf105f8654f379bf1d7f52948b713ee342dbd97eb1896e28b618b442ccf33c716d27a7f67c21cfd2c65f610b5c9677cd5e4faa0e777b8f727552628865c
+  metadata.gz: 0f536c81be4baa5c8e8733705a9a41042b322eb3960ee8a092523bfdfff886893a4183a6b00c69c2960daefe6443a6f06ee0e07596eeb5ffc3b45ceceb86c342
+  data.tar.gz: 05c3e6c5d3641847a0c962811e290313f7d08a4233504466035e94cfc03284cf652f990f5fd4681efd059673050fda5d021bba5a982c0e539b8c3351bd316913

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.7 2025-07-05
+
+- Implement `Module.route_by_host`
+- Add snoozing on DB progress
+
+## 0.6 2025-07-05
+
+- Add support for middleware and error handlers
+
 ## 0.5 2025-07-05
 
 - Refactor App class to use Router

data/README.md

@@ -59,6 +59,7 @@ site/
 ├ _articles/
 | └ 2025-01-01-hello_world.md
 ├ api/
+| ├ _hook.rb
 | └ v1.rb
 ├ assets/
 | ├ css/
@@ -73,10 +74,30 @@ site/
 Syntropy knows how to serve static asset files (CSS, JS, images...) as well as
 render markdown files and run modules written in Ruby.
 
+Some conventions employed in Syntropy-based web apps:
+
+- Files and directories starting with an underscore, e.g. `/_layout` are
+  considered private, and are not exposed to HTTP clients.
+- Normally, a module route only responds to its exact path. To respond to any
+  subtree path, add a plus sign to the end of the module name, e.g. `/api+.rb`.
+- A `_hook.rb` module is invoked on each request routed to anywhere in the
+  corresponding subtree. For example, a hook defined in `/api/_hook.rb` will be
+  used on requests to `/api`, `/api/foo`, `/api/bar` etc.
+- As a corollary, each route "inherits" all hooks defined up the tree. For
+  example, a request to `/api/foo` will invoke hooks defined in `/api/_hook.rb`
+  and `/_hook.rb`.
+- In a similar fashion to hooks, error handlers can be defined for different
+  subtrees in a `_error.rb` module. For each route, in case of an exception,
+  Syntropy will invoke the closest-found error handler module up the tree. For
+  example, an error raised while responding to a request to `/api/foo` will
+  prefer the error handler in `/api/_error.rb`, rather than `/_error.rb`.
+- The Syntrpy router accepts clean URLs for Ruby modules and Markdown files. It
+  also accepts clean URLs for `index.html` files.
+
 ## What does a Syntropic Ruby module look like?
 
-Consider `archive.rb` in the example above. We want to get a list of articles
-and render it with the given layout:
+Consider `site/archive.rb` in the file tree above. We want to get a list of
+articles and render it using the given layout:
 
 ```ruby
 # archive.rb
@@ -97,7 +118,7 @@ export @@layout.apply(title: 'archive') {
 }
 ```
 
-But a module can be something completely different:
+But a module can also be something completely different:
 
 ```ruby
 # api/v1.rb
@@ -121,4 +142,114 @@ export APIV1
 ```
 
 Basically, the exported value can be a template, a callable or a class that
-responds to the request.
+responds to the request. Here's a minimal module that responds with a hello
+world:
+
+```ruby
+export ->(req) { req.respond('Hello, world!') }
+```
+
+## Module Export / Import
+
+Modules communicate with the Syntropy framework and with other modules using
+`export` and `import`. Each module must export a single object, which can be a
+controller class, a callable (a proc/closure) or a template. The exported object
+is used by Syntropy as the entrypoint for the route.
+
+But modules can also import other modules. This permits the use of layouts:
+
+```ruby
+# site/_layout/default.rb
+export template { |**props|
+  header {
+    h1 'Foo'
+  }
+  content {
+    emit_yield(**props)
+  }
+}
+
+# site/index.rb
+layout = import '_layout/default'
+
+export layout.apply { |**props|
+  p 'o hi!'
+}
+```
+
+A module can also be written as a set of methods without any explicit class
+definition. This allows writing modules in a more functional style:
+
+```ruby
+# site/_lib/utils.rb
+
+def foo
+  42
+end
+
+export self
+
+# site/index.rb
+Utils = import '_lib/utils'
+
+export template {
+  h1 "foo = #{Utils.foo}"
+}
+```
+
+## Hooks (a.k.a. Middleware)
+
+A hook is a piece of code that can intercept HTTP requests before they are
+passed off to the correspending route. Hooks are applied to the subtree of the
+directory in which they reside.
+
+Hooks can be used for a variety of purposes:
+
+- Parameter validation
+- Authentication, authorization & session management
+- Logging
+- Request rewriting / redirecting
+
+When multiple hooks are defined up the tree for a particular route, they are
+chained together such that each hook is invoked starting from the file tree root
+and down to the route path.
+
+Hooks are implemented as modules named `_hook.rb`, that export procs (or
+callables) with the following signature:
+
+```ruby
+# **/_hook.rb
+export ->(req, app) { ... }
+```
+
+... where req is the request object, and app is the callable that code. Here's
+an example of an authorization hook:
+
+```ruby
+export ->(req, app) {
+  if (!req.cookies[:session_id])
+    req.redirect('/signin')
+  else
+    app.(req)
+  end
+}
+```
+
+## Error handlers
+
+An error handler can be defined separately for each subtree. When an exception
+is raised that is not rescued by the application code, Syntropy will look for an
+error handler up the file tree, and will invoke the first error handler found.
+
+Error handlers are implemented as modules named `_error.rb`, that export procs (or
+callables) with the following signature:
+
+```ruby
+# **/_error.rb
+->(req, err) { ... }
+```
+
+Using different error handlers for parts of the route tree allows different
+error responses for each route. For example, the error response for an API route
+can be a JSON object, while the error response for a browser page route can be a
+custom HTML page.

data/TODO.md

@@ -1,44 +1,33 @@
-- Refactor routing code into a separate Router class.
-- The Router class is in charge of:
-  - caching routes
-  - loading modules
-  - unloading modules on file change
-  - calculating middleware for routes
-    - middleware is defined in `_hook.rb` modules
-      - interface: ->(req, next)
-    - a special case for handling errors is `_error.rb`
-      - interface: ->(req, err)
-  - dispatching routes
-    - error handling:
-      - on uncaught error, if an `_error.rb` file exists in the same directory
-        or up the file tree
-    - middleware:
-      - a closure is created from the composition of the different hooks
-        defined, from the route's directory and up the file
-    - error handlers and middleware closures are cached as part of the route's
-      entry
-    - on file change for any _hook.rb or _error.rb files, all route entries in
-      the corresponding subtree are invalidated
-
-
-- Middleware
+- Some standard middleware:
+
+  - request rewriter
+  - logger
+  - auth
+  - selector + terminator
 
   ```Ruby
-  # site/_hook.rb
-  export ->(req, &app) do
-    app.call(req)
-  rescue Syntropy::Error => e
-    render_error_page(req, e.http_status)
+  # For the chainable DSL shown below, we need to create a custom class:
+  class Syntropy::Middleware::Selector
+    def initialize(select_proc, terminator_proc = nil)
+      @select_proc = select_proc
+      @terminator_proc = terminator_proc
+    end
+
+    def to_proc
+      ->(req, proc) {
+        @select_proc.(req) ? @terminator_proc.(req) : proc(req)
+      }
+    end
+
+    def terminate(&proc)
+      @terminator_proc = proc
+    end
   end
 
-  # an alternative, at least for errors is a _error.rb file:
-  # site/_error.rb
-  # Just a normal callable:
-  #
-  export ->(req, err) do
-    render_error_page(req, err.http_status)
-  end
+  def Syntropy
+  ```
 
+  ```Ruby
   # a _site.rb file can be used to wrap a whole app
   # site/_site.rb
 

data/lib/syntropy/app.rb

@@ -32,20 +32,20 @@ module Syntropy
       end
     end
 
-    def initialize(machine, src_path, mount_path, opts = {})
+    def initialize(machine, location, mount_path, opts = {})
       @machine = machine
-      @src_path = File.expand_path(src_path)
+      @location = File.expand_path(location)
       @mount_path = mount_path
       @opts = opts
 
-      @module_loader = Syntropy::ModuleLoader.new(@src_path, @opts)
+      @module_loader = Syntropy::ModuleLoader.new(@location, @opts)
       @router = Syntropy::Router.new(@opts, @module_loader)
 
       @machine.spin do
         # we do startup stuff asynchronously, in order to first let TP2 do its
         # setup tasks
         @machine.sleep 0.15
-        @opts[:logger]&.call("Serving from #{File.expand_path(@src_path)}")
+        @opts[:logger]&.call("Serving from #{File.expand_path(@location)}")
         @router.start_file_watcher if opts[:watch_files]
       end
     end
@@ -65,21 +65,32 @@ module Syntropy
     private
 
     def render_entry(req, entry)
+      kind = entry[:kind]
+      return respond_not_found(req) if kind == :not_found
+
+      entry[:proc] ||= calculate_route_proc(entry)
+      entry[:proc].(req)
+    end
+
+    def calculate_route_proc(entry)
+      render_proc = route_render_proc(entry)
+      @router.calc_route_proc_with_hooks(entry, render_proc)
+    end
+
+    def route_render_proc(entry)
       case entry[:kind]
-      when :not_found
-        respond_not_found(req, entry)
       when :static
-        respond_static(req, entry)
+        ->(req) { respond_static(req, entry) }
       when :markdown
-        respond_markdown(req, entry)
+        ->(req) { respond_markdown(req, entry) }
       when :module
-        respond_module(req, entry)
+        load_module(entry)
       else
         raise 'Invalid entry kind'
       end
     end
 
-    def respond_not_found(req, _entry)
+    def respond_not_found(req)
       headers = { ':status' => Qeweney::Status::NOT_FOUND }
       case req.method
       when 'head'
@@ -124,7 +135,7 @@ module Syntropy
     end
 
     def load_module(entry)
-      ref = entry[:fn].gsub(%r{^#{@src_path}/}, '').gsub(/\.rb$/, '')
+      ref = entry[:fn].gsub(%r{^#{@location}/}, '').gsub(/\.rb$/, '')
       o = @module_loader.load(ref)
       o.is_a?(Papercraft::Template) ? wrap_template(o) : o
     rescue Exception => e

data/lib/syntropy/connection_pool.rb

@@ -34,9 +34,7 @@ module Syntropy
     private
 
     def checkout
-      if @queue.count == 0 && @count < @max_conn
-        return create_db
-      end
+      return make_db_instance if @queue.count == 0 && @count < @max_conn
 
       @machine.shift(@queue)
     end
@@ -45,16 +43,11 @@ module Syntropy
       @machine.push(@queue, db)
     end
 
-    def create_db
-      db = Extralite::Database.new(@fn, wal: true)
-      setup_db(db)
-      @count += 1
-      db
-    end
-
-    def setup_db(db)
-      # setup WAL, sync
-      # setup concurrency stuff
+    def make_db_instance
+      Extralite::Database.new(@fn, wal: true).tap do
+        @count += 1
+        it.on_progress(mode: :at_least_once, period: 320, tick: 10) { @machine.snooze }
+      end
     end
   end
 end

data/lib/syntropy/module.rb

@@ -33,6 +33,7 @@ module Syntropy
       mod_body = IO.read(fn)
       mod_ctx = Class.new(Syntropy::Module)
       mod_ctx.loader = self
+      mod_ctx.env = @env
       mod_ctx.module_eval(mod_body, fn, 1)
 
       export_value = mod_ctx.__export_value__
@@ -66,6 +67,10 @@ module Syntropy
       @loader = loader
     end
 
+    def self.env=(env)
+      @env = env
+    end
+
     def self.import(ref)
       @loader.load(ref)
     end
@@ -74,12 +79,29 @@ module Syntropy
       @__export_value__ = ref
     end
 
-    def self.templ(&block)
+    def self.template(&block)
       Papercraft.html(&block)
     end
 
+    def self.route_by_host
+      root = @env[:location]
+      sites = Dir[File.join(root, '*')]
+        .select { File.directory?(it) }
+        .inject({}) { |h, fn|
+          name = File.basename(fn)
+          opts = @env.merge(location: fn)
+          h[name] = Syntropy::App.new(opts[:machine], opts[:location], opts[:mount_path], opts)
+          h
+        }
+      ->(req) {
+        site = sites[req.host]
+        site ? site.call(req) : req.respond(nil, ':status' => Status::BAD_REQUEST)
+      }
+    end
+
     def self.__export_value__
       @__export_value__
     end
+
   end
 end

data/lib/syntropy/router.rb

@@ -2,8 +2,6 @@
 
 module Syntropy
   class Router
-    attr_reader :cache
-
     def initialize(opts, module_loader = nil)
       raise 'Invalid location given' if !File.directory?(opts[:location])
 
@@ -32,6 +30,10 @@ module Syntropy
       @machine.spin { file_watcher_loop }
     end
 
+    def calc_route_proc_with_hooks(entry, proc)
+      compose_up_tree_hooks(entry[:fn], proc)
+    end
+
     private
 
     HIDDEN_RE = /^_/
@@ -204,5 +206,35 @@ module Syntropy
     def remove_entry_cache_keys(entry)
       entry[:cache_keys]&.each_key { @cache.delete(it) }.clear
     end
+
+    def compose_up_tree_hooks(path, proc)
+      parent = File.dirname(path)
+      proc = hook_wrap_if_exists(File.join(parent, '_hook.rb'), proc)
+      proc = error_handler_wrap_if_exists(File.join(parent, '_error.rb'), proc)
+      return proc if parent == @root
+
+      compose_up_tree_hooks(parent, proc)
+    end
+
+    def hook_wrap_if_exists(hook_fn, proc)
+      return proc if !File.file?(hook_fn)
+
+      ref = path_rel(hook_fn).gsub(/\.rb$/, '')
+      hook_proc = @module_loader.load(ref)
+      ->(req) { hook_proc.(req, proc) }
+    end
+
+    def error_handler_wrap_if_exists(error_handler_fn, proc)
+      return proc if !File.file?(error_handler_fn)
+
+      ref = path_rel(error_handler_fn).gsub(/\.rb$/, '')
+      error_proc = @module_loader.load(ref)
+
+      proc do |req|
+        proc.(req)
+      rescue StandardError => e
+        error_proc.(req, e)
+      end
+    end
   end
 end

data/lib/syntropy/version.rb

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

data/test/app/_hook.rb

@@ -0,0 +1,4 @@
+export ->(req, proc) {
+  req.ctx[:foo] = req.query[:foo]
+  proc.(req)
+}

data/test/app/_layout/default.rb

@@ -1,4 +1,4 @@
-->(**props) {
+export template { |**props|
   header {
     h1 'Foo'
   }

data/test/app/_lib/self.rb

@@ -0,0 +1,5 @@
+def foo
+  :bar
+end
+
+export self

data/test/app/about/_error.rb

@@ -0,0 +1,6 @@
+DEFAULT_STATUS = Qeweney::Status::INTERNAL_SERVER_ERROR
+
+export ->(req, err) {
+  status = err.respond_to?(:http_status) ? err.http_status : DEFAULT_STATUS
+  req.respond("<h1>#{err.message}</h1>", ':status' => status, 'Content-Type' => 'text/html')
+}

data/test/app/about/raise.rb

@@ -0,0 +1,3 @@
+export ->(req) {
+  raise 'Raised error'
+}

data/test/app/api+.rb

@@ -15,6 +15,10 @@ class API < Syntropy::RPCAPI
 
     @count += 1
   end
+
+  def req(req)
+    { query: req.query, headers: req.headers }
+  end
 end
 
 export API

data/test/app_multi_site/_site.rb

@@ -0,0 +1 @@
+export route_by_host

data/test/app_multi_site/bar.baz/index.html

@@ -0,0 +1 @@
+<h1>bar.baz</h1>

data/test/app_multi_site/foo.bar/index.html

@@ -0,0 +1 @@
+<h1>foo.bar</h1>

data/test/test_app.rb

@@ -140,6 +140,18 @@ class AppTest < Minitest::Test
   ensure
     IO.write(@tmp_fn, orig_body) if orig_body
   end
+
+  def test_middleware
+    req = make_request(':method' => 'HEAD', ':path' => '/test?foo=42')
+    assert_equal Status::OK, req.response_status
+    assert_nil req.response_body
+    assert_equal '42', req.ctx[:foo]
+
+    req = make_request(':method' => 'HEAD', ':path' => '/test/about/raise?foo=43')
+    assert_equal Status::INTERNAL_SERVER_ERROR, req.response_status
+    assert_equal '<h1>Raised error</h1>', req.response_body
+    assert_equal '43', req.ctx[:foo]
+  end
 end
 
 class CustomAppTest < Minitest::Test
@@ -168,3 +180,36 @@ class CustomAppTest < Minitest::Test
     assert_equal Status::TEAPOT, req.response_status
   end
 end
+
+class MultiSiteAppTest < Minitest::Test
+  Status = Qeweney::Status
+
+  APP_ROOT = File.join(__dir__, 'app_multi_site')
+
+  def setup
+    @machine = UM.new
+    @app = Syntropy::App.load(
+      machine: @machine,
+      location: APP_ROOT,
+      mount_path: '/'
+    )
+  end
+
+  def make_request(*, **)
+    req = mock_req(*, **)
+    @app.call(req)
+    req
+  end
+
+  def test_route_by_host
+    req = make_request(':method' => 'GET', ':path' => '/', 'host' => 'blah')
+    assert_nil req.response_body
+    assert_equal Status::BAD_REQUEST, req.response_status
+
+    req = make_request(':method' => 'GET', ':path' => '/', 'host' => 'foo.bar')
+    assert_equal '<h1>foo.bar</h1>', req.response_body.chomp
+
+    req = make_request(':method' => 'GET', ':path' => '/', 'host' => 'bar.baz')
+    assert_equal '<h1>bar.baz</h1>', req.response_body.chomp
+  end
+end

data/test/test_module.rb

@@ -29,4 +29,10 @@ class ModuleTest < Minitest::Test
     @env[:baz] += 1
     assert_equal 43, mod.bar
   end
+
+  def test_export_self
+    mod = @loader.load('_lib/self')
+    assert_kind_of Syntropy::Module, mod
+    assert_equal :bar, mod.foo
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: syntropy
 version: !ruby/object:Gem::Version
-  version: '0.5'
+  version: '0.7'
 platform: ruby
 authors:
 - Sharon Rosner
@@ -202,12 +202,16 @@ files:
 - lib/syntropy/side_run.rb
 - lib/syntropy/version.rb
 - syntropy.gemspec
+- test/app/_hook.rb
 - test/app/_layout/default.rb
 - test/app/_lib/callable.rb
 - test/app/_lib/klass.rb
 - test/app/_lib/missing-export.rb
+- test/app/_lib/self.rb
+- test/app/about/_error.rb
 - test/app/about/foo.md
 - test/app/about/index.rb
+- test/app/about/raise.rb
 - test/app/api+.rb
 - test/app/assets/style.css
 - test/app/bar.rb
@@ -215,6 +219,9 @@ files:
 - test/app/index.html
 - test/app/tmp.rb
 - test/app_custom/_site.rb
+- test/app_multi_site/_site.rb
+- test/app_multi_site/bar.baz/index.html
+- test/app_multi_site/foo.bar/index.html
 - test/helper.rb
 - test/run.rb
 - test/test_app.rb