syntropy 0.30.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70dae64fe246aa0851a582ff914d647bcfc650755a237ef476a37de8fd0cc052
-  data.tar.gz: 9fde1a73c1136b316f4a5a42d7d0e359df76f4a7015146a5e4c0583eb22c9f76
+  metadata.gz: fbf52e43aad7bcf2dc6259fd40dac6fb6f70d2215513ae89a5e72b120c4b8585
+  data.tar.gz: 7a7fd31a1e47bf999d64ad3216bb2c77345a4eb3753df6e2a51384870d9f764f
 SHA512:
-  metadata.gz: 2a5561fd30d062766fbb5e5df5ab80b1a6840b5a0bb29c2b1bc0e9a3a7872462face8a9e908d72f1a5426f5ad781b91adc079ca2412efbe95071b68f76c030d6
-  data.tar.gz: 22708dd2c98a250068613cbc1d54157ec5673100d2d4df2df216fa353085cbc13c696ae3903a527926c03c17ba746a145c1ff70f0aefddf7fd8996d60527d263
+  metadata.gz: ff3ac2fbb77785db855080dcd0302beb61332c067c30db6330540cda9a60a7ab72ad684b87772951e8498d5c6aa10b2cf57cce7f1a85932f95db889432c704a0
+  data.tar.gz: 84ee4aa581f46c84999109bb102d9c890f9dc45b2803a52f114357981edf9150b84c187ba3a62670691e3eb8629b6396bd8f1789f882857b1558089c198f2877

data/.gitignore

@@ -54,3 +54,5 @@ Gemfile.lock
 
 # Used by RuboCop. Remote config files pulled in from inherit_from directive.
 # .rubocop-https?--*
