stitches 5.1.0.RC4 → 5.1.0.RC5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e1a4aefc1d0249b7b5c8caf2eb06aa6e0866afef4f1d4564d63efa239ef80ce
-  data.tar.gz: 322ab581e74df9bb933d8a1e23d2dc3973c6e3494ebfac23424f16c25cbf589a
+  metadata.gz: f589f4d3f2537a4f9b17328ad88ca1b89031bd80309eddc63657b2799fb7e0e9
+  data.tar.gz: 1c51e01a86ee6ad3fa70f7e7e69b9a700bfc2ea87040f8b9c059e52648a70632
 SHA512:
-  metadata.gz: 5da26d78de12b20c29f2cff453dae8b1b1712ab3f0bbcd373291082eeee1feae3f22dcfb841c512f6a351243f10894b1c91dbc6c5c58400c182be9c0e96ee93c
-  data.tar.gz: 1a2ef89f2e74dfd9478158dfa747c19989de5f32425363f77ae428058468e57d934e29decae0fb1b1bc39a60b1b18abb97c8c82bfd3dfde73ac0b449dc13c995
+  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

@@ -1,8 +1,8 @@
 module Stitches
   # Lightweight stand-in for ApiClient when the caller is identified by
-  # the X-StitchFix-Calling-Service header rather than an API key lookup.
-  # Implements the same interface (.name, .id, .key) so existing code
-  # that reads api_client.name continues to work.
+  # 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

data/lib/stitches/calling_service_middleware.rb

@@ -1,10 +1,10 @@
 require_relative 'calling_service_client'
 
 module Stitches
-  # Rack middleware that populates the api_client env var from the
-  # X-StitchFix-Calling-Service header when no other auth middleware
-  # has already set it. This allows existing code that reads
-  # api_client.name to work transparently after API keys are disabled.
+  # 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
@@ -15,7 +15,6 @@ module Stitches
 
       unless env[client_key]
         header_name = Stitches.configuration.calling_service_header
-        header_name = CallingServiceName::DEFAULT_CALLING_SERVICE_HEADER unless header_name.present?
         rack_key = "HTTP_#{header_name.upcase.tr('-', '_')}"
 
         if (name = env[rack_key]).present?

data/lib/stitches/calling_service_name.rb

@@ -1,17 +1,8 @@
 module Stitches
   module CallingServiceName
-    DEFAULT_CALLING_SERVICE_HEADER = "X-StitchFix-Calling-Service"
-
     def calling_service_name
       @calling_service_name ||=
-        request.headers[calling_service_header_name].presence || ""
-    end
-
-    private
-
-    def calling_service_header_name
-      configured = Stitches.configuration.calling_service_header
-      configured.present? ? configured : DEFAULT_CALLING_SERVICE_HEADER
+        request.headers[Stitches.configuration.calling_service_header].presence || ""
     end
   end
 end

data/lib/stitches/version.rb

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

data/spec/calling_service_middleware_spec.rb

@@ -9,14 +9,14 @@ describe Stitches::CallingServiceMiddleware do
 
   describe "#call" do
     context "when the header is present and env var is not set" do
-      before { env["HTTP_X_STITCHFIX_CALLING_SERVICE"] = "kingmob" }
+      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("kingmob")
+        expect(client.name).to eq("my-app")
         expect(client.id).to be_nil
         expect(client.key).to be_nil
       end

data/spec/calling_service_name_spec.rb

@@ -13,10 +13,10 @@ describe Stitches::CallingServiceName do
 
   describe "#calling_service_name" do
     context "when the header is present" do
-      let(:headers) { {"X-StitchFix-Calling-Service" => "kingmob"} }
+      let(:headers) { {"X-StitchFix-Calling-Service" => "my-app"} }
 
       it "returns the header value" do
-        expect(fake_controller.calling_service_name).to eq("kingmob")
+        expect(fake_controller.calling_service_name).to eq("my-app")
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stitches
 version: !ruby/object:Gem::Version
-  version: 5.1.0.RC4
+  version: 5.1.0.RC5
 platform: ruby
 authors:
 - Stitch Fix Engineering