syntropy 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70dae64fe246aa0851a582ff914d647bcfc650755a237ef476a37de8fd0cc052
-  data.tar.gz: 9fde1a73c1136b316f4a5a42d7d0e359df76f4a7015146a5e4c0583eb22c9f76
+  metadata.gz: 3908853da702fa27301792535415763adf546fe51bd9f3b91d530a65b55f8d66
+  data.tar.gz: 34f6387d31fa46134ed8aa87d609b3400c506b832fe2f9baa64ee5225da1f929
 SHA512:
-  metadata.gz: 2a5561fd30d062766fbb5e5df5ab80b1a6840b5a0bb29c2b1bc0e9a3a7872462face8a9e908d72f1a5426f5ad781b91adc079ca2412efbe95071b68f76c030d6
-  data.tar.gz: 22708dd2c98a250068613cbc1d54157ec5673100d2d4df2df216fa353085cbc13c696ae3903a527926c03c17ba746a145c1ff70f0aefddf7fd8996d60527d263
+  metadata.gz: f899a3f06335acc22181160e5820563fa21f1a1dd981fd33a7f0b1530ac61801455f430f82a1be130682a1c58d7d0b21dfb3d816efc742898c51133fa9223c24
+  data.tar.gz: 4e7a6637bf8b4f280689d3053557e8a77585da711e626fab7e81f8bfa39fdc1065288a9bd9a5d940f2e04ad0b1a0b6a3f53ee3d65e6f53a14ebd7d31883e3696

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+# 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/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/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] = 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 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/mcp-oauth/.ruby-version

@@ -0,0 +1 @@
+4.0.3

data/examples/mcp-oauth/Gemfile

@@ -0,0 +1,8 @@
+source 'https://gem.coop'
+
+gem 'syntropy', path: '../..'
+gem 'jwt'
+
+group :development do
+  gem 'minitest'
+end

data/examples/mcp-oauth/README.md

@@ -0,0 +1,128 @@
+# Syntropy OAuth 2.1 Example App
+
+This app implements a site that includes an MCP server with OAuth 2.1 authorization.
+
+## Authorization workflow:
+
+### Phase 1: Discovery
+
+- MCP client accesses the mcp endpoint:
+
+  `GET /mcp`
+
+  Response headers:
+
+  ```
+  HTTP/1.1 401 Unauthorized
+  WWW-Authenticate: Bearer realm="mcp", resource_metadata="http://localhost:1234/.well-known/oauth-protected-resource"
+  ```
+
+- MCP client makes a request to the protected resource endpoint in order to the
+  protected resource metadata:
+
+  `GET /.well-known/oauth-protected-resource`
+
+  Response JSON:
+
+  ```
+  {
+    resource:               "http://localhost:1234/",
+    authorization_servers:  ["http://localhost:1234/"],
+    scopes_supported:       ["mcp:read", "mcp:write"]
+  }
+  ```
+
+- MCP client makes a request to the authorization server:
+
+  `GET /.well-known/oauth-authorization-server`
+
+  Response JSON:
+
+  ```
+  {
+    issuer:                                 "http://localhost:1234/",
+    registration_endpoint:                  "http://localhost:1234/oauth/register",
+    authorization_endpoint:                 "http://localhost:1234/oauth/authorize",
+    token_endpoint:                         "http://localhost:1234/oauth/token",
+    scopes_supported:                       ["mcp:read", "mcp:write"],
+    response_types_supported:               ["code"]
+  }
+  ```
+
+### Phase 2: Dynamic Client Registration (DCR)
+
+- MCP client makes a request to the register endpoint
+
+  ```
+  POST /oauth/register
+  Content-Type: application/json
+
+  {
+    "client_name": "Cursor AI Agent",
+    "redirect_uris": ["http://localhost:8400/callback"],
+    "grant_types": ["authorization_code", "refresh_token"]
+  }
+  ```
+
+  Response:
+
+  ```
+  HTTP/1.1 201 Created
+  Content-Type: application/json
+  
+  {
+    "client_id": "mcp_client_xyz789",
+    "client_name": "Cursor AI Agent",
+    "redirect_uris": ["http://localhost:8400/callback"],
+    "grant_types": ["authorization_code", "refresh_token"]
+  }
+  ```
+
+### Phase 3: Authorization Request with PKCE
+
+- MCP client opens a browser with a URL pointing to the authorization endpoint:
+
+  `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 HTTP/1.1`
+
+  the server leads the user through signin and consent workflow. Finally it
+  generates a temporary auth code and redirects to the client's callback URL:
+
+  Response:
+
+  ```
+  HTTP/1.1 302 Found
+  Location: http://localhost:8400/callback?code=splat-auth-code-123&state=random_state_string
+  ```
+
+### Phase 4: Token Exchange
+
+- MCP client grabs the code and exchanges it with the token endpoint:
+
+  ```
+  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
+  ```
+
+  The authorization server hashes the code_verifier and verifies it matches the
+  challenge submitted in Phase 3. If it does, it returns an access token:
+
+  ```
+  HTTP/1.1 200 OK
+  Content-Type: application/json
+  
+  {
+    "access_token": "mcp_access_token_abc123",
+    "token_type": "Bearer",
+    "expires_in": 3600,
+    "refresh_token": "mcp_refresh_token_def456"
+  }
+  ```
+
+### And we're done
+
+The client can now seamlessly access the MCP resources by attaching the header:
+
+`Authorization: Bearer mcp_access_token_abc123`

