steppe 0.1.0

data/lib/steppe/openapi_visitor.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Steppe
+  class OpenAPIVisitor < Plumb::JSONSchemaVisitor
+    ENVELOPE = {
+      'openapi' => '3.0.0'
+    }.freeze
+
+    def self.call(node, root: true)
+      data = new.visit(node)
+      return data unless root
+
+      ENVELOPE.merge(data)
+    end
+
+    def self.from_request(service, request)
+      data = call(service)
+      url = request.base_url.to_s
+      return data if data['servers'].any? { |s| s['url'] == url }
+
+      data['servers'] << { 'url' => url, 'description' => 'Current server' }
+      data
+    end
+
+    on(:service) do |node, props|
+      props.merge(
+        'info' => {
+          'title' => node.title,
+          'description' => node.description,
+          'version' => node.version
+        },
+        'servers' => node.servers.map { |s| visit(s) },
+        'tags' => node.tags.map { |s| visit(s) },
+        'paths' => node.endpoints.reduce({}) { |memo, e| visit(e, memo) },
+        'components' => { 'securitySchemes' => visit_security_schemes(node.security_schemes) }
+      )
+    end
+
+    on(:server) do |node, _props|
+      { 'url' => node.url.to_s, 'description' => node.description }
+    end
+
+    on(:tag) do |node, _props|
+      prop = { 'name' => node.name, 'description' => node.description }
+      prop['externalDocs'] = { 'url' => node.external_docs.to_s } if node.external_docs
+      prop
+    end
+
+    on(:endpoint) do |node, paths|
+      return paths unless node.specced?
+
+      path_template = node.path.to_templates.first
+      path = paths[path_template] || {}
+      verb = path[node.verb.to_s] || {}
+      verb = verb.merge(
+        'summary' => node.rel_name.to_s,
+        # operationId can be used for links
+        # https://swagger.io/docs/specification/links/
+        'operationId' => node.rel_name.to_s,
+        'description' => node.description,
+        'tags' => node.tags,
+        'security' => visit_endpoint_security(node.registered_security_schemes),
+        'parameters' => visit_parameters(node.query_schema, node.header_schema),
+        'requestBody' => visit_request_body(node.payload_schemas),
+        'responses' => visit(node.responders)
+      )
+      path = path.merge(node.verb.to_s => verb)
+      paths.merge(path_template => path)
+    end
+
+    on(:responders) do |responders, _props|
+      responders.reduce({}) { |memo, r| visit(r, memo) }
+    end
+
+    on(:responder) do |responder, props|
+      # Naive implementation
+      # of OpenAPI responses status ranges
+      # https://swagger.io/docs/specification/describing-responses/
+      # TODO: OpenAPI only allows 1XX, 2XX, 3XX, 4XX, 5XX
+      status = responder.statuses.size == 1 ? responder.statuses.first.to_s : "#{responder.statuses.first.to_s[0]}XX"
+      status_prop = props[status]
+      return props if status_prop
+      return props unless responder.content_type.subtype == 'json'
+
+      status_prop = {}
+      content = status_prop['content'] || {}
+      content = content.merge(
+        responder.accepts.to_s => {
+          'schema' => visit(responder.serializer)
+        }
+      )
+      status_prop = status_prop.merge(
+        'description' => responder.description,
+        'content' => content
+      )
+      props.merge(status => status_prop)
+    end
+
+    on(:uploaded_file) do |_node, props|
+      props.merge('type' => 'string', 'format' => 'byte')
+    end
+
+    PARAMETERS_IN = %i[query path].freeze
+
+    def visit_endpoint_security(schemes)
+      schemes.map { |name, scopes| { name => scopes } }
+    end
+
+    def visit_parameters(query_schema, header_schema)
+      specs = query_schema._schema.each.with_object({}) do |(name, type), h|
+        h[name.to_s] = type if PARAMETERS_IN.include?(type.metadata[:in])
+      end
+      params = specs.map do |name, type|
+        spec = visit(type)
+
+        ins = spec.delete('in')&.to_s
+
+        {
+          'name' => name,
+          'in' => ins,
+          'description' => spec.delete('description'),
+          'example' => spec.delete('example'),
+          'required' => (ins == 'path'),
+          'schema' => spec.except('in', 'desc', 'options')
+        }.compact
+      end
+
+      header_schema._schema.each.with_object(params) do |(key, type), list|
+        spec = visit(type)
+        list << { 
+          'name' => key.to_s, 
+          'in' => 'header', 
+          'description' => spec.delete('description'),
+          'example' => spec.delete('example'),
+          'required' => !key.optional?,
+          'schema' => spec.except('in', 'desc', 'options')
+        }.compact
+      end
+    end
+
+    def visit_request_body(schemas)
+      return {} if schemas.empty?
+
+      content = schemas.each.with_object({}) do |(content_type, schema), h|
+        h[content_type] = { 'schema' => visit(schema) }
+      end
+
+      { 'required' => true, 'content' => content }
+    end
+
+    def visit_security_schemes(schemes)
+      schemes.transform_values(&:to_openapi)
+    end
+  end
+end

