tweak

Author: heatlikeheatwave

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -69,6 +69,12 @@ export async function ClerkProvider(
 
   let output: ReactNode;
 
+  const detectKeylessEnvDrift = await import('../../server/keyless-telemetry.js').then(
+    mod => mod.detectKeylessEnvDrift,
+  );
+
+  await detectKeylessEnvDrift();
+
   if (shouldRunAsKeyless) {
     output = (
       <KeylessProvider

packages/nextjs/src/app-router/server/keyless-provider.tsx

@@ -47,6 +47,14 @@ export const KeylessProvider = async (props: KeylessProviderProps) => {
     .then(mod => mod.createOrReadKeyless())
     .catch(() => null);
 
+  const detectKeylessEnvDrift = await import('../../server/keyless-telemetry.js').then(
+    mod => mod.detectKeylessEnvDrift,
+  );
+
+  if (newOrReadKeys) {
+    await detectKeylessEnvDrift();
+  }
+
   const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
     '../../server/keyless-log-cache.js'
   );

packages/nextjs/src/server/keyless-telemetry.ts

@@ -6,7 +6,7 @@ import { createClerkClientWithOptions } from './createClerkClient';
 
 const EVENT_KEYLESS_ENV_DRIFT_DETECTED = 'KEYLESS_ENV_DRIFT_DETECTED';
 const EVENT_SAMPLING_RATE = 1; // 100% sampling rate
-const TELEMETRY_FLAG_FILE = '.clerk/.tmp/keyless-telemetry-fired.json';
+const TELEMETRY_FLAG_FILE = '.clerk/.tmp/telemetry.json';
 
 type EventKeylessEnvDriftPayload = {
   publicKeyMatch: boolean;
@@ -19,56 +19,60 @@ type EventKeylessEnvDriftPayload = {
 
 /**
  * Gets the absolute path to the telemetry flag file.
+ *
+ * This file is used to track whether telemetry events have already been fired
+ * to prevent duplicate event reporting during the application lifecycle.
+ *
+ * @returns The absolute path to the telemetry flag file in the project's .clerk/.tmp directory
  */
 function getTelemetryFlagFilePath(): string {
   return join(process.cwd(), TELEMETRY_FLAG_FILE);
 }
 
 /**
- * Checks if the telemetry event has already been fired by looking for a flag file.
- */
-async function hasTelemetryEventBeenFired(): Promise<boolean> {
-  try {
-    await fs.access(getTelemetryFlagFilePath());
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Creates a flag file to mark that the telemetry event has been fired.
+ * Attempts to create a telemetry flag file to mark that a telemetry event has been fired.
+ *
+ * This function uses the 'wx' flag to create the file atomically - it will only succeed
+ * if the file doesn't already exist. This ensures that telemetry events are only fired
+ * once per application lifecycle, preventing duplicate event reporting.
+ *
+ * @returns Promise<boolean> - Returns true if the flag file was successfully created (meaning
+ *   the event should be fired), false if the file already exists (meaning the event was
+ *   already fired) or if there was an error creating the file
  */
-async function markTelemetryEventAsFired(): Promise<void> {
+async function tryMarkTelemetryEventAsFired(): Promise<boolean> {
   try {
-    // Ensure the directory exists
-    const dir = join(process.cwd(), '.clerk/.tmp');
-    await fs.mkdir(dir, { recursive: true });
-
-    // Create the flag file with timestamp
     const flagData = {
       firedAt: new Date().toISOString(),
       event: EVENT_KEYLESS_ENV_DRIFT_DETECTED,
     };
-
-    await fs.writeFile(getTelemetryFlagFilePath(), JSON.stringify(flagData, null, 2));
-  } catch (error) {
-    // Silently handle errors to avoid breaking the application
+    await fs.writeFile(getTelemetryFlagFilePath(), JSON.stringify(flagData, null, 2), { flag: 'wx' });
+    return true;
+  } catch (error: unknown) {
+    if ((error as { code?: string })?.code === 'EEXIST') {
+      return false;
+    }
     console.warn('Failed to create telemetry flag file:', error);
+    return false;
   }
 }
 
 /**
- * Detects environment variable drift for keyless Next.js applications and fires telemetry events.
+ * Detects and reports environment drift between keyless configuration and environment variables.
  *
- * This function compares the publishableKey and secretKey values from `.clerk/.tmp/keyless.json`
- * with the `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` environment variables.
+ * This function compares the Clerk keys stored in the keyless configuration file (.clerk/clerk.json)
+ * with the keys set in environment variables (NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY).
+ * If there's a mismatch (drift), it reports this as a telemetry event to help diagnose configuration issues.
  *
- * If there's a mismatch, it fires a `KEYLESS_ENV_DRIFT_DETECTED` event.
- * For local testing purposes, it also fires a `KEYLESS_ENV_DRIFT_NOT_DETECTED` event when
- * keys exist and match the environment variables.
+ * The function handles several scenarios:
+ * - Normal keyless mode: env vars missing but keyless file has keys (no drift)
+ * - Drift detected: env vars and keyless file have different keys
+ * - Mixed configuration: some keys match, others don't
  *
- * The telemetry event will only fire once per application instance to avoid noise.
+ * Telemetry events are only fired once per application lifecycle using a flag file mechanism
+ * to prevent duplicate reporting.
+ *
+ * @returns Promise<void> - Function completes silently, errors are logged but don't throw
  */
 export async function detectKeylessEnvDrift(): Promise<void> {
   // Only run on server side
@@ -77,11 +81,6 @@ export async function detectKeylessEnvDrift(): Promise<void> {
   }
 
   try {
-    // Check if telemetry event has already been fired
-    if (await hasTelemetryEventBeenFired()) {
-      return;
-    }
-
     // Dynamically import server-side dependencies to avoid client-side issues
     const { safeParseClerkFile } = await import('./keyless-node.js');
 
@@ -130,17 +129,18 @@ export async function detectKeylessEnvDrift(): Promise<void> {
     });
 
     if (hasDrift) {
-      // Fire drift detected event
-      const driftDetectedEvent: TelemetryEventRaw<EventKeylessEnvDriftPayload> = {
-        event: EVENT_KEYLESS_ENV_DRIFT_DETECTED,
-        eventSamplingRate: EVENT_SAMPLING_RATE,
-        payload,
-      };
-
-      clerkClient.telemetry?.record(driftDetectedEvent);
-
-      // Mark the telemetry event as fired to prevent future executions
-      await markTelemetryEventAsFired();
+      const shouldFireEvent = await tryMarkTelemetryEventAsFired();
+
+      if (shouldFireEvent) {
+        // Fire drift detected event only if we successfully created the flag
+        const driftDetectedEvent: TelemetryEventRaw<EventKeylessEnvDriftPayload> = {
+          event: EVENT_KEYLESS_ENV_DRIFT_DETECTED,
+          eventSamplingRate: EVENT_SAMPLING_RATE,
+          payload,
+        };
+
+        clerkClient.telemetry?.record(driftDetectedEvent);
+      }
     }
   } catch (error) {
     // Silently handle errors to avoid breaking the application