syntropy 0.31.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3908853da702fa27301792535415763adf546fe51bd9f3b91d530a65b55f8d66
-  data.tar.gz: 34f6387d31fa46134ed8aa87d609b3400c506b832fe2f9baa64ee5225da1f929
+  metadata.gz: fbf52e43aad7bcf2dc6259fd40dac6fb6f70d2215513ae89a5e72b120c4b8585
+  data.tar.gz: 7a7fd31a1e47bf999d64ad3216bb2c77345a4eb3753df6e2a51384870d9f764f
 SHA512:
-  metadata.gz: f899a3f06335acc22181160e5820563fa21f1a1dd981fd33a7f0b1530ac61801455f430f82a1be130682a1c58d7d0b21dfb3d816efc742898c51133fa9223c24
-  data.tar.gz: 4e7a6637bf8b4f280689d3053557e8a77585da711e626fab7e81f8bfa39fdc1065288a9bd9a5d940f2e04ad0b1a0b6a3f53ee3d65e6f53a14ebd7d31883e3696
+  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,16 @@
+# 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`

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

@@ -29,7 +29,7 @@ parser = OptionParser.new do |o|
 
   o.on('-d', '--dev', 'Development mode') do
     env[:dev_mode] = true
-    env[:watch_files] = 0.1
+    env[:watch_files] = true
   end
 
   o.on('-h', '--help', 'Show this help message') do

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'
+    }
+  }
+}

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

@@ -0,0 +1,38 @@
+@post_store = import '_lib/post_store'
+@layout = import '_layout/default'
+
+export http_methods
+
+def get(req)
+  posts = @post_store.get_all
+  req.respond_html(
+    @template.render(posts:)
+  )
+end
+
+def post(req)
+  data = req.get_form_data
+  title = req.validate(data['title'], String, /.+/)
+  body = req.validate(data['body'], String, /.+/)
+  id = @post_store.create(title, body)
+
+  req.redirect("posts/#{id}")
+end
+
+@template = @layout.apply { |**props|
+  h1 "My blog"
+  props[:posts].each { |post|
+    div {
+      h2 {
+        a post[:title], href: "/posts/#{post[:id]}"
+      }
+      p post[:body]
+    }
+  }
+
+  div {
+    p {
+      a "New post", href: '/posts/new'
+    }
+  }
+}

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

@@ -0,0 +1,29 @@
+@post_store = import '/_lib/post_store'
+@layout = import '/_layout/default'
+
+export http_methods
+
+def get(req)
+  req.respond_html(
+    @template.render
+  )
+end
+
+@template = @layout.apply { |**props|
+  h1 "Create blog post"
+  div {
+    form(action: "/posts", method: 'post') {
+      div {
+        label 'Title', for: 'title'
+        input name: 'title', type: 'text'
+      }
+      div {
+        label 'Body', for: 'body'
+        textarea '', name: 'body', rows: 5
+      }
+      div {
+        button 'Submit', type: 'submit'
+      }
+    }
+  }
+}

data/examples/mcp-oauth/README.md

@@ -69,7 +69,7 @@ This app implements a site that includes an MCP server with OAuth 2.1 authorizat
   ```
   HTTP/1.1 201 Created
   Content-Type: application/json
-  
+
   {
     "client_id": "mcp_client_xyz789",
     "client_name": "Cursor AI Agent",
@@ -102,7 +102,7 @@ This app implements a site that includes an MCP server with OAuth 2.1 authorizat
   POST /oauth/token HTTP/1.1
   Host: auth.example.com
   Content-Type: application/x-www-form-urlencoded
-  
+
   grant_type=authorization_code&code=splat-auth-code-123&redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Fcallback&client_id=mcp_client_xyz789&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
   ```
 
