stipa 0.1.0

data/lib/stipa/connection.rb

@@ -0,0 +1,200 @@
+require 'socket'
+
+module Stipa
+  # Manages the HTTP/1.1 keep-alive request/response loop for a single socket.
+  #
+  # A Connection is created by the Server for every accepted TCP socket and
+  # runs inside a worker thread from the ThreadPool. It owns the socket for
+  # the lifetime of the keep-alive session and closes it on exit.
+  #
+  # Keep-alive protocol:
+  #   HTTP/1.1: persistent by default. We close when:
+  #     - client sends "Connection: close"
+  #     - we've served max_requests on this connection
+  #     - a read/write timeout fires (slow client or idle connection)
+  #     - a parse error occurs (send 400, close — client is misbehaving)
+  #     - an unhandled exception occurs (send 500, close)
+  #   HTTP/1.0: close by default unless client sends "Connection: keep-alive"
+  #
+  # Timeout strategy (using IO.select, not SO_RCVTIMEO):
+  #   - header_read_timeout (10s): time to receive the full header block.
+  #     Applied to the FIRST request on a new connection. Defeats slow-loris.
+  #   - keepalive_timeout (5s): idle time allowed BETWEEN requests on a
+  #     persistent connection. Much shorter than header_read_timeout.
+  #   - body_read_timeout (30s): time to read the request body after headers.
+  #   - write_timeout (10s): time to flush the full response to the client.
+  #
+  # Why IO.select instead of SO_RCVTIMEO?
+  #   SO_RCVTIMEO raises Errno::EAGAIN or EWOULDBLOCK inconsistently across
+  #   Ruby versions, especially in combination with Ruby's IO buffering. IO.select
+  #   is pure Ruby scheduler: it releases the GVL while waiting, allows other
+  #   threads to run, and works identically on Linux, macOS, and JRuby.
+  class Connection
+    CRLF2 = "\r\n\r\n".freeze
+
+    # Default timeouts and limits — all overridable via server config hash
+    DEFAULTS = {
+      header_read_timeout: 10,
+      body_read_timeout:   30,
+      write_timeout:       10,
+      keepalive_timeout:   5,
+      max_requests:        100,
+      max_header_size:     Request::MAX_HEADER_SIZE,
+    }.freeze
+
+    def initialize(socket, app:, logger:, config: {})
+      @socket          = socket
+      @app             = app      # compiled middleware+router callable
+      @logger          = logger
+      cfg              = DEFAULTS.merge(config)
+      @header_timeout  = cfg[:header_read_timeout]
+      @body_timeout    = cfg[:body_read_timeout]
+      @write_timeout   = cfg[:write_timeout]
+      @ka_timeout      = cfg[:keepalive_timeout]
+      @max_requests    = cfg[:max_requests]
+      @max_header_size = cfg[:max_header_size]
+      @requests_served = 0
+      @peer            = @socket.remote_address.inspect_sockaddr rescue 'unknown'
+    end
+
+    # Drive the request/response loop until the connection should be closed.
+    def run
+      loop do
+        # First request: use the full header timeout.
+        # Subsequent requests on the same connection: use the shorter
+        # keepalive idle timeout so we don't hold worker threads too long.
+        idle_timeout = @requests_served.zero? ? @header_timeout : @ka_timeout
+
+        result = read_headers(idle_timeout)
+        break if result.nil?   # clean EOF, timeout, or parse error
+
+        raw_headers, leftover = result
+
+        req = Request.parse(
+          raw_headers,
+          socket:        @socket,
+          peer:          @peer,
+          body_timeout:  @body_timeout,
+          socket_buffer: leftover,
+        )
+
+        res        = Response.new
+        keep_going = dispatch(req, res)
+
+        write_response(res, req)
+        @requests_served += 1
+
+        break unless keep_going && persistent?(req, res)
+      end
+    rescue => e
+      # Unexpected error outside the request cycle (e.g., SSL error)
+      @logger.error("connection error peer=#{@peer}: #{e.class}: #{e.message}")
+    ensure
+      # Always close the socket, even if an exception escapes
+      @socket.close rescue nil
+    end
+
+    private
+
+    # Read from the socket until we have the complete HTTP header block,
+    # identified by the \r\n\r\n separator.
+    #
+    # Returns [header_string, leftover_body_bytes], or nil on EOF/timeout/error.
+    #
+    # Why return leftover? We read in 4096-byte chunks, so a small POST body
+    # may land in the same chunk as the headers. Those bytes must be passed
+    # to Request as a pre-buffered "socket_buffer" — otherwise Request would
+    # try to read them from the socket again and either block or time out.
+    def read_headers(timeout)
+      buf      = String.new(encoding: 'BINARY')
+      deadline = Time.now + timeout
+
+      loop do
+        remaining = deadline - Time.now
+        return nil if remaining <= 0   # timeout before headers arrived
+
+        readable = IO.select([@socket], nil, nil, remaining)
+        return nil if readable.nil?    # select timed out
+
+        chunk = @socket.read_nonblock(4096, exception: false)
+        return nil if chunk.nil?                  # EOF — client disconnected
+        next       if chunk == :wait_readable      # spurious wakeup
+
+        buf << chunk
+
+        if buf.bytesize > @max_header_size
+          @logger.warn('oversized headers, closing', peer: @peer,
+                                                     size: buf.bytesize)
+          return nil
+        end
+
+        break if buf.include?(CRLF2)
+      end
+
+      # Split precisely at the blank line; leftover is body bytes already read.
+      head, leftover = buf.split(CRLF2, 2)
+      [head, leftover || '']
+    rescue EOFError, Errno::ECONNRESET, Errno::EPIPE
+      nil   # client disconnected mid-headers — close silently
+    end
+
+    # Run the middleware+router chain. Returns true if the connection can
+    # continue (keep-alive), false if it should close after this response.
+    def dispatch(req, res)
+      @app.call(req, res)
+      true
+    rescue BadRequest => e
+      # Protocol violation — send 400 and close the connection.
+      # Closing prevents further requests on a potentially corrupt stream.
+      res.status = 400
+      res.body   = "Bad Request: #{e.message}"
+      false
+    rescue => e
+      req_id = req.id || '-'
+      @logger.error("handler error req_id=#{req_id} path=#{req.path}: " \
+                    "#{e.class}: #{e.message}")
+      res.status = 500
+      res.body   = 'Internal Server Error'
+      false   # close after 500 to avoid a corrupted response stream
+    end
+
+    # Write the serialized response to the socket with a deadline.
+    # Uses write_nonblock + IO.select so the worker thread's GVL hold
+    # is minimal and slow clients don't block other in-flight requests.
+    def write_response(res, req)
+      data     = res.to_http(req)
+      deadline = Time.now + @write_timeout
+      written  = 0
+
+      while written < data.bytesize
+        remaining = deadline - Time.now
+        if remaining <= 0
+          @logger.warn('write timeout', peer: @peer)
+          return
+        end
+
+        writable = IO.select(nil, [@socket], nil, remaining)
+        if writable.nil?
+          @logger.warn('write timeout (select)', peer: @peer)
+          return
+        end
+
+        n = @socket.write_nonblock(data.byteslice(written..), exception: false)
+        next if n == :wait_writable
+        written += n
+      end
+
+      @logger.info(req:, res:, bytes_in: req.bytes_in, bytes_out: data.bytesize)
+    rescue Errno::EPIPE, Errno::ECONNRESET
+      # Client disconnected before we finished writing — not an error worth logging
+    end
+
+    # Determine whether to keep the connection alive for another request.
+    def persistent?(req, res)
+      return false if @requests_served >= @max_requests
+      return false if res.status >= 500   # decided to close in dispatch
+      conn = req['connection']&.downcase
+      req.http_version == 'HTTP/1.1' ? conn != 'close' : conn == 'keep-alive'
+    end
+  end
+end

