syntropy 0.6 → 0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 553553edc3b0c81902bc3a77470bc6e9789fcd757066dcd5b4e790d38f7a28bf
-  data.tar.gz: fdb2cec5f581ba49d5156cce188f31a4811d29767c71833bfcfa37899ee0efc5
+  metadata.gz: df2a40954f2c157f5820138528b8c4a5589670b77b5d661a3c55a8f882231f64
+  data.tar.gz: e74d8ab77bf364d4ae4629057fcb0a3027e5901e258b22504f473d99327b9f8a
 SHA512:
-  metadata.gz: 7340ecb01725dcc15a78a66fef5f87a113c2e9759a2305753241b0c1cf738f45b3fd6fea2dcf7bca55196cc3fc309db2ade3e7bb12292fc5aa3abe63362403f9
-  data.tar.gz: 48427e653e2c99022177e5475ef53b66c57143288f43e4997c40f1ba464728b310c5e0df343e7f03e3ed79f9fa8637e305b6a22296b19fb15068b7228cf0531f
+  metadata.gz: 1221b890c2bf0d28cef98e6cca53918e45101c1505d1b745022ec93545a6edbe9e67b281dcadf0f037bcced05a116106c1f27e95eedebdba8f587e03dcc13cd3
+  data.tar.gz: 5fa7d7da0207068c6130bc70bb4582c74bde3f9cecbe164fad2c8f93b56f2f8f30bd445bf0d015aa834c3e0e04ead49ca5bd13c3ba2ce1b872006d3fa6afe31a

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.8 2025-07-05
+
+- Add `MODULE` constant for referencing the module
+- Implement `Module.page_list`
+
+## 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
@@ -151,46 +151,15 @@ module Syntropy
     end
 
     def render_markdown(fn)
-      atts, md = parse_markdown_file(fn)
+      atts, md = Syntropy.parse_markdown_file(fn, @opts)
 
       if atts[:layout]
         layout = @module_loader.load("_layout/#{atts[:layout]}")
-        html = layout.apply { emit_markdown(md) }.render
+        html = layout.apply(**atts) { emit_markdown(md) }.render
       else
         html = Papercraft.markdown(md)
       end
       html
     end
