stitches 5.1.0.RC3 → 5.1.0.RC5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2b49b7056175fa55cc2b597754f143cca6e841a3aafe723fab3681fb646f4c2
-  data.tar.gz: 87a15dcf53ad770755faec02eae327a9195c26b834babaef526dedffe4d9568e
+  metadata.gz: f589f4d3f2537a4f9b17328ad88ca1b89031bd80309eddc63657b2799fb7e0e9
+  data.tar.gz: 1c51e01a86ee6ad3fa70f7e7e69b9a700bfc2ea87040f8b9c059e52648a70632
 SHA512:
-  metadata.gz: b076a27646bd5919cdcf1a2c066536888b90e9a851ce9828369891c3198cbdef8f3208ee1d643344b7f592057d72fefd1b855ab0de0705cdcb708a1d91aa1ccc
-  data.tar.gz: e5d3445946a09d9e54f63060edea96fd5fd0b9156622f9f094850d7ae93cca9a7737d5c7d3800e3c722dbe87a69ea3911e332da1fe3d5ee8c680e4f045cca016
+  metadata.gz: f5e2b42fa7a6609e8dc8e6bec1cf863e4c2e0e7d5bc47ae581187ce7ae2b15c672ec407fb20d07fe3829807e0ec976cbb7b56eeb47d47303352d3807ffd99b40
+  data.tar.gz: 766a73badd49a7aee8c3b16635230082dc0fb7e39cba5e20ef0e7acaaab42641874dd2348b233adcfa7f15aee883bef42965f82d3a7d46187f04799a1e632939

data/README.md

@@ -42,73 +42,77 @@ Stitches.configure do |config|
 end
 ```
 
-### Caller Identification via `X-StitchFix-Calling-Service`
+### Caller Identification
 
 When API key auth is disabled, services lose the ability to identify which
-internal service is calling them. The `Stitches::CallingServiceName` concern
-provides a replacement that works with or without API keys enabled.
+internal service is calling them. Stitches 5.1+ provides two mechanisms that
+work together to restore this — one automatic, one opt-in.
 
-**Include the concern in your API controller:**
+The calling service header name defaults to `X-StitchFix-Calling-Service` but
+is configurable via `Stitches.configuration.calling_service_header`.
 
-```ruby
-class Api::ApiController < ActionController::API
-  include Stitches::CallingServiceName
+#### CallingServiceMiddleware (automatic)
 
-  # Replace api_client.name with calling_service_name anywhere you need
-  # to know who the caller is (stats, routing, updated_by, etc.)
-end
-```
+`CallingServiceMiddleware` is registered via the railtie and runs after the
+`ApiKey` middleware. When no auth middleware has populated the caller identity
+env var (`Stitches.configuration.env_var_to_hold_api_client`), it reads the
+calling service header and populates it with a `CallingServiceClient` struct.
 
-For controllers that don't inherit from your ApiController (e.g. Devise
-controllers), include the concern directly:
+**This means existing code that reads the caller identity object's `.name`
+continues to work with no changes** — the value now comes from the header
+instead of a DB lookup.
 
-```ruby
-class Api::V1::SessionsController < Devise::SessionsController
-  include Stitches::CallingServiceName
-end
-```
+`CallingServiceClient` implements:
+- `.name` — the header value (e.g. "my-app")
+- `.id` — nil
+- `.key` — nil
 
-**Resolution order:**
+**Resolution order (for `request.env[env_var_to_hold_api_client]`):**
 
-1. `X-StitchFix-Calling-Service` request header (preferred)
-2. `api_client&.name` — the stitches-authenticated ApiClient (works when API keys are enabled)
-3. `""` (empty string) — fallback when neither is available
+1. If the `ApiKey` middleware authenticated a key → `ApiClient` record (has `.name`, `.id`, `.key`)
+2. If JWT or other auth middleware set the env var → that object (e.g. a user)
+3. If neither ran, but `X-StitchFix-Calling-Service` header is present → `CallingServiceClient` struct
+4. If nothing → nil
 
-This is backwards compatible. When `disable_api_key_support` is false, the
-stitches middleware still populates `api_client`, so the fallback returns the
-authenticated name. When true, callers identify themselves via the header.
+**Middleware ordering:** `ApiKey` → `CallingServiceMiddleware` → `ValidMimeType`
 
-**Client-side setup:**
+#### CallingServiceName concern (opt-in)
 
-Clients using `stitchfix-api_client` (v5.1+) automatically send this header.
-The value is derived from the `app_name` config option or `ENV["APP_NAME"]`:
+For cases where you want strictly the header value (e.g. metrics tags where
+you never want a human user's name), include the concern:
 
 ```ruby