data/lib/stipa/generator.rb

@@ -0,0 +1,19 @@
+require_relative 'generators/base'
+require_relative 'generators/vue'
+require_relative 'generators/api'
+
+module Stipa
+  module Generator
+    TEMPLATES = {
+      'vue' => Generators::Vue,
+      'api' => Generators::Api,
+    }.freeze
+
+    DEFAULT = 'vue'
+
+    def self.new(name, template: DEFAULT)
+      klass = TEMPLATES.fetch(template) { abort "Unknown template '#{template}'. Available: #{TEMPLATES.keys.join(', ')}" }
+      klass.new(name)
+    end
+  end
+end

data/lib/stipa/generators/api.rb

@@ -0,0 +1,126 @@
+require_relative 'base'
+
+module Stipa
+  module Generators
+    class Api < Base
+      private
+
+      def template_name = 'api'
+
+      def dirs
+        %w[config controllers]
+      end
+
+      def done_message
+        <<~DONE
+
+          Done! Next steps:
+            cd #{name}
+            bundle install
+            bundle exec ruby server.rb
+        DONE
+      end
+
+      def files
+        {
+          'Gemfile'                                => t_gemfile,
+          'server.rb'                              => t_server,
+          'config/routes.rb'                       => t_routes(
+            extra_requires: ['../controllers/health_controller'],
+            extra_routes:   ["get '/health', to: 'health#show'"],
+          ),
+          'controllers/application_controller.rb' => t_application_controller,
+          'controllers/health_controller.rb'       => t_health_controller,
+        }
+      end
+
+      def t_server
+        <<~RUBY
+          require 'stipa'
+          require_relative 'config/routes'
+
+          app = Stipa::App.new
+
+          app.use Stipa::Middleware::RequestId
+          app.use Stipa::Middleware::Timing
+          app.use Stipa::Middleware::Cors
+
+          Routes.draw(app)
+
+          app.start(host: '0.0.0.0', port: 3710)
+        RUBY
+      end
+
+      def t_application_controller
+        <<~RUBY
+          require 'uri'
+          require 'json'
+
+          class ApplicationController
+            attr_reader :req, :res
+
+            def initialize(req, res)
+              @req    = req
+              @res    = res
+              @params = nil
+            end
+
+            private
+
+            def json(data, status: 200)
+              res.status = status
+              res.json(data)
+            end
+
+            def not_found!(message = 'Not found')
+              res.status = 404
+              res.json(error: message)
+              throw :halt
+            end
+
+            def unprocessable!(errors)
+              res.status = 422
+              res.json(errors: errors)
+              throw :halt
+            end
+
+            def params
+              @params ||= begin
+                p = req.params.dup
+
+                req.query_string.split('&').each do |pair|
+                  next if pair.empty?
+                  k, v = pair.split('=', 2)
+                  p[k.to_sym] = URI.decode_www_form_component(v.to_s)
+                end
+
+                if req['content-type']&.include?('application/json')
+                  begin
+                    body = JSON.parse(req.body, symbolize_names: true)
+                    p.merge!(body) if body.is_a?(Hash)
+                  rescue JSON::ParserError
+                    # ignore malformed JSON body
+                  end
+                end
+
+                p
+              end
+            end
+          end
+        RUBY
+      end
+
+      def t_health_controller
+        <<~RUBY
+          require_relative 'application_controller'
+
+          class HealthController < ApplicationController
+            def show
+              json(status: 'ok', framework: 'Stipa', version: Stipa::VERSION, ts: Time.now.utc.iso8601)
+            end
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/stipa/generators/base.rb