-
-    DATE_REGEXP = /(\d{4}\-\d{2}\-\d{2})/
-    FRONT_MATTER_REGEXP = /\A(---\s*\n.*?\n?)^((---|\.\.\.)\s*$\n?)/m
-    YAML_OPTS = {
-      permitted_classes: [Date],
-      symbolize_names: true
-    }
-
-    # Parses the markdown file at the given path.
-    #
-    # @param path [String] file path
-    # @return [Array] an tuple containing properties<Hash>, contents<String>
-    def parse_markdown_file(path)
-      content = IO.read(path) || ''
-      atts = {}
-
-      # Parse date from file name
-      if (m = path.match(DATE_REGEXP))
-        atts[:date] ||= Date.parse(m[1])
-      end
-
-      if (m = content.match(FRONT_MATTER_REGEXP))
-        front_matter = m[1]
-        content = m.post_match
-
-        yaml = YAML.safe_load(front_matter, **YAML_OPTS)
-        atts = atts.merge(yaml)
-      end
-
-      [atts, content]
-    end
   end
 end

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/markdown.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Syntropy
+  DATE_REGEXP = /(\d{4}-\d{2}-\d{2})/
+  FRONT_MATTER_REGEXP = /\A(---\s*\n.*?\n?)^((---|\.\.\.)\s*$\n?)/m
+  YAML_OPTS = {
+    permitted_classes: [Date],
+    symbolize_names: true
+  }
+
+  # Parses the markdown file at the given path.
+  #
+  # @param path [String] file path
+  # @return [Array] an tuple containing properties<Hash>, contents<String>
+  def self.parse_markdown_file(path, opts)
+    content = IO.read(path) || ''
+    atts = {}
+
+    # Parse date from file name
+    m = path.match(DATE_REGEXP)
+    atts[:date] ||= Date.parse(m[1]) if m
+
+    if (m = content.match(FRONT_MATTER_REGEXP))
+      front_matter = m[1]
+      content = m.post_match
+
+      yaml = YAML.safe_load(front_matter, **YAML_OPTS)
+      atts = atts.merge(yaml)
+    end
+
+    if opts[:location]
+      atts[:url] = path
+                   .gsub(/#{opts[:location]}/, '')
+                   .gsub(/\.md$/, '')
+    end
+
+    [atts, content]
+  end
+end

data/lib/syntropy/module.rb

@@ -32,7 +32,7 @@ module Syntropy
 
       mod_body = IO.read(fn)
       mod_ctx = Class.new(Syntropy::Module)
-      mod_ctx.loader = self
+      mod_ctx.prepare(loader: self, env: @env)
       mod_ctx.module_eval(mod_body, fn, 1)
 
       export_value = mod_ctx.__export_value__
@@ -62,24 +62,56 @@ module Syntropy
       @env = env
     end
 
-    def self.loader=(loader)
-      @loader = loader
-    end
+    class << self
+      def prepare(loader:, env:)
+        @loader = loader
+        @env = env
+        const_set(:MODULE, self)
+      end
 
-    def self.import(ref)
-      @loader.load(ref)
-    end
+      attr_reader :__export_value__
 
-    def self.export(ref)
-      @__export_value__ = ref
-    end
+      def import(ref)
+        @loader.load(ref)
+      end
 
-    def self.templ(&block)
-      Papercraft.html(&block)
-    end
+      def export(ref)
+        @__export_value__ = ref
+      end
 
-    def self.__export_value__
-      @__export_value__
+      def template(&block)
+        Papercraft.html(&block)
+      end
+
+      def route_by_host(map = nil)
+        root = @env[:location]
+        sites = Dir[File.join(root, '*')]
+                .select { File.directory?(it) }
+                .each_with_object({}) { |fn, h|
+          name = File.basename(fn)
+          opts = @env.merge(location: fn)
+          h[name] = Syntropy::App.new(opts[:machine], opts[:location], opts[:mount_path], opts)
+        }
+
+        map&.each do |k, v|
+          sites[k] = sites[v]
+        end
+
+        lambda { |req|
+          site = sites[req.host]
+          site ? site.call(req) : req.respond(nil, ':status' => Status::BAD_REQUEST)
+        }
+      end
+
+      def page_list(ref)
+        full_path = File.join(@env[:location], 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: }
+        }
+      end
     end
   end
 end

data/lib/syntropy/version.rb

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

data/lib/syntropy.rb

@@ -4,14 +4,15 @@ require 'qeweney'
 require 'uringmachine'
 require 'tp2'
 
-require 'syntropy/errors'
+require 'syntropy/app'
 require 'syntropy/connection_pool'
+require 'syntropy/errors'
+require 'syntropy/markdown'
 require 'syntropy/module'
+require 'syntropy/request_extensions'
+require 'syntropy/router'
 require 'syntropy/rpc_api'
 require 'syntropy/side_run'
-require 'syntropy/router'
-require 'syntropy/app'
-require 'syntropy/request_extensions'
 
 module Syntropy
   Status = Qeweney::Status
@@ -34,7 +35,7 @@ module Syntropy
   CLEAR = "\e[0m"
   YELLOW = "\e[33m"
 
-  BANNER = (
+  BANNER =
     "\n"\
     "  #{GREEN}\n"\
     "  #{GREEN} ooo\n"\
@@ -44,5 +45,4 @@ module Syntropy
     "  #{GREEN}  #{YELLOW}|#{GREEN}  vvv o    #{CLEAR}https://github.com/noteflakes/syntropy\n"\
     "  #{GREEN} :#{YELLOW}|#{GREEN}:::#{YELLOW}|#{GREEN}::#{YELLOW}|#{GREEN}:\n"\
     "#{YELLOW}+++++++++++++++++++++++++++++++++++++++++++++++++++++++++\e[0m\n\n"
-  )
 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.8'
 platform: ruby
 authors:
 - Sharon Rosner
@@ -195,6 +195,7 @@ files:
 - lib/syntropy/connection_pool.rb
 - lib/syntropy/errors.rb
 - lib/syntropy/file_watch.rb
+- lib/syntropy/markdown.rb
 - lib/syntropy/module.rb
 - lib/syntropy/request_extensions.rb
 - lib/syntropy/router.rb
@@ -207,6 +208,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 +220,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