stir_fry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7a00e29a6a5328edd5213cd08821bd05627ac300c11bed5cc473a54059e63fc
+  data.tar.gz: d529099f09b0056ed4be196a62b0cfea2bcf99c2b0bb4c747116bcf92a8b16ba
+SHA512:
+  metadata.gz: 59c837dd40c9dc13e80a8d467fd8ce1618cef3c8e4fc5e1dcffe25cc5faefcdb45bd22ffaaf5da531a9e9f6969e481ad8c1a7fcd0cf501c64194c3b516a5cbad
+  data.tar.gz: 97a6c2f514e52a7304f1900e802d4132ebeaac41ad623c1bcd00202fc1f476b286d6f2a2c825cf6077323d509c283e654f01546debd140885c611adf0044d05f

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-08-10
+
+Initial release of the whole framework including:
+
+- Rack compatible App to run the app server in a way that is easy to use.
+- Components for reacting to routes.
+- Request & Response helpers

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "irb"
+gem "pstore"
+gem "puma"
+gem "rake", "~> 13.0"
+gem "rdoc"
+gem "rerun"
+gem "rspec", "~> 3.13"
+gem "rubocop", "~> 1.21"
+gem "rubocop-rake", ">= 0.7.1"
+gem "rubocop-rspec", "~> 3.10", require: false

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Tim Anema
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,99 @@
+# StirFry
+A small, simple web framework that lets you enjoy ruby with a JSX type flavour. 
+
+## Installation
+
+`gem install 'stir_fry'`
+
+## Usage
+An example project could look like this. The templating leverages a weird feature 
+of ruby with the `__END__` data sections [ref](https://til.hashrocket.com/posts/17787bf181-rubys-end)
+to inline templates in the same file and be able to parse them where they are. 
+I have not yet figured out how to add syntax highlighting for it but it is a start.
+
+### layout.rb
+
+```ruby
+class Layout < StirFry::Component; end
+__END__
+<html>
+  <body>{ yield }</body>
+</html>
+```
+
+### home.rb
+
+```ruby
+class Home < StirFry::Component
+  def name = "Bobby"
+end
+
+__END__
+<Layout>
+    <h1>Hello {name}</h1>
+</Layout>
+```
+
+### app.rb
+
+```
+require "layout"
+require "home"
+
+class App < StirFry::App 
+  # Render the components
+  get "/", Home
+  # Raw API call
+  get "/hello/:name" do|request:, response:, name:| 
+    response.text("Hello #{req.args["name"]}") 
+  end
+end
+
+StirFry.run!(App)
+```
+
+See the `/examples` directory for more in-depth examples.
+
+### Multiple Inline templates
+Multiple templates can be defined in the same file as well with an addition of 
+an `@@` label. This idea was taken from [Sinatra](#acknowledgment).
+
+```ruby
+class Layout < StirFry::Component; end
+class Home < StirFry::Component; end
+
+__END__
+@@Layout
+<html>
+  <body>{ yield }</body>
+</html>
+
+@@Home
+<Layout><h1>Hello Bobby</h1></Layout>
+```
+
+## Development
+
+After checking out the repo, 
+
+- run `bundle install` to install dependencies. 
+- run `./example/todos_app/app.rb` to run the example todo app.
+- run `./example/chat_app/app.rb` to run the example chat app.
+- run `rake` to run the specs, rubocop and rdoc. 
+
+## Further Reading
+
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [License](https://opensource.org/licenses/MIT)
+
+## Acknowledgment 
+These are the projects that I took both inspiration and code chunks from. Since I 
+wanted an interface a lot like Sinatra, I used their codebase heavily for routing.
+Also since I wanted a reactjs markdown style, I used rbexy initially but then 
+ended up re-writing a lot of it to remove all rails integrations and I ended up 
+rewriting to more of a classical recursive descent parser since I find push-down
+automata harder to parse personally and it would be more comfortable for me to work on.
+
+- [Sinatra](https://github.com/sinatra/sinatra/)
+- [Rbexy](https://github.com/patbenatar/rbexy)
+- [Rack](https://github.com/rack/rack)

data/Rakefile

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require "rdoc/task"
+require "rerun"
+
+task default: %i[spec rubocop rdoc:coverage]
+
+RuboCop::RakeTask.new
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = ["--require spec_helper"]
+  t.verbose = ENV.fetch("VERBOSE", nil)
+end
+
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.generator = "aliki"
+  rdoc.rdoc_files.include(
+    "lib/**/*.rb",
+    "rbxrb/lib/**/*.rb",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "README.md",
+    "LICENSE"
+  )
+  rdoc.rdoc_dir = "docs"
+  rdoc.markup = "markdown"
+end
+
+desc "Run an irb console with the library loaded"
+task :console do
+  require "stir_fry"
+  require "irb"
+  ARGV.clear
+  IRB.start
+end

data/lib/stir_fry/app.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require "rack"
+require "rack/session"
+require "mustermann"
+
+module StirFry
+  # App is the root of your StirFry app that makes it runnable and ready for use
+  # on any rack server
+  #
+  # Example:
+  #
+  # ```ruby
+  # class App < StirFry::App
+  #   get "/greet/:name" do |response:, **|
+  #     response.text("Hello #{name}")
+  #   end
+  #   get "/todo", Todos::List
+  # end
+  #
+  # StirFry.run!(App)
+  # ```
+  class App
+    DEFAULT_ERROR_HANDLERS = { # :nodoc: disable in production
+      OKAY => ->(**args) { pass_through(status: :ok, **args) },
+      Found => ->(**args) { pass_through(status: :found, **args) },
+      NotModified => ->(**args) { pass_through(status: :not_modified, **args) },
+      NotFound => Pages::NotFoundPage
+    }.freeze
+
+    REQUEST_ENV_KEY = "stir_fry.request" # :nodoc:
+    RESPONSE_ENV_KEY = "stir_fry.response" # :nodoc:
+
+    attr_accessor :request, :response, :env # :nodoc:
+
+    class << self
+      def routes = @routes ||= {} # :nodoc:
+      def all_routes = @all_routes ||= [] # :nodoc:
+      def error_handlers = @error_handlers ||= DEFAULT_ERROR_HANDLERS.dup # :nodoc:
+      def call(env) = root_app.call(env) # :nodoc:
+
+      # sugar for `use Rack::Session::Cookie, config`
+      # See https://github.com/rack/rack-session for more config.
+      # Params:
+      # - `domain`       host for the cookie security (example: 'mywebsite.com')
+      # - `path`         path for the cookie security (example: '/')
+      # - `expire_after` mark the cookie as expired after seconds (example: 3600*24)
+      # - `max_age`      similar to expires_after.
+      # - `secret`       *required* a random string 64 character long or longer. Used to encrypt cookie.
+      def use_session(**config)
+        raise "cannot enable sessions without a :secret set." if config[:secret].nil?
+
+        secret_len = config[:secret].length
+        if secret_len < 64
+          raise "session secret too short, secret is #{secret_len} but session secret is required to be >= 64"
+        end
+
+        use Rack::Session::Cookie, config
+      end
+
+      # Add a GET request route to the application
+      def get(pattern, klass = nil, &) = route("GET", pattern, klass, &)
+
+      # Add a HEAD request route to the application
+      def head(pattern, klass = nil, &) = route("HEAD", pattern, klass, &)
+
+      # Add a OPTIONS request route to the application
+      def options(pattern, klass = nil, &) = route("OPTIONS", pattern, klass, &)
+
+      # Add a POST request route to the application
+      def post(pattern, klass = nil, &) = route("POST", pattern, klass, &)
+
+      # Add a PUT request route to the application
+      def put(pattern, klass = nil, &) = route("PUT", pattern, klass, &)
+
+      # Add a PATCH request route to the application
+      def patch(pattern, klass = nil, &) = route("PATCH", pattern, klass, &)
+
+      # Add a DELETE request route to the application
+      def delete(pattern, klass = nil, &) = route("DELETE", pattern, klass, &)
+
+      # running environment for this app.
+      def app_env = StirFry.app_env
+
+      # is the app running in development.
+      def development? = app_env == :development
+
+      # is the app running in test.
+      def test? = app_env == :test
+
+      # is the app running in production
+      def production? = app_end == :production
+
+      # configured logger for the application for easy access in the app
+      def logger = StirFry.logger
+
+      def pass_through(response:, status:, **) # :nodoc:
+        response.status(status)
+      end
+
+      ##
+      # Add a handler for an error raised during runtime.
+      #
+      # Example:
+      #
+      # ```ruby
+      # class App < StirFry::App
+      #   rescue_from StirFry::NotFound do |response:, **|
+      #     response.text("Not Found", :not_found)
+      #   end
+      # end
+      # ```
+      def rescue_from(klass, &block) = error_handlers[klass] = block
+
+      ##
+      # Adds a middleware class to the chain of middleware. The order of operations
+      # is significant! So if you create routes before you add a middleware, the
+      # routes will not include the later middleware. This can be nice to scope
+      # your middleware but it can also be an easy mistake.
+      def use(middleware_class, *args, &block) = context.last[1] << [middleware_class, args, block]
+
+      ##
+      # Hosts a directory of static files. Every file within the directory will
+      # be requestable and sym links are followed so be careful what you host.
+      # A prefix can be added to the file routes to allow them to be scoped to a
+      # certain endpoint.
+      #
+      # Example:
+      #
+      # ```ruby
+      # class App < StirFry::App
+      #   static File.join(__dir__, "public")
+      # end
+      # ```
+      def static(dirname, path: "/")
+        files = Rack::Files.new(File.expand_path(dirname))
+        path = route_prefix + path
+        static_apps << (path == "/" ? files : Rack::URLMap.new(path => files))
+      end
+
+      ##
+      # Creates a sub-scope of routes that allow to prefix all the routes and add
+      # specific middleware that only applies to those routes.
+      #
+      # Example:
+      #
+      # ```ruby
+      # class App < StirFry::App
+      #   scope "/todos" do
+      #     use AuthenticationMiddleware
+      #
+      #     get "/:id", Todo
+      #     delete "/:id", Todo
+      #     post "/:id", Todo
+      #   end
+      # end
+      # ```
+      def scope(prefix = "", &)
+        context.push([prefix, []])
+        yield
+      ensure
+        context.pop
+      end
+
+      ##
+      # Raw route builder, used by the other helper models so `get("/")` becomes
+      # `route("GET", "/")`
+      def route(verb, pattern, klass, &block)
+        path_pattern = Mustermann.new(route_prefix + pattern)
+        all_routes << path_pattern.to_s unless path_pattern.to_s.start_with?("/stir_fry")
+        (routes[verb] ||= []) << [path_pattern, route_handler(klass || block)]
+      end
+
+      protected
+
+      def setup_default_middleware # :nodoc:
+        use Middleware::Logger, logger
+        use Rack::Head
+        use Rack::ShowStatus if development?
+        use Rack::ShowExceptions if development?
+        use Rack::ContentLength
+      end
+
+      def setup_framework_routes # :nodoc:
+        scope "/stir_fry" do
+          static File.join(__dir__, "static")
+          get "/routes", Pages::RoutesPage
+        end
+      end
+
+      private
+
+      def static_apps = @static_apps ||= []
+      def context = @context ||= [["", []]]
+      def route_prefix = context.map(&:first).join
+      def route_handler(handler) = build_rack_app(context[1..].flat_map(&:last), wrap_handler(handler))
+
+      def root_app
+        @root_app ||= begin
+          builder = Rack::Builder.new
+          context[0][1].each { |c, a, b| builder.use(c, *a, &b) }
+          builder.run(Rack::Cascade.new(static_apps + [->(env) { new(env).call }]))
+          builder.to_app
+        end
+      end
+
+      def wrap_handler(handler)
+        lambda do |env|
+          req = env.fetch(REQUEST_ENV_KEY)
+          resp = env.fetch(RESPONSE_ENV_KEY)
+          verb = req.request_method.downcase.to_sym
+          handler = handler.method(verb) if handler.respond_to?(verb)
+          call_params = req.args.to_h { |k, v| [k.to_sym, v] }
+          default_handler_params = { application: self, request: req, response: resp }
+          handler.call(**call_params, **default_handler_params)
+          resp.finish
+        end
+      end
+
+      def build_rack_app(middleware, handler)
+        builder = Rack::Builder.new
+        middleware.each { |c, a, b| builder.use(c, *a, &b) }
+        builder.run(handler)
+        builder.to_app
+      end
+    end
+
+    # Hook into the app to define development routes and default middleware
+    def self.inherited(subclass)
+      super
+      subclass.class_eval do
+        subclass.setup_default_middleware
+        subclass.setup_framework_routes if subclass.development?
+      end
+    end
+
+    def initialize(env) # :nodoc:
+      @env = env
+      @request = Request.new(env)
+      @response = Response.new(env)
+      env[REQUEST_ENV_KEY] = request
+      env[RESPONSE_ENV_KEY] = response
+    end
+
+    # running environment for this app.
+    def app_env = self.class.app_env
+    # is the app running in development.
+    def development? = self.class.development?
+    # is the app running in test.
+    def test? = self.class.test?
+    # is the app running in production
+    def production? = self.class.production?
+    # configured logger for the application for easy access in the app
+    def logger = self.class.logger
+
+    def call # :nodoc:
+      find_route.call(env)
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    def all_routes # :nodoc:
+      self.class.all_routes
+    end
+
+    private
+
+    def handle_error(err)
+      response.request_error = err
+      handler = error_handler_for(err.class)
+      handler.call(error: err, application: self, request: request, response: response)
+      response.finish
+    end
+
+    def error_handler_for(err_class)
+      error_handlers = self.class.error_handlers
+      err_class.ancestors.each { |klass| return error_handlers[klass] if error_handlers.key?(klass) }
+      Pages::ErrorPage
+    end
+
+    def find_route
+      self.class.routes[request.request_method]&.each do |route|
+        params = route[0].params(request.path_info)
+        request.args = params if params
+        return route[1] if params
+      end
+      raise NotFound
+    end
+  end
+end

data/lib/stir_fry/component.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module StirFry
+  # Component is a request/response view handler. It can be a plain class with a
+  # template inlined in the same file but it can also have the request class methods
+  # such as `self.get`, `self.post`, `self.delete` ect. so that specific requests
+  # can have more rich handling and different views can be returned.
+  #
+  # Example:
+  #
+  #
+  # ```ruby
+  # module Todos
+  #   class Todo < StirFry::Component
+  #     attr_reader :todo
+  #
+  #     class << self
+  #       # PUT /todo/:id/toggle
+  #       def put(request:, response:, id:)
+  #         todo = ::App.todos.find { |t| t["id"] == id.to_i }
+  #         todo["done"] = !todo["done"]
+  #         response.ok(new(todo: todo)) # Return a Todo view
+  #       end
+  #
+  #       # DELETE /todo/:id
+  #       def delete(request:, response:, id:)
+  #         ::App.todos.delete_if { |t| t["id"] == id.to_i }
+  #         response.render(List.new(todos: ::App.todos)) # Return a list view instead
+  #       end
+  #     end
+  #
+  #     def initialize(todo:)
+  #       super()
+  #       @todo = todo
+  #     end
+  #   end
+  # end
+  # ```
+  class Component
+    include RBX::Component
+
+    # application is root application where all the routes are defined and maybe
+    # where you might keep config or database references.
+    # This is only defined on the root component that is defined on the route.
+    attr_accessor :application
+    # request is the request that called this component. This is only defined on the root
+    # component that is defined on the route.
+    attr_accessor :request
+    # response is the response that is used for responding in the component.
+    # This is only defined on the root component that is defined on the route.
+    attr_accessor :response
+
+    # Simple access to StirFry.logger
+    def self.logger = StirFry.logger
+
+    # call it the method called from routing. It is called with the request and response
+    # first, and the arguments to initialize the component will be appended to the
+    # end. It will set the request, and response on the component and call render
+    # on the component.
+    def self.call(application: nil, request: nil, response: nil, **args)
+      new(application: application, request: request, response: response, **args).call
+    end
+
+    # create a new component with a request and response
+    def initialize(application: nil, request: nil, response: nil, **_args)
+      self.application = application
+      self.request = request
+      self.response = response
+    end
+
+    # call is sugar for `response.html(render)` and should be overriden to change how
+    # a component responds.
+    def call
+      response.html(render)
+    end
+
+    # Simple access to StirFry.logger
+    def logger = StirFry.logger
+  end
+end