gemstack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39317af6119a78833f6f2223b54d72f629cf72ed2d1a1d87d6c1dd5b09b1d755
+  data.tar.gz: 77c7d2c8616cad5484be73a0b2b5e22638db88b6be21b3f4c1e33b6311f11d1e
+SHA512:
+  metadata.gz: 2446525d9b09584be6a6d6bbf21a858b97a48ef177d7c8011c79c968e057bae21de4d181a965077c64a2bbcd3cd802c998bb4af4777e910b9226b19f1dcb491e
+  data.tar.gz: aa46e6be80e88973f82760d83f299e92346ce78ea176b6ea7ec65146257f59cb95dc722b92d96301fe9d6b16134453b858f64c254bde438429a6fb68da232c2e

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+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,29 @@
+# gemstack
+
+GemStack: a fast, modular Ruby API framework for Next.js applications.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+```bash
+gem install gemstack
+gemstack new myapp
+```
+
+This gem is the framework: it depends on every module an app needs (core, cache, schema, http, contract, dev, cli). Optional modules are added per app.
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/getting-started.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/application.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+module GemStack
+  # A GemStack application: configuration + autoloaded code + routes, served
+  # as a Rack app. There is one per process, available as GemStack.application.
+  #
+  # Boot sequence (idempotent):
+  #   1. load .env files (development/test)          config.env_files
+  #   2. load config/environments/<env>.rb if present
+  #   3. run plugin hooks                             GemStack::Plugins
+  #   4. set up Zeitwerk for every directory in app/  (+ config.autoload_paths)
+  #   5. load config/routes.rb
+  #   6. compile the middleware stack                 config.http.middleware
+  #   7. eager load in production                     config.eager_load
+  class Application
+    attr_reader :config, :loader, :router
+
+    def initialize(config: GemStack.config)
+      @config = config
+      @booted = false
+      @boot_lock = Mutex.new
+      @shutdown_hooks = []
+      @reload_hooks = []
+    end
+
+    def root = Pathname.new(config.root)
+
+    def boot!
+      @boot_lock.synchronize do
+        return self if @booted
+
+        load_env_files
+        load_environment_config
+        enable_jit
+        Plugins.run(self)
+        setup_loader
+        @router = build_router { load_routes }
+        install_reloader if config.reload_code
+        @http = HTTP::App.new(config: config.http, router: @router)
+        eager_load! if config.eager_load
+        @booted = true
+      end
+      self
+    end
+
+    def booted? = @booted
+
+    def call(env)
+      boot! unless @booted
+      @http.call(env)
+    end
+
+    # Replaces the route table. Called by config/routes.rb via GemStack.routes.
+    def draw_routes(&)
+      raise ArgumentError, "GemStack.routes needs a block" unless block_given?
+
+      @pending_routes << Proc.new(&) if @pending_routes # collected while (re)loading routes.rb
+    end
+
+    def routes = @router&.routes || []
+
+    # Unloads and reloads app/ code and routes. Used by the development
+    # Reloader; safe to call from the console.
+    def reload!
+      unless config.reload_code
+        raise ConfigurationError, "code reloading is disabled; set config.reload_code = true (default in development)"
+      end
+
+      @loader&.reload
+      @router = build_router { load_routes }
+      @http.router = @router
+      @reload_hooks.each(&:call)
+      GemStack.logger.debug("reloaded application code")
+      true
+    end
+
+    def eager_load!
+      @loader&.eager_load
+    end
+
+    # Runs after code and routes reload (development), e.g. to re-read config/channels.rb.
+    def on_reload(&block)
+      @reload_hooks << block
+    end
+
+    def on_shutdown(&block)
+      @shutdown_hooks << block
+    end
+
+    def shutdown
+      @shutdown_hooks.reverse_each(&:call)
+    end
+
+    def autoload_dirs
+      app_dirs = Dir.glob(root.join("app/*").to_s)
+      extra = Array(config.autoload_paths).map { |path| File.expand_path(path, root) }
+      (app_dirs + extra).select { |path| File.directory?(path) }
+    end
+
+    private
+
+    def load_env_files = GemStack.load_env_files!
+
+    # Enables config.jit unless a JIT is already running (e.g. `ruby --yjit`).
+    def enable_jit
+      jit = config.jit
+      return unless jit
+
+      engine = { yjit: :YJIT, zjit: :ZJIT }.fetch(jit.to_sym) do
+        raise ConfigurationError, "unknown config.jit #{jit.inspect} (use :yjit, :zjit or nil)"
+      end
+      return unless RubyVM.const_defined?(engine)
+      return if %i[YJIT ZJIT].any? { |name| RubyVM.const_defined?(name) && RubyVM.const_get(name).enabled? }
+
+      RubyVM.const_get(engine).enable
+    end
+
+    def load_environment_config
+      file = root.join("config/environments/#{GemStack.env}.rb")
+      load file.to_s if file.file?
+    end
+
+    def setup_loader
+      @loader = Zeitwerk::Loader.new
+      @loader.tag = "gemstack.app"
+      autoload_dirs.each { |dir| @loader.push_dir(dir) }
+      @loader.enable_reloading if config.reload_code
+      @loader.setup
+    end
+
+    # Inside the ErrorHandler, so errors raised while reloading (e.g. a
+    # SyntaxError) are rendered as JSON error responses.
+    def install_reloader
+      stack = config.http.middleware
+      return if stack.include?(Reloader)
+
+      if stack.include?(HTTP::Middleware::ErrorHandler)
+        stack.insert_after(HTTP::Middleware::ErrorHandler, Reloader, self)
+      else
+        stack.unshift(Reloader, self)
+      end
+    end
+
+    def load_routes
+      file = root.join("config/routes.rb")
+      load file.to_s if file.file?
+    end
+
+    def build_router
+      @pending_routes = []
+      yield
+      router = HTTP::Router.new(prefix: config.http.api_path)
+      @pending_routes.each { |block| router.draw(&block) }
+      router
+    ensure
+      @pending_routes = nil
+    end
+  end
+end

