apiwork 0.0.0.pre → 0.1.2

data/lib/apiwork/contract/response_parser.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    class ResponseParser
+      class << self
+        def parse(contract_class, action_name, response)
+          new(contract_class, action_name).parse(response)
+        end
+      end
+
+      def initialize(contract_class, action_name)
+        @contract_class = contract_class
+        @action_name = action_name.to_sym
+      end
+
+      def parse(response)
+        return Result.new(response:) unless action
+
+        shape = action.response.body
+        return Result.new(response:) unless shape
+        return Result.new(response:) unless shape.params.any?
+
+        validated = shape.validate(response.body)
+        Result.new(issues: validated.issues, response: Response.new(body: validated.params))
+      end
+
+      private
+
+      def action
+        @action ||= @contract_class.action_for(@action_name)
+      end
+    end
+  end
+end

data/lib/apiwork/contract/union.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    # @api public
+    # Block context for defining inline union types.
+    #
+    # Accessed via `union :name, discriminator: do` inside contract actions.
+    # Use {#variant} to define possible types.
+    #
+    # @see API::Union Block context for reusable unions
+    # @see Contract::Element Block context for variant types
+    #
+    # @example instance_eval style
+    #   union :payment_method, discriminator: :type do
+    #     variant tag: 'card' do
+    #       object do
+    #         string :last_four
+    #       end
+    #     end
+    #     variant tag: 'bank' do
+    #       object do
+    #         string :account_number
+    #       end
+    #     end
+    #   end
+    #
+    # @example yield style
+    #   union :payment_method, discriminator: :type do |union|
+    #     union.variant tag: 'card' do |variant|
+    #       variant.object do |object|
+    #         object.string :last_four
+    #       end
+    #     end
+    #     union.variant tag: 'bank' do |variant|
+    #       variant.object do |object|
+    #         object.string :account_number
+    #       end
+    #     end
+    #   end
+    class Union < Apiwork::Union
+      attr_reader :contract_class
+
+      def initialize(contract_class, discriminator: nil)
+        super(discriminator:)
+        @contract_class = contract_class
+      end
+
+      private
+
+      def build_element
+        Element.new(@contract_class)
+      end
+    end
+  end
+end

data/lib/apiwork/contract_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class ContractError < ConstraintError
+    def layer
+      :contract
+    end
+  end
+end

