stipa 0.1.0

data/lib/stipa/request.rb

@@ -0,0 +1,163 @@
+module Stipa
+  # Raised for any HTTP/1.1 protocol violation.
+  # Caught by Connection#dispatch and turned into a 400 response.
+  # Not a subclass of StandardError to avoid accidental rescue-all clauses
+  # catching it — but we keep it as StandardError for practical simplicity.
+  class BadRequest < StandardError; end
+
+  # Parses a raw HTTP/1.1 header block (already read by Connection) and
+  # reads the body from the socket using Content-Length.
+  #
+  # Design notes:
+  #   - Headers are stored with lower-cased keys for O(1) case-insensitive
+  #     lookup (RFC 7230 §3.2: header names are case-insensitive).
+  #   - Body is read with IO.select + read_nonblock rather than SO_RCVTIMEO
+  #     because SO_RCVTIMEO behaves inconsistently across Ruby versions and
+  #     platforms. IO.select releases the GVL while waiting.
+  #   - `id` and `params` are writable: RequestId middleware sets `id`,
+  #     the router sets `params` after matching.
+  #   - We reject header folding (obsolete since RFC 7230) with a 400.
+  #   - Chunked Transfer-Encoding is not supported in this version.
+  class Request
+    MAX_HEADER_SIZE = 8 * 1024          #  8 KB — slow-loris defence
+    MAX_BODY_SIZE   = 1 * 1024 * 1024   #  1 MB default; configurable per-server
+    VALID_METHODS   = %w[GET POST PUT PATCH DELETE HEAD OPTIONS TRACE CONNECT].freeze
+
+    attr_accessor :id, :params
+    attr_reader   :method, :path, :query_string, :http_version,
+                  :headers, :body, :bytes_in
+
+    # Factory — called by Connection after reading the header block.
+    #
+    # @param raw_headers    [String]  everything up to (not including) \r\n\r\n
+    # @param socket         [Socket]  live socket for reading remaining body bytes
+    # @param peer           [String]  remote address string (for error messages)
+    # @param body_timeout   [Numeric] seconds allowed for body read
+    # @param socket_buffer  [String]  body bytes already read by Connection
+    #                                 when it over-read past the header boundary
+    # @param config         [Hash]    server-level config overrides
+    def self.parse(raw_headers, socket:, peer:, body_timeout:,
+                   socket_buffer: '', config: {})
+      new(raw_headers, socket:, peer:, body_timeout:,
+          socket_buffer:, config:)
+    end
+
+    def initialize(raw_headers, socket:, peer:, body_timeout:,
+                   socket_buffer: '', config: {})
+      @socket        = socket
+      @peer          = peer
+      @body_timeout  = body_timeout
+      @socket_buffer = socket_buffer.b   # binary copy of pre-read body bytes
+      @max_body      = config.fetch(:max_body_size, MAX_BODY_SIZE)
+      @bytes_in      = raw_headers.bytesize
+      @id            = nil   # set by RequestId middleware
+      @params        = {}    # set by App#dispatch after route match
+      parse_headers(raw_headers)
+      read_body
+    end
+
+    # Case-insensitive header lookup: req['Content-Type'] or req['content-type']
+    def [](name)
+      @headers[name.to_s.downcase]
+    end
+
+    private
+
+    def parse_headers(raw)
+      lines = raw.split("\r\n", -1)
+      raise BadRequest, 'empty request' if lines.empty? || lines[0].empty?
+
+      parse_request_line(lines.shift)
+
+      @headers = {}
+      lines.each do |line|
+        # RFC 7230 §3.2.4: header field folding is obsolete — reject with 400
+        raise BadRequest, 'header folding not supported' if line.start_with?(' ', "\t")
+        name, value = line.split(':', 2)
+        raise BadRequest, "malformed header: #{line.inspect}" unless value
+        # RFC 7230: no whitespace between field name and colon
+        raise BadRequest, "whitespace before colon" if name != name.rstrip
+        @headers[name.downcase.strip] = value.strip
+      end
+    end
+
+    def parse_request_line(line)
+      parts = line.split(' ', 3)
+      raise BadRequest, "bad request line: #{line.inspect}" unless parts.length == 3
+
+      @method, full_path, @http_version = parts
+
+      raise BadRequest, "unknown method: #{@method}" unless VALID_METHODS.include?(@method)
+      raise BadRequest, "unknown HTTP version: #{@http_version}" \
+        unless @http_version.match?(/\AHTTP\/1\.[01]\z/)
+
+      # Separate path from query string
+      if (q = full_path.index('?'))
+        @path         = full_path[0, q]
+        @query_string = full_path[q + 1..]
+      else
+        @path         = full_path
+        @query_string = ''
+      end
+    end
+
+    def read_body
+      cl = @headers['content-length']
+      unless cl
+        @body = ''
+        return
+      end
+
+      # Integer() raises ArgumentError on non-numeric strings
+      begin
+        length = Integer(cl, 10)
+      rescue ArgumentError
+        raise BadRequest, "invalid Content-Length: #{cl.inspect}"
+      end
+
+      raise BadRequest, 'negative Content-Length' if length < 0
+      raise BadRequest, "body exceeds #{@max_body} bytes limit" if length > @max_body
+
+      @body      = read_exactly(length)
+      @bytes_in += @body.bytesize
+    end
+
+    # Read exactly `n` bytes for the body.
+    #
+    # Drains @socket_buffer first (bytes already read by Connection when it
+    # over-read past the header/body boundary), then reads remaining bytes
+    # from the live socket using IO.select + read_nonblock.
+    #
+    # GVL note: IO.select releases the GVL while waiting, so other Ruby
+    # threads continue running during I/O waits.
+    def read_exactly(n)
+      return '' if n == 0
+
+      # Start with whatever Connection already buffered
+      buf = @socket_buffer.byteslice(0, n) || ''
+      buf = String.new(buf, encoding: 'BINARY')
+
+      return buf if buf.bytesize >= n   # entire body was pre-buffered
+
+      deadline = Time.now + @body_timeout
+
+      while buf.bytesize < n
+        remaining = deadline - Time.now
+        raise BadRequest, 'body read timeout' if remaining <= 0
+
+        readable = IO.select([@socket], nil, nil, remaining)
+        raise BadRequest, 'body read timeout' if readable.nil?
+
+        want  = [n - buf.bytesize, 65_536].min
+        chunk = @socket.read_nonblock(want, exception: false)
+
+        raise BadRequest, 'unexpected EOF during body read' if chunk.nil?
+        next if chunk == :wait_readable   # spurious wakeup, retry
+
+        buf << chunk
+      end
+
+      buf
+    end
+  end
+end

