Cline rules

1# Feature Gating with MSIDFlightManager
2 
3## Overview
4 
5This document provides guidance for AI agents on implementing feature flags in the Microsoft Authentication Library (MSAL) for iOS and macOS using `MSIDFlightManager`. Feature flags enable controlled rollout of new features and A/B testing capabilities.
6 
7## Important Limitations
8 
9⚠️ **CRITICAL: Microsoft Internal Use Only**
10 
11The `MSIDFlightManager` feature flag system is **ONLY available in broker context** or when the broker returns flight configurations as part of its response. This is a Microsoft-internal mechanism and is **NOT accessible to third-party developers**.
12 
13### Broker Context Requirement
14 
15- Feature flags are **only available** when:
16  1. The application is running inside the Microsoft Authenticator or Company Portal broker
17  2. The broker explicitly returns flight configurations in its authentication response
18  
19- **Third-party developers must NOT rely on this system** for their applications
20- Third-party developers should implement their own feature flag provider if needed
21 
22### Third-Party Developer Guidance
23 
24If you are a third-party developer:
25 
26- ✅ Implement your own feature flag system using:
27  - Remote configuration services (for example: Azure App Configuration)
28  - Custom backend configuration endpoints
29  - Local configuration files with remote updates
30 
31## MSIDFlightManager Architecture
32 
33### Location
34 
35`MSIDFlightManager` is part of the **IdentityCore** common library:
36 
37```
38MSAL/IdentityCore/IdentityCore/src/MSIDFlightManager.h
39MSAL/IdentityCore/IdentityCore/src/MSIDFlightManager.m
40```
41 
42### Key Characteristics
43 
44- **Singleton pattern**: Accessed via `[MSIDFlightManager sharedInstance]`
45- **Thread-safe**: Uses `dispatch_once` for initialization
46- **Broker-dependent**: Only populated with data from broker responses
47- **Read-only for MSAL**: MSAL code reads flags, broker sets them
48 
49## When to Use Feature Flags
50 
51Feature flags should be used for:
52 
531. **New Features**: Gradual rollout of new functionality
542. **Breaking Changes**: Safe migration paths with fallback behavior
553. **A/B Testing**: Testing different implementation approaches
564. **Risk Mitigation**: Ability to quickly disable problematic features
575. **Platform-Specific Behavior**: Different behavior for iOS vs macOS vs visionOS
58 
59Feature flags should **NOT** be used for:
60 
61- Permanent configuration options (use config classes instead)
62- User-facing preferences (use proper settings)
63- Build-time configurations (use compiler flags)
64- Debug-only features (use `#if DEBUG`)
65 
66## Implementation Pattern
67 
68### Step 1: Define the Feature Flag Key
69 
70Feature flag keys should follow naming conventions:
71 
72```objc
73// In MSIDFlightManager.h or appropriate header
74static NSString * const MSIDFlightKeyNewAuthFlow = @"new_auth_flow";
75static NSString * const MSIDFlightKeyEnhancedTokenCache = @"enhanced_token_cache";
76static NSString * const MSIDFlightKeyNativeAuthV2 = @"native_auth_v2";
77```
78 
79**Naming Convention:**
80 
81- Use snake_case for flag keys
82- Prefix with feature area if applicable
83- Keep names descriptive but concise
84- Document in code comments
85 
86### Step 2: Check Feature Flag in Code
87 
88Always provide a default fallback behavior when feature flag is not available:
89 
90```objc
91// Example: Checking if new feature is enabled
92BOOL isNewAuthFlowEnabled = [[MSIDFlightManager sharedInstance] 
93                             isFlightEnabled:MSIDFlightKeyNewAuthFlow];
94 
95if (isNewAuthFlowEnabled)
96{
97    // New implementation
98    [self performNewAuthenticationFlow];
99}
100else
101{
102    // Existing/fallback implementation
103    [self performLegacyAuthenticationFlow];
104}
105```
106 
107### Step 3: Handle Missing/Default State
108 
109**CRITICAL**: Always assume feature flags may be unavailable (nil or NO):
110 
111```objc
112- (void)performOperationWithContext:(id<MSIDRequestContext>)context
113{
114    // Default to NO/false if flag is not set by broker
115    BOOL useEnhancedCache = [[MSIDFlightManager sharedInstance] 
116                             isFlightEnabled:MSIDFlightKeyEnhancedTokenCache];
117    
118    if (useEnhancedCache)
119    {
120        MSID_LOG_WITH_CTX(MSIDLogLevelInfo, context, 
121                          @"Using enhanced token cache (feature flag enabled)");
122        [self useEnhancedTokenCache];
123    }
124    else
125    {
126        MSID_LOG_WITH_CTX(MSIDLogLevelInfo, context, 
127                          @"Using standard token cache (feature flag disabled or unavailable)");
128        [self useStandardTokenCache];
129    }
130}
131```
132 
133### Step 4: Add Logging
134 
135Always log feature flag decisions for debugging:
136 
137```objc
138BOOL isFeatureEnabled = [[MSIDFlightManager sharedInstance] 
139                         isFlightEnabled:MSIDFlightKeyNewFeature];
140 
141MSID_LOG_WITH_CTX_PII(MSIDLogLevelInfo, context, 
142                      @"Feature 'new_feature' is %@", 
143                      isFeatureEnabled ? @"ENABLED" : @"DISABLED");
144```
145 
146## Common Patterns
147 
148### Pattern 1: Simple On/Off Toggle
149 
150```objc
151- (void)processAuthenticationWithParameters:(MSALTokenParameters *)parameters
152                                      error:(NSError **)error
153{
154    BOOL useNewFlow = [[MSIDFlightManager sharedInstance] 
155                       isFlightEnabled:@"new_auth_flow"];
156    
157    if (useNewFlow)
158    {
159        return [self processAuthenticationNewFlow:parameters error:error];
160    }
161    else
162    {
163        return [self processAuthenticationLegacyFlow:parameters error:error];
164    }
165}
166```
167 
168### Pattern 2: Platform-Specific Feature Flags
169 
170```objc
171- (void)configureWebView:(WKWebView *)webView
172{
173    #if TARGET_OS_IOS
174    BOOL useEnhancedWebView = [[MSIDFlightManager sharedInstance] 
175                               isFlightEnabled:@"enhanced_webview_ios"];
176    #elif TARGET_OS_OSX
177    BOOL useEnhancedWebView = [[MSIDFlightManager sharedInstance] 
178                               isFlightEnabled:@"enhanced_webview_macos"];
179    #else
180    BOOL useEnhancedWebView = NO;
181    #endif
182    
183    if (useEnhancedWebView)
184    {
185        [self configureEnhancedWebView:webView];
186    }
187    else
188    {
189        [self configureStandardWebView:webView];
190    }
191}
192```
193 
194### Pattern 3: Multiple Flag Combinations
195 
196```objc
197- (void)performAdvancedOperation
198{
199    BOOL featureA = [[MSIDFlightManager sharedInstance] isFlightEnabled:@"feature_a"];
200    BOOL featureB = [[MSIDFlightManager sharedInstance] isFlightEnabled:@"feature_b"];
201    
202    if (featureA && featureB)
203    {
204        // Both features enabled
205        [self performOperationWithBothFeatures];
206    }
207    else if (featureA)
208    {
209        // Only feature A enabled
210        [self performOperationWithFeatureA];
211    }
212    else if (featureB)
213    {
214        // Only feature B enabled
215        [self performOperationWithFeatureB];
216    }
217    else
218    {
219        // Neither feature enabled - use baseline
220        [self performBaselineOperation];
221    }
222}
223```
224 
225## Best Practices
226 
227### 1. Always Provide Fallback
228 
229```objc
230// ✅ GOOD: Has clear fallback
231BOOL useNewFeature = [[MSIDFlightManager sharedInstance] 
232                      isFlightEnabled:@"new_feature"];
233if (useNewFeature)
234{
235    [self useNewImplementation];
236}
237else
238{
239    [self useStableImplementation];  // Clear fallback
240}
241 
242// ❌ BAD: Assumes flag will always be available
243if ([[MSIDFlightManager sharedInstance] isFlightEnabled:@"new_feature"])
244{
245    [self useNewImplementation];
246}
247// What happens if flag is NO or unavailable?
248```
249 
250### 2. Document Flag Dependencies
251 
252```objc
253/**
254 Performs token acquisition with optional enhanced caching.
255 
256 @param parameters Token acquisition parameters
257 @param error Error if operation fails
258 
259 @return MSALResult on success, nil on failure
260 
261 @note This method uses the 'enhanced_token_cache' feature flag when
262       available in broker context. Falls back to standard caching
263       when flag is disabled or unavailable.
264 */
265- (MSALResult *)acquireTokenWithParameters:(MSALTokenParameters *)parameters
266                                     error:(NSError **)error;
267```
268 
269### 3. Log Feature Flag State
270 
271```objc
272- (void)performOperation
273{
274    BOOL featureEnabled = [[MSIDFlightManager sharedInstance] 
275                           isFlightEnabled:@"my_feature"];
276    
277    MSID_LOG_WITH_CTX(MSIDLogLevelInfo, nil, 
278                      @"Feature 'my_feature' state: %@", 
279                      featureEnabled ? @"ENABLED" : @"DISABLED");
280    
281    // ... rest of implementation
282}
283```
284 
285### 4. Plan for Removal
286 
287Feature flags should be temporary. Document removal plan:
288 
289```objc
290/**
291 TODO: Remove feature flag check after Q2 2025 rollout
292 
293 Feature flag: 'new_auth_flow'
294 Rollout started: 2024-Q4
295 Expected completion: 2025-Q2
296 Tracking: https://example.com/feature/new-auth-flow
297 
298 Once rollout is complete, remove the flag check and keep only
299 the new implementation.
300 */
301BOOL useNewAuthFlow = [[MSIDFlightManager sharedInstance] 
302                       isFlightEnabled:@"new_auth_flow"];
303```
304 
305### 5. Avoid Deep Nesting
306 
307```objc
308// ❌ BAD: Too many nested feature flags
309if ([[MSIDFlightManager sharedInstance] isFlightEnabled:@"feature_a"])
310{
311    if ([[MSIDFlightManager sharedInstance] isFlightEnabled:@"feature_b"])
312    {
313        if ([[MSIDFlightManager sharedInstance] isFlightEnabled:@"feature_c"])
314        {
315            // Complex logic here
316        }
317    }
318}
319 
320// ✅ GOOD: Extract to separate method with clear logic
321BOOL featureA = [[MSIDFlightManager sharedInstance] isFlightEnabled:@"feature_a"];
322BOOL featureB = [[MSIDFlightManager sharedInstance] isFlightEnabled:@"feature_b"];
323BOOL featureC = [[MSIDFlightManager sharedInstance] isFlightEnabled:@"feature_c"];
324 
325[self performOperationWithFeatureA:featureA 
326                          featureB:featureB 
327                          featureC:featureC];
328```
329 
330### 6. Consider Performance
331 
332```objc
333// ✅ GOOD: Cache flag value if checked multiple times
334- (void)performMultipleOperations
335{
336    // Check once and cache
337    BOOL useOptimization = [[MSIDFlightManager sharedInstance] 
338                            isFlightEnabled:@"optimization"];
339    
340    [self operation1WithOptimization:useOptimization];
341    [self operation2WithOptimization:useOptimization];
342    [self operation3WithOptimization:useOptimization];
343}
344 
345// ❌ LESS EFFICIENT: Checking same flag multiple times
346- (void)performMultipleOperations
347{
348    [self operation1WithOptimization:[[MSIDFlightManager sharedInstance] 
349                                      isFlightEnabled:@"optimization"]];
350    [self operation2WithOptimization:[[MSIDFlightManager sharedInstance] 
351                                      isFlightEnabled:@"optimization"]];
352    [self operation3WithOptimization:[[MSIDFlightManager sharedInstance] 
353                                      isFlightEnabled:@"optimization"]];
354}
355```
356 
357## Error Handling with Feature Flags
358 
359```objc
360- (BOOL)performOperationWithError:(NSError **)error
361{
362    BOOL useNewImplementation = [[MSIDFlightManager sharedInstance] 
363                                 isFlightEnabled:@"new_implementation"];
364    
365    if (useNewImplementation)
366    {
367        NSError *internalError = nil;
368        BOOL result = [self performNewImplementationWithError:&internalError];
369        
370        if (!result)
371        {
372            MSID_LOG_WITH_CTX(MSIDLogLevelError, nil, 
373                              @"New implementation failed, falling back: %@", 
374                              internalError);
375            
376            // Optional: Fall back to old implementation on failure
377            result = [self performLegacyImplementationWithError:&internalError];
378        }
379        
380        if (!result && error)
381        {
382            *error = internalError;
383        }
384        
385        return result;
386    }
387    else
388    {
389        return [self performLegacyImplementationWithError:error];
390    }
391}
392```
393 
394## Example: Adding a New Feature with Flag
395 
396Here's a complete example of adding a new feature behind a feature flag:
397 
398```objc
399// 1. Define the flag key constant
400static NSString * const MSIDFlightKeyEnhancedErrorReporting = @"enhanced_error_reporting";
401 
402// 2. Implement the feature-flagged method
403- (void)reportError:(NSError *)error 
404        withContext:(id<MSIDRequestContext>)context
405{
406    // Check feature flag
407    BOOL useEnhancedReporting = [[MSIDFlightManager sharedInstance] 
408                                 isFlightEnabled:MSIDFlightKeyEnhancedErrorReporting];
409    
410    // Log the decision
411    MSID_LOG_WITH_CTX(MSIDLogLevelInfo, context, 
412                      @"Enhanced error reporting: %@", 
413                      useEnhancedReporting ? @"ENABLED" : @"DISABLED");
414    
415    if (useEnhancedReporting)
416    {
417        // New enhanced reporting
418        [self reportErrorEnhanced:error withContext:context];
419    }
420    else
421    {
422        // Existing stable reporting
423        [self reportErrorLegacy:error withContext:context];
424    }
425}
426 
427// 3. Implement both code paths
428- (void)reportErrorEnhanced:(NSError *)error 
429                withContext:(id<MSIDRequestContext>)context
430{
431    // New implementation with additional telemetry, diagnostics, etc.
432    MSID_LOG_WITH_CTX(MSIDLogLevelError, context, 
433                      @"Enhanced error report: %@ (domain: %@, code: %ld)", 
434                      error.localizedDescription, 
435                      error.domain, 
436                      (long)error.code);
437    
438    // Additional enhanced reporting logic
439    [self collectDiagnostics:error];
440    [self sendTelemetryForError:error];
441}
442 
443- (void)reportErrorLegacy:(NSError *)error 
444              withContext:(id<MSIDRequestContext>)context
445{
446    // Existing stable implementation
447    MSID_LOG_WITH_CTX(MSIDLogLevelError, context, 
448                      @"Error: %@", error.localizedDescription);
449}
450```
451 
452## Checklist for Adding Feature Flags
453 
454When implementing a new feature behind a feature flag:
455 
456- [ ] Define clear, descriptive flag key constant
457- [ ] Implement both new and fallback code paths
458- [ ] Add logging for feature flag state
459- [ ] Handle nil/NO case gracefully (default to stable behavior)
460- [ ] Write unit tests for both enabled and disabled states
461- [ ] Document the feature flag in code comments
462- [ ] Add telemetry/metrics if appropriate
463- [ ] Plan for eventual flag removal (add TODO with timeline)
464- [ ] Verify behavior when broker context is unavailable
465- [ ] Test in real broker context (Microsoft Authenticator/Company Portal)
466 
467## Summary
468 
469**Key Takeaways for AI Agents:**
470 
4711. ✅ **Use feature flags for gradual rollout** of new features
4722. ✅ **Always provide stable fallback** behavior
4733. ✅ **Remember: Only works in broker context** - not for third-party apps
4744. ✅ **Log feature flag decisions** for debugging
4755. ✅ **Test both enabled and disabled states**
4766. ✅ **Plan for eventual removal** of feature flags
4777. ✅ **Document flag dependencies** in code comments
4788. ❌ **Don't use for permanent configuration**
4799. ❌ **Don't assume flags will always be available**
48010. ❌ **Don't leave flags in code indefinitely**
481 
482## Related Documentation
483 
484- `.clinerules/04-Code-style-guidelines.md` - Code style requirements
485- `MSAL/IdentityCore/IdentityCore/src/MSIDFlightManager.h` - Flight manager API
486- Microsoft internal documentation for broker flight configuration
487 
488## Questions?
489 
490For questions about feature flag implementation:
491 
492- **Microsoft employees**: Contact MSAL iOS team or check internal documentation
493- **Third-party developers**: Implement your own feature flag system 
494