philiprehberger-middleware 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29bf5f1bc723e0258d69143b9fe27f6518ed7df927364c41c43ff9ae513feb50
+  data.tar.gz: 90803aef2b5619ff376fad5b0c1033e6649311652b4692cd51ddd7aef0c66aa9
+SHA512:
+  metadata.gz: 7cb953d12ccd0a5a9f8125c8c1c045bd3a571cbc9394b202d762e59b31e984fbc2e84b88eabfb9cbf1a86507abb6ac0110a5792b9da79d5550fd812d74f3cb79
+  data.tar.gz: bbfd92e64de7c312eef8198da722b3b6e5c89473641454e4653a23258f20b99fc458652c427dcc70500a49b7deee3ba27af19ad4898a5566637f642997692a47

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Middleware stack with sequential execution
+- Lambda and class-based middleware support
+- Named middleware entries for targeted manipulation
+- Insert before and after named entries
+- Remove middleware by name
+- Short-circuit capability for early termination
+- Stack introspection via `to_a`

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+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,104 @@
+# philiprehberger-middleware
+
+[![Tests](https://github.com/philiprehberger/rb-middleware/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-middleware/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-middleware.svg)](https://rubygems.org/gems/philiprehberger-middleware)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-middleware)](LICENSE)
+
+Generic middleware stack for composing processing pipelines
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-middleware"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-middleware
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/middleware"
+
+stack = Philiprehberger::Middleware::Stack.new
+stack.use(->(env, next_mw) { next_mw.call(env.merge(logged: true)) }, name: :logger)
+stack.use(->(env, next_mw) { next_mw.call(env.merge(authed: true)) }, name: :auth)
+
+result = stack.call({})
+# => { logged: true, authed: true }
+```
+
+### Class-Based Middleware
+
+```ruby
+class TimingMiddleware
+  def call(env, next_mw)
+    start = Time.now
+    result = next_mw.call(env)
+    result.merge(elapsed: Time.now - start)
+  end
+end
+
+stack = Philiprehberger::Middleware::Stack.new
+stack.use(TimingMiddleware.new, name: :timing)
+```
+
+### Insert and Remove
+
+```ruby
+stack = Philiprehberger::Middleware::Stack.new
+stack.use(->(env, next_mw) { next_mw.call(env) }, name: :first)
+stack.use(->(env, next_mw) { next_mw.call(env) }, name: :last)
+
+stack.insert_before(:last, ->(env, next_mw) { next_mw.call(env) }, name: :middle)
+stack.to_a  # => [:first, :middle, :last]
+
+stack.remove(:middle)
+stack.to_a  # => [:first, :last]
+```
+
+### Short-Circuit
+
+```ruby
+stack = Philiprehberger::Middleware::Stack.new
+stack.use(lambda { |env, _next_mw|
+  return { error: 'unauthorized' } unless env[:token]
+
+  _next_mw.call(env)
+}, name: :auth)
+```
+
+## API
+
+### `Stack`
+
+| Method | Description |
+|--------|-------------|
+| `.new` | Create an empty middleware stack |
+| `#use(mw, name:)` | Append middleware to the stack |
+| `#insert_before(name, mw, name:)` | Insert middleware before a named entry |
+| `#insert_after(name, mw, name:)` | Insert middleware after a named entry |
+| `#remove(name)` | Remove middleware by name |
+| `#call(env)` | Execute the stack with the given environment |
+| `#to_a` | List middleware names in order |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/middleware/stack.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module Middleware
+    # A composable middleware stack for processing pipelines.
+    #
+    # Middleware can be a lambda `(env, next_mw)` or an object responding to `#call(env, next_mw)`.
+    class Stack
+      # Create a new empty middleware stack.
+      def initialize
+        @entries = []
+      end
+
+      # Append a middleware to the end of the stack.
+      #
+      # @param middleware [#call, Proc] middleware callable accepting (env, next_mw)
+      # @param name [String, Symbol, nil] optional name for insertion/removal
+      # @return [self]
+      def use(middleware, name: nil)
+        validate_middleware!(middleware)
+        @entries << Entry.new(middleware: middleware, name: name)
+        self
+      end
+
+      # Insert a middleware before the named entry.
+      #
+      # @param target_name [String, Symbol] name of the entry to insert before
+      # @param middleware [#call, Proc] middleware callable
+      # @param name [String, Symbol, nil] optional name for the new entry
+      # @return [self]
+      # @raise [Error] if the target name is not found
+      def insert_before(target_name, middleware, name: nil)
+        validate_middleware!(middleware)
+        index = find_index!(target_name)
+        @entries.insert(index, Entry.new(middleware: middleware, name: name))
+        self
+      end
+
+      # Insert a middleware after the named entry.
+      #
+      # @param target_name [String, Symbol] name of the entry to insert after
+      # @param middleware [#call, Proc] middleware callable
+      # @param name [String, Symbol, nil] optional name for the new entry
+      # @return [self]
+      # @raise [Error] if the target name is not found
+      def insert_after(target_name, middleware, name: nil)
+        validate_middleware!(middleware)
+        index = find_index!(target_name)
+        @entries.insert(index + 1, Entry.new(middleware: middleware, name: name))
+        self
+      end
+
+      # Remove a middleware by name.
+      #
+      # @param target_name [String, Symbol] name of the entry to remove
+      # @return [self]
+      # @raise [Error] if the target name is not found
+      def remove(target_name)
+        index = find_index!(target_name)
+        @entries.delete_at(index)
+        self
+      end
+
+      # Execute the middleware stack with the given environment.
+      #
+      # @param env [Object] the environment/context passed through the stack
+      # @return [Object] the final environment after all middleware have run
+      def call(env)
+        chain = build_chain
+        chain.call(env)
+      end
+
+      # Return the list of middleware names/entries.
+      #
+      # @return [Array<String, Symbol, nil>] names of middleware in order
+      def to_a
+        @entries.map(&:name)
+      end
+
+      private
+
+      Entry = Struct.new(:middleware, :name, keyword_init: true)
+
+      def validate_middleware!(middleware)
+        raise Error, 'middleware must respond to #call' unless middleware.respond_to?(:call)
+      end
+
+      def find_index!(target_name)
+        index = @entries.index { |e| e.name == target_name }
+        raise Error, "middleware '#{target_name}' not found" unless index
+
+        index
+      end
+
+      def build_chain
+        # Build from right to left: last middleware calls the terminal,
+        # each preceding middleware calls the next one.
+        terminal = ->(env) { env }
+
+        @entries.reverse.reduce(terminal) do |next_mw, entry|
+          ->(env) { entry.middleware.call(env, next_mw) }
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/middleware/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module Middleware
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/middleware.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'middleware/version'
+require_relative 'middleware/stack'
+
+module Philiprehberger
+  module Middleware
+    class Error < StandardError; end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-middleware
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies: []
+description: A composable middleware stack that supports lambda and class-based middleware,
+  named entries with insert-before/after and removal, and sequential execution with
+  short-circuit capability.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/middleware.rb
+- lib/philiprehberger/middleware/stack.rb
+- lib/philiprehberger/middleware/version.rb
+homepage: https://github.com/philiprehberger/rb-middleware
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-middleware
+  source_code_uri: https://github.com/philiprehberger/rb-middleware
+  changelog_uri: https://github.com/philiprehberger/rb-middleware/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-middleware/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Generic middleware stack for composing processing pipelines
+test_files: []