Disable client when project token is missing

Author: marandaneto

src/PostHog/Config/PostHogOptions.cs

@@ -1,4 +1,5 @@
 using Microsoft.Extensions.Options;
+using PostHog.Library;
 
 namespace PostHog;
 
@@ -26,6 +27,15 @@ public string? ProjectToken
 
     internal bool HasLegacyProjectApiKey => _projectApiKey is not null;
 
+    internal void Normalize()
+    {
+        _projectToken = _projectToken.NullIfEmpty();
+        _projectApiKey = _projectApiKey.NullIfEmpty();
+        PersonalApiKey = PersonalApiKey.NullIfEmpty();
+        HostUrl = HostUrl.NormalizeHostUrl();
+        Disabled = Disabled || ProjectToken is null;
+    }
+
     /// <summary>
     /// Obsolete alias for <see cref="ProjectToken"/>.
     /// </summary>
@@ -49,6 +59,11 @@ public string? ProjectApiKey
     /// </remarks>
     public string? PersonalApiKey { get; set; }
 
+    /// <summary>
+    /// Whether this client is disabled and should no-op instead of sending data to PostHog. (Default: false)
+    /// </summary>
+    public bool Disabled { get; set; }
+
     /// <summary>
     /// PostHog API host, usually 'https://us.i.posthog.com' (default) or 'https://eu.i.posthog.com'
     /// </summary>

src/PostHog/PostHogClient.cs

@@ -95,16 +95,42 @@ static void NormalizeOptions(PostHogOptions options, ILogger<PostHogClient> logg
             logger.LogWarningProjectApiKeyDeprecated();
         }
 
-        options.ProjectToken = options.ProjectToken?.Trim();
-        options.PersonalApiKey = options.PersonalApiKey.NullIfEmpty();
-        options.HostUrl = options.HostUrl.NormalizeHostUrl();
+        options.Normalize();
 
-        if (string.IsNullOrEmpty(options.ProjectToken))
+        if (options.ProjectToken is null)
         {
             logger.LogErrorProjectTokenRequired();
         }
     }
 
+    bool IsDisabled(string methodName)
+    {
+        if (!_options.Value.Disabled)
+        {
+            return false;
+        }
+
+        _logger.LogWarningClientDisabled(methodName);
+        return true;
+    }
+
+    // A personal_api_key is only required for feature flag calls when callers explicitly request
+    // local-only evaluation. Without it we cannot download local flag definitions, and the
+    // local-only option means we must not fall back to remote /flags evaluation.
+    bool RequiresMissingPersonalApiKey(AllFeatureFlagsOptions? options, string methodName)
+        => options is { OnlyEvaluateLocally: true } && IsPersonalApiKeyMissing(methodName);
+
+    bool IsPersonalApiKeyMissing(string methodName)
+    {
+        if (_options.Value.PersonalApiKey is not null)
+        {
+            return false;
+        }
+
+        _logger.LogWarningPersonalApiKeyMissing(methodName);
+        return true;
+    }
+
     /// <summary>
     /// To marry up whatever a user does before they sign up or log in with what they do after you need to make an
     /// alias call. This will allow you to answer questions like "Which marketing channels leads to users churning
@@ -122,27 +148,48 @@ public async Task<ApiResult> AliasAsync(
         string previousId,
         string newId,
         CancellationToken cancellationToken)
-        => await _apiClient.AliasAsync(previousId, newId, cancellationToken);
+    {
+        if (IsDisabled(nameof(AliasAsync)))
+        {
+            return new ApiResult(0);
+        }
+
+        return await _apiClient.AliasAsync(previousId, newId, cancellationToken);
+    }
 
     /// <inheritdoc/>
     public async Task<ApiResult> IdentifyAsync(
         string distinctId,
         Dictionary<string, object>? personPropertiesToSet,
         Dictionary<string, object>? personPropertiesToSetOnce,
         CancellationToken cancellationToken)
