composable-client 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dd40f2e54bb8bd4ae807d120d9cf791d5a943302783fd25d946daa6e109fef3
-  data.tar.gz: '091f77972ba7ad1331ee7f24f620e276801434ee4c58990903fc2d999d33c111'
+  metadata.gz: 8df11c5d1490ba7df19f3133dfe586f175803ab74ff0af9609a68423c72911f1
+  data.tar.gz: 14cbb35ef55afd129435e3607f8f4d04605398702966924fdda20b0cf1ed2afd
 SHA512:
-  metadata.gz: 63a5545a8ede6f7ed5ffd8c027b5c0c93ad59925e409387b8a900375d3ffe9b8e7aacfa51b9d6d9dec98574e786601de8e43ceba61c1f12d6cf5e64916bcd477
-  data.tar.gz: 8cdfd01d74f200368c4d76db990271e6c5bcb26079cef9e296a2230c9ba0b7ed758e2bf051429453f4e10ab45e9c1314bb2aed963f1ee5a04ab9628bd38d652c
+  metadata.gz: b2ee5510644d5c9fca86cd8e1c0e654f196129c3719f3ccfdc88de22455772670fca9d96a7c90f8341f4c939bae00a92bd50d3be1593d63190dd8fefda3280f4
+  data.tar.gz: b5e0effbf438e1cdc2f05b7fe6b8882c3557b9ef49e7291dd6519188660dfda8701ca7bdf6c16171a552d9c754a369742486720452ff28ae3ed6bc6a76507689

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+- Reject infinite and NaN timeout values before starting a request.
+- Require HTTPS by default; sanitize URL failures and reject embedded credentials.
+- Set positive timeouts, certificate/hostname verification, and explicit proxy/retry policy.
+- Preserve inherited command results and require a request implementation.
+- Document the API and add complete coverage with local HTTP/TLS tests.
+
 ## [0.1.0] - 2023-03-06
 
 - Initial release

data/README.md

@@ -1,43 +1,162 @@
-# Composable::Client
+# composable-client
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/composable/client`. To experiment with that code, run `bin/console` for an interactive prompt.
+HTTP clients with typed inputs, validation, lifecycle callbacks and command
+results. Requires Ruby 3.2+ and ActiveModel/ActiveSupport 7.2+.
+Install `gem "composable-client"`; require `composable/client`.
 
-TODO: Delete this and the text above, and describe your gem
+## Implement a request
 
-## Installation
+```ruby
+require "composable/client"
 
-Add this line to your application's Gemfile:
+class CatalogClient < Composable::Client::Base
+  attribute :endpoint, type: :string, default: "https://api.example.test"
 
-```ruby
-gem 'composable-client'
+  before_request do
+    headers["Authorization"] = "Bearer #{ENV.fetch('CATALOG_API_TOKEN')}"
+  end
+
+  private
+
+  def request
+    get("items")
+  end
+end
+
+# Configure CATALOG_API_TOKEN before calling the client.
+# operation = CatalogClient.call
+# response = operation.result
 ```
 
-And then execute:
+Implement `request`; omitting it raises `NotImplementedError`. The private helpers
+`get`, `post`, `put`, `patch`, and `delete` return a `Net::HTTPResponse`. They append
+`/path` to `endpoint`; use an endpoint without a trailing slash and paths without
+a leading slash. The response becomes `.result`.
 
-    $ bundle install
+## Inputs and lifecycle
 
-Or install it yourself as:
+| Attribute | Default | Meaning |
+| --- | --- | --- |
+| `endpoint` | Required when requesting | HTTP(S) base URL without embedded credentials |
+| `payload` | `{}` | JSON body, sent when present |
+| `headers` | `{}` | Request headers |
+| `basic_auth` | `{}` | String keys `"user"` and `"password"` |
+| `allow_http` | `false` | Explicitly allow unencrypted HTTP |
+| `open_timeout` | `10` | Positive, finite connection timeout in seconds |
+| `read_timeout` | `30` | Positive, finite read timeout in seconds |
+| `write_timeout` | `30` | Positive, finite write timeout in seconds |
 