data/examples/mcp-oauth/app/.well-known/oauth-authorization-server.rb

@@ -0,0 +1,18 @@
+# https://datatracker.ietf.org/doc/html/rfc8414#section-2
+export ->(req) {
+  req.respond_json(
+    {
+      issuer:                                 "http://localhost:1234/",
+      registration_endpoint:                  "http://localhost:1234/oauth/register",
+      authorization_endpoint:                 "http://localhost:1234/oauth/authorize",
+      token_endpoint:                         "http://localhost:1234/oauth/token",
+      scopes_supported:                       ["mcp:read", "mcp:write"],
+      response_types_supported:               ["code"]
+      # jwks_uri:                               "http://localhost:1234/.well-known/jwks.json",
+      # grant_types_supported:                  ["authorization_code", "refresh_token"],
+      # code_challenge_methods_supported:       ["S256"],
+      # claims_supported:                       ["aud", "iss", "exp", "scope", "sub"],
+      # client_id_metadata_document_supported:  true
+    }
+  )
+}

data/examples/mcp-oauth/app/.well-known/oauth-protected-resource.rb

@@ -0,0 +1,10 @@
+# https://datatracker.ietf.org/doc/html/rfc9728#name-protected-resource-metadata
+export ->(req) {
+  req.respond_json(
+    {
+      resource:                 "http://localhost:1234/",
+      authorization_servers:    ["http://localhost:1234/"],
+      scopes_supported:         ["mcp:read", "mcp:write"]
+    }
+  )
+}

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

@@ -0,0 +1,23 @@
+export self
+
+require 'securerandom'
+
+@store = {}
+
+def store(params)
+  key = SecureRandom.hex(16)
+  @store[key] = params
+  key
+end
+
+def fetch(key)
+  @store[key]
+end
+
+def update(key, value)
+  @store[key] = value
+end
+
+def fetch_and_remove(key)
+  @store.delete(key)
+end

data/examples/mcp-oauth/app/index.md

@@ -0,0 +1 @@
+# Syntropy OAuth 2.1 Example

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