data/lib/steppe/request.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rack/request'
+require 'steppe/utils'
+
+module Steppe
+  class Request < Rack::Request
+    ROUTER_PARAMS = 'router.params'
+    BLANK_HASH = {}.freeze
+
+    def steppe_url_params
+      @steppe_url_params ||= begin
+        upstream_params = env[ROUTER_PARAMS] || BLANK_HASH
+        Utils.deep_symbolize_keys(params).merge(Utils.deep_symbolize_keys(upstream_params))
+      end
+    end
+
+    def set_url_params!(params)
+      @steppe_url_params = params
+    end
+  end
+end

data/lib/steppe/responder.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'papercraft'
+require 'steppe/content_type'
+require 'steppe/serializer'
+
+module Steppe
+  # Handles response formatting for specific HTTP status codes and content types.
+  #
+  # A Responder is a pipeline that processes a result and formats it into a Rack response.
+  # Each responder is registered for a specific range of status codes and content type,
+  # and includes a serializer to format the response body.
+  #
+  # @example Basic JSON responder
+  #   Responder.new(statuses: 200, accepts: :json) do |r|
+  #     r.serialize do
+  #       attribute :message, String
+  #       def message = "Success"
+  #     end
+  #   end
+  #
+  # @example HTML responder with Papercraft
+  #   Responder.new(statuses: 200, accepts: :html) do |r|
+  #     r.serialize do |result|
+  #       html5 do
+  #         h1 result.params[:title]
+  #       end
+  #     end
+  #   end
+  #
+  # @example Responder for a range of status codes
+  #   Responder.new(statuses: 200..299, accepts: :json) do |r|
+  #     r.description = "Successful responses"
+  #     r.serialize SuccessSerializer
+  #   end
+  #
+  # @see Serializer
+  # @see PapercraftSerializer
+  class Responder < Plumb::Pipeline
+    DEFAULT_STATUSES = (200..200).freeze
+    DEFAULT_SERIALIZER = Types::Static[{}.freeze].freeze
+
+    def self.inline_serializers
+      @inline_serializers ||= {}
+    end
+
+    inline_serializers[:json] = proc do |block|
+      block.is_a?(Proc) ? Class.new(Serializer, &block) : block
+    end
+
+    inline_serializers[:html] = proc do |block|
+      block
+    end
+
+    # @return [Range] The range of HTTP status codes this responder handles
+    attr_reader :statuses
+
+    # @return [ContentType] The content type pattern this responder matches (from Accept header)
+    attr_reader :accepts
+
+    # @return [ContentType] The actual Content-Type header value set in the response
+    attr_reader :content_type
+
+    # @return [Serializer, Proc] The serializer used to format the response body
+    attr_reader :serializer
+
+    # @return [String, nil] Optional description of this responder (used in documentation)
+    attr_accessor :description
+
+    # Creates a new Responder instance.
+    #
+    # @param statuses [Integer, Range] HTTP status code(s) to handle (default: 200)
+    # @param accepts [String, Symbol] Content type to match from Accept header (default: :json)
+    # @param content_type [String, Symbol, nil] Specific Content-Type header for response (defaults to accepts value)
+    # @param serializer [Class, Proc, nil] Serializer to format response body
+    # @yield [responder] Optional configuration block
+    # @yieldparam responder [Responder] self for configuration
+    #
+    # @example Basic responder
+    #   Responder.new(statuses: 200, accepts: :json)
+    #
+    # @example With custom Content-Type header
+    #   Responder.new(statuses: 200, accepts: :json, content_type: 'application/vnd.api+json')
+    #
+    # @example With inline serializer
+    #   Responder.new(statuses: 200, accepts: :json) do |r|
+    #     r.serialize { attribute :data, Object }
+    #   end
+    def initialize(statuses: DEFAULT_STATUSES, accepts: ContentTypes::JSON, content_type: nil, serializer: nil, &)
+      @statuses = statuses.is_a?(Range) ? statuses : (statuses..statuses)
+      @description = nil
+      @accepts = ContentType.parse(accepts)
+      @content_type = content_type ? ContentType.parse(content_type) : @accepts
+      @content_type_subtype = @content_type.subtype.to_sym
+      super(freeze_after: false, &)
+      serialize(serializer) if serializer
+      freeze
+    end
+
+    # Registers a serializer for this responder.
+    #
+    # The serializer is selected based on the content type's subtype (:json or :html).
+    # For JSON responses, pass a Serializer class or a block that defines attributes.
+    # For HTML responses, pass a Papercraft template or block.
+    #
+    # @param serializer [Class, Proc, nil] Serializer class or template
+    # @yield Block to define inline serializer
+    #
+    # @raise [ArgumentError] If responder already has a serializer
+    #
+    # @example JSON serializer with block
+    #   responder.serialize do
+    #     attribute :users, [UserType]
+    #     def users = result.params[:users]
+    #   end
+    #
+    # @example JSON serializer with class
+    #   responder.serialize(UserListSerializer)
+    #
+    # @example HTML serializer with Papercraft
+    #   responder.serialize do |result|
+    #     html5 { h1 result.params[:title] }
+    #   end
+    #
+    # @return [void]
+    def serialize(serializer = nil, &block)
+      raise ArgumentError, "this responder already has a serializer" if @serializer
+
+      builder = self.class.inline_serializers.fetch(@content_type_subtype)
+      @serializer = builder.call(serializer || block)
+      step do |conn|
+        output = @serializer.render(conn)
+        conn.copy(value: output)
+      end
+    end
+
+    # Compares two responders for equality.
+    #
+    # Two responders are equal if they handle the same status codes and content type.
+    #
+    # @param other [Object] Object to compare
+    # @return [Boolean] True if responders are equal
+    def ==(other)
+      other.is_a?(Responder) && other.statuses == statuses && other.content_type == content_type
+    end
+
+    # @return [String] Human-readable representation of the responder
+    def inspect = "<#{self.class}##{object_id} #{description} statuses:#{statuses} content_type:#{content_type}>"
+
+    # @return [Symbol] Node name for pipeline inspection
+    def node_name = :responder
+
+    # Processes the result through the serializer pipeline and creates a Rack response.
+    #
+    # @param conn [Result] The result object to process
+    # @return [Result::Halt] Result with Rack response
+    def call(conn)
+      conn = super(conn)
+      conn.respond_with(conn.response.status) do |response|
+        response[Rack::CONTENT_TYPE] = content_type.to_s
+        Rack::Response.new(conn.value, response.status, response.headers)
+      end
+    end
+  end
+end

