vallkey 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 074654bc2f673408657502e765d210f70111952010045420dc5ebc9e9145e8f6
+  data.tar.gz: 8afe3aa50b9cfb716e50479bd512f8434350469c4fb31a535b4bf71e9d05115a
+SHA512:
+  metadata.gz: a26f6c8a1f422ff6dd939c9019b44f6f35d85711edfb386a2750031335b62d9ecd4c1f24978a688843faea2dcbac7bbd290f5355256cdb0de56ae49f6b8732c9
+  data.tar.gz: 45ef6f57c399b065d32faa0699520a55bc22f5dbc6c7c64d3f5ed94dbe2e69896030700649fc86c9e1b1ac91cc3a4cfa6d7156476de436b8806e88926caaec6f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vallkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,18 @@
+# vallkey (Ruby)
+
+Send any Ruby SDK through [Vallkey](https://vallkey.com) with no code changes. Requests that carry a ghost key go to Vallkey, which swaps in the real key under your rules. Every other request is left alone.
+
+```sh
+gem install vallkey
+RUBYOPT=-rvallkey/auto bundle exec rails server
+```
+
+Using `bundle exec`? Add `gem "vallkey"` to your Gemfile too: Bundler only loads the gems it lists.
+
+Covers Net::HTTP, which carries almost every Ruby SDK (Stripe, OpenAI, Anthropic, AWS, and Twilio, Octokit and Slack through Faraday).
+
+| Setting | What it does |
+|---|---|
+| `VALLKEY_API` | The Vallkey server (default `https://api.vallkey.com`) |
+| `VALLKEY_AUTO=0` | Turns it off |
+| `VALLKEY_DEBUG=1` | Logs each request sent to Vallkey (never the key) |

data/lib/vallkey/auto.rb

@@ -0,0 +1,5 @@
+# RUBYOPT=-rvallkey/auto, or require "vallkey/auto": sends requests that carry a ghost
+# key to Vallkey. VALLKEY_AUTO=0 turns it off.
+require "vallkey"
+
+Vallkey.install unless ENV["VALLKEY_AUTO"] == "0"

data/lib/vallkey/patch.rb

@@ -0,0 +1,200 @@
+# Sends every request that carries a ghost key to Vallkey instead of the provider, with
+# the same path, so any SDK works without setting a base URL. Requests without a ghost
+# key are not touched.
+#
+# Covers Net::HTTP, which carries almost every Ruby SDK: on its own (Stripe, OpenAI,
+# Anthropic, AWS), and under Faraday, HTTParty and rest-client (Twilio, Octokit, Slack).
+# Net::HTTP is patched once the app loads it, never loaded from here: under Bundler,
+# loading it before the app could pick another version than the app's Gemfile.lock.
+#
+# Each request sent to Vallkey says in x-vallkey-host which address it was for, and in
+# x-vallkey-hook what sent it: this hook, Ruby's version, the platform and VALLKEY_ENV, so
+# the dashboard can show each place a key is used. Never app names or secrets.
+#
+# VALLKEY_API      the Vallkey server (default https://api.vallkey.com)
+# VALLKEY_DEBUG=1  logs each request sent to Vallkey (never the key)
+# VALLKEY_ENV      a name for this place (production, staging...), shown in the dashboard
+module Vallkey
+  module Patch
+    GHOST = /gk_[a-z]{2,20}_[A-Za-z0-9_-]{22}_[A-Za-z0-9_-]{43}/.freeze
+    HOOK_HEADER = "x-vallkey-host".freeze
+    WHO_HEADER = "x-vallkey-hook".freeze
+
+    # The platform, from variables each one sets itself. The same list, in the same order,
+    # is in every Vallkey hook, so the dashboard names a place the same way in any language.
+    PLATFORMS = [
+      %w[VERCEL vercel], %w[AWS_LAMBDA_FUNCTION_NAME aws-lambda], %w[ECS_CONTAINER_METADATA_URI_V4 aws-ecs],
+      %w[ECS_CONTAINER_METADATA_URI aws-ecs], %w[FUNCTION_TARGET cloud-functions], %w[K_SERVICE cloud-run],
+      %w[GAE_APPLICATION app-engine], %w[FUNCTIONS_WORKER_RUNTIME azure-functions], %w[CONTAINER_APP_NAME azure-container-apps],
+      %w[WEBSITE_SITE_NAME azure-app-service], %w[RAILWAY_PROJECT_ID railway], %w[RENDER render], %w[FLY_APP_NAME fly],
+      %w[DYNO heroku], %w[NETLIFY netlify], %w[KOYEB_APP_NAME koyeb], %w[GITHUB_ACTIONS github-actions],
+      %w[GITLAB_CI gitlab-ci], %w[KUBERNETES_SERVICE_HOST kubernetes]
+    ].freeze
+
+    Target = Struct.new(:scheme, :host, :port) do
+      def host_with_port
+        default = scheme == "https" ? 443 : 80
+        port == default ? host : "#{host}:#{port}"
+      end
+    end
+
+    class << self
+      attr_reader :installed
+
+      def install
+        return if @installed
+        @installed = true
+        patch_net_http if defined?(::Net::HTTP)
+        watch_requires unless @net_http
+      end
+
+      def uninstall
+        @installed = false
+      end
+
+      def target
+        raw = ENV["VALLKEY_API"].to_s.empty? ? "https://api.vallkey.com" : ENV["VALLKEY_API"]
+        m = %r{\A(https?)://([^/:]+)(?::(\d+))?}.match(raw)
+        return Target.new("https", "api.vallkey.com", 443) unless m
+        Target.new(m[1], m[2], (m[3] || (m[1] == "https" ? 443 : 80)).to_i)
+      end
+
+      # A ghost key in a header value, including inside Basic credentials.
+      def in_value?(value)
+        text = value.to_s
+        return true if GHOST.match?(text)
+        basic = /\A\s*basic\s+([A-Za-z0-9+\/=]+)\s*\z/i.match(text)
+        return false unless basic
+        GHOST.match?(basic[1].unpack1("m").to_s)
+      rescue StandardError
+        false
+      end
+
+      def ghost?(path, headers, body)
+        query = path.to_s.split("?", 2)[1]
+        return true if query && GHOST.match?(unescape(query))
+        headers.each { |_, value| return true if in_value?(value) }
+        body.is_a?(String) && GHOST.match?(body.b)
+      end
+
+      def unescape(text)
+        text.gsub(/%([0-9A-Fa-f]{2})/) { Regexp.last_match(1).hex.chr }.gsub("+", " ")
+      end
+
+      def who
+        @who ||= begin
+          parts = ["ruby/#{Vallkey::VERSION}", "runtime=#{RUBY_VERSION}"]
+          platform = PLATFORMS.find { |name, _| !ENV[name].to_s.empty? }&.last
+          platform ||= "docker" if File.exist?("/.dockerenv")
+          parts << "platform=#{platform}" if platform
+          place = ENV["VALLKEY_ENV"].to_s
+          parts << "env=#{place}" if place.match?(/\A[A-Za-z0-9._-]{1,40}\z/)
+          parts.join("; ").freeze
+        end
+      end
+
+      def log(from, to)
+        warn "[vallkey] #{from} -> #{to}" if ENV["VALLKEY_DEBUG"] == "1"
+      end
+
+      def patch_net_http
+        return if @net_http
+        @net_http = true
+        ::Net::HTTP.prepend(NetHTTP)
+      end
+
+      # Patches Net::HTTP as soon as anything loads it (require, or an autoload).
+      def watch_requires
+        return if @watching
+        @watching = true
+        ::Kernel.module_eval do
+          alias_method :vallkey_original_require, :require
+          class << self
+            alias_method :vallkey_original_require, :require
+          end
+
+          def require(path)
+            loaded = vallkey_original_require(path)
+            Vallkey::Patch.patch_net_http if loaded && defined?(::Net::HTTP) && Vallkey::Patch.installed
+            loaded
+          end
+          module_function :require
+        end
+      end
+
+      # One kept-open connection to Vallkey for each thread, as the app's own one to the
+      # provider would be; a forked worker opens its own.
+      def connection(target, from)
+        cache = (Thread.current[:__vallkey_connections] ||= {})
+        key = [Process.pid, target.scheme, target.host, target.port]
+        http = cache[key]
+        unless http
+          http = ::Net::HTTP.new(target.host, target.port)
+          http.use_ssl = target.scheme == "https"
+          cache[key] = http
+        end
+        %i[open_timeout read_timeout write_timeout ssl_timeout continue_timeout keep_alive_timeout].each do |name|
+          next unless from.respond_to?(name) && http.respond_to?("#{name}=")
+          value = from.public_send(name)
+          http.public_send("#{name}=", value) unless value.nil?
+        end
+        http
+      end
+    end
+
+    module NetHTTP
+      # Most libraries start the connection first and send requests on it after
+      # (Faraday, the AWS SDK, connection pools): the connection is only opened when the
+      # first request that stays with the provider is sent, so one whose ghost key sends
+      # it to Vallkey never opens a connection to the provider at all.
+      def request(req, body = nil, &block)
+        moved = Vallkey::Patch.installed && Vallkey::Patch.redirect?(self, req, body)
+        unless moved
+          if @vallkey_deferred
+            @vallkey_deferred = false
+            connect
+          end
+          return super
+        end
+        target, from = moved
+        req.delete("host")
+        req[HOOK_HEADER] = from
+        req[WHO_HEADER] = Vallkey::Patch.who
+        req["host"] = target.host_with_port
+        http = Vallkey::Patch.connection(target, self)
+        http.start unless http.started?
+        http.request(req, body, &block)
+      end
+
+      private
+
+      def do_start
+        return super unless Vallkey::Patch.installed
+        @vallkey_deferred = true
+        @started = true
+      end
+
+      def do_finish
+        @vallkey_deferred = false
+        super
+      end
+    end
+
+    class << self
+      def redirect?(http, req, body)
+        t = target
+        return false if http.address == t.host && http.port == t.port
+        headers = []
+        req.each_header { |name, value| headers << [name, value] }
+        return false unless ghost?(req.path, headers, body || req.body)
+        scheme = http.use_ssl? ? "https" : "http"
+        default = http.use_ssl? ? 443 : 80
+        from = http.port == default ? http.address : "#{http.address}:#{http.port}"
+        log("#{scheme}://#{from}#{req.path.to_s.split('?', 2)[0]}", "#{t.scheme}://#{t.host_with_port}")
+        [t, from]
+      rescue StandardError
+        false # anything unusual goes out as it was
+      end
+    end
+  end
+end

data/lib/vallkey/version.rb

@@ -0,0 +1,3 @@
+module Vallkey
+  VERSION = "0.1.0"
+end

data/lib/vallkey.rb

@@ -0,0 +1,13 @@
+require "vallkey/version"
+require "vallkey/patch"
+
+# Vallkey for Ruby. Start with RUBYOPT=-rvallkey/auto, or require "vallkey/auto".
+module Vallkey
+  def self.install
+    Patch.install
+  end
+
+  def self.uninstall
+    Patch.uninstall
+  end
+end

metadata

@@ -0,0 +1,47 @@
+--- !ruby/object:Gem::Specification
+name: vallkey
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vallkey
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Requests that carry a Vallkey ghost key go to Vallkey; nothing else is
+  touched. Turn it on with RUBYOPT=-rvallkey/auto.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/vallkey.rb
+- lib/vallkey/auto.rb
+- lib/vallkey/patch.rb
+- lib/vallkey/version.rb
+homepage: https://vallkey.com
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://vallkey.com/docs/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Send any Ruby SDK through Vallkey with no code changes.
+test_files: []