+
+examples/**/*.db*

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+# 0.32.0 2026-06-01
+
+- Ensure HTTP request body is consumed (skipped) before treating next request
+- Fix `Request#auth_bearer_token`
+- Add `syntropy console` CLI command
+- Add `Module#http_methods` method for simpler REST controllers
+- Add `App#setup_db` method
+- Add `DB::Schema` for schema migrations with support for migration modules
+- Add `DB::Store` class
+- Rename `ConnectionPool` to `DB::ConnectionPool`
+- Add support for setup file (`_setup.rb`)
+- Remove escape_utils dependency
+
+# 0.31.0 2026-05-29
+
+- Add message kwarg to `Request#validate`
+- Reraise internal server error in test mode
+- Use strings rather than symbols for query keys
+- Add content type validation
+- Add syntropy CLI commands: serve, test, help
+- Rename `#auto_refresh_watch!` to `#auto_refresh!`
+- Use `zed` instead of `vscode` scheme for editor links (in HTML-rendered error
+  backtraces)
+- Implement basic `HTTP::Client` API
+- Rename `#json_response` to `#respond_json`, `#html_response` to
+  `#respond_html`
+- Rename `HTTP::Connection` to `HTTP::ServerConnection`
+- Refactor HTTP protocol into UM::IO extensions
+- Fix routing for files/dirs starting with . (e.g. /.well-known/*)
+
 # 0.30.0 2026-05-10
 
 - Refactor HTTP modules

data/TODO.md

@@ -1,5 +1,44 @@
 ## Immediate
 
+- [ ] Session
+
+  https://guides.rubyonrails.org/action_controller_overview.html#session
+
+  We want something that offers the same features as in Ruby on Rails. A storage
+  space for session metadata which can include a user_id, flash messages etc.
+
+  - The session is attached to the request, and is valid for the browser
+    session.
+  - The session is a KV store. It can be used to store any data relevant to the
+    user's browser session.
+  - Each session has a unique ID and that ID is passed to the browser as a
+    non-persistent cookie.
+  - A session expires if not used (e.g. after 7 days)
+  - Session storage either in memory or in DB
+  - The session is generated (and session cookie set) upon first write to
+    session.
+  - Session `Set-Cookie` header should be injected into the HTTP response.
+  - The entire session info can be stored in a cookie, provided it does not
+    exceed 4KB.
+
+  ```ruby
+  req.session[:flash] = 'Title cannot be empty!'
+  req.redirect '/blah'
+  ```
+
+- [ ] Flash messages
+
+  - Flash messages are a sub-feature of session storage and are used to relay
+    messages from one request to the next in the same session.
+  - Flash messages have more complex semantics:
+    - There can be more than one.
+    - They have types - notice, alert, etc.
+    - They normally disappear on the next request (i.e. the session cookie
+      should be updated in the response with Set-Cookie).
+    - But, you can keep them for the next request with `req.session.flash.keep`
+    - The flash messages could be used for the current request with
+      `req.session.flash.now`
+
 - [ ] Collection - treat directories and files as collections of data.
 
   Kind of similar to the routing tree, but instead of routes it just takes a
@@ -39,9 +78,15 @@
 - [ ] Website
 - [v] Frontend part of JSON API
 - [v] Auto-refresh page when file changes
+- [ ] SQLite database capabilities
+  - [ ] Model API + tools
+    - [ ] Do we need/want migrations?
+  - [ ] Stores
+    - [ ] KV store (with TTL)
 - [v] Examples
   - [v] Reactive app - counter or some other simple app showing interaction with
     server
+  - [ ] blog
 
 ## Testing facilities
 
@@ -49,7 +94,7 @@
   - Routes
   - Route responses
   - Changes to state / DB
-  -
+  - Rendered HTML - presence of certain markup / elements / text
 
 ## Support for applets
 

data/bin/syntropy

@@ -1,93 +1,15 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'syntropy'
-require 'optparse'
+require_relative '../cmd/_banner'
 
-env = {
-  mount_path: '/',
-  banner: Syntropy::BANNER,
-  logger: true,
-  builtin_applet_path: '/.syntropy',
-  server_extensions: {
-    date: true,
-    name: 'Syntropy'
-  }
-}
+def cmd_fn(cmd)= File.join(__dir__, "../cmd/#{cmd}.rb")
 
-parser = OptionParser.new do |o|
-  o.banner = 'Usage: syntropy [options] DIR'
+cmd = ARGV.shift || 'help'
+cmd = 'help' if cmd !~ /^[a-z]+$/
 
-  o.on('-b', '--bind BIND', String,
-       'Bind address (default: http://0.0.0.0:1234). You can specify this flag multiple times to bind to multiple addresses.') do
-    env[:bind] ||= []
-    env[:bind] << it
-  end
+fn = cmd_fn(cmd)
+fn = cmd_fn('help') if !File.file?(fn)
 
-  o.on('-s', '--silent', 'Silent mode') do
-    env[:banner] = nil
-    env[:logger] = nil
-  end
-
-  o.on('-d', '--dev', 'Development mode') do
-    env[:dev_mode] = true
-    env[:watch_files] = 0.1
-  end
-
-  o.on('-h', '--help', 'Show this help message') do
-    puts o
-    exit
-  end
-
-  o.on('-m', '--mount PATH', 'Set mount path (default: /)') do |path|
-    p mount: path
-    env[:mount_path] = path
-    env[:builtin_applet_path] = File.join(path, '.syntropy')
-  end
-
-  o.on('--no-builtin-applet', 'Do not mount builtin applet') do
-    env[:builtin_applet_path] = nil
-  end
-
-  o.on('--no-server-headers', 'Don\'t include Server and Date headers') do
-    env[:server_extensions] = nil
-  end
-
-  o.on('-v', '--version', 'Show version') do
-    require 'syntropy/version'
-    puts "Syntropy version #{Syntropy::VERSION}"
-    exit
-  end
-end
-
-RubyVM::YJIT.enable rescue nil
-
-begin
-  parser.parse!
-rescue StandardError => e
-  puts e.message
-  puts e.backtrace.join("\n")
-  exit
-end
-
-$syntropy_dev_mode = env[:dev_mode]
-env[:root_dir] = (ARGV.shift || '.').gsub(/\/$/, '')
-
-if !File.directory?(env[:root_dir])
-  puts "#{File.expand_path(env[:root_dir])} Not a directory"
-  exit
-end
-
-puts env[:banner] if env[:banner]
-env[:banner] = false
-
-
-# We set Syntropy.machine so we can reference it from anywhere
-env[:machine] = Syntropy.machine = UM.new
-env[:logger] = env[:logger] && Syntropy::Logger.new(env[:machine], **env)
-
-require 'syntropy/version'
-require 'syntropy/dev_mode' if env[:dev_mode]
-
-app = Syntropy::App.load(env)
-Syntropy.run(env) { app.call(it) }
+puts SYNTROPY_BANNER
+require(fn)

data/cmd/_banner.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+green = "\e[32m"
+clear = "\e[0m"
+yellow = "\e[33m"
+
+SYNTROPY_BANNER =
+  "\n"\
+  "  #{green}\n"\
+  "  #{green} ooo\n"\
+  "  #{green}ooooo\n"\
+  "  #{green} ooo vvv       #{clear}Syntropy - a web framework for Ruby\n"\
+  "  #{green}  o vvvvv     #{clear}--------------------------------------\n"\
+  "  #{green}  #{yellow}|#{green}  vvv o    #{clear}https://github.com/digital-fabric/syntropy\n"\
+  "  #{green} :#{yellow}|#{green}:::#{yellow}|#{green}::#{yellow}|#{green}:\n"\
+  "#{yellow}++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#{clear}\n\n"

data/cmd/console.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative '../lib/syntropy'
+require 'optparse'
+
+env = {
+  mount_path:           '/',
+  logger:               true,
+  builtin_applet_path:  '/.syntropy',
+  watch_files:          true
+}
+
+parser = OptionParser.new do |o|
+  o.banner = 'Usage: syntropy serve [options] DIR'
+
+  o.on('-h', '--help', 'Show this help message') do
+    puts o
+    exit
+  end
+
+  o.on('-m', '--mount PATH', 'Set mount path (default: /)') do |path|
+    p mount: path
+    env[:mount_path] = path
+    env[:builtin_applet_path] = File.join(path, '.syntropy')
+  end
+
+  o.on('--no-builtin-applet', 'Do not mount builtin applet') do
+    env[:builtin_applet_path] = nil
+  end
+end
+
+RubyVM::YJIT.enable rescue nil
+
+begin
+  parser.parse!
+rescue OptionParser::InvalidOption
+  puts parser
+  exit
+rescue StandardError => e
+  p e
+  puts e.message
+  puts e.backtrace.join("\n")
+  exit
+end
+
+$syntropy_dev_mode = env[:dev_mode]
+env[:root_dir] = (ARGV.shift || '.').gsub(/\/$/, '')
+
+if !File.directory?(env[:root_dir])
+  puts "#{File.expand_path(env[:root_dir])} Not a directory"
+  exit
+end
+
+puts env[:banner] if env[:banner]
+env[:banner] = false
+
+# We set Syntropy.machine so we can reference it from anywhere
+env[:machine] = Syntropy.machine = UM.new
+env[:logger] = env[:logger] && Syntropy::Logger.new(env[:machine], **env)
+
+@app = Syntropy::App.load(env)
+@env = env
+@machine = env[:machine]
+@connection_pool = @app.connection_pool if @app.respond_to?(:connection_pool)
+@schema = @app.schema if @app.respond_to?(:schema)
+@module_loader = @app.module_loader
+
+require 'uringmachine/fiber_scheduler'
+@scheduler = UM::FiberScheduler.new(@machine)
+Fiber.set_scheduler(@scheduler)
+
+def import(ref)
+  @module_loader.load(ref)
+end
+
+require 'irb'
+IRB.start

data/cmd/help.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+HELP = <<~MSG
+  Usage: syntropy COMMAND [options]
+
+  Available commands:
+
+    serve     Start a Syntropy server
+    test      Run tests
+MSG
+
+$stdout << HELP

data/cmd/serve.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative '../lib/syntropy'
+require 'optparse'
+
+env = {
+  mount_path: '/',
+  logger: true,
+  builtin_applet_path: '/.syntropy',
+  server_extensions: {
+    date: true,
+    name: 'Syntropy'
+  }
+}
+
+parser = OptionParser.new do |o|
+  o.banner = 'Usage: syntropy serve [options] DIR'
+
+  o.on('-b', '--bind BIND', String,
+       'Bind address (default: http://0.0.0.0:1234). You can specify this flag multiple times to bind to multiple addresses.') do
+    env[:bind] ||= []
+    env[:bind] << it
+  end
+
+  o.on('-s', '--silent', 'Silent mode') do
+    env[:banner] = nil
+    env[:logger] = nil
+  end
+
+  o.on('-d', '--dev', 'Development mode') do
+    env[:dev_mode] = true
+    env[:watch_files] = true
+  end
+
+  o.on('-h', '--help', 'Show this help message') do
+    puts o
+    exit
+  end
+
+  o.on('-m', '--mount PATH', 'Set mount path (default: /)') do |path|
+    p mount: path
+    env[:mount_path] = path
+    env[:builtin_applet_path] = File.join(path, '.syntropy')
+  end
+
+  o.on('--no-builtin-applet', 'Do not mount builtin applet') do
+    env[:builtin_applet_path] = nil
+  end
+
+  o.on('--no-server-headers', 'Don\'t include Server and Date headers') do
+    env[:server_extensions] = nil
+  end
+
+  o.on('-v', '--version', 'Show version') do
+    require 'syntropy/version'
+    puts "Syntropy version #{Syntropy::VERSION}"
+    exit
+  end
+end
+
+RubyVM::YJIT.enable rescue nil
+
+begin
+  parser.parse!
+rescue OptionParser::InvalidOption
+  puts parser
+  exit
+rescue StandardError => e
+  p e
+  puts e.message
+  puts e.backtrace.join("\n")
+  exit
+end
+
+$syntropy_dev_mode = env[:dev_mode]
+env[:root_dir] = (ARGV.shift || '.').gsub(/\/$/, '')
+
+if !File.directory?(env[:root_dir])
+  puts "#{File.expand_path(env[:root_dir])} Not a directory"
+  exit
+end
+
+puts env[:banner] if env[:banner]
+env[:banner] = false
+
+
+# We set Syntropy.machine so we can reference it from anywhere
+env[:machine] = Syntropy.machine = UM.new
+env[:logger] = env[:logger] && Syntropy::Logger.new(env[:machine], **env)
+
+require 'syntropy/version'
+require 'syntropy/dev_mode' if env[:dev_mode]
+
+app = Syntropy::App.load(env)
+Syntropy.run(env) { app.call(it) }

data/cmd/test.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+env = {}
+argv_copy = ARGV.dup
+case ARGV[0]
+when '-w', '--watch'
+  env[:watch_mode] = true
+  ARGV.shift
+when '-h', '--help'
+  puts <<~MSG
+    Usage: syntropy test [options] [minitest options]
+        -w, --watch         Rerun tests on file system changes
+        -h, --help          Show this help message
+  MSG
+  exit
+end
+
+require_relative '../lib/syntropy'
+require_relative '../lib/syntropy/test'
+
+$stdout.sync = true
+$stderr.sync = true
+
+Dir.glob("./test/test_*.rb").each { require(it) }
+
+def watch_for_file_changes
+  m = UM.new
+  puts "Waiting for file changes in #{FileUtils.pwd}"
+  m.file_watch(FileUtils.pwd, UM::IN_CREATE | UM::IN_DELETE | UM::IN_CLOSE_WRITE) {
+    puts "Detected changes to #{it[:fn]}, restarting"
+    break
+  }
+end
+
+Minitest.run ARGV
+if env[:watch_mode]
+  puts
+  watch_for_file_changes
+  exec("ruby", __FILE__, *argv_copy)
+end

data/examples/{counter.rb → basic/counter.rb}

@@ -18,6 +18,6 @@ export template {
       div { font-weight: bold; font-size: 1.3em }
       value { display: inline-block; padding: 0 1em; color: blue; width: 1em }
     CSS
-    auto_refresh_watch!
+    auto_refresh!
   }
 }

data/examples/{templates.rb → basic/templates.rb}

@@ -32,7 +32,7 @@ export template {
 
       Card()
     }
-    auto_refresh_watch!
+    auto_refresh!
     debug_template!
   }
 }

data/examples/blog/app/_layout/default.rb

@@ -0,0 +1,11 @@
+export template { |**props|
+  html {
+    head {
+      title "My awesome blog"
+    }
+    body {
+      render_children(**props)
+      auto_refresh!
+    }
+  }
+}

data/examples/blog/app/_lib/post_store.rb

@@ -0,0 +1,47 @@
+class PostStore < Syntropy::DB::Store
+  # @return [Integer] post id
+  def create(title, body)
+    query_single_value <<~SQL, title:, body:
+      insert into posts (title, body)
+      values (:title, :body)
+      returning id;
+    SQL
+  end
+
+  # @return [void]
+  def update(id, title, body)
+    execute <<~SQL, id:, title:, body:
+      update posts
+      set title = :title, body = :body
+      where id = :id
+    SQL
+  end
+
+  # @return [void]
+  def delete(id)
+    execute <<~SQL, id:
+      delete from posts
+      where id = :id
+    SQL
+  end
+
+  # return [Hash]
+  def get(id)
+    query_single_row <<~SQL, id:
+      select id, title, body
+      from posts
+      where id = :id
+    SQL
+  end
+
+  # return [Array<Hash>]
+  def get_all
+    query <<~SQL
+      select id, title, body
+      from posts
+      order by id desc
+    SQL
+  end
+end
+
+export PostStore.new(@app.connection_pool)

data/examples/blog/app/_schema/2026-01-01-initial.rb

@@ -0,0 +1,9 @@
+export ->(db) {
+  db.execute <<~SQL
+    create table posts (
+      id integer primary key autoincrement,
+      title text,
+      body text
+    )
+  SQL
+}

data/examples/blog/app/_setup.rb

@@ -0,0 +1,4 @@
+@app.setup_db(
+  db_path:      File.join(@app.root_dir, '../blog.db'),
+  schema_root:  '_schema'
+)

data/examples/blog/app/index.rb

@@ -0,0 +1,7 @@
+layout = import '_layout/default'
+
+export layout.apply {
+  p {
+    a 'Blog posts', href: '/posts'
+  }
+}

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

@@ -0,0 +1,33 @@
+@post_store = import '/_lib/post_store'
+@layout = import '/_layout/default'
+
+export http_methods
+
+def get(req)
+  id = req.route_params['id'].to_i
+  post = @post_store.get(id)
+  raise Syntropy::Error.not_found if !post
+
+  req.respond_html(
+    @template.render(post:)
+  )
+end
+
+@template = @layout.apply { |post:, **props|
+  h1 "Edit blog post"
+  div {
+    form(action: "/posts/#{post[:id]}", method: 'post') {
+      div {
+        label 'Title', for: 'title'
+        input name: 'title', type: 'text', value: post[:title]
+      }
+      div {
+        label 'Body', for: 'body'
+        textarea post[:body], name: 'body', rows: 5
+      }
+      div {
+        button 'Submit', type: 'submit'
+      }
+    }
+  }
+}

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

@@ -0,0 +1,58 @@
+@post_store = import '/_lib/post_store'
+@layout = import '/_layout/default'
+
+export http_methods
+
+def get(req)
+  id = req.route_params['id'].to_i
+  post = @post_store.get(id)
+  raise Syntropy::Error.not_found if !post
+
+  req.respond_html(
+    @template.render(post:)
+  )
+end
+
+def post(req)
+  data = req.get_form_data
+  return delete(req) if data['method'] == 'delete'
+
+  id = req.route_params['id'].to_i
+  title = req.validate(data['title'], String, /.+/)
+  body = req.validate(data['body'], String, /.+/)
+
+  updated = @post_store.update(id, title, body)
+  raise BadRequestError, "Failed to update post" if updated != 1
+
+  req.redirect "/posts/#{id}", Syntropy::HTTP::SEE_OTHER
+end
+
+def delete(req)
+  id = req.route_params['id'].to_i
+
+  deleted = @post_store.delete(id)
+  raise BadRequestError, "Failed to delete post" if deleted != 1
+
+  req.redirect "/posts", Syntropy::HTTP::SEE_OTHER
+end
+
+@template = @layout.apply { |post:, **props|
+  h1 "My blog"
+  div {
+    h2 {
+      a post[:title]
+    }
+    p post[:body]
+  }
+  p {
+    a "Edit", href: "/posts/#{post[:id]}/edit"
+    span '|'
+    a "Back to posts", href: '/posts'
+  }
+  div {
+    form(method: 'post') {
+      input type: 'hidden', name: 'method', value: 'delete'
+      button 'Delete this post', name: 'delete', type: 'submit'
+    }
+  }
+}