data/lib/steppe/responder_registry.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'steppe/status_map'
+require 'steppe/content_type'
+
+module Steppe
+  class ResponderRegistry
+    include Enumerable
+
+    WILDCARD = '*'
+
+    attr_reader :node_name
+
+    def initialize
+      @map = {}
+      @node_name = :responders
+    end
+
+    def freeze
+      @map.each_value(&:freeze)
+      @map.freeze
+      super
+    end
+
+    def <<(responder)
+      accepts = responder.accepts
+      @map[accepts.type] ||= {}
+      @map[accepts.type][accepts.subtype] ||= StatusMap.new
+      @map[accepts.type][accepts.subtype] << responder
+      self
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      @map.each_value do |subtype_map|
+        subtype_map.each_value do |status_map|
+          status_map.each(&block)
+        end
+      end
+    end
+
+    def resolve(response_status, accepted_content_types)
+      content_types = ContentType.parse_accept(accepted_content_types)
+      status_map = find_status_map(content_types)
+      status_map&.find(response_status.to_i)
+    end
+
+    private
+
+    def find_status_map(content_types)
+      content_types.each do |ct|
+        # For each content type, try to find the most specific match
+        # 1. application/json
+        # 2. application/* return first available subtype
+        # If no match, try the next content type in the list
+        # If no match, return try '*/*'
+        # If no match, return nil
+        #
+        # If accepts is '*/*', return the first available responder
+        return @map.values.first.values.first if ct.type == WILDCARD
+
+        type_level = @map[ct.type] # 'application'
+        next unless type_level
+
+        if ct.subtype == WILDCARD # find first available subtype. More specific ones should be first
+          return type_level.values.first
+        else
+          status_map = type_level[ct.subtype] # 'application/json'
+          status_map ||= type_level[WILDCARD] # 'application/*'
+          return status_map if status_map
+        end
+      end
+
+      wildcard_level = @map[WILDCARD]
+      wildcard_level ? wildcard_level[WILDCARD] : nil
+    end
+  end
+end