-MyServiceClient.new(
-  endpoint: "https://my-service.internal",
-  app_name: "kingmob"  # sent as X-StitchFix-Calling-Service
-)
+class Api::ApiController < ActionController::API
+  include Stitches::CallingServiceName
+end
+
+# Returns the header value only, empty string if absent:
+calling_service_name  # => "my-app" or ""
 ```
 
-If `app_name` is not set, `ENV["APP_NAME"]` is used (typically set in
-production deployments). If neither is available, the header is not sent.
+#### Configuration
+
+The header name is configurable (defaults to `X-StitchFix-Calling-Service`):
+
+```ruby
+Stitches.configure do |config|
+  config.calling_service_header = "X-My-Custom-Header"
+end
+```
 
 #### Security considerations
 
 `X-StitchFix-Calling-Service` is a **self-declared, unsigned header**. Any
 caller that can reach your service can set it to any value. This means:
 
-- **Do not use `calling_service_name` as a sole authorization mechanism for
-  sensitive operations** (e.g. granting admin tokens, bypassing verification
-  flows) unless the network layer guarantees that only the legitimate service
-  can reach the endpoint.
+- **Do not use it as a sole authorization mechanism** for sensitive operations
+  unless the network layer guarantees that only the legitimate service can
+  reach the endpoint.
 - **Strip this header at public ingress points** (Traefik, ALB, API gateway)
   to prevent external callers from spoofing internal service identities.
-  Internal-only traffic should be the only source of this header.
-- **This header replaces API key-based identity, not authorization.** API
-  keys provided a weak form of authentication (possession of a shared secret).
-  This header provides identification only. If you need to verify the caller's
-  identity cryptographically, use mTLS or a service mesh AuthorizationPolicy.
+- **This header replaces API key-based identity, not authorization.** It
+  provides identification only. If you need to verify the caller's identity
+  cryptographically, use mTLS or a service mesh AuthorizationPolicy.
 - **Safe uses:** stats tagging, logging, `updated_by` audit fields, routing
   hints, non-security-critical behavioral branching.
 - **Unsafe without network enforcement:** access control decisions, privilege

data/lib/stitches/calling_service_client.rb

@@ -0,0 +1,15 @@
+module Stitches
+  # Lightweight stand-in for ApiClient when the caller is identified by
+  # the calling service header rather than an API key lookup. Implements
+  # the same interface (.name, .id, .key) so existing code that reads
+  # the caller identity object continues to work.
+  CallingServiceClient = Struct.new(:name) do
+    def id
+      nil
+    end
+
+    def key
+      nil
+    end
+  end
+end

data/lib/stitches/calling_service_middleware.rb

@@ -0,0 +1,28 @@
+require_relative 'calling_service_client'
+
+module Stitches
+  # Rack middleware that populates the caller identity env var from the
+  # calling service header when no other auth middleware has already set
+  # it. This allows existing code that reads the caller identity object
+  # to work transparently after API keys are disabled.
+  class CallingServiceMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      client_key = Stitches.configuration.env_var_to_hold_api_client
+
+      unless env[client_key]
+        header_name = Stitches.configuration.calling_service_header
+        rack_key = "HTTP_#{header_name.upcase.tr('-', '_')}"
+
+        if (name = env[rack_key]).present?
+          env[client_key] = CallingServiceClient.new(name)
+        end
+      end
+
+      @app.call(env)
+    end
+  end
+end

data/lib/stitches/calling_service_name.rb

@@ -2,9 +2,7 @@ module Stitches
   module CallingServiceName
     def calling_service_name
       @calling_service_name ||=
-        request.headers[Stitches.configuration.calling_service_header].presence ||
-        request.env[Stitches.configuration.env_var_to_hold_api_client]&.name ||
-        ""
+        request.headers[Stitches.configuration.calling_service_header].presence || ""
     end
   end
 end

data/lib/stitches/railtie.rb

@@ -1,10 +1,12 @@
 require 'stitches/api_key'
 require 'stitches/valid_mime_type'
 require 'stitches/api_client_access_wrapper'
+require 'stitches/calling_service_middleware'
 
 module Stitches
   class Railtie < Rails::Railtie
     config.app_middleware.use Stitches::ApiKey
+    config.app_middleware.use Stitches::CallingServiceMiddleware
     config.app_middleware.use Stitches::ValidMimeType
   end
 end

data/lib/stitches/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stitches
-  VERSION = '5.1.0.RC3'
+  VERSION = '5.1.0.RC5'
 end

data/spec/calling_service_middleware_spec.rb

@@ -0,0 +1,72 @@
+require 'rails_helper'
+
+describe Stitches::CallingServiceMiddleware do
+  let(:app) { ->(env) { [200, env, "OK"] } }
+  let(:middleware) { described_class.new(app) }
+  let(:env) { Rack::MockRequest.env_for("/api/test", method: "POST") }
+
+  let(:client_key) { Stitches.configuration.env_var_to_hold_api_client }
+
+  describe "#call" do
+    context "when the header is present and env var is not set" do
+      before { env["HTTP_X_STITCHFIX_CALLING_SERVICE"] = "my-app" }
+
+      it "populates the env var with a CallingServiceClient" do
+        _status, result_env, _body = middleware.call(env)
+        client = result_env[client_key]
+
+        expect(client).to be_a(Stitches::CallingServiceClient)
+        expect(client.name).to eq("my-app")
+        expect(client.id).to be_nil
+        expect(client.key).to be_nil
+      end
+    end
+
+    context "when the env var is already set (API key or JWT auth ran)" do
+      let(:existing_client) { double("ApiClient", name: "existing-client", id: 42) }
+
+      before do
+        env[client_key] = existing_client
+        env["HTTP_X_STITCHFIX_CALLING_SERVICE"] = "some-service"
+      end
+
+      it "does not overwrite the existing value" do
+        _status, result_env, _body = middleware.call(env)
+        expect(result_env[client_key]).to eq(existing_client)
+      end
+    end
+
+    context "when the header is absent and env var is not set" do
+      it "leaves the env var nil" do
+        _status, result_env, _body = middleware.call(env)
+        expect(result_env[client_key]).to be_nil
+      end
+    end
+
+    context "when the header is blank" do
+      before { env["HTTP_X_STITCHFIX_CALLING_SERVICE"] = "" }
+
+      it "leaves the env var nil" do
+        _status, result_env, _body = middleware.call(env)
+        expect(result_env[client_key]).to be_nil
+      end
+    end
+
+    context "with a custom configured header" do
+      before do
+        Stitches.configuration.calling_service_header = "X-Custom-Caller"
+        env["HTTP_X_CUSTOM_CALLER"] = "custom-service"
+      end
+
+      after { Stitches.configuration.reset_to_defaults! }
+
+      it "reads from the configured header" do
+        _status, result_env, _body = middleware.call(env)
+        client = result_env[client_key]
+
+        expect(client).to be_a(Stitches::CallingServiceClient)
+        expect(client.name).to eq("custom-service")
+      end
+    end
+  end
+end

data/spec/calling_service_name_spec.rb

@@ -2,8 +2,7 @@ require 'rails_helper'
 
 describe Stitches::CallingServiceName do
   let(:headers) { {} }
-  let(:env) { {} }
-  let(:fake_request) { double("request", headers: headers, env: env) }
+  let(:fake_request) { double("request", headers: headers) }
   let(:fake_controller) {
     req = fake_request
     Object.new.tap { |c|
@@ -13,53 +12,27 @@ describe Stitches::CallingServiceName do
   }
 
   describe "#calling_service_name" do
-    context "when X-StitchFix-Calling-Service header is present" do
-      let(:headers) { {"X-StitchFix-Calling-Service" => "kingmob"} }
+    context "when the header is present" do
+      let(:headers) { {"X-StitchFix-Calling-Service" => "my-app"} }
 
       it "returns the header value" do
-        expect(fake_controller.calling_service_name).to eq("kingmob")
-      end
-
-      context "and env var client is also present" do
-        let(:env) { {Stitches.configuration.env_var_to_hold_api_client => double(name: "other-service")} }
-
-        it "prefers the header" do
-          expect(fake_controller.calling_service_name).to eq("kingmob")
-        end
+        expect(fake_controller.calling_service_name).to eq("my-app")
       end
     end
 
-    context "when header is absent but env var client is present" do
-      let(:env) { {Stitches.configuration.env_var_to_hold_api_client => double(name: "mobile-service")} }
-
-      it "returns the client name from env" do
-        expect(fake_controller.calling_service_name).to eq("mobile-service")
-      end
-    end
-
-    context "when header is blank" do
-      let(:headers) { {"X-StitchFix-Calling-Service" => ""} }
-      let(:env) { {Stitches.configuration.env_var_to_hold_api_client => double(name: "fallback-service")} }
-
-      it "treats blank as absent and falls through to env var client" do
-        expect(fake_controller.calling_service_name).to eq("fallback-service")
-      end
-    end
-
-    context "when neither header nor env var client is present" do
+    context "when the header is absent" do
       it "returns empty string" do
         expect(fake_controller.calling_service_name).to eq("")
       end
     end
 
-    context "when env var client is nil" do
-      let(:env) { {Stitches.configuration.env_var_to_hold_api_client => nil} }
+    context "when the header is blank" do
+      let(:headers) { {"X-StitchFix-Calling-Service" => ""} }
 
       it "returns empty string" do
         expect(fake_controller.calling_service_name).to eq("")
       end
     end
-
   end
 
   describe "configurable header" do
@@ -70,13 +43,8 @@ describe Stitches::CallingServiceName do
     context "when configured to a custom header" do
       let(:headers) { {"X-Custom-Caller" => "my-service"} }
 
-      before do
-        Stitches.configuration.calling_service_header = "X-Custom-Caller"
-      end
-
-      after do
-        Stitches.configuration.reset_to_defaults!
-      end
+      before { Stitches.configuration.calling_service_header = "X-Custom-Caller" }
+      after { Stitches.configuration.reset_to_defaults! }
 
       it "reads from the configured header" do
         expect(fake_controller.calling_service_name).to eq("my-service")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stitches
 version: !ruby/object:Gem::Version
-  version: 5.1.0.RC3
+  version: 5.1.0.RC5
 platform: ruby
 authors:
 - Stitch Fix Engineering
@@ -174,6 +174,8 @@ files:
 - lib/stitches/api_key.rb
 - lib/stitches/api_migration_generator.rb
 - lib/stitches/api_version_constraint.rb
+- lib/stitches/calling_service_client.rb
+- lib/stitches/calling_service_middleware.rb
 - lib/stitches/calling_service_name.rb
 - lib/stitches/configuration.rb
 - lib/stitches/deprecation.rb
@@ -209,6 +211,7 @@ files:
 - owners.json
 - spec/api_key_middleware_spec.rb
 - spec/api_version_constraint_middleware_spec.rb
+- spec/calling_service_middleware_spec.rb
 - spec/calling_service_name_spec.rb
 - spec/configuration_spec.rb
 - spec/deprecation_spec.rb
@@ -306,6 +309,7 @@ summary: You'll be in stitches at how easy it is to create a service at Stitch F
 test_files:
 - spec/api_key_middleware_spec.rb
 - spec/api_version_constraint_middleware_spec.rb
+- spec/calling_service_middleware_spec.rb
 - spec/calling_service_name_spec.rb
 - spec/configuration_spec.rb
 - spec/deprecation_spec.rb