Add HTTP.base_uri

Introduce a chainable `base_uri` option that resolves relative request
paths against a configured base URI.

Closes #519.

Author: sferik

CHANGELOG.md

@@ -23,6 +23,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `HTTP.base_uri` for setting a base URI that resolves relative request paths
+  per RFC 3986. Supports chaining (`HTTP.base_uri("https://api.example.com/v1")
+  .get("users")`), and integrates with `persistent` connections by deriving the
+  host when omitted (#519, #512, #493)
 - `Feature#on_request` and `Feature#around_request` lifecycle hooks, called
   before/around each request attempt (including retries), for per-attempt side
   effects like instrumentation spans and circuit breakers (#826)

README.md

@@ -126,6 +126,26 @@ end
 Pattern matching is also supported on `HTTP::Response::Status`, `HTTP::Headers`,
 `HTTP::ContentType`, and `HTTP::URI`.
 
+### Base URI
+
+Set a base URI to avoid repeating the scheme and host in every request:
+
+```ruby
+api = HTTP.base_uri("https://api.example.com/v1")
+api.get("users")       # GET https://api.example.com/v1/users
+api.get("users/1")     # GET https://api.example.com/v1/users/1
+```
+
+Relative paths are resolved per [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986#section-5).
+Combine with `persistent` to reuse the connection:
+
+```ruby
+HTTP.base_uri("https://api.example.com/v1").persistent do |http|
+  http.get("users")
+  http.get("posts")
+end
+```
+
 ### Thread Safety
 
 Configured sessions are safe to share across threads:

lib/http/chainable.rb

@@ -57,18 +57,45 @@ def timeout(options)
       )
     end
 
+    # Set a base URI for resolving relative request paths
+    #
+    # The first call must use an absolute URI that includes a scheme
+    # (e.g. "https://example.com"). Once a base URI is set, subsequent chained
+    # calls may use relative paths that are resolved against the existing base.
+    #
+    # @example
+    #   HTTP.base_uri("https://example.com/api/v1").get("users")
+    #
+    # @example Chaining base URIs
+    #   HTTP.base_uri("https://example.com").base_uri("api/v1").get("users")
+    #
+    # @param [String, HTTP::URI] uri the base URI (absolute with scheme when
+    #   no base is set; may be relative when chaining)
+    # @return [HTTP::Session]
+    # @raise [HTTP::Error] if no base URI is set and the given URI has no scheme
+    # @api public
+    def base_uri(uri)
+      branch default_options.with_base_uri(uri)
+    end
+
     # Open a persistent connection to a host
     #
+    # When no host is given, the origin is derived from the configured base URI.
+    #
     # @example
     #   HTTP.persistent("http://example.com").get("/")
     #
-    # @overload persistent(host, timeout: 5)
+    # @example Derive host from base URI
+    #   HTTP.base_uri("https://example.com/api").persistent.get("users")
+    #
+    # @overload persistent(host = nil, timeout: 5)
     #   Flags as persistent
-    #   @param  [String] host
+    #   @param  [String, nil] host connection origin (derived from base URI when nil)
     #   @option [Integer] timeout Keep alive timeout
+    #   @raise  [ArgumentError] if host is nil and no base URI is set
     #   @raise  [Request::Error] if Host is invalid
     #   @return [HTTP::Client] Persistent client
-    # @overload persistent(host, timeout: 5, &block)
+    # @overload persistent(host = nil, timeout: 5, &block)
     #   Executes given block with persistent client and automatically closes
     #   connection at the end of execution.
     #
@@ -94,7 +121,10 @@ def timeout(options)
     #   @return [Object] result of last expression in the block
     # @return [HTTP::Client, Object]
     # @api public
-    def persistent(host, timeout: 5)
+    def persistent(host = nil, timeout: 5)
+      host ||= default_options.base_uri&.origin
+      raise ArgumentError, "host is required for persistent connections" unless host
+
       options = default_options.merge(keep_alive_timeout: timeout).with_persistent(host)
       p_client = make_client(options)
       return p_client unless block_given?

lib/http/options.rb

@@ -150,6 +150,7 @@ def initialize(
       body: nil,
       follow: nil,
       retriable: nil,
+      base_uri: nil,
       persistent: nil,
       ssl_context: nil
     )

lib/http/options/definitions.rb

@@ -90,6 +90,30 @@ def retriable=(value)
         end
     end
 
+    def_option :base_uri, reader_only: true
+
+    # Sets the base URI for resolving relative request paths
+    #
+    # @param [String, HTTP::URI, nil] value
+    # @api private
+    # @return [HTTP::URI, nil]
+    def base_uri=(value)
+      @base_uri = value ? parse_base_uri(value) : nil
+      validate_base_uri_and_persistent!
+    end
+
+    # Checks whether a base URI is set
+    #
+    # @example
+    #   opts = HTTP::Options.new(base_uri: "https://example.com")
+    #   opts.base_uri?
+    #
+    # @api public
+    # @return [Boolean]
+    def base_uri?
+      !base_uri.nil?
+    end
+
     def_option :persistent, reader_only: true
 
     # Sets persistent connection origin
@@ -99,6 +123,7 @@ def retriable=(value)
     # @return [String, nil]
     def persistent=(value)
       @persistent = value ? HTTP::URI.parse(value).origin : nil
+      validate_base_uri_and_persistent!
     end
 
     # Checks whether persistent connection is enabled
@@ -112,5 +137,53 @@ def persistent=(value)
     def persistent?
       !persistent.nil?
     end
+
+    private
+
+    # Parses and validates a base URI value
+    #
+    # @param [String, HTTP::URI] value the base URI to parse
+    # @api private
+    # @return [HTTP::URI]
+    def parse_base_uri(value)
+      uri = HTTP::URI.parse(value)
+
+      base = @base_uri
+      return resolve_base_uri(base, uri) if base
+
+      argument_error!(format("Invalid base URI: %s", value)) unless uri.scheme
+      uri
+    end
+
+    # Resolves a relative URI against an existing base URI
+    #
+    # @param [HTTP::URI] base the existing base URI
+    # @param [HTTP::URI] relative the URI to join
+    # @api private
+    # @return [HTTP::URI]
+    def resolve_base_uri(base, relative)
+      unless base.path.end_with?("/")
+        base = base.dup
+        base.path = "#{base.path}/"
+      end
+
+      HTTP::URI.parse(base.join(relative))
+    end
+
+    # Validates that base URI and persistent origin are compatible
+    #
+    # @api private
+    # @return [void]
+    def validate_base_uri_and_persistent!
+      base = @base_uri
+      persistent = @persistent
+      return unless base && persistent
+      return if base.origin == persistent
+
+      argument_error!(
+        format("Persistence origin (%s) conflicts with base URI origin (%s)",
+               persistent, base.origin)
+      )
+    end
   end
 end

lib/http/request/builder.rb

@@ -81,7 +81,11 @@ def wrap(request)
       def make_request_uri(uri)
         uri = uri.to_s
 
-        uri = "#{@options.persistent}#{uri}" if @options.persistent? && uri !~ HTTP_OR_HTTPS_RE
+        if @options.base_uri? && uri !~ HTTP_OR_HTTPS_RE
+          uri = resolve_against_base(uri)
+        elsif @options.persistent? && uri !~ HTTP_OR_HTTPS_RE
+          uri = "#{@options.persistent}#{uri}"
+        end
 
         uri = HTTP::URI.parse uri
 
@@ -95,6 +99,26 @@ def make_request_uri(uri)
         uri
       end
 
+      # Resolve a relative URI against the configured base URI
+      #
+      # Ensures the base URI path has a trailing slash so that relative
+      # paths are appended rather than replacing the last path segment,
+      # per the convention described in RFC 3986 Section 5.
+      #
+      # @param uri [String] the relative URI to resolve
+      # @return [String] the resolved absolute URI
+      # @api private
+      def resolve_against_base(uri)
+        base = @options.base_uri or raise Error, "base_uri is not set"
+
+        unless base.path.end_with?("/")
+          base = base.dup
+          base.path = "#{base.path}/"
+        end
+
+        String(base.join(uri))
+      end
+
       # Merge query parameters into URI
       #
       # @return [void]

sig/http.rbs

@@ -56,12 +56,14 @@ module HTTP
       ?body: untyped,
       ?follow: bool,
       ?retriable: bool,
+      ?base_uri: String | URI | nil,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
     ) -> Response
     def timeout: (Numeric | Hash[Symbol, Numeric] | :null options) -> Session
-    def persistent: (String host, ?timeout: Integer) -> Client
-                   | (String host, ?timeout: Integer) { (Client) -> void } -> void
+    def base_uri: (String | URI uri) -> Session
+    def persistent: (?String? host, ?timeout: Integer) -> Client
+                   | (?String? host, ?timeout: Integer) { (Client) -> void } -> void
     def via: (*(String | Integer | Hash[String, String]) proxy) -> Session
     alias through via
     def follow: (?strict: bool, ?max_hops: Integer, ?on_redirect: (^(Response, Request) -> void)?) -> Session
@@ -116,6 +118,7 @@ module HTTP
       ?body: untyped,
       ?follow: bool,
       ?retriable: bool,
+      ?base_uri: String | URI | nil,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
     ) -> Response
