[posiczko-ferret]

Summary

Replaces rest-client with Faraday, requires Ruby 3.3+, and fixes five bugs found reviewing the gem against Procore's OpenAPI spec. Reasoning for the HTTP client switch is in docs/adr/0001-replace-rest-client-with-faraday.md.

 lib/procore/
 ├── requestable.rb        # Faraday + faraday-retry + faraday-multipart
-│                         # rest-client
+│                         # Accept header (was "Accepts"), versioned paths pass through
+├── request.rb            # Procore::Request struct replaces RestClient::Request
 ├── response.rb
+│                         # empty body -> {}, pagination keeps rest/vX.Y or vapid
 ├── errors.rb             # Struct stand-ins replace OpenStruct (Ruby 4.0)
 ├── util.rb               # bearer tokens redacted in every log line
 └── auth/
     ├── token.rb
+    │                     # explicit to_h / to_json for the Session, Redis and Dalli stores
     ├── access_token_credentials.rb
+    │                     # revoke failures raise Procore::OAuthError
     └── stores/file.rb    # YAML.safe_load with permitted classes (Ruby 3.4+)

Error mapping for callers:

on(request)
  2xx            -> Response
  401/403/404    -> AuthorizationError / ForbiddenError / NotFoundError
  400/422        -> InvalidRequestError
  429            -> RateLimitError
  other          -> ServerError
  timeout, refused, reset, closed   -> retry with 1.5s * 1.5^n backoff,
                                       then APIConnectionError
  DNS, unreachable, TLS             -> APIConnectionError   (was a raw exception)

Bug fixes on top of the migration:

• Gem failed outside Rails: three ActiveSupport core extensions were used but never required. Session/Redis/Dalli stores serialized a token as "#<Procore::Auth::Token:0x...>", sync raised on deep_merge, OAuthError raised on presence.
• Empty bodies (204) parsed to the String "{}".
• pagination[:next] dropped the API version, so following a v1.1, v2.0 or vapid link requested v1.0.
• README showed e.response.errors and rescue Procore:Error, neither of which works.
• Header sent as Accepts instead of Accept.
• Pre-existing: delete ignored company_id; DELETE requests logged the Authorization header.

Evidence

• Before: rake test on main passes, but a bare ruby -e 'require "procore"' process shows the breakage the suite hides because test_helper loads ActiveRecord:

  Procore::Auth::Token.new(...).to_json  #=> "#<Procore::Auth::Token:0x...>"
  {}.deep_merge({})                      #=> NoMethodError
  Procore::Response.new(body: "", ...).body  #=> "{}" (String)
  

  After: test/procore/standalone_load_test.rb runs those scenarios in a subprocess with only require "procore".

  bundle exec rake test
  125 runs, 203 assertions, 0 failures, 3 errors, 0 skips
  

  The 3 errors are the Dalli store tests, which need the memcached from docker-compose.yaml; they pass in CI where memcached is a service.

• test/procore/rest_client_leakage_test.rb is the migration's acceptance check: nine of its tests failed before the switch and pass now.

Merge Danger

Door: two-way until 2.0.0 is pushed to RubyGems. Reverting the merge restores rest-client with no data or external state to unwind.

Blast Radius: consumers

This is the 2.0.0 major. Breaking for gem users:

• Ruby 3.3+ required.
• Response#request is a Procore::Request, not a RestClient::Request.
• APIConnectionError#cause and Requestable::HTTP_EXCEPTIONS are Faraday classes; TLS, DNS and unreachable-host failures now raise APIConnectionError.
• Response#pagination paths include the version segment ("rest/v1.0/projects?page=2").
• activesupport >= 7.0.
• Apps that got RestClient transitively through this gem must add it themselves.

Merging triggers the Release workflow, since lib/procore/version.rb changes in this PR. On this fork the RubyGems push step has no credentials and will fail without side effects.

Parts generated with Claude Code