data/lib/apiwork/controller.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module Apiwork
+  # @api public
+  # Mixin for API controllers that provides request validation and response helpers.
+  #
+  # Include in controllers to access {#contract}, {#expose}, and {#expose_error}.
+  # Automatically validates requests against the contract before actions run.
+  #
+  # @example Basic controller
+  #   class InvoicesController < ApplicationController
+  #     include Apiwork::Controller
+  #
+  #     def index
+  #       expose Invoice.all
+  #     end
+  #
+  #     def show
+  #       invoice = Invoice.find(params[:id])
+  #       expose invoice
+  #     end
+  #
+  #     def create
+  #       invoice = Invoice.create(contract.body[:invoice])
+  #       expose invoice
+  #     end
+  #   end
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      wrap_parameters false
+
+      before_action :validate_contract
+
+      rescue_from ConstraintError do |error|
+        render_error error
+      end
+    end
+
+    # @!method self.skip_contract_validation!(only: nil, except: nil)
+    #   @api public
+    #   Skips contract validation for specified actions.
+    #
+    #   @param except [Array<Symbol>]
+    #     Skip for all except these actions.
+    #   @param only [Array<Symbol>]
+    #     Skip only for these actions.
+    #
+    #   @example Skip for specific actions
+    #     skip_contract_validation! only: [:ping, :status]
+    #
+    #   @example Skip for all actions
+    #     skip_contract_validation!
+    class_methods do
+      def skip_contract_validation!(except: nil, only: nil)
+        skip_before_action :validate_contract, except:, only:
+      end
+    end
+
+    # @api public
+    # The contract for this controller.
+    #
+    # Contains parsed query parameters and request body with type coercion applied.
+    # Access parameters via {Contract::Base#query} and {Contract::Base#body}.
+    #
+    # @return [Contract::Base]
+    # @see Contract::Base
+    #
+    # @example Access parsed parameters
+    #   def create
+    #     invoice = Invoice.new(contract.body)
+    #     # contract.body contains validated, coerced params
+    #   end
+    #
+    # @example Check for specific parameters
+    #   def index
+    #     if contract.query[:include]
+    #       # handle include parameter
+    #     end
+    #   end
+    def contract
+      @contract ||= begin
+        api_request = Request.new(
+          body: request.request_parameters,
+          query: request.query_parameters,
+        ).transform(&:deep_symbolize_keys)
+        contract_class.new(action_name, api_request, coerce: true)
+      end
+    end
+
+    # @api public
+    # Exposes data as an API response.
+    #
+    # When a representation is linked via {Contract::Base.representation}, data is serialized
+    # through the representation. Otherwise, data is rendered as-is. Key transformation
+    # is applied according to the API's {API::Base.key_format}.
+    #
+    # @param data [Object, Array]
+    #   The record(s) to expose.
+    # @param meta [Hash] ({})
+    #   The metadata to include in response (pagination, etc.).
+    # @param status [Symbol, Integer, nil] (nil)
+    #   The HTTP status (:ok, or :created for create action).
+    # @see Representation::Base
+    #
+    # @example Expose a single record
+    #   def show
+    #     invoice = Invoice.find(params[:id])
+    #     expose invoice
+    #   end
+    #
+    # @example Expose a collection with metadata
+    #   def index
+    #     invoices = Invoice.all
+    #     expose invoices, meta: { total: invoices.count }
+    #   end
+    #
+    # @example Custom status
+    #   def create
+    #     invoice = Invoice.create(contract.body[:invoice])
+    #     expose invoice, status: :created
+    #   end
+    def expose(data, meta: {}, status: nil)
+      if contract_class.actions[action_name.to_sym]&.response&.no_content?
+        head :no_content
+        return
+      end
+
+      representation_class = contract_class.representation_class
+
+      body = if representation_class
+               action = resource.actions[action_name.to_sym]
+               if action.collection?
+                 adapter.process_collection(data, representation_class, contract.request, context:, meta:)
+               else
+                 adapter.process_member(data, representation_class, contract.request, context:, meta:)
+               end
+             else
+               data[:meta] = meta if meta.present?
+               data
+             end
+
+      response = Response.new(body:)
+
+      if Rails.env.development?
+        result = contract_class.parse_response(response, action_name)
+        result.issues.each { |issue| Rails.logger.warn(issue.to_s) }
+      end
+
+      response = api_class.prepare_response(response)
+
+      render json: response.body, status: status || (action_name.to_sym == :create ? :created : :ok)
+    end
+
+    # @api public
+    # Exposes an error response using a registered error code.
+    #
+    # Defaults to I18n lookup when detail is not provided.
+    #
+    # @param code_key [Symbol]
+    #   The registered error code (:not_found, :unauthorized, etc.).
+    # @param detail [String, nil] (nil)
+    #   The custom error message (uses I18n lookup if nil).
+    # @param meta [Hash] ({})
+    #   The additional metadata to include.
+    # @param path [Array<String, Symbol>, nil] (nil)
+    #   The JSON path to the error.
+    # @see ErrorCode
+    # @see Issue
+    #
+    # @example Not found error
+    #   def show
+    #     invoice = Invoice.find_by(id: params[:id])
+    #     return expose_error :not_found unless invoice
+    #     expose invoice
+    #   end
+    #
+    # @example With custom message
+    #   expose_error :forbidden, detail: 'You cannot access this invoice'
+    def expose_error(
+      code_key,
+      detail: nil,
+      path: nil,
+      meta: {}
+    )
+      error_code = ErrorCode.find!(code_key)
+
+      issue = Issue.new(
+        error_code.key,
+        detail || error_code.description(locale_key: api_class.locale_key),
+        meta:,
+        path: path || (error_code.attach_path? ? relative_path.split('/').reject(&:blank?) : []),
+      )
+
+      render_error HttpError.new([issue], error_code)
+    end
+
+    # @api public
+    # The context for this controller.
+    #
+    # Passed to representations during serialization. Override to provide
+    # current user, permissions, locale, or feature flags.
+    #
+    # @return [Hash]
+    #
+    # @example Provide current user context
+    #   def context
+    #     { current_user: current_user }
+    #   end
+    #
+    # @example Access context in representation
+    #   class InvoiceRepresentation < Apiwork::Representation::Base
+    #     attribute :editable, type: :boolean
+    #
+    #     def editable
+    #       context[:current_user].admin?
+    #     end
+    #   end
+    def context
+      {}
+    end
+
+    private
+
+    def validate_contract
+      return unless resource
+      return if contract.valid?
+
+      raise ContractError, contract.issues
+    end
+
+    def render_error(error)
+      representation_class = resource ? contract_class.representation_class : nil
+      json = adapter.process_error(error, representation_class, context:)
+      render json:, status: error.status
+    end
+
+    def contract_class
+      @contract_class ||= begin
+        klass = resource&.resolve_contract_class
+        klass || raise_contract_not_found_error
+      end
+    end
+
+    def api_class
+      @api_class ||= find_api_class || raise_api_not_found_error
+    end
+
+    def adapter
+      api_class.adapter
+    end
+
+    def resource
+      @resource ||= api_class.root_resource.find_resource_for_path(relative_path)
+    end
+
+    def relative_path
+      @relative_path ||= request.path.delete_prefix(api_class.base_path)
+    end
+
+    def raise_api_not_found_error
+      path = path_parts.empty? ? '/' : "/#{path_parts[0..1].join('/')}"
+      api_file = "config/apis/#{path.split('/').reject(&:blank?).join('_')}.rb"
+
+      raise ConfigurationError,
+            "No API found for #{self.class.name}. " \
+            "Create the API: #{api_file} (Apiwork::API.define '#{path}')"
+    end
+
+    def raise_contract_not_found_error
+      resource_base = resource.name.to_s.singularize
+      namespaces = api_class.namespaces
+
+      contract_name = [*namespaces.map { |namespace| namespace.to_s.camelize }, "#{resource_base.camelize}Contract"].join('::')
+      contract_path = ['app/contracts', *namespaces, "#{resource_base}_contract.rb"].join('/')
+
+      raise ConfigurationError,
+            "No contract found for #{self.class.name}. " \
+            "Create the contract: #{contract_path} (#{contract_name})"
+    end
+
+    def find_api_class
+      parts = path_parts
+      return API.find('/') if parts.empty?
+
+      (parts.length - 1).downto(1) do |index|
+        base_path = "/#{parts[0...index].join('/')}"
+        api_class = API.find(base_path)
+        return api_class if api_class
+      end
+
+      nil
+    end
+
+    def path_parts
+      @path_parts ||= request.path.split('/').reject(&:blank?)
+    end
+  end
+end

data/lib/apiwork/domain_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class DomainError < ConstraintError
+    def layer
+      :domain
+    end
+
+    def error_code
+      @error_code ||= ErrorCode.find!(:unprocessable_entity)
+    end
+  end
+end