data/lib/steppe/result.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module Steppe
+  class Result
+    attr_reader :value, :params, :errors, :request, :response
+
+    def initialize(value, params: {}, errors: {}, request:, response: nil)
+      @value = value
+      @params = params
+      @errors = errors
+      @request = request
+      @response = response || Rack::Response.new('', 200, {})
+    end
+
+    def valid? = true
+    def invalid? = !valid?
+    # TODO: continue and valid are different things.
+    # continue = pipeline can proceed with next step
+    # valid = result has no errors.
+    def continue? = valid?
+
+    def inspect
+      %(<#{self.class}##{object_id} [#{response.status}] value:#{value.inspect} errors:#{errors.inspect}>)
+    end
+
+    def copy(value: @value, params: @params, errors: @errors, request: @request, response: @response)
+      self.class.new(value, params:, errors:, request:, response:)
+    end
+
+    def respond_with(status = nil, &)
+      response.status = status if status
+      @response = yield(response) if block_given?
+      self
+    end
+
+    def reset(value)
+      @value = value
+      self
+    end
+
+    def valid(val = value)
+      Continue.new(val, params:, errors:, request:, response:)
+    end
+
+    def invalid(val = value, errors: {})
+      Halt.new(val, params:, errors:, request:, response:)
+    end
+
+    def continue(...) = valid(...)
+    def halt(...) = invalid(...)
+
+    class Continue < self
+      def map(callable)
+        callable.call(self)
+      end
+    end
+
+    class Halt < self
+      def valid? = false
+
+      def map(_)
+        self
+      end
+    end
+  end
+end

data/lib/steppe/serializer.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Steppe
+  # Base class for response serialization in Steppe endpoints.
+  #
+  # Serializers transform response data into structured output using Plumb types
+  # and attributes. They provide a declarative way to define the structure of
+  # response bodies with type validation and examples for OpenAPI documentation.
+  #
+  # @example Basic serializer for a user resource
+  #   class UserSerializer < Steppe::Serializer
+  #     attribute :id, Types::Integer.example(1)
+  #     attribute :name, Types::String.example('Alice')
+  #     attribute :email, Types::Email.example('alice@example.com')
+  #
+  #     # Optional: custom attribute methods
+  #     def name
+  #       object.full_name.titleize
+  #     end
+  #   end
+  #
+  # @example Nested serializers and arrays
+  #   class UserListSerializer < Steppe::Serializer
+  #     attribute :users, [UserSerializer]
+  #     attribute :count, Types::Integer
+  #     attribute :page, Types::Integer.default(1)
+  #
+  #     def users
+  #       object # Assuming object is an array of user objects
+  #     end
+  #
+  #     def count
+  #       object.size
+  #     end
+  #   end
+  #
+  # @example Error response serializer
+  #   class ErrorSerializer < Steppe::Serializer
+  #     attribute :errors, Types::Hash.example({ 'name' => 'is required' })
+  #     attribute :message, Types::String.example('Validation failed')
+  #
+  #     def errors
+  #       result.errors
+  #     end
+  #
+  #     def message
+  #       'Request validation failed'
+  #     end
+  #   end
+  #
+  # @example Using in endpoint responses
+  #   api.get :users, '/users' do |e|
+  #     e.step do |conn|
+  #       users = User.all
+  #       conn.valid(users)
+  #     end
+  #
+  #     # Using a predefined serializer class
+  #     e.serialize 200, UserListSerializer
+  #
+  #     # Using inline serializer definition
+  #     e.serialize 404 do
+  #       attribute :error, String
+  #       def error = 'Users not found'
+  #     end
+  #   end
+  #
+  # @example Accessing result context
+  #   class UserWithMetaSerializer < Steppe::Serializer
+  #     attribute :user, UserSerializer
+  #     attribute :request_id, String
+  #
+  #     def user
+  #       object
+  #     end
+  #
+  #     def request_id
+  #       result.request.env['HTTP_X_REQUEST_ID'] || 'unknown'
+  #     end
+  #   end
+  #
+  # @note Serializers automatically generate attribute reader methods that delegate
+  #   to the @object instance variable (the response data)
+  # @note The #result method provides access to the full Result context including
+  #   request, params, errors, and response data
+  # @note Type definitions support .example() for OpenAPI documentation generation
+  #
+  # @see Endpoint#serialize
+  # @see Responder#serialize
+  # @see Result
+  class Serializer
+    extend Plumb::Composable
+    include Plumb::Attributes
+
+    class << self
+      # Serialize an object using this serializer class.
+      #
+      # @private
+      # Internal method that defines attribute reader methods.
+      # Automatically creates methods that delegate to @object.attribute_name
+      def __plumb_define_attribute_reader_method__(name)
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def #{name} = @object.#{name}
+        RUBY
+      end
+
+      RenderError = Class.new(StandardError)
+
+      # @param conn [Result] The result object containing the value to serialize
+      # @return [String, nil] JSON string of serialized value or nil if no value
+      def render(conn)
+        result = call(conn)
+        raise RenderError, result.errors if result.invalid?
+
+        result.value ? JSON.dump(result.value) : nil
+      end
+
+      # @private
+      # Internal method called during endpoint processing to serialize results.
+      #
+      # @param conn [Result] The result object containing the value to serialize
+      # @return [Result] New result with serialized value
+      def call(conn)
+        hash = new(conn).serialize
+        conn.copy(value: hash)
+      end
+    end
+
+    # @!attribute [r] object
+    #   @return [Object] The object being serialized (same as result.value)
+
+    # @!attribute [r] result
+    #   @return [Result] The full result context with request, params, errors, etc.
+    attr_reader :object, :result
+
+    # Initialize a new serializer instance.
+    #
+    # @param result [Result] The result object containing the value to serialize
+    #   and full request context
+    def initialize(result)
+      @result = result
+      @object = result.value
+    end
+
+    def conn = result
+
+    # Serialize the object to a hash using defined attributes.
+    #
+    # Iterates through all defined attributes, calls the corresponding method
+    # (either auto-generated or custom), and applies the attribute's type
+    # transformation and validation.
+    #
+    # @return [Hash] The serialized hash with symbol keys
+    # @example
+    #   serializer = UserSerializer.new(result)
+    #   serializer.serialize
+    #   # => { id: 1, name: "Alice", email: "alice@example.com" }
+    def serialize
+      self.class._schema._schema.each.with_object({}) do |(key, type), ret|
+        ret[key.to_sym] = serialize_attribute(key.to_sym, type)
+      end
+    end
+
+    # Serialize a single attribute using its defined type.
+    #
+    # @param key [Symbol] The attribute name
+    # @param type [Plumb::Type] The Plumb type definition for the attribute
+    # @return [Object] The serialized attribute value
+    # @example
+    #   serialize_attribute(:name, Types::String)
+    #   # => "Alice"
+    def serialize_attribute(key, type)
+      # Ex. value = self.name
+      value = send(key)
+      type.call(result.copy(value:)).value
+    end
+  end
+end