otto 1.1.0.pre.alpha4 → 1.3.0

data/README.md

@@ -1,150 +1,99 @@
-# Otto - 1.0 (2024-04-05)
+# Otto - 1.2 (2025-08-18)
 
-**Auto-define your rack-apps in plain-text.**
+**Define your rack-apps in plain-text with built-in security.**
 
-## Overview
+![Otto mascot](public/img/otto.jpg "Otto - All Rack, no Pinion")
 
-Apps built with Otto have three, basic parts: a rackup file, a ruby file, and a routes file. If you've built a [Rack app](https://github.com/rack/rack) before, then you've seen a rackup file before. The ruby file is your actual app and the routes file is what Otto uses to map URI paths to a Ruby class and method.
-
-A barebones app directory looks something like this:
+Otto apps have three files: a rackup file, a Ruby class, and a routes file. The routes file is just plain text that maps URLs to Ruby methods.
 
 ```bash
-  $ cd myapp
-  $ ls
-  config.ru app.rb routes
+$ cd myapp && ls
+config.ru app.rb routes
 ```
 
-See the examples/ directory for a working app.
+## Routes File
+```
+# routes
 
+GET   /                         App#index
+POST  /feedback                 App#receive_feedback
+GET   /product/:id              App#show_product
+GET   /robots.txt               App#robots_text
+GET   /404                      App#not_found
+```
 
-### Routes
+## Ruby Class
+```ruby
+# app.rb
 
-The routes file is just a plain-text file which defines the end points of your application. Each route has three parts:
+class App
+  def initialize(req, res)
+    @req, @res = req, res
+  end
 
- * HTTP verb (GET, POST, PUT, DELETE or HEAD)
- * URI path
- * Ruby class and method to call
+  def index
+    res.body = '<h1>Hello Otto</h1>'
+  end
 
-Here is an example:
+  def show_product
+    product_id = req.params[:id]
+    res.body = "Product: #{product_id}"
+  end
 
-```ruby
-  GET   /                         App#index
-  POST  /                         App#receive_feedback
-  GET   /redirect                 App#redirect
-  GET   /robots.txt               App#robots_text
-  GET   /product/:prodid          App#display_product
-
-  # You can also define these handlers when no
-  # route can be found or there's a server error. (optional)
-  GET   /404                      App#not_found
-  GET   /500                      App#server_error
+  def robots_text
+    res.header['Content-Type'] = "text/plain"
+    rules = 'User-agent: *', 'Disallow: /private/keep/out'
+    res.body = rules.join($/)
+  end
+end
 ```
 
-### App
+## Rackup File
+```ruby
+# config.ru
 
-There is nothing special about the Ruby class. The only requirement is that the first two arguments to initialize be a Rack::Request object and a Rack::Response object. Otherwise, you can do anything you want. You're free to use any templating engine, any database mapper, etc. There is no magic.
+require 'otto'
+require 'app'
 
-```ruby
-  class App
-    attr_reader :req, :res
-
-    # Otto creates an instance of this class for every request
-    # and passess the Rack::Request and Rack::Response objects.
-    def initialize req, res
-      @req, @res = req, res
-    end
-
-    def index
-      res.header['Content-Type'] = "text/html; charset=utf-8"
-      lines = [
-        '<img src="/img/otto.jpg" /><br/><br/>',
-        'Send feedback:<br/>',
-        '<form method="post"><input name="msg" /><input type="submit" /></form>',
-        '<a href="/product/100">A product example</a>'
-      ]
-      res.body = lines.join($/)
-    end
-
-    def receive_feedback
-      res.body = req.params.inspect
-    end
-
-    def redirect
-      res.redirect '/robots.txt'
-    end
-
-    def robots_text
-      res.header['Content-Type'] = "text/plain"
-      rules = 'User-agent: *', 'Disallow: /private'
-      res.body = rules.join($/)
-    end
-
-    def display_product
-      res.header['Content-Type'] = "application/json; charset=utf-8"
-      prodid = req.params[:prodid]
-      res.body = '{"product":%s,"msg":"Hint: try another value"}' % [prodid]
-    end
-
-    def not_found
-      res.status = 404
-      res.body = "Item not found!"
-    end
-
-    def server_error
-      res.status = 500
-      res.body = "There was a server error!"
-    end
-  end
+run Otto.new("./routes")
 ```
 
 