@@ -0,0 +1,38 @@
+export ->(req) {
+  req.validate_http_method('post')
+  req.validate_content_type('application/json')
+
+  if valid_token?(req)
+    respond_authorized(req)
+  else
+    respond_unauthorized(req)
+  end
+}
+
+def valid_token?(req)
+  false
+end
+
+def respond_unauthorized(req)
+  req.respond_json(
+    {
+      error:    'unauthorized',
+      message:  'Authentication required'
+    },
+    ':status'           => HTTP::UNAUTHORIZED,
+    'WWW-Authenticate'  => <<~EOF.tr("\n", ' ')
+      Bearer realm="mcp",
+      resource_metadata="http://localhost:1234/.well-known/oauth-protected-resource"
+    EOF
+  )
+end
+
+def respond_authorized(req)
+  req.respond_json(
+    {
+      resource:               "http://localhost:1234/mcp",
+      authorization_servers:  ["http://localhost:1234/"],
+      scopes_supported:       ["mcp:tools", "mcp:resources"]
+    }
+  )
+end

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

@@ -0,0 +1,26 @@
+AuthStore = import '../_lib/auth_store'
+
+# https://datatracker.ietf.org/doc/html/rfc6749#section-3.1
+export ->(req) {
+  req.validate_http_method('get')
+  params = req.query
+  req.validate(params['response_type'], 'code')
+
+  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,
+    'Location' => '/signin',
+    'Set-Cookie' => "oauth_signin_id=#{key}"
+  })
+}

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

@@ -0,0 +1,86 @@
+AuthStore = import '../_lib/auth_store'
+
+export ->(req) {
+  case req.method
+  when 'get'
+    render_consent_form(req)
+  when 'post'
+    validate_consent(req)
+  else
+    raise Syntropy::Error.method_not_allowed
+  end
+}
+
+def render_consent_form(req)
+  oauth_signin_id = req.cookies['oauth_signin_id']
+  auth_info = AuthStore.fetch(oauth_signin_id)
+  req.validate(auth_info, Hash)
+
+  client_id = auth_info['client_id']
+  req.validate(client_id, String)
+  client_info = AuthStore.fetch(client_id)
+
+  sid = auth_info['sid']
+  req.validate(sid, String)
+  session_info = AuthStore.fetch(sid)
+
+  req.respond_html(@consent_form.render(client_info, session_info))
+end
+
+def validate_consent(req)
+  data = req.get_form_data
+  decision = data['decision']
+  req.validate(decision, ['deny', 'allow'])
+
+  oauth_signin_id = req.cookies['oauth_signin_id']
+  auth_info = AuthStore.fetch(oauth_signin_id)
+  req.validate(auth_info, Hash)
+
+  callback_query = case decision
+  when 'deny'
+    {
+      error: 'access_denied',
+      state: auth_info['state']
+    }
+  when 'allow'
+    auth_code = AuthStore.store(auth_info)
+    {
+      code: auth_code,
+      state: auth_info['state']
+    }
+  end
+
+  uri = format(
+    '%s?%s', auth_info['redirect_uri'],
+    URI.encode_www_form(callback_query)
+  )
+  req.respond(
+    nil,
+    ':status' => Syntropy::HTTP::FOUND,
+    'Location' => uri
+  )
+end
+
+@consent_form = template { |client_info, session_info|
+  html {
+    head {
+      title 'My awesome site'
+    }
+    body {
+      h2 client_info['client_name']
+      p {
+        span 'wants to access my awesome site on behalf of '
+        em session_info[:username]
+        span '.'
+      }
+
+      form(action: '') {
+        div {
+          button 'Deny',  type: 'submit', name: 'decision', value: 'deny'
+          button 'Allow', type: 'submit', name: 'decision', value: 'allow'
+        }
+      }
+    }
+    auto_refresh!
+  }
+}

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

@@ -0,0 +1,15 @@
+AuthStore = import '../_lib/auth_store'
+
+# https://datatracker.ietf.org/doc/html/rfc7591
+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)
+
+  req.respond_json(
+    { client_id: }.merge(client_info),
+    ':status' => HTTP::CREATED
+  )
+}