-        => await _apiClient.IdentifyAsync(
+    {
+        if (IsDisabled(nameof(IdentifyAsync)))
+        {
+            return new ApiResult(0);
+        }
+
+        return await _apiClient.IdentifyAsync(
             distinctId,
             personPropertiesToSet,
             personPropertiesToSetOnce,
             cancellationToken);
+    }
 
     /// <inheritdoc/>
     public Task<ApiResult> GroupIdentifyAsync(
         string type,
         StringOrValue<int> key,
         Dictionary<string, object>? properties,
         CancellationToken cancellationToken)
-    => _apiClient.GroupIdentifyAsync(type, key, properties, cancellationToken);
+    {
+        if (IsDisabled(nameof(GroupIdentifyAsync)))
+        {
+            return Task.FromResult(new ApiResult(0));
+        }
+
+        return _apiClient.GroupIdentifyAsync(type, key, properties, cancellationToken);
+    }
 
     /// <inheritdoc/>
     public Task<ApiResult> GroupIdentifyAsync(
@@ -151,7 +198,14 @@ public Task<ApiResult> GroupIdentifyAsync(
         StringOrValue<int> key,
         Dictionary<string, object>? properties,
         CancellationToken cancellationToken)
-    => _apiClient.GroupIdentifyAsync(type, key, properties, cancellationToken, distinctId);
+    {
+        if (IsDisabled(nameof(GroupIdentifyAsync)))
+        {
+            return Task.FromResult(new ApiResult(0));
+        }
+
+        return _apiClient.GroupIdentifyAsync(type, key, properties, cancellationToken, distinctId);
+    }
 
     /// <inheritdoc/>
     public bool Capture(
@@ -162,6 +216,11 @@ public bool Capture(
         bool sendFeatureFlags,
         DateTimeOffset? timestamp = null)
     {
+        if (IsDisabled(nameof(Capture)))
+        {
+            return false;
+        }
+
         // If custom timestamp provided, add it to properties
         if (timestamp.HasValue)
         {
@@ -218,6 +277,11 @@ public bool CaptureException(
         bool sendFeatureFlags,
         DateTimeOffset? timestamp = null)
     {
+        if (IsDisabled(nameof(CaptureException)))
+        {
+            return false;
+        }
+
         if (exception == null)
         {
             _logger.LogErrorCaptureExceptionNull();
@@ -305,6 +369,16 @@ public async Task<bool> IsFeatureEnabledAsync(
         FeatureFlagOptions? options,
         CancellationToken cancellationToken)
     {
+        if (IsDisabled(nameof(IsFeatureEnabledAsync)))
+        {
+            return false;
+        }
+
+        if (RequiresMissingPersonalApiKey(options, nameof(IsFeatureEnabledAsync)))
+        {
+            return false;
+        }
+
         var result = await GetFeatureFlagAsync(
             featureKey,
             distinctId,
@@ -321,6 +395,16 @@ public async Task<bool> IsFeatureEnabledAsync(
         FeatureFlagOptions? options,
         CancellationToken cancellationToken)
     {
+        if (IsDisabled(nameof(GetFeatureFlagAsync)))
+        {
+            return null;
+        }
+
+        if (RequiresMissingPersonalApiKey(options, nameof(GetFeatureFlagAsync)))
+        {
+            return null;
+        }
+
         LocalEvaluator? localEvaluator;
         try
         {
@@ -461,9 +545,13 @@ void HandleRemoteError(Exception ex, string errorType)
     /// <inheritdoc/>
     public async Task<JsonDocument?> GetRemoteConfigPayloadAsync(string key, CancellationToken cancellationToken)
     {
-        if (_options.Value.PersonalApiKey is null)
+        if (IsDisabled(nameof(GetRemoteConfigPayloadAsync)))
+        {
+            return null;
+        }
+
+        if (IsPersonalApiKeyMissing(nameof(GetRemoteConfigPayloadAsync)))
         {
-            _logger.LogWarningPersonalApiKeyRequiredForRemoteConfigPayload();
             return null;
         }
 
@@ -565,6 +653,16 @@ public async Task<IReadOnlyDictionary<string, FeatureFlag>> GetAllFeatureFlagsAs
         AllFeatureFlagsOptions? options,
         CancellationToken cancellationToken)
     {
+        if (IsDisabled(nameof(GetAllFeatureFlagsAsync)))
+        {
+            return new Dictionary<string, FeatureFlag>();
+        }
+
+        if (RequiresMissingPersonalApiKey(options, nameof(GetAllFeatureFlagsAsync)))
+        {
+            return new Dictionary<string, FeatureFlag>();
+        }
+
         if (_options.Value.PersonalApiKey is not null)
         {
             // Attempt to load local feature flags.
@@ -650,9 +748,13 @@ public async Task LoadFeatureFlagsAsync(CancellationToken cancellationToken)
     {
         _logger.LogInfoLoadFeatureFlags();
 
-        if (_options.Value.PersonalApiKey is null)
+        if (IsDisabled(nameof(LoadFeatureFlagsAsync)))
+        {
+            return;
+        }
+
+        if (IsPersonalApiKeyMissing(nameof(LoadFeatureFlagsAsync)))
         {
-            _logger.LogWarningPersonalApiKeyRequired();
             return;
         }
 
@@ -678,7 +780,15 @@ public async Task LoadFeatureFlagsAsync(CancellationToken cancellationToken)
     }
 
     /// <inheritdoc/>
-    public async Task FlushAsync() => await _asyncBatchHandler.FlushAsync();
+    public async Task FlushAsync()
+    {
+        if (IsDisabled(nameof(FlushAsync)))
+        {
+            return;
+        }
+
+        await _asyncBatchHandler.FlushAsync();
+    }
 
     /// <inheritdoc/>
     public string Version => VersionConstants.Version;
@@ -688,6 +798,11 @@ public async Task LoadFeatureFlagsAsync(CancellationToken cancellationToken)
     [Obsolete("This method is for internal use only and may go away soon.")]
     internal async Task<LocalEvaluator?> GetLocalEvaluatorAsync(CancellationToken cancellationToken)
     {
+        if (IsDisabled(nameof(GetLocalEvaluatorAsync)))
+        {
+            return null;
+        }
+
         try
         {
             return await _featureFlagsLoader.GetFeatureFlagsForLocalEvaluationAsync(cancellationToken);
@@ -705,7 +820,15 @@ public async Task LoadFeatureFlagsAsync(CancellationToken cancellationToken)
     /// <summary>
     /// Clears the local flags cache.
     /// </summary>
-    public void ClearLocalFlagsCache() => _featureFlagsLoader.Clear();
+    public void ClearLocalFlagsCache()
+    {
+        if (IsDisabled(nameof(ClearLocalFlagsCache)))
+        {
+            return;
+        }
+
+        _featureFlagsLoader.Clear();
+    }
 
     /// <inheritdoc/>
     public async ValueTask DisposeAsync()
@@ -796,12 +919,6 @@ public static partial void LogWarnCaptureFailed(
         int propertiesCount,
         int count);
 
-    [LoggerMessage(
-        EventId = 9,
-        Level = LogLevel.Warning,
-        Message = "[FEATURE FLAGS] You have to specify a personal_api_key to fetch remote config payloads.")]
-    public static partial void LogWarningPersonalApiKeyRequiredForRemoteConfigPayload(this ILogger<PostHogClient> logger);
-
     [LoggerMessage(
         EventId = 10,
         Level = LogLevel.Error,
@@ -846,12 +963,6 @@ public static partial void LogErrorUnableToGetRemoteConfigPayload(
         Message = "[FEATURE FLAGS] Loading feature flags for local evaluation")]
     public static partial void LogInfoLoadFeatureFlags(this ILogger<PostHogClient> logger);
 
-    [LoggerMessage(
-        EventId = 17,
-        Level = LogLevel.Warning,
-        Message = "[FEATURE FLAGS] You have to specify a personal_api_key to use feature flags.")]
-    public static partial void LogWarningPersonalApiKeyRequired(this ILogger<PostHogClient> logger);
-
     [LoggerMessage(
         EventId = 18,
         Level = LogLevel.Debug,
@@ -875,4 +986,16 @@ public static partial void LogErrorUnableToGetRemoteConfigPayload(
         Level = LogLevel.Error,
         Message = "CaptureException failed with an exception")]
     public static partial void LogErrorCaptureExceptionFailed(this ILogger<PostHogClient> logger, Exception exception);
+
+    [LoggerMessage(
+        EventId = 21,
+        Level = LogLevel.Warning,
+        Message = "PostHog SDK is disabled; {MethodName} is a no-op.")]
+    public static partial void LogWarningClientDisabled(this ILogger<PostHogClient> logger, string methodName);
+
+    [LoggerMessage(
+        EventId = 22,
+        Level = LogLevel.Warning,
+        Message = "PostHog personal_api_key is not configured; {MethodName} is a no-op.")]
+    public static partial void LogWarningPersonalApiKeyMissing(this ILogger<PostHogClient> logger, string methodName);
 }