data/lib/gemstack/interlock.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module GemStack
+  # A readers/writer lock. Requests hold a shared lock while application code
+  # runs; code reloading takes the exclusive lock, so a reload never happens
+  # while another thread is executing code that is about to be unloaded.
+  class Interlock
+    def initialize
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @readers = 0
+      @writer = false
+      @waiting_writers = 0
+    end
+
+    def acquire_shared
+      @mutex.synchronize do
+        # Waiting writers get priority so a busy server can't starve a reload.
+        @condition.wait(@mutex) while @writer || @waiting_writers.positive?
+        @readers += 1
+      end
+    end
+
+    def release_shared
+      @mutex.synchronize do
+        @readers -= 1
+        @condition.broadcast if @readers.zero?
+      end
+    end
+
+    def exclusive
+      @mutex.synchronize do
+        @waiting_writers += 1
+        @condition.wait(@mutex) while @writer || @readers.positive?
+        @waiting_writers -= 1
+        @writer = true
+      end
+      yield
+    ensure
+      @mutex.synchronize do
+        @writer = false
+        @condition.broadcast
+      end
+    end
+  end
+end

data/lib/gemstack/reloader.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "gemstack/dev/file_watcher"
+
+module GemStack
+  # Development middleware: reloads application code and routes before a
+  # request when files under app/ or config/routes.rb have changed
+  # (DECISIONS D-007). The shared lock is held until the response body is
+  # closed, so streamed responses finish on the code that produced them.
+  class Reloader
+    WATCHED = ["app/**/*", "config/routes.rb"].freeze
+
+    def initialize(app, application)
+      @app = app
+      @application = application
+      @watcher = Dev::FileWatcher.new(WATCHED, root: application.root)
+      @interlock = Interlock.new
+      @check = Mutex.new
+    end
+
+    def call(env)
+      reload_if_changed
+      @interlock.acquire_shared
+      begin
+        status, headers, body = @app.call(env)
+      rescue Exception # rubocop:disable Lint/RescueException -- release the lock, then re-raise anything
+        @interlock.release_shared
+        raise
+      end
+      [status, headers, Rack::BodyProxy.new(body) { @interlock.release_shared }]
+    end
+
+    private
+
+    def reload_if_changed
+      changed = @check.synchronize { @watcher.changed? }
+      return unless changed
+
+      @interlock.exclusive { @application.reload! }
+    end
+  end
+end