@@ -164,6 +167,7 @@ module HTTP
       ?body: untyped,
       ?follow: bool,
       ?retriable: bool,
+      ?base_uri: String | URI | nil,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
     ) -> Response
@@ -495,6 +499,7 @@ module HTTP
       ?body: untyped,
       ?follow: bool,
       ?retriable: bool,
+      ?base_uri: String | URI | nil,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
     ) -> void
@@ -504,6 +509,8 @@ module HTTP
 
     def follow=: (bool value) -> void
     def retriable=: (bool value) -> void
+    def base_uri=: (String | URI | nil value) -> void
+    def base_uri?: () -> bool
     def persistent=: (String? value) -> String?
     def persistent?: () -> bool
     def merge: (Hash[Symbol, untyped] | Options other) -> Options
@@ -530,13 +537,15 @@ module HTTP
     attr_accessor encoding: Encoding?
     attr_reader follow: Hash[Symbol, untyped]?
     attr_reader retriable: Hash[Symbol, untyped]?
+    attr_reader base_uri: URI?
     attr_reader persistent: String?
 
     def with_headers: (Hash[String | Symbol, untyped] | Headers value) -> Options
     def with_encoding: (String | Encoding value) -> Options
     def with_features: (Array[Symbol | Hash[Symbol, untyped]] value) -> Options
     def with_follow: (Hash[Symbol, untyped] | bool value) -> Options
     def with_retriable: (Hash[Symbol, untyped] | bool value) -> Options
