Merge pull request #756 from ZenUml/fix/track-endpoint-timeout

feat(docs): add Firebase Emulator Testing Guide and update firebase.j…

Author: MrCoder

docs/firebase-emulator-testing.md

@@ -0,0 +1,145 @@
+# Firebase Emulator Testing Guide
+
+This guide explains how to run the Firebase emulator locally and test your Firebase functions using cURL.
+
+## Running the Firebase Emulator
+
+1. Navigate to your project root directory:
+   ```bash
+   cd /Users/pengxiao/workspaces/zenuml/web-sequence
+   ```
+
+2. Start the Firebase emulator:
+   ```bash
+   firebase emulators:start
+   ```
+
+   This will start the emulator and display the available endpoints in the terminal.
+
+## Accessing the Emulator UI
+
+The Firebase Emulator Suite includes a web-based UI that provides a dashboard for all your emulated services:
+
+1. When you start the emulators, look for a message like:
+   ```
+   ✔  emulators: All emulators ready! It is now safe to connect.
+   i  emulators: View Emulator UI at http://localhost:4000/
+   ```
+
+2. Open the provided URL in your browser (typically http://localhost:4000)
+
+3. The UI provides:
+   - A list of all your Cloud Functions endpoints
+   - The ability to view logs for each function
+   - A way to test functions directly from the UI
+   - Firestore database viewer (if enabled)
+   - Authentication emulator (if enabled)
+
+This UI makes it easier to debug and test your Firebase functions without having to use cURL commands for everything.
+
+## Testing Firebase Functions with cURL
+
+### Testing the Info Endpoint
+
+To verify that the emulator is running correctly, test the `/info` endpoint:
+
+```bash
+curl -X POST \
+  http://localhost:5000/info \
+  -H 'Content-Type: application/json' \
+  -d '{"event": {"event": "testEvent", "category": "test"}, "userId": "test-user"}'
+```
+
+You should receive a response like:
+```
+Hello from web-sequence-local!
+```
+
+### Testing the Track Endpoint
+
+To test the `/track` endpoint:
+
+```bash
+curl -X POST \
+  http://localhost:5000/track \
+  -H 'Content-Type: application/json' \
+  -d '{"event": {"event": "testEvent", "category": "test"}, "userId": "test-user"}'
+```
+
+You should receive a response like:
+```
+Event tracked successfully
+```
+
+### Testing Different Payload Formats
+
+The track endpoint supports two different payload formats:
+
+1. Object format (recommended):
+   ```bash
+   curl -X POST \
+     http://localhost:5002/track \
+     -H 'Content-Type: application/json' \
+     -d '{"event": {"event": "testEvent", "category": "test"}, "userId": "test-user"}'
+   ```
+
+2. String format (legacy):
+   ```bash
+   curl -X POST \
+     http://localhost:5002/track \
+     -H 'Content-Type: application/json' \
+     -d '{"event": "testEvent", "category": "test", "userId": "test-user"}'
+   ```
+
+## Monitoring Logs
+
+While the emulator is running, you can monitor the logs in the terminal. These logs will show:
+
+1. Incoming requests
+2. Function execution details
+3. Any errors or warnings
+4. Mixpanel tracking information
+
+## Troubleshooting
+
+### Functions Emulator Shows as "OFF" in the UI
+
+If the Functions emulator shows as "OFF" in the Emulator UI:
+
+1. Make sure your `firebase.json` file has the proper emulators configuration:
+   ```json
+   "emulators": {
+     "functions": {
+       "port": 5002
+     },
+     "hosting": {
+       "port": 5000
+     },
+     "ui": {
+       "enabled": true,
+       "port": 4000
+     }
+   }
+   ```
+
+2. Try starting the emulator with the explicit `--only` flag:
+   ```bash
+   firebase emulators:start --only functions
+   ```
+
+3. Check the terminal output for any error messages related to the Functions emulator.
+
+### Timeout Issues with the Track Endpoint
+
+If you encounter a timeout issue with the `/track` endpoint:
+
+1. Check the emulator logs for any errors
+2. Verify that the function is responding immediately without waiting for Mixpanel
+3. Make sure the payload format is correct
+
+## Notes on URL Structure
+
+- Direct function URLs: `http://localhost:5002/{functionName}`
+- If you've added rewrite rules in firebase.json, you can also use: `http://localhost:5000/{path}`
+
+Remember to stop the emulator when you're done testing by pressing `Ctrl+C` in the terminal.

firebase.json

@@ -1,7 +1,11 @@
 {
   "hosting": {
     "public": "app",
-    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
+    "ignore": [
+      "firebase.json",
+      "**/.*",
+      "**/node_modules/**"
+    ],
     "rewrites": [
       {
         "source": "/sync-diagram",
@@ -20,11 +24,45 @@
         "function": {
           "functionId": "track"
         }
+      },
+      {
+        "source": "/info",
+        "function": {
+          "functionId": "info"
+        }
       }
     ]
   },
   "firestore": {
     "rules": "firestore.rules",
     "indexes": "firestore.indexes.json"
-  }
+  },
+  "emulators": {
+    "functions": {
+      "port": 5002
+    },
+    "firestore": {
+      "port": 8080
+    },
+    "hosting": {
+      "port": 5000
+    },
+    "ui": {
+      "enabled": true,
+      "port": 4000
+    }
+  },
+  "functions": [
+    {
+      "source": "functions",
+      "codebase": "default",
+      "ignore": [
+        "node_modules",
+        ".git",
+        "firebase-debug.log",
+        "firebase-debug.*.log",
+        "*.local"
+      ]
+    }
+  ]
 }

functions/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+*.local

functions/index.js

@@ -10,7 +10,7 @@ const mixpanel = Mixpanel.init('0c62cea9ed2247f4824bf196f6817941');
 
 const webhook = require('./webhook');
 const alertParser = require('./alert_parser');
-const pubKey = functions.config().paddle.pub_key;
+const pubKey = functions.config().paddle?.pub_key;
 const https = require('https');
 
 exports.info = functions.https.onRequest((req, res) => {
@@ -19,7 +19,7 @@ exports.info = functions.https.onRequest((req, res) => {
 
 const verifyIdToken = (token) => admin.auth().verifyIdToken(token);
 
-const supportedProductIds = (functions.config().paddle.product_ids || '')
+const supportedProductIds = (functions.config().paddle?.product_ids || '')
   .split(',')
   .filter(Boolean);
 const checkSupportedProductIds = (productId) => {
@@ -125,7 +125,7 @@ exports.track = functions.https.onRequest(async (req, res) => {
     event_label: req.body.label,
     displayProductName: 'FireWeb',
   });
-  
+
   // Send a success response to prevent 502 Bad Gateway error
   res.status(200).send('Event tracked successfully');
 });