client-api-builder 0.5.6 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 212fbedc035c5b2b1b406bd024a10b1739839d540a4be74ef2b67d57ed3a29d8
-  data.tar.gz: 18160a35e27ff5432a35a266b7062adda945de69f7c5e7eb6494a25cfbb66c5d
+  metadata.gz: ae35befd024cba590ae2f644877243c536612ef9ce0e66c6c7c69f2481a7fc20
+  data.tar.gz: cd843e5f96ed9a63f9fb4012ab94b7ebe7b8bd443fa2cec35fe04e1bf50e0806
 SHA512:
-  metadata.gz: fec92f548db39eec3123b5ea613f6d390af534def8c60fb1522323dd2d2c578cb6a657b896896aad05d36f7bcb9e93dcf60fc282f1c8cefa3c477113d675d106
-  data.tar.gz: ec306c4f5d78b85da0bbf5ea97c19a1e012053af75447d40600e2c358635a681579dbb933b44c40d46e4a0159a1ffe72f427270fa2833eeb34f9ad16db93575f
+  metadata.gz: a97833f34c6dde60bc8edbe9d38180e6f2904884ceb5b85a38e43358856e6e9c95f57e06f4356c0a10fe50d33801513e89132b452482bd689abf610a9ac53894
+  data.tar.gz: 9686a7f14ed8144f3e310cddf9abdf0681bfd237149397adba9d1376ca5d47a106530e099e165d22264bd7178b663e026a9e0658a2e95ef6a9b1fb1c3beb874e

