syntropy 0.6 → 0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 553553edc3b0c81902bc3a77470bc6e9789fcd757066dcd5b4e790d38f7a28bf
-  data.tar.gz: fdb2cec5f581ba49d5156cce188f31a4811d29767c71833bfcfa37899ee0efc5
+  metadata.gz: b86a65bfeb990aa38b76b5bb6487210887e7103bab652e40c3790d68c1ab48df
+  data.tar.gz: 89397a9faf63d2a07c69ab69f93048cb92c82014e30d7ca6ed9399671c17bb48
 SHA512:
-  metadata.gz: 7340ecb01725dcc15a78a66fef5f87a113c2e9759a2305753241b0c1cf738f45b3fd6fea2dcf7bca55196cc3fc309db2ade3e7bb12292fc5aa3abe63362403f9
-  data.tar.gz: 48427e653e2c99022177e5475ef53b66c57143288f43e4997c40f1ba464728b310c5e0df343e7f03e3ed79f9fa8637e305b6a22296b19fb15068b7228cf0531f
+  metadata.gz: 0f536c81be4baa5c8e8733705a9a41042b322eb3960ee8a092523bfdfff886893a4183a6b00c69c2960daefe6443a6f06ee0e07596eeb5ffc3b45ceceb86c342
+  data.tar.gz: 05c3e6c5d3641847a0c962811e290313f7d08a4233504466035e94cfc03284cf652f990f5fd4681efd059673050fda5d021bba5a982c0e539b8c3351bd316913

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 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

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/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
@@ -135,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/version.rb

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

data/test/app/_hook.rb

@@ -1,5 +1,4 @@
 export ->(req, proc) {
   req.ctx[:foo] = req.query[:foo]
-  # p proc: proc
   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/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

@@ -180,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.6'
+  version: '0.7'
 platform: ruby
 authors:
 - Sharon Rosner
@@ -207,6 +207,7 @@ files:
 - 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
@@ -218,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