data/lib/stipa/response.rb

@@ -0,0 +1,148 @@
+require 'json'
+
+module Stipa
+  # Builds a valid HTTP/1.1 response and serializes it to wire bytes.
+  #
+  # Design notes:
+  #   - Content-Length is ALWAYS computed from body.bytesize in to_http,
+  #     never stored manually. This prevents handler authors from setting
+  #     a wrong value and makes binary correctness automatic.
+  #   - Header names are stored in Title-Case for wire compatibility but
+  #     set_header accepts any casing for developer ergonomics.
+  #   - Keep-alive vs Connection:close is decided in to_http based on the
+  #     request's HTTP version, so handler code never needs to think about it.
+  #   - The Date header is injected automatically — required by RFC 7231.
+  class Response
+    STATUS_MESSAGES = {
+      200 => 'OK',
+      201 => 'Created',
+      204 => 'No Content',
+      301 => 'Moved Permanently',
+      302 => 'Found',
+      304 => 'Not Modified',
+      400 => 'Bad Request',
+      401 => 'Unauthorized',
+      403 => 'Forbidden',
+      404 => 'Not Found',
+      405 => 'Method Not Allowed',
+      408 => 'Request Timeout',
+      413 => 'Payload Too Large',
+      422 => 'Unprocessable Entity',
+      429 => 'Too Many Requests',
+      500 => 'Internal Server Error',
+      502 => 'Bad Gateway',
+      503 => 'Service Unavailable',
+      504 => 'Gateway Timeout',
+    }.freeze
+
+    attr_accessor :status, :body, :template_engine
+    attr_reader   :headers
+
+    def initialize
+      @status          = 200
+      @headers         = {}
+      @body            = ''
+      @template_engine = nil
+    end
+
+    # Set a response header. Name is normalized to Title-Case.
+    # Accepts any casing: set_header('content-type', 'text/html') is fine.
+    def set_header(name, value)
+      @headers[titlecase(name)] = value.to_s
+    end
+    alias []= set_header
+
+    def [](name)
+      @headers[titlecase(name)]
+    end
+
+    # Render an ERB template and set the body + Content-Type to text/html.
+    #
+    # Requires a template engine to be configured on the app:
+    #   app = Stipa::App.new(views: 'views')
+    #
+    # Examples:
+    #   res.render('home')
+    #   res.render('users/show', locals: { user: @user })
+    #   res.render('welcome',    locals: { name: 'Alice' }, layout: false)
+    #   res.render('dashboard',  layout: 'layouts/admin')
+    #
+    # Returns self for chaining.
+    def render(template, locals: {}, layout: :default)
+      raise 'No template engine configured. Pass views: "path" to Stipa::App.new.' \
+        unless @template_engine
+
+      set_header('Content-Type', 'text/html; charset=utf-8')
+      @body = @template_engine.render(template, locals: locals, layout: layout)
+      self
+    end
+
+    # Set body to a JSON representation of `data` and set Content-Type.
+    # Returns self so it can be used as the last expression in a handler.
+    def json(data)
+      @body = JSON.generate(data)
+      set_header('Content-Type', 'application/json; charset=utf-8')
+      self
+    end
+
+    # Serialize to the exact HTTP/1.1 bytes to write to the socket.
+    # `req` is used to decide the Connection header (keep-alive or close).
+    def to_http(req = nil)
+      # Force binary encoding so bytesize is always the byte count,
+      # not the character count (matters for multi-byte UTF-8 bodies).
+      body_bytes = @body.to_s.b
+
+      finalize_headers(body_bytes, req)
+
+      status_text  = STATUS_MESSAGES.fetch(@status, 'Unknown')
+      status_line  = "HTTP/1.1 #{@status} #{status_text}"
+      header_block = @headers.map { |k, v| "#{k}: #{v}" }.join("\r\n")
+
+      # RFC 7230: blank line (CRLF CRLF) separates header block from body
+      "#{status_line}\r\n#{header_block}\r\n\r\n#{body_bytes}"
+    end
+
+    private
+
+    # Inject protocol-level headers last so handlers cannot accidentally
+    # set a wrong Content-Length or omit a required header.
+    def finalize_headers(body_bytes, req)
+      # Content-Length: always recomputed from actual bytes
+      set_header('Content-Length', body_bytes.bytesize)
+
+      # Default Content-Type if handler didn't set one
+      set_header('Content-Type', 'text/plain; charset=utf-8') \
+        unless @headers.key?('Content-Type')
+
+      # Date: required by RFC 7231 §7.1.1.2
+      set_header('Date', Time.now.utc.strftime('%a, %d %b %Y %H:%M:%S GMT'))
+
+      # Server: identifies the framework
+      set_header('Server', "Stipa/#{Stipa::VERSION}")
+
+      inject_connection_header(req) if req
+    end
+
+    # Set Connection header based on HTTP version and client's preference.
+    # HTTP/1.1 defaults to keep-alive; HTTP/1.0 defaults to close.
+    def inject_connection_header(req)
+      if keep_alive?(req)
+        set_header('Connection', 'keep-alive')
+        set_header('Keep-Alive', 'timeout=5, max=100')
+      else
+        set_header('Connection', 'close')
+      end
+    end
+
+    def keep_alive?(req)
+      return false if @status >= 500   # always close after server errors
+      conn = req['connection']&.downcase
+      req.http_version == 'HTTP/1.1' ? conn != 'close' : conn == 'keep-alive'
+    end
+
+    # Convert any casing to HTTP Title-Case: "content-type" → "Content-Type"
+    def titlecase(name)
+      name.to_s.split('-').map(&:capitalize).join('-')
+    end
+  end
+end