-    $ gem install composable-client
+Validation precedes `before_request`, `around_request`, and `after_request`.
+Callbacks can update headers/payload. An aborted callback or a `false` request
+result records failure. `.call` returns the command, and `.call!` raises on errors.
+Timeout, TLS and transport errors propagate unless an application `rescue_from`
+handler translates them into errors. A received HTTP 4xx/5xx response is still a
+completed request; interpret status codes in your client/application.
 
-## Usage
+## Transport security
 
-TODO: Write usage instructions here
+HTTPS validates the peer certificate through Ruby/OpenSSL. Plain HTTP needs
+`allow_http: true`, intended for explicitly controlled endpoints such as a local
+test server. URLs with credentials, unsupported schemes, missing hosts or invalid
+syntax are rejected without including the URL in the error. Automatic retries,
+redirect following and environment-provided HTTP proxies are disabled.
 
-## Development
+Use endpoints defined by trusted application configuration. This gem is not an
+SSRF firewall: it does not restrict DNS resolution, private addresses or paths
+supplied by users. Enforce allowed destinations and network egress when accepting
+user-configurable integrations. Never log auth headers, secrets or entire payloads.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Send JSON and interpret HTTP status
 
-## Contributing
+This client creates an item and treats non-success HTTP responses as command
+failures. The endpoint is synthetic: replace it with trusted configuration before
+making a real request.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/composable-client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/composable-client/blob/master/CODE_OF_CONDUCT.md).
+```ruby
+class CreateCatalogItem < Composable::Client::Base
+  attribute :endpoint, type: :string, default: "https://api.example.test"
+  attribute :name, type: :string
+  validates :name, presence: true
+
+  before_request do
+    self.payload = { name: name }
+    headers["Accept"] = "application/json"
+  end
+
+  private
+
+  def request
+    response = post("items")
+    errors.add(:base, "Catalog rejected the request") unless response.is_a?(Net::HTTPSuccess)
+    response
+  end
+end
+
+operation = CreateCatalogItem.call(name: "Example item", read_timeout: 5)
+if operation.success?
+  item = JSON.parse(operation.result.body)
+else
+  messages = operation.errors.full_messages
+end
+```
+
+An HTTP error still leaves the response in `result` in this example. Checking
+`success?` before parsing also avoids treating an error page as successful JSON.
+Successful responses can still contain malformed JSON; handle that separately
+according to the remote API's contract.
+
+## Handle transport failures
 
-## License
+```ruby
+class ResilientCatalogClient < CatalogClient
+  rescue_from Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout do
+    errors.add(:base, "Catalog request timed out")
+  end
+end
+
+# With the endpoint and token configured:
+# operation = ResilientCatalogClient.call(open_timeout: 2, read_timeout: 5)
+# operation.failure? # => true if a handled timeout occurred
+```
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+A handled transport error may have no response, so inspect status before reading
+`result`. `.call!` propagates transport exceptions. No retry is performed; decide
+at the application level whether the operation is safe to retry.
+
+## Supply basic authentication or use a local server
+
+```ruby
+# Supply credentials from your application's secret configuration.
+operation = CreateCatalogItem.call(
+  name: "Example item",
+  basic_auth: {
+    "user" => ENV.fetch("CATALOG_USERNAME"),
+    "password" => ENV.fetch("CATALOG_PASSWORD")
+  }
+)
+```
+
+The earlier `CatalogClient` adds a Bearer header in its callback; use
+`CreateCatalogItem` above for Basic authentication. For local development, supply
+an explicitly allowed HTTP endpoint to a client such as:
+
+```ruby
+class LocalCatalogClient < Composable::Client::Base
+  private
+
+  def request
+    get("items")
+  end
+end
+
+# Requires a server running on this address.
+# LocalCatalogClient.call(endpoint: "http://127.0.0.1:3001", allow_http: true)
+```
 