+    def with_base_uri: (String | URI value) -> Options
     def with_persistent: (String value) -> Options
     def with_proxy: (Hash[Symbol, untyped] value) -> Options
     def with_params: (Hash[String | Symbol, untyped] value) -> Options
@@ -557,6 +566,9 @@ module HTTP
 
     def assign_options: (Binding env) -> void
     def argument_error!: (String message) -> bot
+    def parse_base_uri: (String | URI value) -> URI
+    def resolve_base_uri: (URI base, URI relative) -> URI
+    def validate_base_uri_and_persistent!: () -> void
   end
 
   class URI
@@ -651,6 +663,7 @@ module HTTP
       private
 
       def make_request_uri: (String | URI uri) -> URI
+      def resolve_against_base: (String uri) -> String
       def merge_query_params!: (URI uri) -> void
       def make_request_headers: () -> Headers
       def make_request_body: (Headers headers) -> untyped

test/http/client_test.rb

@@ -160,6 +160,56 @@ def simple_response(body, status = 200)
     end
   end
 
+  describe "base_uri" do
+    it "resolves relative paths against base URI" do
+      client = StubbedClient.new(base_uri: "https://example.com/api").stub(
+        "https://example.com/api/users" => simple_response("OK")
+      )
+
+      assert_equal "OK", client.get("users").to_s
+    end
+
+    it "resolves absolute paths from host root" do
+      client = StubbedClient.new(base_uri: "https://example.com/api").stub(
+        "https://example.com/users" => simple_response("OK")
+      )
+
+      assert_equal "OK", client.get("/users").to_s
+    end
+
+    it "ignores base_uri for absolute URLs" do
+      client = StubbedClient.new(base_uri: "https://example.com/api").stub(
+        "https://other.com/path" => simple_response("OK")
+      )
+
+      assert_equal "OK", client.get("https://other.com/path").to_s
+    end
+
+    it "handles parent path traversal" do
+      client = StubbedClient.new(base_uri: "https://example.com/api/v1").stub(
+        "https://example.com/api/v2" => simple_response("OK")
+      )
+
+      assert_equal "OK", client.get("../v2").to_s
+    end
+
+    it "handles base URI without trailing slash" do
+      client = StubbedClient.new(base_uri: "https://example.com/api").stub(
+        "https://example.com/api/users" => simple_response("OK")
+      )
+
+      assert_equal "OK", client.get("users").to_s
+    end
+
+    it "handles base URI with trailing slash" do
+      client = StubbedClient.new(base_uri: "https://example.com/api/").stub(
+        "https://example.com/api/users" => simple_response("OK")
+      )
+
+      assert_equal "OK", client.get("users").to_s
+    end
+  end
+
   describe "parsing params" do
     let(:client) { HTTP::Client.new }