data/lib/stipa/server.rb

@@ -0,0 +1,190 @@
+require 'socket'
+require_relative 'thread_pool'
+require_relative 'connection'
+require_relative 'request'
+require_relative 'response'
+require_relative 'logger'
+
+module Stipa
+  # TCP accept loop and connection lifecycle manager.
+  #
+  # Architecture:
+  #
+  #   Main thread (accept loop)          Worker threads (pool)
+  #   ─────────────────────────          ──────────────────────────────────
+  #   TCPServer.accept_nonblock            Connection.new(socket, ...).run
+  #     └─> pool.submit(job)   ─────>        └─> Request.parse
+  #           (drop → 503)                    └─> app.call(req, res)
+  #           (accept continues)              └─> write_response
+  #
+  # Socket options:
+  #   SO_REUSEADDR  — always set; allows rebinding immediately after SIGTERM
+  #                   without waiting for the TIME_WAIT timeout (~60 s).
+  #   SO_REUSEPORT  — set on Linux ≥ 3.9 when available; multiple processes
+  #                   can bind the same port simultaneously, enabling zero-
+  #                   downtime rolling restarts via a process supervisor.
+  #   TCP_NODELAY   — disables Nagle's algorithm; reduces latency for small
+  #                   responses (JSON APIs) by sending immediately rather than
+  #                   waiting to coalesce small writes.
+  #   listen(1024)  — kernel-level SYN backlog; OSes cap at net.core.somaxconn.
+  #
+  # Backpressure (when all workers are busy and the queue is full):
+  #   We write a 503 directly on the accept thread without involving a worker.
+  #   This keeps the accept loop free to continue processing new connections
+  #   and avoids wasting a worker thread on a connection we'll immediately reject.
+  #
+  # Graceful shutdown (SIGTERM / SIGINT):
+  #   1. @running = false → accept loop exits after the current poll returns
+  #   2. pool.shutdown(drain_timeout:) → waits for in-flight requests to finish
+  #   3. server socket is closed in the ensure block of start
+  class Server
+    DEFAULT_CONFIG = {
+      host:                '0.0.0.0',
+      port:                3710,
+      pool_size:           32,
+      queue_depth:         64,
+      drain_timeout:       30,
+      header_read_timeout: 10,
+      body_read_timeout:   30,
+      write_timeout:       10,
+      keepalive_timeout:   5,
+      max_requests:        100,
+      max_header_size:     8 * 1024,
+      max_body_size:       1 * 1024 * 1024,
+      backpressure:        :drop,   # :drop (503) or :block (wait briefly)
+      log_level:           :info,
+    }.freeze
+
+    def initialize(app:, **overrides)
+      @app    = app   # compiled middleware+router callable
+      @config = DEFAULT_CONFIG.merge(overrides)
+      @logger = Logger.new(level: @config[:log_level])
+      @pool   = ThreadPool.new(
+        size:        @config[:pool_size],
+        queue_depth: @config[:queue_depth],
+        on_error:    method(:pool_error),
+      )
+      @running = false
+    end
+
+    # Start the server. Blocks until SIGTERM/SIGINT.
+    def start
+      @server  = build_server_socket
+      @running = true
+
+      register_signals
+
+      @logger.info(
+        req: nil, res: nil,
+        msg: 'Stīpa listening',
+        host: @config[:host],
+        port: @config[:port],
+        workers: @config[:pool_size],
+        queue: @config[:queue_depth],
+      )
+
+      accept_loop
+    ensure
+      @server&.close rescue nil
+      @logger.info(req: nil, res: nil, msg: 'Stīpa stopped')
+    end
+
+    private
+
+    def accept_loop
+      while @running
+        begin
+          # accept_nonblock raises IO::WaitReadable when no connection is
+          # waiting. We use IO.select to poll every 100ms so @running is
+          # checked regularly for clean shutdown.
+          socket = @server.accept_nonblock
+        rescue IO::WaitReadable
+          IO.select([@server], nil, nil, 0.1)
+          retry
+        rescue Errno::ECONNABORTED, Errno::EPROTO
+          # Connection was aborted between SYN and accept — ignore and continue
+          retry
+        rescue IOError, Errno::EBADF
+          # Server socket was closed (shutdown path) — exit the loop
+          break
+        end
+
+        configure_client(socket)
+        enqueue_or_503(socket)
+      end
+    end
+
+    # Try to hand the socket to the thread pool. If the queue is full,
+    # write a 503 directly on the accept thread and close the socket.
+    def enqueue_or_503(socket)
+      submitted = @pool.submit(mode: @config[:backpressure]) do
+        Connection.new(
+          socket,
+          app:    @app,
+          logger: @logger,
+          config: @config,
+        ).run
+      end
+
+      return if submitted
+
+      # Queue is full — fast reject
+      @logger.warn('backpressure 503', queue_depth: @pool.queue_depth)
+      begin
+        socket.write(
+          "HTTP/1.1 503 Service Unavailable\r\n" \
+          "Content-Type: text/plain\r\n" \
+          "Content-Length: 19\r\n" \
+          "Connection: close\r\n" \
+          "\r\n" \
+          "Service Unavailable"
+        )
+      rescue nil
+      ensure
+        socket.close rescue nil
+      end
+    end
+
+    def build_server_socket
+      server = TCPServer.new(@config[:host], @config[:port])
+
+      # SO_REUSEADDR: rebind immediately after SIGTERM without TIME_WAIT delay
+      server.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+
+      # SO_REUSEPORT (Linux ≥ 3.9): allows multiple processes on the same port
+      # for zero-downtime rolling restarts. Guard with const_defined? for
+      # portability across macOS, BSD, and older Linux kernels.
+      if Socket.const_defined?(:SO_REUSEPORT)
+        server.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEPORT, true)
+      end
+
+      # Backlog of 1024: kernel queues up to this many SYN_RCVD connections.
+      # The actual limit is min(1024, net.core.somaxconn) on Linux.
+      server.listen(1024)
+      server
+    end
+
+    def configure_client(socket)
+      # TCP_NODELAY disables Nagle's algorithm so small responses
+      # (e.g., a 200-byte JSON body) are sent in one TCP segment
+      # rather than waiting 40–200ms for more data to coalesce.
+      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true)
+    rescue StandardError
+      # Not fatal — continue without TCP_NODELAY
+    end
+
+    def register_signals
+      shutdown_proc = ->(_signal) {
+        @logger.warn('shutdown signal received')
+        @running = false
+        @pool.shutdown(drain_timeout: @config[:drain_timeout])
+      }
+      trap('TERM', &shutdown_proc)
+      trap('INT',  &shutdown_proc)
+    end
+
+    def pool_error(err, _job)
+      @logger.error("worker crash: #{err.class}: #{err.message}")
+    end
+  end
+end