-## Code of Conduct
+Headers are applied after `basic_auth`; an explicit `Authorization` header takes
+precedence. Implement `request`, not `call`, in client subclasses. Endpoint
+defaults configured in an application base client are inherited by its children,
+and payload/header defaults are independent for each instance.
 
-Everyone interacting in the Composable::Client project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/composable-client/blob/master/CODE_OF_CONDUCT.md).
+See [testing](../docs/testing.md) for real local HTTP/TLS tests and coverage.

data/lib/composable/client/base.rb

@@ -7,28 +7,32 @@ module Composable
       include Callbacks
       include HTTPVerbMethods
 
-      class << self
-        def inherited(subclass)
-          super
-          subclass.prepend(Core::Command)
-          subclass.attribute :endpoint, type: :string, default: -> { raise "endpoint is required" }
-          subclass.attribute :payload, default: {}
-          subclass.attribute :headers, default: {}
-          subclass.attribute :basic_auth, default: {}
-        end
-      end
+      prepend Core::Command
+
+      attribute :endpoint, type: :string, default: -> { raise "endpoint is required" }
+      attribute :payload, default: {}
+      attribute :headers, default: {}
+      attribute :basic_auth, default: {}
+      attribute :allow_http, type: :boolean, default: false
+      attribute :open_timeout, type: :float, default: 10
+      attribute :read_timeout, :write_timeout, type: :float, default: 30
+      validates :open_timeout, :read_timeout, :write_timeout,
+        numericality: { greater_than: 0, less_than: Float::INFINITY }
 
       def call
         return unless valid?
 
-        run_callbacks :request do
+        completed = run_callbacks :request do
           @result = request
         end
+        errors.add(:base, :invalid) if completed == false
+        @result
       end
 
       private
 
       def request
+        raise Core::Command::NotImplementedError, "implement #request in your client"
       end
     end
   end

data/lib/composable/client/gem_version.rb

@@ -10,7 +10,7 @@ module Composable
     module VERSION
       MAJOR = 0
       MINOR = 0
-      TINY  = 13
+      TINY  = 14
       PRE   = nil
 
       STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/composable/client/http_verb_methods.rb

@@ -7,8 +7,13 @@ module Composable
 
       def parse_uri(uri)
         URI.parse(uri).tap do |uri|
-          raise "Invalid URL: #{uri}" unless uri.host
+          unless uri.host && %w[http https].include?(uri.scheme) && uri.userinfo.nil?
+            raise ArgumentError, "endpoint must be an HTTP(S) URL without credentials"
+          end
+          raise ArgumentError, "HTTP requires allow_http: true" if uri.scheme == "http" && !allow_http
         end
+      rescue URI::InvalidURIError
+        raise ArgumentError, "endpoint is not a valid URL", cause: nil
       end
 
       def get(path)
@@ -33,8 +38,14 @@ module Composable
 
       def make_request(method, path)
         uri          = parse_uri("#{endpoint}/#{path}")
-        http         = Net::HTTP.new(uri.host, uri.port)
+        http         = Net::HTTP.new(uri.host, uri.port, nil)
         http.use_ssl = uri.scheme == "https"
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.verify_hostname = true
+        http.open_timeout = open_timeout
+        http.read_timeout = read_timeout
+        http.write_timeout = write_timeout
+        http.max_retries = 0
 
         request = Net::HTTP.const_get(method.to_s.capitalize).new(uri).tap do |r|
           r.body         = payload.to_json if payload.present?

data/lib/composable/client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "uri"
 require "net/http"
 require "composable/core"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: composable-client
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.14
 platform: ruby
 authors:
 - Jairo Vazquez
 bindir: exe
 cert_chain: []
-date: 2025-08-09 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: composable-core
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.13
+        version: 0.0.14
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.13
+        version: 0.0.14
 description: Composable Client provides CURD operations for a REST API
 email:
 - jairovm20@gmail.com
@@ -53,7 +53,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="