@@ -112,7 +112,7 @@ This app implements a site that includes an MCP server with OAuth 2.1 authorizat
   ```
   HTTP/1.1 200 OK
   Content-Type: application/json
-  
+
   {
     "access_token": "mcp_access_token_abc123",
     "token_type": "Bearer",

data/examples/mcp-oauth/app/mcp.rb

@@ -1,16 +1,26 @@
+AuthStore = import './_lib/auth_store'
+
 export ->(req) {
   req.validate_http_method('post')
   req.validate_content_type('application/json')
 
-  if valid_token?(req)
-    respond_authorized(req)
-  else
+  if !(token_info = valid_token?(req))
     respond_unauthorized(req)
+    return
   end
+
+  handle(req, token_info)
 }
 
+# @param req [Syntropy::Request]
 def valid_token?(req)
-  false
+  token = req.auth_bearer_token
+  return false if !token
+
+  token_info = AuthStore.fetch(token)
+  return false if !token_info
+
+  true
 end
 
 def respond_unauthorized(req)
@@ -27,12 +37,49 @@ def respond_unauthorized(req)
   )
 end
 
-def respond_authorized(req)
+def handle(req, token_info)
+  req.validate_http_method('post')
+  req.validate_content_type('application/json')
+  json = JSON.parse(req.read)
+
+  req.validate(json['jsonrpc'], '2.0')
+  req.validate(json['id'], [Integer, String])
+
+  method = req.validate(json['method'], String)
+  sym = :"handle_#{method}"
+  raise Syntropy::ValidationError, 'METHOD_NOT_FOUND: method not found' if !respond_to?(sym)
+
+  send(sym, req, json, token_info)
+rescue Syntropy::ValidationError => e
+  if (m = e.message.match(/(.+)\: (.+)/))
+    type, message = m[1], m[2]
+  else
+    type, message = 'INVALID_REQUEST', e.message
+  end
+  respond_error(req, json, type, message)
+end
+
+ERROR_CODES = {
+  'INVALID_REQUEST'   => -32600,
+  'METHOD_NOT_FOUND'  => -32601,
+  'INVALID_PARAMS'    => -32602,
+  'INTERNAL_ERROR'    => -32603,
+  'PARSE_ERROR'       => -32700
+}
+
+def respond_error(req, json, error_type, error_message)
+  error_code = ERROR_CODES[type] || ERROR_CODES['INTERNAL_ERROR']
   req.respond_json(
     {
-      resource:               "http://localhost:1234/mcp",
-      authorization_servers:  ["http://localhost:1234/"],
-      scopes_supported:       ["mcp:tools", "mcp:resources"]
+      jsonrpc: '2.0',
+      id: json['id'],
+      error: {
+        code:     error_code,
+        message:  error_message
+      }
     }
   )
 end
+
+def handle_initialize()
+end

data/examples/mcp-oauth/app/oauth/authorize.rb

@@ -9,14 +9,6 @@ export ->(req) {
   client_info = AuthStore.fetch(params['client_id'])
   req.validate(client_info, Hash)
 
-  # GET /oauth/authorize?
-  # response_type=code
-  # client_id=mcp_client_xyz789
-  # redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Fcallback
-  # code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
-  # code_challenge_method=S256
-  # state=random_state_string
-
   key = AuthStore.store(req.query)
   req.respond(nil, {
     ':status' => Syntropy::HTTP::FOUND,

data/examples/mcp-oauth/app/oauth/register.rb

@@ -4,7 +4,6 @@ AuthStore = import '../_lib/auth_store'
 export ->(req) {
   req.validate_http_method('post')
   req.validate_content_type('application/json')
-
   client_info = JSON.parse(req.read)
   client_id = AuthStore.store(client_info)
 

data/lib/syntropy/app.rb

@@ -6,7 +6,7 @@ require 'yaml'
 require 'papercraft'
 
 require 'syntropy/errors'
-require 'syntropy/module'
+require 'syntropy/module_loader'
 require 'syntropy/routing_tree'
 require 'syntropy/mime_types'
 
@@ -35,7 +35,7 @@ module Syntropy
     end
 
     attr_reader :module_loader, :routing_tree, :root_dir, :mount_path, :env
-    attr_accessor :test_mode
+    attr_accessor :raise_on_internal_server_error
 
     def initialize(**env)
       @machine = env[:machine]
@@ -102,6 +102,21 @@ module Syntropy
       route
     end
 
+    def setup_db(db_path:, schema_root: '_schema')
+      @env[:db_path] = db_path
+      @env[:schema_root] = schema_root
+
+      class << self
+        def connection_pool
+          @connection_pool ||= DB::ConnectionPool.new(@machine, @env[:db_path], 4)
+        end
+
+        def schema
+          @schema ||= DB::Schema.new(module_loader: @module_loader, schema_root: @env[:schema_root])
+        end
+      end
+    end
+
     private
 
     # Handles a not found error, taking into account hooks up the tree from the
@@ -458,7 +473,7 @@ module Syntropy
       req.respond(msg, ':status' => status) rescue nil
     }
 
-    TEST_MODE_DEFAULT_ERROR_HANDLER = ->(req, err) {
+    RAISE_INTERNAL_SERVER_ERROR_DEFAULT_ERROR_HANDLER = ->(req, err) {
       status = Syntropy::Error.http_status(err)
       raise if status == HTTP::INTERNAL_SERVER_ERROR
 
@@ -471,8 +486,10 @@ module Syntropy
       @default_error_handler ||= begin
         if @builtin_applet
           @builtin_applet.module_loader.load('/default_error_handler')
+        elsif @raise_on_internal_server_error
+          RAISE_INTERNAL_SERVER_ERROR_DEFAULT_ERROR_HANDLER
         else
-          @test_mode ? TEST_MODE_DEFAULT_ERROR_HANDLER : RAW_DEFAULT_ERROR_HANDLER
+          RAW_DEFAULT_ERROR_HANDLER
         end
       end
     end
@@ -482,6 +499,8 @@ module Syntropy
     #
     # @return [void]
     def start
+      @module_loader.load('_setup', raise_on_missing: false)
+
       @machine.spin do
         # we do startup stuff asynchronously, in order to first let Syntropy do
         # its setup tasks.
@@ -500,9 +519,6 @@ module Syntropy
     #
     # @return [void]
     def file_watcher_loop
-      wf = @env[:watch_files]
-      period = wf.is_a?(Numeric) ? wf : 0.1
-
       @machine.file_watch(@root_dir, UM::IN_CREATE | UM::IN_DELETE | UM::IN_CLOSE_WRITE) { |e|
         fn = e[:fn]
         @logger&.info(message: 'File change detected', fn: fn)
@@ -510,8 +526,6 @@ module Syntropy
         debounce_file_change
       }
 
-
-
       # Syntropy.file_watch(@machine, @root_dir, period: period) do |event, fn|
       #   @logger&.info(message: 'File change detected', fn: fn)
       #   @module_loader.invalidate_fn(fn)