data/lib/stipa/static.rb

@@ -0,0 +1,92 @@
+module Stipa
+  module Middleware
+    # Serve static files from a directory (typically 'public/').
+    #
+    # Features:
+    #   - Path traversal prevention (no ../../ escaping the root)
+    #   - Correct MIME types for web assets including .vue and .mjs files
+    #   - ETag-based conditional GET (304 Not Modified)
+    #   - HEAD request support
+    #   - Only intercepts GET/HEAD; other methods fall through to the app
+    #
+    # Usage:
+    #   app.use Stipa::Middleware::Static, root: 'public'
+    #   app.use Stipa::Middleware::Static, root: '/srv/myapp/public', prefix: '/assets'
+    class Static
+      MIME_TYPES = {
+        '.html'  => 'text/html; charset=utf-8',
+        '.css'   => 'text/css; charset=utf-8',
+        '.js'    => 'application/javascript; charset=utf-8',
+        '.mjs'   => 'application/javascript; charset=utf-8',
+        # .vue files are served as JS so the browser can import them as ES modules
+        '.vue'   => 'application/javascript; charset=utf-8',
+        '.json'  => 'application/json; charset=utf-8',
+        '.png'   => 'image/png',
+        '.jpg'   => 'image/jpeg',
+        '.jpeg'  => 'image/jpeg',
+        '.gif'   => 'image/gif',
+        '.webp'  => 'image/webp',
+        '.svg'   => 'image/svg+xml',
+        '.ico'   => 'image/x-icon',
+        '.woff'  => 'font/woff',
+        '.woff2' => 'font/woff2',
+        '.ttf'   => 'font/ttf',
+        '.eot'   => 'application/vnd.ms-fontobject',
+        '.map'   => 'application/json',
+        '.txt'   => 'text/plain; charset=utf-8',
+        '.xml'   => 'application/xml; charset=utf-8',
+      }.freeze
+
+      # root:   directory to serve files from (absolute or relative to cwd)
+      # prefix: URL path prefix that triggers static file serving (default '/')
+      def initialize(next_app, root:, prefix: '/')
+        @next_app = next_app
+        @root   = File.expand_path(root)
+        @prefix = prefix.chomp('/')
+      end
+
+      def call(req, res)
+        if %w[GET HEAD].include?(req.method) && req.path.start_with?("#{@prefix}/", @prefix)
+          rel = req.path.delete_prefix(@prefix)
+          found = serve_static(rel, req, res)
+          return found if found
+        end
+        @next_app.call(req, res)
+      end
+
+      private
+
+      def serve_static(rel_path, req, res)
+        full_path = File.expand_path(File.join(@root, rel_path))
+
+        # Security: reject any path that escapes the root directory.
+        # File.expand_path resolves '..' so this comparison is reliable.
+        root_with_sep = @root.end_with?(File::SEPARATOR) ? @root : "#{@root}#{File::SEPARATOR}"
+        return nil unless full_path.start_with?(root_with_sep)
+        return nil unless File.file?(full_path)
+
+        stat         = File.stat(full_path)
+        etag         = %("stipa-#{stat.mtime.to_i}-#{stat.size}")
+        content_type = MIME_TYPES.fetch(File.extname(full_path).downcase, 'application/octet-stream')
+
+        res['ETag']          = etag
+        res['Cache-Control'] = 'public, max-age=3600'
+        res['Content-Type']  = content_type
+
+        if req['if-none-match'] == etag
+          res.status = 304
+          res.body   = ''
+        elsif req.method == 'HEAD'
+          res.status = 200
+          res.body   = ''
+          res['Content-Length'] = stat.size.to_s
+        else
+          res.status = 200
+          res.body   = File.binread(full_path)
+        end
+
+        res
+      end
+    end
+  end
+end