Skip to content

feat: Add opt-in proxy option to the client - #581

Open
ajay-k wants to merge 2 commits into
mainfrom
devin/1795220081-ruby-proxy-option
Open

ajay-k wants to merge 2 commits into
mainfrom
devin/1795220081-ruby-proxy-option

Conversation

@ajay-k

@ajay-k ajay-k commented Nov 21, 2026 •

Copy link
Copy Markdown

Description

Today the only way to send SDK traffic through a proxy is the http_proxy environment variable, which applies to every Net::HTTP client in the process. A customer asked for a way to set it per client so they can roll a proxy out gradually.

This adds an optional proxy setting, available on WorkOS::Client.new(proxy:), WorkOS.configure { |c| c.proxy = ... } and WorkOS::PublicClient.create(proxy:):

proxied = WorkOS::Client.new(api_key: "sk_...", proxy: "http://user:pass@proxy.example.com:8080")

Behavior:

  • Unset (default): nothing changes. BaseClient#build_http still calls Net::HTTP.new(host, port) with no proxy arguments, so http_proxy / no_proxy are read from the environment as before. Passing an explicit nil proxy address would have turned that lookup off, so it is deliberately avoided. The connection cache key is also unchanged for these clients.
  • Set: the proxy is always used for that client and takes precedence over the environment (no_proxy does not apply to it). Percent-encoded credentials in the URL are decoded before use.
  • Validation: only http:// URLs with a host are accepted (a String or URI::HTTP); anything else raises ArgumentError at construction. The error message never echoes the URL, since it can contain credentials. https:// proxy URLs are rejected because the net-http bundled with Ruby 3.3 cannot connect to a proxy over TLS. API traffic is still tunneled with CONNECT and encrypted end to end.
  • Connection pool: pooled connections are shared by every client on a thread, so connection_key now appends a SHA-256 of the proxy URL when one is set. Clients with different proxies can't reuse each other's connection, and credentials are not stored in the key.

Not included: a per-request request_options[:proxy] override. Per-client covers the gradual-rollout use case and keeps the change small.

Testing:

  • bundle exec rake test and bundle exec standardrb pass on Ruby 3.3, 3.4 and 4.0.
  • Ran against two local CONNECT proxies and the real api.workos.com on Ruby 3.3 and 4.0: an explicit proxy is used (with decoded credentials), two clients with different proxies each use their own, a client without proxy goes direct, a client without proxy still follows http_proxy, and an explicit proxy wins over http_proxy.

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

The README has a new "Proxy" section; no API reference changes.

Link to Devin session: https://workos.devinenterprise.com/sessions/67a6ce68d6d4482eab98a872fb79f92e
Open in Devin Desktop: https://workos.devinenterprise.com/desktop/session/67a6ce68d6d4482eab98a872fb79f92e?variant=devin
Requested by: @ajay-k


🟢 Devin Review found nothing to fix · View findings

Devin Review

Lets a single client route its requests through an HTTP proxy instead of relying on the process-wide http_proxy environment variable. When the option is unset, Net::HTTP keeps reading the proxy from the environment as before.

Co-Authored-By: Ajay Kumar <ajay.kumar@workos.com>
@ajay-k
ajay-k requested a review from a team as a code owner November 21, 2026 00:20
@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

Original prompt from Ajay

investigate: https://app.plain.com/workspace/w_01KEZ48Y1GZPN4PXQ41666E911/thread/th_01M7XNJMG72QQMFETQJPKFCF1P/

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@greptile-apps

greptile-apps Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issues remain from this review.

Summary

Adds an optional per-client HTTP proxy while keeping the existing environment-based behavior when proxy is unset.

  • Each WorkOS client can use its own HTTP proxy.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Client settings] --> B{Explicit proxy?}
  B -->|Yes| C[Validate HTTP proxy URL]
  C --> D[Include proxy hash in connection key]
  D --> E[Reuse or open connection through proxy]
  B -->|No| F[Keep existing connection key]
  F --> G[Reuse or open connection using environment settings]
Loading

Reviews (2) · Last reviewed commit: "Exercise pooled connection reuse in prox..." · Reviewed by Greptile

Comment thread test/workos/test_base_client.rb Resolved
Co-Authored-By: Ajay Kumar <ajay.kumar@workos.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant