sofia 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 206fd38384d4c79e94ccee05f74f6d1d5d6f6769f47d1d0f3034bdb2cb5cd4e2
-  data.tar.gz: '076318a13a06efdd73e64c5e8881fce8696251c77b41861e3974683bd7396e7d'
+  metadata.gz: 8b5f47033833ca64f26bc2c6c9e7807dd68c2eae26c5f9e425390f9bf08d7b3d
+  data.tar.gz: 77fb9dbbb9106d5d3c15363bed3b218b0c6796cf8434047775de552b01e96765
 SHA512:
-  metadata.gz: 738e9c8d2ffafae77c103f2e10f812bd9bddea560233b5fd668896e1daf12b79b8c552c17fa932e2a48fad00a64c4ab05eb17ad3fa8f092663897bbaf79cd9a2
-  data.tar.gz: 24317f9caf4547f76b3f87ba900da84fcb151734ecebeed99028e08bafa4ef6d3b3dbaf128d6c1da16adf3692277f30cf381bb6ba5e2a6c50fbc767f355e76a8
+  metadata.gz: b94051c45846711ad7939161b963928443fb1a877d80fe1b786eba4a888d78b7f48b00deb31edf9baaf8c0f46fd063cc91805ef6b92c863c204b3f48cce8e134
+  data.tar.gz: f73c2498619c4bd113c5aa79ef113b6e99152b8c0432f52ac469ea7b6201cfac42b671c03ee062329742f590721e50b28ed0bf4e39a984251435152fb0a102b0

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.1.3] - 2026-04-17
+
+### Added
+
+- Soren gem updated to 0.1.3
+
+## [0.1.2] - 2026-04-17
+
+### Added
+
+- Soren adapter (`adapter: :soren`) — a second pluggable HTTP backend backed by the [soren](https://github.com/KubaJadrzak/soren) gem.
+
+### Fixed
+
+- `Sofia::Response#headers` now returns `Hash[String, Array[String]]` instead of `Hash[String, String]`, correctly preserving multi-value headers such as `Set-Cookie`.
+
 ## [0.1.0] - 2025-09-25
 
 - Initial release

data/CLAUDE.md

@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+bin/setup          # Install dependencies
+rake test          # Run all tests
+rake rubocop       # Lint with RuboCop
+bundle exec srb tc # Sorbet type checking (run after every change)
+bin/console        # IRB prompt with gem loaded
+```
+
+Run a single test file:
+```bash
+bundle exec ruby -Ilib:test test/sofia/client_test.rb
+```
+
+## Architecture
+
+Sofia is a Ruby gem providing a lightweight HTTP client abstraction with pluggable adapters (similar to Faraday). Ruby >= 3.1 required. Uses Sorbet for static type checking (`# typed: strict` throughout).
+
+**Request lifecycle:**
+1. `Sofia.new(base_url:, adapter:)` → `Sofia::Client`
+2. User calls `.get`, `.post`, etc. with a block that configures a `Request`
+3. Client delegates to the adapter's `#call(request:)` method
+4. Adapter returns a `Sofia::Response`
+
+**Key classes:**
+- `Sofia::Client` — stores base URL + adapter; exposes HTTP verb methods
+- `Sofia::Request` — mutable DSL object; builds full URL from base + path + params
+- `Sofia::Response` — immutable result; `#body` parses JSON, `#success?` checks 2xx
+- `Sofia::Adapter::Base` — abstract; subclasses implement `#call(request:) → Response`
+- `Sofia::Adapter::NetHTTP` — only current adapter; uses stdlib `Net::HTTP` with SSL auto-detection
+
+**Type wrappers** (`lib/sofia/types/`) validate and normalize all inputs at construction time (fail-fast). `BaseUrl` auto-prepends `https://`; `Path` ensures leading `/`; `Headers` defaults to JSON content/accept types; `Body` strips nil values recursively.
+
+**Error hierarchy** all inherit from `Sofia::Error::Base < StandardError`: `ArgumentError`, `ConnectionFailed`, `SSLError`, `TimeoutError`, `ParserError`.
+
+## Adding a New Adapter
+
+1. Create `lib/sofia/adapter/your_adapter.rb` subclassing `Sofia::Adapter::Base`
+2. Implement `sig { override.params(request: Sofia::Request).returns(Sofia::Response) }` on `#call`
+3. Register the adapter symbol in `lib/sofia/types/adapter.rb`
+
+## Testing Notes
+
+Tests mix real HTTP calls (against httpbin.org) in `test/sofia/client_test.rb` with unit tests for type wrappers. FactoryBot factories live in `test/factories/`.
+
+## RuboCop
+
+Config at `.rubocop.yml` uses `EnabledByDefault: true` (strict). Key limits: method 40 lines, class 200 lines, cyclomatic complexity 12. Trailing commas required in multiline literals.

data/README.md

@@ -1,6 +1,72 @@
 # Sofia
 
-This is a personal project created for self-learning purposes. The goal is to create a simplified version of Faraday gem. For now, Sofia will support only NetHTTP as adapter, but I have plans to write my own adapter in the future. Initially wanted to name this project alice but there is already an alice gem :(
+This is a personal project created for self-learning purposes. The goal is to create a simple HTTP client abstraction layer, similar to `Faraday`. At the current moment `Sofia` supports only `NetHTTP` as adapter, and only with `Content-Type: JSON` and default configuration. While basic, at the current moment `Sofia` is implemented into my other project [Shopik](https://github.com/KubaJadrzak/Shopik) and allows to perform HTTP requests correctly. I will add more functionality with time. The goal is to ultimately create my own HTTP client as well.
+
+# How it works
+
+In order to perform a request with `Sofia` you need to initialize an instance of `client` class by providing `base_url` and `adapter`. At the current moment the only supported adapter is `NetHTTP` and it will be used by default.
+```rb
+ @client = Sofia.new(base_url: base_url, adapter: adapter)
+```
+
+You can perform a request via method `send` on the instance of `client` class. You need to provide http request type (for now only `get`, `post`, `put`, `patch`, `delete` are supported) as method argument as well as block of code with configuration, for example: 
+```rb
+    response = @client.send(method) do |req|
+      req.path = path
+      req.headers['Accept'] = 'application/json'
+      req.headers['Authorization'] = "Basic #{encoded_credentials}"
+      req.body = body if body
+    end
+```
+It is a good practice to rescue errors which can be thrown by `Sofia`. The response codes `400-499`  and `500-599` are not errors, instead you need to handle these on your own. This is an example of the entire flow that allows you to make a request based on my [Shopik](https://github.com/KubaJadrzak/Shopik) project where `Sofia` is implement as HTTP client abstraction layer:
+```rb
+class EspagoClient
+
+  def initialize
+    base_url = ENV.fetch('ESPAGO_BASE_URL')
+    @user = Rails.application.credentials.dig(:espago, :app_id)
+    @password = Rails.application.credentials.dig(:espago, :password)
+
+    @client = Sofia.new(base_url: base_url)
+  end
+
+  def send(path, body: nil, method: :get)
+    response = @client.send(method) do |req|
+      req.path = path
+      req.headers['Accept'] = 'application/vnd.espago.v3+json'
+      req.headers['Authorization'] = "Basic #{encoded_credentials}"
+      req.body = body if body
+    end
+
+    ::Response.new(
+      connected: true,
+      status:    response.status,
+      body:      response.body,
+    )
+  rescue Sofia::Error::TimeoutError
+    ::Response.new(connected: false, body: { error: 'timeout' })
+  rescue Sofia::Error::ConnectionFailed
+    ::Response.new(connected: false, body: { error: 'connection_failed' })
+  rescue Sofia::Error::SSLError
+    ::Response.new(connected: false, body: { error: 'ssl_error' })
+  rescue Sofia::Error::ParserError
+    ::Response.new(connected: false, body: { error: 'parsing_error' })
+  rescue URI::InvalidURIError, URI::BadURIError
+    ::Response.new(connected: false, body: { error: 'invalid_uri' })
+  rescue StandardError
+    ::Response.new(connected: false, body: { error: 'unexpected_error' })
+  end
+
+  private
+
+  #: -> String
+  def encoded_credentials
+    Base64.strict_encode64("#{@user}:#{@password}")
+  end
+end
+
+```
+
 
 ## Development
 

data/lib/sofia/adapter/net_http.rb

@@ -17,34 +17,48 @@ module Sofia
         # @override
         #: (Sofia::Request request) -> Sofia::Response
         def call(request)
-          uri = URI.parse(request.url)
-
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = uri.scheme == 'https'
+          uri = parse_uri(request.url)
+          http = configure_http(uri, request)
+          net_req = build_request(uri, request)
+          response = perform_request(http, net_req)
+          adapt_response(response, request)
+        end
 
-          klass = Net::HTTP.const_get(request.http_method.capitalize)
+        private
 
+        #: (String url) -> URI::HTTP
+        def parse_uri(url)
+          uri = URI.parse(url)
           raise Sofia::Error::ArgumentError, 'only HTTP(S) URLs are supported' unless uri.is_a?(URI::HTTP)
 
-          net_req = klass.new(uri.request_uri)
+          uri
+        end
 
+        #: (URI::HTTP uri, Sofia::Request request) -> Net::HTTP
+        def configure_http(uri, request)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl      = uri.scheme == 'https'
+          http.read_timeout = request.options.read_timeout.to_f
+          http.write_timeout = request.options.write_timeout.to_f
+          http.open_timeout  = request.options.connection_timeout.to_f
+          http
+        end
+
+        #: (URI::HTTP uri, Sofia::Request request) -> Net::HTTPRequest
+        def build_request(uri, request)
+          klass = Net::HTTP.const_get(request.http_method.capitalize)
+          net_req = klass.new(uri.request_uri)
           request.headers.each { |k, v| net_req[k] = v }
           body_hash = request.body.to_h
           net_req.body = JSON.dump(body_hash) unless body_hash.empty? || request.http_method == :get
-
-
-          response = perform_request(http, net_req)
-
-          adapt_response(response, request)
+          net_req
         end
 
-        private
-
         #: (Net::HTTPResponse response, Sofia::Request request) -> Sofia::Response
         def adapt_response(response, request)
           Sofia::Response.new(
             status:   response.code.to_i,
-            headers:  response.each_header.to_h,
+            headers:  response.to_hash,
             raw_body: response.body,
             request:  request,
           )

data/lib/sofia/adapter/soren.rb

@@ -0,0 +1,101 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'soren'
+
+module Sofia
+  module Adapter
+    class Soren < Base
+      class << self
+
+        SOREN_CONNECTION_EXCEPTIONS = T.let(
+          [
+            ::Soren::Error::ConnectionError,
+            ::Soren::Error::ConnectionRefused,
+            ::Soren::Error::DNSFailure,
+          ].freeze,
+          T::Array[T.class_of(::Soren::Error::Base)],
+        )
+
+        SOREN_TIMEOUT_EXCEPTIONS = T.let(
+          [
+            ::Soren::Error::TimeoutError,
+            ::Soren::Error::ReadTimeout,
+          ].freeze,
+          T::Array[T.class_of(::Soren::Error::Base)],
+        )
+
+        # @override
+        #: (Sofia::Request request) -> Sofia::Response
+        def call(request)
+          uri        = parse_uri(request.url)
+          connection = build_connection(uri, request)
+          soren_req  = build_request(uri, request)
+          response   = perform_request(connection, soren_req)
+          adapt_response(response, request)
+        end
+
+        private
+
+        #: (String url) -> URI::HTTP
+        def parse_uri(url)
+          uri = URI.parse(url)
+          raise Sofia::Error::ArgumentError, 'only HTTP(S) URLs are supported' unless uri.is_a?(URI::HTTP)
+
+          uri
+        end
+
+        #: (URI::HTTP uri, Sofia::Request request) -> ::Soren::Connection
+        def build_connection(uri, request)
+          ::Soren::Connection.new(
+            host:    uri.host,
+            port:    uri.port,
+            scheme:  uri.scheme,
+            options: {
+              connect_timeout: request.options.connection_timeout.to_f,
+              read_timeout:    request.options.read_timeout.to_f,
+              write_timeout:   request.options.write_timeout.to_f,
+            },
+          )
+        end
+
+        #: (URI::HTTP uri, Sofia::Request request) -> ::Soren::Request
+        def build_request(uri, request)
+          body_hash = request.body.to_h
+          body = body_hash.empty? || request.http_method == :get ? nil : JSON.dump(body_hash)
+
+          ::Soren::Request.new(
+            method:  request.http_method.to_s,
+            target:  uri.request_uri,
+            headers: request.headers.to_h,
+            body:    body,
+          )
+        end
+
+        #: (::Soren::Connection connection, ::Soren::Request soren_req) -> ::Soren::Response
+        def perform_request(connection, soren_req)
+          connection.send(soren_req)
+        rescue ::Soren::Error::SSLError => e
+          raise Sofia::Error::SSLError, e
+        rescue *SOREN_CONNECTION_EXCEPTIONS => e
+          raise Sofia::Error::ConnectionFailed, e
+        rescue *SOREN_TIMEOUT_EXCEPTIONS => e
+          raise Sofia::Error::TimeoutError, e
+        rescue ::Soren::Error::ParseError => e
+          raise Sofia::Error::ParserError, e
+        end
+
+        #: (::Soren::Response response, Sofia::Request request) -> Sofia::Response
+        def adapt_response(response, request)
+          Sofia::Response.new(
+            status:   response.code,
+            headers:  response.headers,
+            raw_body: response.body,
+            request:  request,
+          )
+        end
+
+      end
+    end
+  end
+end

data/lib/sofia/adapter.rb

@@ -18,3 +18,4 @@ module Sofia
 end
 
 require_relative 'adapter/net_http'
+require_relative 'adapter/soren'

data/lib/sofia/client.rb

@@ -5,10 +5,11 @@ module Sofia
   class Client
     HTTP_METHODS = %w[get post put patch delete].freeze
 
-    #: (base_url: untyped, adapter: untyped) -> void
-    def initialize(base_url:, adapter:)
-      @base_url = Sofia::Types::BaseUrl.new(base_url) #: Sofia::Types::BaseUrl
-      @adapter = Sofia::Types::Adapter.new(adapter) #: Sofia::Types::Adapter
+    #: (base_url: untyped, adapter: untyped, ?options: untyped) -> void
+    def initialize(base_url:, adapter:, options: nil)
+      @base_url = Sofia::Types::Client::BaseUrl.new(base_url) #: Sofia::Types::Client::BaseUrl
+      @adapter  = Sofia::Types::Client::Adapter.new(adapter) #: Sofia::Types::Client::Adapter
+      @options  = Sofia::Types::Client::Options.new(options).value #: Sofia::Options
     end
 
     #: -> String
@@ -21,6 +22,9 @@ module Sofia
       @adapter.to_sym
     end
 
+    #: Sofia::Options
+    attr_reader :options
+
     #: ?{ (Request req) -> untyped } -> Response
     def get(&) = request(:get, &)
 
@@ -45,6 +49,7 @@ module Sofia
       req = Request.new(
         http_method: http_method,
         base_url:    @base_url,
+        options:     @options,
       )
 
       block.call(req)

data/lib/sofia/defaults/timeouts.rb

@@ -0,0 +1,12 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sofia
+  module Defaults
+    module Timeouts
+      READ_TIMEOUT = 30
+      WRITE_TIMEOUT = 30
+      CONNECTION_TIMEOUT = 10
+    end
+  end
+end

data/lib/sofia/defaults.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sofia
+  module Defaults; end
+end
+
+require_relative 'defaults/timeouts'

data/lib/sofia/options.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sofia
+  class Options
+
+    #: Sofia::Types::Options::Timeout::Read
+    attr_reader :read_timeout
+
+    #: Sofia::Types::Options::Timeout::Write
+    attr_reader :write_timeout
+
+    #: Sofia::Types::Options::Timeout::Connection
+    attr_reader :connection_timeout
+
+    #: (?read_timeout: untyped, ?write_timeout: untyped, ?connection_timeout: untyped) -> void
+    def initialize(read_timeout: nil, write_timeout: nil, connection_timeout: nil)
+      @read_timeout = Sofia::Types::Options::Timeout::Read.new(
+        read_timeout || Sofia::Defaults::Timeouts::READ_TIMEOUT,
+      ) #: Sofia::Types::Options::Timeout::Read
+      @write_timeout = Sofia::Types::Options::Timeout::Write.new(
+        write_timeout || Sofia::Defaults::Timeouts::WRITE_TIMEOUT,
+      ) #: Sofia::Types::Options::Timeout::Write
+      @connection_timeout = Sofia::Types::Options::Timeout::Connection.new(
+        connection_timeout || Sofia::Defaults::Timeouts::CONNECTION_TIMEOUT,
+      ) #: Sofia::Types::Options::Timeout::Connection
+    end
+  end
+end

data/lib/sofia/request.rb

@@ -7,43 +7,47 @@ module Sofia
     #: Symbol
     attr_reader :http_method
 
-    #: Sofia::Types::Headers
+    #: Sofia::Types::Client::Headers
     attr_reader :headers
 
-    #: Sofia::Types::Params
+    #: Sofia::Types::Client::Params
     attr_reader :params
 
-    #: Sofia::Types::Body
+    #: Sofia::Types::Client::Body
     attr_reader :body
 
-    #: (http_method: Symbol, base_url: Sofia::Types::BaseUrl) -> void
-    def initialize(http_method:, base_url:)
+    #: Sofia::Options
+    attr_reader :options
+
+    #: (http_method: Symbol, base_url: Sofia::Types::Client::BaseUrl, ?options: Sofia::Options) -> void
+    def initialize(http_method:, base_url:, options: Sofia::Options.new)
       @http_method = http_method
-      @base_url = base_url
-      @path     = Sofia::Types::Path.new #: Sofia::Types::Path
-      @params   = Sofia::Types::Params.new #: Sofia::Types::Params
-      @headers  = Sofia::Types::Headers.new #: Sofia::Types::Headers
-      @body     = Sofia::Types::Body.new #: Sofia::Types::Body
+      @base_url    = base_url
+      @options     = options #: Sofia::Options
+      @path        = Sofia::Types::Client::Path.new #: Sofia::Types::Client::Path
+      @params      = Sofia::Types::Client::Params.new #: Sofia::Types::Client::Params
+      @headers     = Sofia::Types::Client::Headers.new #: Sofia::Types::Client::Headers
+      @body        = Sofia::Types::Client::Body.new #: Sofia::Types::Client::Body
     end
 
     #: (untyped path) -> void
     def path=(path)
-      @path = Sofia::Types::Path.new(path)
+      @path = Sofia::Types::Client::Path.new(path)
     end
 
     #: (untyped params) -> void
     def params=(params)
-      @params = Sofia::Types::Params.new(params)
+      @params = Sofia::Types::Client::Params.new(params)
     end
 
     #: (untyped headers) -> void
     def headers=(headers)
-      @headers = Sofia::Types::Headers.new(headers)
+      @headers = Sofia::Types::Client::Headers.new(headers)
     end
 
     #: (untyped? body) -> void
     def body=(body)
-      @body = Sofia::Types::Body.new(body)
+      @body = Sofia::Types::Client::Body.new(body)
     end
 
     #: -> String

data/lib/sofia/response.rb

@@ -7,7 +7,7 @@ module Sofia
     #: Integer
     attr_reader :status
 
-    #: Hash[String, String]
+    #: Hash[String, Array[String]]
     attr_reader :headers
 
     #: String?
@@ -16,7 +16,7 @@ module Sofia
     #: Sofia::Request
     attr_reader :request
 
-    #: (status: Integer, headers: Hash[String, String], raw_body: String?, request: Sofia::Request) -> void
+    #: (status: Integer, headers: Hash[String, Array[String]], raw_body: String?, request: Sofia::Request) -> void
     def initialize(status:, headers:, raw_body:, request:)
       @status  = status
       @headers = headers

data/lib/sofia/types/client/adapter.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sofia
+  module Types
+    module Client
+      class Adapter
+
+        #: singleton(Sofia::Adapter::Base)
+        attr_reader :klass
+
+        #: (?untyped adapter) -> void
+        def initialize(adapter = :net_http)
+          name, klass = validate_and_set(adapter || :net_http)
+          @name  = T.let(name, Symbol)
+          @klass = T.let(klass, T.class_of(Sofia::Adapter::Base))
+        end
+
+        #: -> Symbol
+        def to_sym
+          @name
+        end
+
+        private
+
+        #: (untyped) -> [Symbol, singleton(Sofia::Adapter::Base)]
+        def validate_and_set(adapter)
+          case adapter&.to_sym
+          when :net_http
+            [:net_http, Sofia::Adapter::NetHTTP]
+          when :soren
+            [:soren, Sofia::Adapter::Soren]
+          else
+            Kernel.raise Sofia::Error::ArgumentError, "unknown adapter #{adapter}"
+          end
+
+        rescue NoMethodError
+          Kernel.raise Sofia::Error::ArgumentError, "unknown adapter #{adapter}"
+        end
+      end
+    end
+  end
+end

data/lib/sofia/types/client/base_url.rb

@@ -0,0 +1,35 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sofia
+  module Types
+    module Client
+      class BaseUrl
+
+        #: (untyped base_url) -> void
+        def initialize(base_url)
+          @base_url = validate_and_normalize(base_url).freeze #: String
+        end
+
+        #: -> String
+        def to_s
+          @base_url
+        end
+
+        private
+
+        #: (untyped) -> String
+        def validate_and_normalize(base_url)
+          unless base_url.is_a?(String) && !base_url.strip.empty?
+            raise Sofia::Error::ArgumentError, 'base_url must be a non-empty String'
+          end
+
+          normalized = base_url.chomp('/')
+          return normalized if normalized.start_with?('http://', 'https://')
+
+          "https://#{normalized}"
+        end
+      end
+    end
+  end
+end

data/lib/sofia/types/client/body.rb

@@ -0,0 +1,62 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sofia
+  module Types
+    module Client
+      class Body
+
+        #:  Hash[String, untyped]
+        attr_reader :body
+
+        #: (?untyped? body) -> void
+        def initialize(body = nil)
+          @body = validate_and_normalize(body) #:  Hash[String, untyped]
+        end
+
+        #: -> Hash[String, untyped]
+        def to_h
+          @body.dup
+        end
+
+        private
+
+        #: (untyped? body) -> Hash[String, untyped]
+        def validate_and_normalize(body)
+          return {} unless body
+
+          Kernel.raise Sofia::Error::ArgumentError, 'body must be a Hash' unless body.is_a?(Hash)
+          body.each_with_object({}) do |(key, value), acc|
+            next if value.nil?
+
+            acc[key.to_s] =
+              case value
+              when Hash
+                validate_and_normalize(value)
+              when Array
+                validate_and_normalize_array(value)
+              else
+                value
+              end
+          end
+        end
+
+        #: (Array[untyped]) -> Array[untyped]
+        def validate_and_normalize_array(array)
+          array.each_with_object([]) do |value, acc|
+            next if value.nil?
+
+            acc << case value
+                   when Hash
+                     validate_and_normalize(value)
+                   when Array
+                     validate_and_normalize_array(value)
+                   else
+                     value
+                   end
+          end
+        end
+      end
+    end
+  end
+end