feat(network-details): Extend SentryReplayOptions API

Implement SDK fields, setters and validation for network details capture:
 https://docs.sentry.io/platforms/javascript/session-replay/configuration/#network-details

- String patterns for prefix matching (e.g., "https://api.example.com" matches subpaths)
- NSRegularExpression patterns for complex regex matching
- Deny list precedence over allow list
- Empty string filtering to handle invalid input gracefully

Author: 43jay

Sources/Swift/Integrations/SessionReplay/SentryReplayOptions.swift

@@ -1,4 +1,4 @@
-// swiftlint:disable file_length missing_docs
+// swiftlint:disable file_length missing_docs type_body_length
 import Foundation
 
 @objcMembers
@@ -25,6 +25,13 @@ public class SentryReplayOptions: NSObject, SentryRedactOptions {
         public static let excludedViewClasses: Set<String> = []
         public static let includedViewClasses: Set<String> = []
 
+        // Network capture configuration defaults
+        public static let networkDetailAllowUrls: [Any] = []
+        public static let networkDetailDenyUrls: [Any] = []
+        public static let networkCaptureBodies: Bool = true
+        public static let networkRequestHeaders: [String] = ["Content-Type", "Content-Length", "Accept"]
+        public static let networkResponseHeaders: [String] = ["Content-Type", "Content-Length", "Accept"]
+
         // The following properties are defaults which are not configurable by the user.
 
         fileprivate static let sdkInfo: [String: Any]? = nil
@@ -292,6 +299,131 @@ public class SentryReplayOptions: NSObject, SentryRedactOptions {
      */
     public var enableFastViewRendering: Bool
 
+    /**
+     * A list of URL patterns to capture request and response details for during session replay.
+     * 
+     * When non-empty, network requests with URLs matching any of these patterns will have their
+     * headers and bodies captured for session replay.
+     * 
+     * Supports both String and NSRegularExpression patterns (See [JavaScript SDK](https://github.com/getsentry/sentry-javascript/blob/6fb1ee139a92a6055b52b0bbf5136fa0e5a9353f/packages/core/src/utils/string.ts#L114-L119)):
+     * - String: Uses substring contains
+     * - NSRegularExpression: Uses full regex matching
+     * 
+     * Default: empty array (network detail capture disabled)
+     *
+     * Example:
+     * ```swift
+     * // String patterns (substring matching)
+     * options.sessionReplay.networkDetailAllowUrls = [
+     *     "api.example.com",              // Matches any URL containing this string
+     *     "/api/v1/",                      // Matches any URL containing this path
+     *     "https://analytics.myapp.com"   // Matches any URL containing this prefix
+     * ]
+     * 
+     * // NSRegularExpression patterns (full regex matching)
+     * let apiRegex = try? NSRegularExpression(pattern: "^https://api\\.example\\.com/v[0-9]+/.*")
+     * let imageRegex = try? NSRegularExpression(pattern: ".*\\.(jpg|jpeg|png|gif)$")
+     * 
+     * // Mixed array of both types
+     * options.sessionReplay.networkDetailAllowUrls = [
+     *     "api.example.com",               // String: substring match
+     *     apiRegex!,                       // Regex: versioned API endpoints
+     *     imageRegex!                      // Regex: image files
+     * ]
+     * ```
+     *
+     * - Note: Request and response bodies are truncated to 150KB maximum.
+     * - Note: See ``SentryReplayOptions.DefaultValues.networkDetailAllowUrls`` for the default value.
+     */
+    public var networkDetailAllowUrls: [Any]
+
+    /**
+     * A list of URL patterns to exclude from network detail capture during session replay.
+     * 
+     * URLs matching any pattern in this array will NOT have their headers and bodies captured,
+     * even if they match patterns in `networkDetailAllowUrls`. This provides fine-grained 
+     * control for excluding sensitive endpoints from capture.
+     * 
+     * Supports both String and NSRegularExpression patterns (mirroring JavaScript SDK):
+     * - String: Uses substring containment check (like JavaScript's `includes()`)
+     * - NSRegularExpression: Uses full regex matching
+     * 
+     * Default: empty array (no URLs explicitly denied)
+     *
+     * Examples:
+     * - String patterns: "/auth/", "/payment/", "password", ".internal."
+     * - NSRegularExpression patterns: Use try NSRegularExpression(pattern:) to create regex objects
+     * - Mixed arrays are supported with both types
+     */
+    public var networkDetailDenyUrls: [Any]
+
+    /**
+     * Whether to capture request and response bodies for allowed URLs.
+     *
+     * When `true` (default), bodies will be captured and parsed (JSON bodies are
+     * parsed for structured display in the Sentry UI).
+     *
+     * When `false`, only headers and metadata will be captured for allowed URLs.
+     *
+     * Default: `true`
+     *
+     * - Note: This setting only applies when ``networkDetailAllowUrls`` is non-empty.
+     * - Note: Bodies are automatically truncated to 150KB to prevent excessive memory usage.
+     */
+    public var networkCaptureBodies: Bool
+
+    /**
+     * Request headers to capture for allowed URLs during session replay.
+     * 
+     * Specifies which HTTP request headers should be captured and included in session replay
+     * network details. Header matching is case-insensitive (e.g., "content-type", "Content-Type", 
+     * and "CoNtEnT-tYpE" are all equivalent).
+     * 
+     * Default (always included): `["Content-Type", "Content-Length", "Accept"]`
+     *
+     * Example:
+     * ```
+     * options.sessionReplay.networkRequestHeaders = [
+     *     "Authorization",
+     *     "User-Agent"
+     * ]
+     * ```
+     *
+     * - Note: This setting only applies when ``networkDetailAllowUrls`` is non-empty.
+     * - Note: Header names preserve the case seen on the request, not the case specified here.
+     */
+    public var networkRequestHeaders: [String] {
+        get { _networkRequestHeaders }
+        set { _networkRequestHeaders = Self.mergeWithDefaultHeaders(newValue, defaults: DefaultValues.networkRequestHeaders) }
+    }
+    private var _networkRequestHeaders: [String]
+
+    /**
+     * Response headers to capture for allowed URLs during session replay.
+     * 
+     * Specifies which HTTP response headers should be captured and included in session replay
+     * network details. Header matching is case-insensitive (e.g., "content-type", "Content-Type", 
+     * and "CoNtEnT-tYpE" are all equivalent).
+     * 
+     * Default (always included): `["Content-Type", "Content-Length", "Accept"]`
+     *
+     * Example:
+     * ```
+     * options.sessionReplay.networkResponseHeaders = [
+     *     "Cache-Control",    // Custom header
+     *     "Set-Cookie"        // Custom header
+     * ]
+     * ```
+     *
+     * - Note: This setting only applies when ``networkDetailAllowUrls`` is non-empty.
+     * - Note: Header names preserve the case seen on the response, not the case specified here.
+     */
+    public var networkResponseHeaders: [String] {
+        get { _networkResponseHeaders }
+        set { _networkResponseHeaders = Self.mergeWithDefaultHeaders(newValue, defaults: DefaultValues.networkResponseHeaders) }
+    }
+    private var _networkResponseHeaders: [String]
+
     /**
      * Defines the quality of the session replay.
      *
@@ -351,6 +483,60 @@ public class SentryReplayOptions: NSObject, SentryRedactOptions {
      */
     var sdkInfo: [String: Any]?
 
+    /**
+     * Determines if network detail capture is enabled for a given URL.
+     *
+     * - Parameter urlString: The URL string to check
+     * - Returns: `true` if network details should be captured for this URL, `false` otherwise
+     */
+    @objc
+    public func isNetworkDetailCaptureEnabled(for urlString: String) -> Bool {
+        // If allow list is empty, network detail capture is disabled
+        guard !networkDetailAllowUrls.isEmpty else {
+            return false
+        }
+        
+        if matchesAnyPattern(urlString, patterns: networkDetailDenyUrls) {
+            return false
+        }
+        
+        return matchesAnyPattern(urlString, patterns: networkDetailAllowUrls)
+    }
+    
+    /**
+     * Helper method to check if a URL string matches any pattern in a list.
+     *
+     * Supports both String and NSRegularExpression patterns:
+     * - String: Uses substring containment check (like JavaScript's includes())
+     * - NSRegularExpression: Uses full regex matching
+     *
+     * - Parameters:
+     *   - urlString: The URL string to test
+     *   - patterns: Array of String or NSRegularExpression patterns
+     * - Returns: `true` if the URL matches any pattern, `false` otherwise
+     */
+    private func matchesAnyPattern(_ urlString: String, patterns: [Any]) -> Bool {
+        for pattern in patterns {
+            if let stringPattern = pattern as? String {
+                // String provided: substring match
+                // Filter out empty strings and whitespace-only strings
+                let trimmed = stringPattern.trimmingCharacters(in: .whitespacesAndNewlines)
+                guard !trimmed.isEmpty else { continue }
+                
+                if urlString.contains(stringPattern) {
+                    return true
+                }
+            } else if let regexPattern = pattern as? NSRegularExpression {
+                // NSRegularExpression: use regex matching
+                let range = NSRange(location: 0, length: urlString.utf16.count)
+                if regexPattern.firstMatch(in: urlString, options: [], range: range) != nil {
+                    return true
+                }
+            }
+        }
+        return false
+    }
+    
     /**
      * Initialize session replay options disabled
      *
@@ -374,7 +560,12 @@ public class SentryReplayOptions: NSObject, SentryRedactOptions {
             frameRate: nil,
             errorReplayDuration: nil,
             sessionSegmentDuration: nil,
-            maximumDuration: nil
+            maximumDuration: nil,
+            networkDetailAllowUrls: nil,
+            networkDetailDenyUrls: nil,
+            networkCaptureBodies: nil,
+            networkRequestHeaders: nil,
+            networkResponseHeaders: nil
         )
     }
 
@@ -409,7 +600,12 @@ public class SentryReplayOptions: NSObject, SentryRedactOptions {
             sessionSegmentDuration: (dictionary["sessionSegmentDuration"] as? NSNumber)?.doubleValue,
             maximumDuration: (dictionary["maximumDuration"] as? NSNumber)?.doubleValue,
             excludedViewClasses: (dictionary["excludedViewClasses"] as? [String]).map { Set($0) },
-            includedViewClasses: (dictionary["includedViewClasses"] as? [String]).map { Set($0) }
+            includedViewClasses: (dictionary["includedViewClasses"] as? [String]).map { Set($0) },
+            networkDetailAllowUrls: Self.validateNetworkDetailUrlPatterns(from: dictionary["networkDetailAllowUrls"]),
+            networkDetailDenyUrls: Self.validateNetworkDetailUrlPatterns(from: dictionary["networkDetailDenyUrls"]),
+            networkCaptureBodies: (dictionary["networkCaptureBodies"] as? NSNumber)?.boolValue,
+            networkRequestHeaders: Self.parseStringArray(from: dictionary["networkRequestHeaders"]),
+            networkResponseHeaders: Self.parseStringArray(from: dictionary["networkResponseHeaders"])
         )
     }
 
@@ -456,10 +652,81 @@ public class SentryReplayOptions: NSObject, SentryRedactOptions {
             sessionSegmentDuration: nil,
             maximumDuration: nil,
             excludedViewClasses: nil,
-            includedViewClasses: nil
+            includedViewClasses: nil,
+            networkDetailAllowUrls: nil,
+            networkDetailDenyUrls: nil,
+            networkCaptureBodies: nil,
+            networkRequestHeaders: nil,
+            networkResponseHeaders: nil
         )
     }
 
+    /**
+     * Helper method to parse and filter string arrays from dictionary configuration.
+     * 
+     * Filters out non-string entries from mixed arrays while preserving valid strings.
+     * Returns nil when the input is not an array type, allowing callers to fall back to defaults.
+     * 
+     * - Parameter value: The value from the dictionary to parse
+     * - Returns: Filtered array of strings, or nil if input is not an array
+     */
+    private static func parseStringArray(from value: Any?) -> [String]? {
+        guard let array = value as? [Any] else {
+            return nil
+        }
+        return array.compactMap { $0 as? String }
+    }
+    
+    /**
+     * Validates developer-provided NetworkDetail URL patterns and returns a subset of only valid entries.
+     * 
+     * Accepts both String and NSRegularExpression objects.
+     * Filters out invalid entries and preserves valid patterns.
+     * Filters out empty strings and whitespace-only strings.
+     * 
+     * - Parameter value: The value from the dictionary to parse
+     * - Returns: Filtered array of String and NSRegularExpression patterns, or nil if input is not an array
+     */
+    private static func validateNetworkDetailUrlPatterns(from value: Any?) -> [Any]? {
+        guard let array = value as? [Any] else {
+            if let nonNilValue = value {
+                SentrySDKLog.log(message: "Invalid networkDetail URL pattern configuration: expected array, got \(type(of: nonNilValue))", 
+                               andLevel: .warning)
+            }
+            return nil
+        }
+        
+        var validPatterns: [Any] = []
+        var invalidCount = 0
+        
+        for (index, element) in array.enumerated() {
+            if let stringElement = element as? String {
+                // Filter out empty strings and whitespace-only strings
+                let trimmed = stringElement.trimmingCharacters(in: .whitespacesAndNewlines)
+                if trimmed.isEmpty {
+                    SentrySDKLog.log(message: "Invalid networkDetail URL pattern at index \(index): empty or whitespace-only string discarded", 
+                                   andLevel: .warning)
+                    invalidCount += 1
+                } else {
+                    validPatterns.append(stringElement)
+                }
+            } else if let regexElement = element as? NSRegularExpression {
+                validPatterns.append(regexElement)
+            } else {
+                SentrySDKLog.log(message: "Invalid networkDetail URL pattern at index \(index): expected String or NSRegularExpression, got \(type(of: element))", 
+                               andLevel: .warning)
+                invalidCount += 1
+            }
+        }
+        
+        if invalidCount > 0 {
+            SentrySDKLog.log(message: "NetworkDetail URL patterns: \(invalidCount) invalid entries discarded, \(validPatterns.count) valid patterns retained", 
+                           andLevel: .info)
+        }
+        
+        return validPatterns
+    }
+
     // swiftlint:disable:next function_parameter_count cyclomatic_complexity
     private init(
         sessionSampleRate: Float?,
@@ -477,7 +744,12 @@ public class SentryReplayOptions: NSObject, SentryRedactOptions {
         sessionSegmentDuration: TimeInterval?,
         maximumDuration: TimeInterval?,
         excludedViewClasses: Set<String>? = nil,
-        includedViewClasses: Set<String>? = nil
+        includedViewClasses: Set<String>? = nil,
+        networkDetailAllowUrls: [Any]? = nil,
+        networkDetailDenyUrls: [Any]? = nil,
+        networkCaptureBodies: Bool? = nil,
+        networkRequestHeaders: [String]? = nil,
+        networkResponseHeaders: [String]? = nil
     ) {
         self.sessionSampleRate = sessionSampleRate ?? DefaultValues.sessionSampleRate
         self.onErrorSampleRate = onErrorSampleRate ?? DefaultValues.onErrorSampleRate
@@ -495,8 +767,49 @@ public class SentryReplayOptions: NSObject, SentryRedactOptions {
         self.maximumDuration = maximumDuration ?? DefaultValues.maximumDuration
         self.excludedViewClasses = excludedViewClasses ?? DefaultValues.excludedViewClasses
         self.includedViewClasses = includedViewClasses ?? DefaultValues.includedViewClasses
+        self.networkDetailAllowUrls = Self.validateNetworkDetailUrlPatterns(from: networkDetailAllowUrls) ?? DefaultValues.networkDetailAllowUrls
+        self.networkDetailDenyUrls = Self.validateNetworkDetailUrlPatterns(from: networkDetailDenyUrls) ?? DefaultValues.networkDetailDenyUrls
+        self.networkCaptureBodies = networkCaptureBodies ?? DefaultValues.networkCaptureBodies
+        self._networkRequestHeaders = Self.mergeWithDefaultHeaders(networkRequestHeaders, defaults: DefaultValues.networkRequestHeaders)
+        self._networkResponseHeaders = Self.mergeWithDefaultHeaders(networkResponseHeaders, defaults: DefaultValues.networkResponseHeaders)
 
         super.init()
     }
+    
+    /**
+     * Merges user-provided headers with default headers, ensuring defaults are always included.
+     *
+     * - Parameter userHeaders: Headers specified by the user (can be nil)
+     * - Parameter defaults: Default headers that must always be included
+     * - Returns: Array containing both user headers and default headers (with duplicates removed)
+     */
+    private static func mergeWithDefaultHeaders(_ userHeaders: [String]?, defaults: [String]) -> [String] {
+        let providedHeaders = userHeaders ?? []
+        
+        // Use Set to remove duplicates, then convert back to Array
+        // Case-insensitive comparison to avoid duplicate headers with different casing
+        var seenHeaders = Set<String>()
+        var result: [String] = []
+        
+        // Add default headers first
+        for header in defaults {
+            let lowercased = header.lowercased()
+            if !seenHeaders.contains(lowercased) {
+                seenHeaders.insert(lowercased)
+                result.append(header)
+            }
+        }
+        
+        // Add user-provided headers
+        for header in providedHeaders {
+            let lowercased = header.lowercased()
+            if !seenHeaders.contains(lowercased) {
+                seenHeaders.insert(lowercased)
+                result.append(header)
+            }
+        }
+        
+        return result
+    }
 }
-// swiftlint:enable file_length missing_docs
+// swiftlint:enable file_length missing_docs type_body_length