-### Rackup
+## Security Features
 
-There is also nothing special about the rackup file. It just builds a Rack app using your routes file.
+Otto includes optional security features for production apps:
 
 ```ruby
-  require 'otto'
-  require 'app'
-
-  app = Otto.new("./routes")
-
-  map('/') {
-    run app
-  }
+# Enable security features
+app = Otto.new("./routes", {
+  csrf_protection: true,      # CSRF tokens and validation
+  request_validation: true,   # Input sanitization and limits
+  trusted_proxies: ['10.0.0.0/8']
+})
 ```
 
-See the examples/ directory for a working app.
+Security features include CSRF protection, input validation, security headers, and trusted proxy configuration.
 
+## Requirements
 
-## Installation
+- Ruby 3.4+
+- Rack 3.1+
 
-Get it in one of the following ways:
+## Installation
 
 ```bash
-  $ gem install otto
-
-  [ Add it to yer Gemfile]
-  $ bundle install
-
-  $ git clone git://github.com/delano/otto.git
+gem install otto
 ```
 
+## AI Development Assistance
 
-You can also download via [tarball](https://github.com/delano/otto/tarball/latest) or [zip](https://github.com/delano/otto/zipball/latest).
-
-
-## More Information
-
-* [Homepage](https://github.com/delano/otto)
-
-
-## In the wild
-
-Services that use Otto:
-
-* [Onetime Secret](https://onetimesecret.com/) -- A safe way to share sensitive data.
+Version 1.2.0's security features were developed with AI assistance:
 
+* **Zed Agent (Claude Sonnet 4)** - Security implementation and testing
+* **Claude Desktop** - Rack 3+ compatibility and debugging
+* **GitHub Copilot** - Code completion
 
+The maintainer remains responsible for all security decisions and implementation. We believe in transparency about development tools, especially for security-focused software.
 
 ## License
 

data/examples/basic/app.rb

@@ -0,0 +1,78 @@
+# examples/basic/app.rb (Streamlined with Design System)
+
+require_relative '../../lib/otto/design_system'
+
+class App
+  include Otto::DesignSystem
+
+  attr_reader :req, :res
+
+  def initialize(req, res)
+    @req                        = req
+    @res                        = res
+    res.headers['content-type'] = 'text/html; charset=utf-8'
+  end
+
+  def index
+    content = <<~HTML
+      <div class="otto-card otto-text-center">
+        <img src="/img/otto.jpg" alt="Otto Framework" class="otto-logo" />
+        <h1>Otto Framework</h1>
+        <p>Minimal Ruby web framework with style</p>
+      </div>
+
+      #{otto_card('Send Feedback') do
+        otto_form_wrapper do
+          otto_input('msg', placeholder: 'Your message...') +
+          otto_button('Send Feedback')
+        end
+      end}
+    HTML
+
+    res.send_secure_cookie :sess, 1_234_567, 3600
+    res.body = otto_page(content)
+  end
+
+  def receive_feedback
+    message = req.params['msg']&.strip
+
+    content = if message.nil? || message.empty?
+      otto_alert('error', 'Empty Message', 'Please enter a message before submitting.')
+    else
+      otto_alert('success', 'Feedback Received', 'Thanks for your message!') +
+        otto_card('Your Message') { otto_code_block(message, 'text') }
+    end
+
+    content += "<p>#{otto_link('← Back', '/')}</p>"
+    res.body = otto_page(content, 'Feedback')
+  end
+
+  def redirect
+    res.redirect '/robots.txt'
+  end
+
+  def robots_text
+    res.headers['content-type'] = 'text/plain'
+    res.body                    = ['User-agent: *', 'Disallow: /private'].join($/)
+  end
+
+  def display_product
+    res.headers['content-type'] = 'application/json; charset=utf-8'
+    prodid                      = req.params[:prodid]
+    res.body                    = format('{"product":%s,"msg":"Hint: try another value"}', prodid)
+  end
+
+  def not_found
+    res.status = 404
+    content    = otto_alert('error', 'Not Found', 'The requested page could not be found.')
+    content   += "<p>#{otto_link('← Home', '/')}</p>"
+    res.body   = otto_page(content, '404')
+  end
+
+  def server_error
+    res.status = 500
+    content    = otto_alert('error', 'Server Error', 'An internal server error occurred.')
+    content   += "<p>#{otto_link('← Home', '/')}</p>"
+    res.body   = otto_page(content, '500')
+  end
+end

data/examples/basic/config.ru

@@ -0,0 +1,30 @@
+# examples/basic/config.ru
+
+# OTTO EXAMPLE APP CONFIG - 2011-12-17
+#
+# Usage:
+#
+#     $ thin -e dev -R config.ru -p 10770 start
+
+public_path = File.expand_path('../../public', __dir__)
+
+require_relative '../../lib/otto'
+require_relative 'app'
+
+app = Otto.new('routes')
+
+# DEV: Run web apps with extra logging and reloading
+if Otto.env?(:dev)
+
+  map('/') do
+    use Rack::CommonLogger
+    use Rack::Reloader, 0
+    app.option[:public] = public_path
+    app.add_static_path '/favicon.ico'
+    run app
+  end
+
+# PROD: run the webapp on the metal
+else
+  map('/') { run app }
+end

data/examples/basic/routes

@@ -0,0 +1,20 @@
+# examples/basic/routes
+
+# OTTO - ROUTES EXAMPLE
+
+# Each route has three parts:
+#  * HTTP verb (GET, POST, PUT, DELETE or HEAD)
+#  * URI path
+#  * Ruby class and method to call
+
+GET   /                         App#index
+POST  /                         App#receive_feedback
+GET   /redirect                 App#redirect
+GET   /robots.txt               App#robots_text
+
+GET   /bogus                    App#no_such_method
+
+# You can also define these handlers when no
+# route can be found or there's a server error. (optional)
+GET   /404                      App#not_found
+GET   /500                      App#server_error

data/examples/dynamic_pages/app.rb

@@ -0,0 +1,115 @@
+# examples/basic/app.rb (Streamlined with Design System)
+
+require_relative '../../lib/otto/design_system'
+
+class App
+  include Otto::DesignSystem
+
+  attr_reader :req, :res
+
+  def initialize(req, res)
+    @req                        = req
+    @res                        = res
+    res.headers['content-type'] = 'text/html; charset=utf-8'
+  end
+
+  def index
+    # This demonstrates nested heredocs in Ruby
+    # The outer heredoc uses <<~HTML delimiter
+    content = <<~HTML
+      <div class="otto-card otto-text-center">
+        <img src="/img/otto.jpg" alt="Otto Framework" class="otto-logo" />
+        <h1>Otto Framework</h1>
+        <p>Minimal Ruby web framework with style</p>
+      </div>
+
+      #{otto_card('Dynamic Pages') do
+        # This is a nested heredoc within the outer HTML heredoc
+        # It uses a different delimiter (EXAMPLES) to avoid conflicts
+        # The #{} interpolation allows the inner heredoc to be embedded
+        <<~EXAMPLES
+          #{otto_link('Product #100', '/product/100')} - View product page<br>
+          #{otto_link('Product #42', '/product/42')} - Different product<br>
+          #{otto_link('API Data', '/product/100.json')} - JSON endpoint
+        EXAMPLES
+      end}
+    HTML
+
+    res.send_secure_cookie :sess, 1_234_567, 3600
+    res.body = otto_page(content)
+  end
+
+  def receive_feedback
+    message = req.params['msg']&.strip
+
+    content = if message.nil? || message.empty?
+      otto_alert('error', 'Empty Message', 'Please enter a message before submitting.')
+    else
+      otto_alert('success', 'Feedback Received', 'Thanks for your message!') +
+        otto_card('Your Message') { otto_code_block(message, 'text') }
+    end
+
+    content += "<p>#{otto_link('← Back', '/')}</p>"
+    res.body = otto_page(content, 'Feedback')
+  end
+
+  def redirect
+    res.redirect '/robots.txt'
+  end
+
+  def robots_text
+    res.headers['content-type'] = 'text/plain'
+    res.body                    = ['User-agent: *', 'Disallow: /private'].join($/)
+  end
+
+  def display_product
+    prodid = req.params[:prodid]
+
+    # Check if JSON is requested via .json extension or Accept header
+    wants_json = req.path_info.end_with?('.json') ||
+                 req.env['HTTP_ACCEPT']&.include?('application/json')
+
+    if wants_json
+      res.headers['content-type'] = 'application/json; charset=utf-8'
+      res.body                    = format('{"product":%s,"msg":"Hint: try another value"}', prodid)
+    else
+      # Return HTML product page
+      product_data = {
+        'Product ID' => prodid,
+        'Name' => "Sample Product ##{prodid}",
+        'Price' => "$#{rand(10..999)}.99",
+        'Description' => 'This is a demonstration product showing dynamic routing with parameter :prodid',
+        'Stock' => rand(0..50) > 5 ? 'In Stock' : 'Out of Stock',
+      }
+
+      product_html = product_data.map do |key, value|
+        "<p><strong>#{key}:</strong> #{escape_html(value.to_s)}</p>"
+      end.join
+
+      content = <<~HTML
+        #{otto_card('Product Details') { product_html }}
+
+        <p>
+          #{otto_link('← Back to Home', '/')} |
+          #{otto_link('View as JSON', "/product/#{prodid}.json")}
+        </p>
+      HTML
+
+      res.body = otto_page(content, "Product ##{prodid}")
+    end
+  end
+
+  def not_found
+    res.status = 404
+    content    = otto_alert('error', 'Not Found', 'The requested page could not be found.')
+    content   += "<p>#{otto_link('← Home', '/')}</p>"
+    res.body   = otto_page(content, '404')
+  end
+
+  def server_error
+    res.status = 500
+    content    = otto_alert('error', 'Server Error', 'An internal server error occurred.')
+    content   += "<p>#{otto_link('← Home', '/')}</p>"
+    res.body   = otto_page(content, '500')
+  end
+end

data/examples/dynamic_pages/config.ru

@@ -0,0 +1,30 @@
+# examples/basic/config.ru
+
+# OTTO EXAMPLE APP CONFIG - 2025-08-18
+#
+# Usage:
+#
+#     $ thin -e dev -R config.ru -p 10770 start
+
+public_path = File.expand_path('../../public', __dir__)
+
+require_relative '../../lib/otto'
+require_relative 'app'
+
+app = Otto.new('routes')
+
+# DEV: Run web apps with extra logging and reloading
+if Otto.env?(:dev)
+
+  map('/') do
+    use Rack::CommonLogger
+    use Rack::Reloader, 0
+    app.option[:public] = public_path
+    app.add_static_path '/favicon.ico'
+    run app
+  end
+
+# PROD: run the webapp on the metal
+else
+  map('/') { run app }
+end

data/{example → examples/dynamic_pages}/routes

@@ -1,3 +1,5 @@
+# examples/basic/routes
+
 # OTTO - ROUTES EXAMPLE
 
 # Each route has three parts:
@@ -13,7 +15,7 @@ GET   /product/:prodid          App#display_product
 
 GET   /bogus                    App#no_such_method
 
-# You can also define these handlers when no 
-# route can be found or there's a server error. (optional) 
+# You can also define these handlers when no
+# route can be found or there's a server error. (optional)
 GET   /404                      App#not_found
-GET   /500                      App#server_error
+GET   /500                      App#server_error