@@ -0,0 +1,117 @@
+require 'fileutils'
+require 'json'
+require 'pathname'
+
+module Stipa
+  module Generators
+    class Base
+      GEM_JS   = File.expand_path('../../js', __dir__)
+      GEM_MEDIA = File.expand_path('../../../media', __dir__)
+      GEM_ROOT = File.expand_path('../..', GEM_JS)
+
+      attr_reader :name, :target
+
+      def initialize(name)
+        @name   = name
+        @target = File.expand_path(name, Dir.pwd)
+      end
+
+      def generate
+        abort "Error: '#{name}' already exists." if Dir.exist?(target)
+
+        say "Creating #{name} (#{template_name})..."
+        make_dirs
+        write_files
+        post_generate
+        say done_message
+      end
+
+      private
+
+      def make_dirs
+        dirs.each { |d| FileUtils.mkdir_p(File.join(target, d)) }
+      end
+
+      def write_files
+        files.each do |path, content|
+          File.write(File.join(target, path), content)
+          say "  create  #{path}"
+        end
+      end
+
+      def post_generate = nil
+
+      def say(msg) = puts(msg)
+
+      def app_title
+        name.split(/[-_]/).map(&:capitalize).join(' ')
+      end
+
+      # ── Shared templates ───────────────────────────────────────────────────────
+
+      def t_gemfile
+        <<~RUBY
+          source 'https://rubygems.org'
+
+          gem 'stipa'
+        RUBY
+      end
+
+      def t_routes(extra_requires: [], extra_routes: [], method_override: false)
+        requires = extra_requires.map { |r| "require_relative '#{r}'" }.join("\n")
+        override = method_override ? <<~RUBY : ''
+          # ── Method Override ────────────────────────────────────────────────────────
+          # Allows HTML forms to tunnel PUT/DELETE via a hidden _method field.
+
+          MethodOverride = lambda do |req, res, next_app|
+            if req.method == 'POST' && req['content-type']&.include?('application/x-www-form-urlencoded')
+              form = req.body.split('&').each_with_object({}) do |pair, h|
+                k, v = pair.split('=', 2)
+                h[k] = URI.decode_www_form_component(v.to_s) if k
+              end
+              override = form['_method']&.upcase
+              req.instance_variable_set(:@method, override) if %w[PUT PATCH DELETE].include?(override)
+            end
+            next_app.call(req, res)
+          end
+
+        RUBY
+
+        use_override = method_override ? "\n            @app.use MethodOverride\n" : ''
+        routes_body  = extra_routes.map { |r| "            #{r}" }.join("\n")
+
+        <<~RUBY
+          require 'uri'
+          #{requires}
+          #{override}
+          class Routes
+            def self.draw(app) = new(app).draw
+
+            def initialize(app)
+              @app = app
+            end
+
+            def draw#{use_override}
+          #{routes_body}
+            end
+
+            private
+
+            def resolve(to)
+              ctrl, action = to.split('#', 2)
+              klass = Object.const_get(ctrl.split('_').map(&:capitalize).join + 'Controller')
+              [klass, action.to_sym]
+            end
+
+            %w[get post put patch delete].each do |verb|
+              define_method(verb) do |pattern, to:|
+                klass, action = resolve(to)
+                @app.public_send(verb, pattern) { |req, res| klass.new(req, res).public_send(action) }
+              end
+            end
+          end
+        RUBY
+      end
+    end
+  end
+end