data/lib/gemstack/testing.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "rack/test"
+require "json"
+
+module GemStack
+  # Test helpers for GemStack applications (Minitest + rack-test).
+  #
+  #   class ProductsTest < GemStack::TestCase
+  #     def test_index
+  #       get_json "/api/products"
+  #       assert_status 200
+  #       assert_equal [], json_body
+  #     end
+  #   end
+  module Testing
+    module Helpers
+      include Rack::Test::Methods
+
+      def app = GemStack.application
+
+      # Parsed JSON body of the last response.
+      def json_body
+        JSON.parse(last_response.body)
+      end
+
+      def get_json(path, params = {}, headers = {})
+        get(path, params, json_headers(headers))
+      end
+
+      %w[post put patch delete].each do |verb|
+        define_method(:"#{verb}_json") do |path, body = {}, headers = {}|
+          public_send(verb, path, JSON.generate(body),
+                      json_headers(headers).merge("CONTENT_TYPE" => "application/json"))
+        end
+      end
+
+      def assert_status(expected, message = nil)
+        expected = Rack::Utils::SYMBOL_TO_STATUS_CODE.fetch(expected) if expected.is_a?(Symbol)
+        message ||= "Expected status #{expected}, got #{last_response.status}: #{last_response.body[0, 500]}"
+        assert_equal expected, last_response.status, message
+      end
+
+      # assert_error 422, "validation_failed"
+      def assert_error(status, code = nil)
+        assert_status status
+        assert_equal code, json_body.dig("error", "code") if code
+      end
+
+      private
+
+      def json_headers(headers) = { "HTTP_ACCEPT" => "application/json" }.merge(headers)
+    end
+  end
+
+  class TestCase < Minitest::Test
+    include Testing::Helpers
+  end
+end

data/lib/gemstack.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "gemstack/core"
+require "gemstack/cache"
+require "gemstack/http"
+require "gemstack/dev"
+require "gemstack/contract" # /api/docs in development; `gemstack contract`
+require_relative "gemstack/interlock"
+require_relative "gemstack/reloader"
+require_relative "gemstack/application"
+
+module GemStack
+  class Config
+    # Reload app/ code and routes between requests when files change.
+    setting :reload_code, default: -> { GemStack.env.development? }
+    # Load all application code at boot (faster first requests, copy-on-write
+    # friendly with Puma workers).
+    setting :eager_load, default: -> { !GemStack.env.local? }
+    # Extra directories to autoload, relative to the root (e.g. ["lib"]).
+    setting :autoload_paths, default: []
+    # Ruby JIT enabled at boot: :yjit (production default, measured fastest),
+    # :zjit (Ruby 4's newer JIT, opt-in), or nil. GEMSTACK_JIT=yjit|zjit|off overrides.
+    setting :jit, default: lambda {
+      case ENV.fetch("GEMSTACK_JIT", nil)
+      when "off", "none", "" then nil
+      when String then ENV["GEMSTACK_JIT"].to_sym
+      else GemStack.env.production? ? :yjit : nil
+      end
+    }
+  end
+
+  # Short names for application code:
+  #   class ApplicationController < GemStack::Controller
+  Controller = HTTP::Controller
+  Params = HTTP::Params
+  # GemStack::Schema, GemStack::Serializer and GemStack::Types come from gemstack-schema.
+
+  class << self
+    def application
+      @application ||= Application.new(config: config)
+    end
+
+    attr_writer :application
+
+    def boot! = application.boot!
+
+    # config/routes.rb:
+    #   GemStack.routes do
+    #     resources :products
+    #   end
+    def routes(&)
+      return application.routes unless block_given?
+
+      application.draw_routes(&)
+    end
+
+    alias reset_core! reset!
+
+    def reset!
+      reset_core!
+      @application = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: gemstack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gemstack-cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-contract
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-dev
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.4'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gemstack.rb
+- lib/gemstack/application.rb
+- lib/gemstack/interlock.rb
+- lib/gemstack/reloader.rb
+- lib/gemstack/testing.rb
+homepage: https://github.com/gemstack-rb/gemstack
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack: a fast, modular Ruby API framework for Next.js applications'
+test_files: []