data/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop --format github
+
+  test:
+    name: Tests (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.2', '3.3', '3.4']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec
+
+      - name: Upload coverage to Codecov
+        if: matrix.ruby == '3.4'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage/coverage.xml
+          fail_ci_if_error: false
+          verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

data/.rubocop.yml

@@ -0,0 +1,79 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+    - 'coverage/**/*'
+
+# Relaxed metrics for existing codebase
+Metrics/MethodLength:
+  Max: 100
+
+Metrics/AbcSize:
+  Max: 80
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/ModuleLength:
+  Max: 320
+
+Metrics/CyclomaticComplexity:
+  Max: 30
+
+Metrics/PerceivedComplexity:
+  Max: 30
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/ParameterLists:
+  Max: 7
+
+# Style preferences
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: always
+
+Layout/LineLength:
+  Max: 170
+  Exclude:
+    - 'spec/**/*'
+
+# File naming - allow hyphenated gem name
+Naming/FileName:
+  Exclude:
+    - 'lib/client-api-builder.rb'
+
+# Allow short parameter names for unused exception variables
+Naming/MethodParameterName:
+  AllowedNames:
+    - e
+    - _e
+    - io
+
+# Gemspec settings
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+# Style relaxations for existing code patterns
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+Style/StringConcatenation:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+# Note: Previously had exclusions for Style/ClassVars, Style/PerlBackrefs, and
+# Lint/RescueException in router.rb - these have been fixed:
+# - ClassVars: Changed to thread-local storage
+# - PerlBackrefs: Changed to Regexp.last_match
+# - RescueException: Changed to StandardError

data/ARCHITECTURE.md

@@ -6,143 +6,218 @@ This document describes the internal architecture and design of the Client API B
 
 Client API Builder is a Ruby gem that provides a declarative way to create API clients. It uses a modular architecture with several key components working together to provide a flexible and extensible API client framework.
 
+## File Structure
+
+```
+lib/
+├── client-api-builder.rb              # Main entry point, autoloads, error classes
+└── client_api_builder/
+    ├── router.rb                      # Core Router module with route DSL
+    ├── nested_router.rb               # NestedRouter class for hierarchical APIs
+    ├── section.rb                     # Section module for creating nested routers
+    ├── net_http_request.rb            # Net::HTTP request execution and streaming
+    ├── query_params.rb                # Custom query parameter builder
+    ├── active_support_notifications.rb # ActiveSupport instrumentation
+    └── active_support_log_subscriber.rb # ActiveSupport logging
+```
+
 ## Core Components
 
 ### 1. Router Module (`ClientApiBuilder::Router`)
 
-The `Router` module is the core component that provides the main functionality for defining and executing API requests. It includes:
+The `Router` module is the core component that provides the main functionality for defining and executing API requests.
+
+**Class Methods** (defined in `ClassMethods`):
+- `base_url`: Sets the base URL for all requests
+- `header`: Adds headers to requests (supports values, symbols, or procs)
+- `route`: Defines API endpoints with dynamic method generation
+- `body_builder`: Configures request body formatting (`:to_json`, `:to_query`, `:query_params`, or custom)
+- `query_builder`: Configures query parameter formatting
+- `query_param`: Adds query parameters to all requests
+- `connection_option`: Sets Net::HTTP connection options
+- `configure_retries`: Sets retry behavior (max_retries, sleep time)
+- `namespace`: Groups routes under a common path prefix
+
+**Instance Methods**:
+- `build_headers`: Constructs request headers, evaluating procs/symbols
+- `build_connection_options`: Merges default and request-specific options
+- `build_query`: Formats query parameters using configured builder
+- `build_body`: Formats request body using configured builder
+- `build_uri`: Constructs full URI with base_url, path, and query
+- `handle_response`: Processes API responses, parses JSON by default
+- `request_wrapper`: Manages request execution with retry and instrumentation
+- `root_router`: Returns self (overridden in NestedRouter)
+
+**Instance Attributes** (via `attr_reader`):
+- `response`: The last Net::HTTP response object
+- `request_options`: Hash of method, uri, body, headers, connection_options
+- `total_request_time`: Duration of last request in seconds
+- `request_attempts`: Number of attempts for last request
+
+### 2. Route Code Generation
+
+The `route` class method dynamically generates two methods per endpoint using `generate_route_code`:
+
+```ruby
+route :get_user, '/users/:id', expected_response_code: 200
+```
+
+Generates:
+- `get_user_raw_response(id:, **options, &block)` - Makes HTTP request, sets `@response` and `@request_options`
+- `get_user(id:, **options, &block)` - Wraps raw_response with retry logic, response code validation, and response handling
 
-- **Class Methods**: Configuration methods for setting up the API client
-  - `base_url`: Sets the base URL for all requests
-  - `header`: Adds headers to requests
-  - `route`: Defines API endpoints
-  - `body_builder`: Configures how request bodies are formatted
-  - `query_builder`: Configures how query parameters are formatted
-  - `configure_retries`: Sets retry behavior for failed requests
+**Path Parameters**: Extracted from `:param` or `{param}` syntax in path
+**Body/Query Parameters**: Extracted from `body:` and `query:` options using symbol values
 
-- **Instance Methods**: Methods for executing requests and handling responses
-  - `build_headers`: Constructs request headers
-  - `build_connection_options`: Sets up connection options
-  - `build_query`: Formats query parameters
-  - `build_body`: Formats request body
-  - `handle_response`: Processes API responses
-  - `request_wrapper`: Manages request execution and retries
+### 3. HTTP Method Auto-Detection
 
-### 2. Nested Router (`ClientApiBuilder::NestedRouter`)
+When `method:` is not specified in route options, `auto_detect_http_method` infers it from the method name:
 
-The `NestedRouter` class enables hierarchical API client organization by allowing routes to be grouped under namespaces. It:
+| Prefix Pattern | HTTP Method |
+|---------------|-------------|
+| `post`, `create`, `add`, `insert` | POST |
+| `put`, `update`, `modify`, `change` | PUT |
+| `patch` | PATCH |
+| `delete`, `remove` | DELETE |
+| (default) | GET |
 
-- Inherits from the base Router functionality
-- Maintains a reference to its root router
-- Allows for nested route definitions
-- Shares configuration with its parent router
+### 4. Nested Router (`ClientApiBuilder::NestedRouter`)
 
-### 3. Section Module (`ClientApiBuilder::Section`)
+Enables hierarchical API client organization:
 
-The `Section` module provides the mechanism for creating nested routers. It:
+```ruby
+section :users do
+  route :list, '/'
+  route :get, '/:id'
+end
+# Usage: client.users.get(id: 123)
+```
+
+Key behaviors:
+- Includes `ClientApiBuilder::Router` module
+- Stores `root_router` reference to access shared state
+- Stores `nested_router_options` passed from section definition
+- Overrides `base_url` to fall back to root_router's base_url
+- Delegates `handle_response` to root_router
+- Overrides `get_instance_method` to access root_router's instance variables in paths
 
-- Defines the `section` class method for creating nested route groups
-- Dynamically generates methods for accessing nested routers
-- Handles the creation of nested router classes
+### 5. Section Module (`ClientApiBuilder::Section`)
 
-### 4. Request Handling
+Creates nested routers dynamically using `InheritanceHelper::ClassBuilder::Utils.create_class`:
 
-The request handling system is built on top of Ruby's `Net::HTTP` and includes:
+```ruby
+def section(name, nested_router_options={}, &block)
+  # Creates: MyClient::UsersNestedRouter < ClientApiBuilder::NestedRouter
+  # Defines: MyClient.users_router (class method)
+  # Defines: MyClient#users (instance method, memoized)
+end
+```
 
-- **Request Building**: Constructs HTTP requests with proper headers, body, and query parameters
-- **Response Processing**: Handles different response formats and status codes
-- **Error Handling**: Provides custom error classes for API-specific errors
-- **Retry Mechanism**: Implements configurable retry logic for failed requests
+### 6. NetHTTP::Request Module
 
-### 5. ActiveSupport Integration
+Provides HTTP request execution using Net::HTTP:
 
-The gem integrates with ActiveSupport for:
+**Methods**:
+- `request(method:, uri:, body:, headers:, connection_options:)` - Standard request with optional block
+- `stream(...)` - Streams response body in chunks via `read_body`
+- `stream_to_io(..., io:)` - Writes streamed chunks to an IO object
+- `stream_to_file(..., file:)` - Opens file and streams to it
 
-- **Logging**: Provides request/response logging
-- **Notifications**: Implements instrumentation for request timing and monitoring
-- **Query Parameter Building**: Uses ActiveSupport's parameter formatting when available
+**Supported HTTP Methods** (via `METHOD_TO_NET_HTTP_CLASS`):
+`copy`, `delete`, `get`, `head`, `lock`, `mkcol`, `move`, `options`, `patch`, `post`, `propfind`, `proppatch`, `put`, `trace`, `unlock`
 
-## Design Patterns
+### 7. QueryParams Class
 
-### 1. Module Inclusion Pattern
+Standalone query parameter builder (used when ActiveSupport unavailable):
 
-The gem uses Ruby's module inclusion pattern extensively:
+- Handles nested hashes with bracket notation: `user[name]=John`
+- Handles arrays: `ids[]=1&ids[]=2`
+- Configurable separators: `name_value_separator` (default `=`), `param_separator` (default `&`)
+- Supports custom escape proc
+
+### 8. ActiveSupport Integration
+
+**ActiveSupportNotifications** (conditionally included when ActiveSupport defined):
+- Overrides `instrument_request` to use `ActiveSupport::Notifications.instrument`
+- Event name: `client_api_builder.request`
+- Payload includes `client: self`
+
+**ActiveSupportLogSubscriber**:
+- Subscribes to `client_api_builder.request` events for logging
+
+## Design Patterns
+
+### Module Inclusion Pattern
 
 ```ruby
 module ClientApiBuilder
   module Router
     def self.included(base)
+      base.extend InheritanceHelper::Methods
       base.extend ClassMethods
-      base.include InstanceMethods
+      base.include ::ClientApiBuilder::Section
+      base.include ::ClientApiBuilder::NetHTTP::Request
+      base.include(::ClientApiBuilder::ActiveSupportNotifications) if defined?(ActiveSupport)
+      base.send(:attr_reader, :response, :request_options, :total_request_time, :request_attempts)
     end
   end
 end
 ```
 
-This pattern allows for clean separation of class and instance methods while maintaining a single namespace.
-
-### 2. Builder Pattern
-
-The request building process follows the builder pattern:
+### Builder Pattern
 
+Request components built separately then combined:
 ```ruby
-def build_headers(options)
-  headers = {}
-  # ... build headers
-  headers
-end
+__uri__ = build_uri(__path__, __query__, __options__)
+__body__ = build_body(__body__, __options__)
+__headers__ = build_headers(__options__)
+__connection_options__ = build_connection_options(__options__)
 ```
 
-Each component (headers, body, query) is built separately and then combined into the final request.
-
-### 3. Decorator Pattern
-
-The nested router implementation uses a decorator-like pattern:
+### Configuration Inheritance
 
+Uses `inheritance-helper` gem's `add_value_to_class_method` for configuration that properly inherits to subclasses:
 ```ruby
-class NestedRouter
-  include ::ClientApiBuilder::Router
-  attr_reader :root_router
-  # ... adds additional functionality while delegating to root_router
+def base_url(url = nil)
+  return default_options[:base_url] unless url
+  add_value_to_class_method(:default_options, base_url: url)
 end
 ```
 
-## Configuration Management
-
-The gem uses a hierarchical configuration system:
+## Configuration Hierarchy
 
-1. **Default Options**: Defined in `Router.default_options`
-2. **Class-level Configuration**: Set through class methods
-3. **Instance-level Configuration**: Can override class-level settings
-4. **Request-level Configuration**: Specific to individual requests
+1. **Default Options**: `Router.default_options` returns frozen hash with defaults
+2. **Class-level Configuration**: Set through DSL methods, stored via `add_value_to_class_method`
+3. **Instance-level**: Access class config, can override in method calls
+4. **Request-level**: `**__options__` parameter on generated methods
 
 ## Error Handling
 
-The error handling system includes:
-
 - `ClientApiBuilder::Error`: Base error class
-- `ClientApiBuilder::UnexpectedResponse`: For handling unexpected API responses
-- Custom error handling through response procs
+- `ClientApiBuilder::UnexpectedResponse`: Raised when response code doesn't match expected codes
+  - Stores `response` for inspection
+- Response procs: Per-route custom response handling stored in `default_options[:response_procs]`
+- Retry on exception: `retry_request?` method (always returns true by default, override to customize)
 
-## Extensibility
+## Streaming Support
 
-The architecture is designed to be extensible through:
+Routes can specify streaming behavior:
 
-1. **Custom Body Builders**: Implement custom body formatting
-2. **Custom Query Builders**: Implement custom query parameter formatting
-3. **Response Processors**: Add custom response handling
-4. **Nested Routers**: Create custom nested router implementations
+```ruby
+route :download, '/file', stream: :file    # stream_to_file, requires file: argument
+route :stream, '/events', stream: :io      # stream_to_io, requires io: argument
+route :process, '/data', stream: :block    # stream with block for each chunk
+route :download, '/file', stream: true     # alias for :file
+```
 
 ## Dependencies
 
-- `inheritance-helper`: For class inheritance and method management
-- `json`: For JSON parsing and serialization
-- `net/http`: For HTTP request handling
-- `active_support` (optional): For additional functionality when available
+- `inheritance-helper`: Class inheritance and configuration management
+- `json`: JSON parsing and serialization (stdlib)
+- `net/http`: HTTP request handling (stdlib)
+- `cgi`: URL encoding in QueryParams (stdlib)
+- `active_support` (optional): Enhanced query building and instrumentation
 
-## Performance Considerations
+## Thread Safety
 
-1. **Request Caching**: No built-in request caching
-2. **Connection Pooling**: Uses standard Net::HTTP connection handling
-3. **Memory Usage**: Minimal object creation during request processing
-4. **Thread Safety**: No explicit thread safety mechanisms 
+The library is not thread-safe. Each client instance maintains state (`@response`, `@request_options`, etc.) that would cause race conditions if shared across threads. Create separate client instances per thread.

data/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Client API Builder is a Ruby gem for creating API clients through declarative configuration. It uses Ruby's module inclusion pattern with `ClientApiBuilder::Router` as the core component.
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/client_api_builder/router_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/client_api_builder/router_spec.rb:42
+
+# Run linter
+bundle exec rubocop
+
+# Build the gem
+gem build client-api-builder.gemspec
+```
+
+## Architecture
+
+### Core Components
+
+- **Router** (`lib/client_api_builder/router.rb`): Main module providing `route`, `base_url`, `header`, `body_builder`, `query_builder`, and `configure_retries` class methods. Uses `InheritanceHelper::Methods` for configuration inheritance.
+
+- **NestedRouter** (`lib/client_api_builder/nested_router.rb`): Enables hierarchical API organization. Maintains reference to `root_router` and shares configuration with parent.
+
+- **Section** (`lib/client_api_builder/section.rb`): Provides `section` class method for creating nested route groups via dynamically generated classes.
+
+- **NetHTTP::Request** (`lib/client_api_builder/net_http_request.rb`): HTTP request execution using `Net::HTTP`. Handles standard requests and streaming (`:file`, `:io`, `:block` modes).
+
+- **QueryParams** (`lib/client_api_builder/query_params.rb`): Custom query parameter builder used when ActiveSupport's `to_query` is unavailable.
+
+- **ActiveSupportNotifications/LogSubscriber**: Optional integration for logging and instrumentation when ActiveSupport is present.
+
+### Route Code Generation
+
+The `route` class method in Router uses `generate_route_code` to dynamically create two methods per route:
+1. `method_name_raw_response` - Makes the HTTP request
+2. `method_name` - Wraps the request with retry logic and response handling
+
+### HTTP Method Auto-Detection
+
+Methods are auto-detected from route names: `post/create/add/insert` → POST, `put/update/modify/change` → PUT, `patch` → PATCH, `delete/remove` → DELETE, others → GET.
+
+### Configuration Hierarchy
+
+1. `default_options` class method (base defaults)
+2. Class-level configuration via DSL methods
+3. Instance-level overrides
+4. Request-level options (`**__options__`)
+
+## Key Patterns
+
+- Module inclusion with `self.included(base)` extending ClassMethods and including InstanceMethods
+- `add_value_to_class_method` from `inheritance-helper` for configuration inheritance
+- Response procs stored per method name for custom response handling
+- `root_router` method for accessing the top-level router from nested routers
+
+## Dependencies
+
+- `inheritance-helper` (runtime): Class inheritance and method management
+- `webmock` (test): HTTP request stubbing
+- `activesupport` (optional): Enhanced query param building and instrumentation
+
+## Code Commits
+
+Format using angular formatting:
+```
+<type>(<scope>): <short summary>
+```
+- **type**: build|ci|docs|feat|fix|perf|refactor|test
+- **scope**: The feature or component of the service we're working on
+- **summary**: Summary in present tense. Not capitalized. No period at the end.
+
+## Documentation Maintenance
+
+When modifying the codebase, keep documentation in sync:
+- **ARCHITECTURE.md** - Update when adding/removing classes, changing component relationships, or altering data flow patterns
+- **README.md** - Update when adding new features, changing public APIs, or modifying usage examples
+- **Code comments** - Update inline documentation when changing method signatures or behavior

data/Gemfile

@@ -5,10 +5,11 @@ source 'http://rubygems.org'
 gem 'inheritance-helper'
 
 group :development do
-  gem 'rake'
-  gem 'rubocop'
   gem 'activesupport'
+  gem 'rake'
   gem 'rspec'
+  gem 'rubocop'
   gem 'simplecov'
+  gem 'simplecov-cobertura'
   gem 'webmock'
 end