Add /v1/cwv-distribution endpoint

.github/workflows/dependabot.yml → .github/workflows/test.yml

@@ -9,6 +9,7 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    if: github.head_ref != 'development'
     steps:
       - uses: actions/checkout@v6
       - run: |

src/controllers/cwvDistributionController.js

@@ -0,0 +1,125 @@
+import { bigquery } from '../utils/db.js';
+import { convertToArray } from '../utils/helpers.js';
+import {
+  handleControllerError,
+  generateETag,
+  isModified,
+  sendValidationError
+} from '../utils/controllerHelpers.js';
+
+/**
+ * Build the BigQuery SQL for the CWV distribution histogram.
+ * rank is applied to p.rank only (no rank column on device_summary).
+ */
+const buildQuery = (rankFilter) => {
+  const rankClause = rankFilter ? 'AND p.rank <= @rank' : '';
+
+  return `WITH metrics AS (
+  SELECT
+    client,
+    t.technology,
+    root_page,
+    ANY_VALUE(p75_lcp) AS lcp,
+    ANY_VALUE(p75_inp) AS inp,
+    ANY_VALUE(p75_cls) AS cls,
+    ANY_VALUE(p75_fcp) AS fcp,
+    ANY_VALUE(p75_ttfb) AS ttfb
+  FROM
+    \`httparchive.crawl.pages\` p,
+    UNNEST(technologies) t,
+    \`chrome-ux-report.materialized.device_summary\` c
+  WHERE
+    p.date = @date AND
+    c.date = @date AND
+    t.technology IN UNNEST(@technologies) AND
+    root_page = origin || '/' AND
+    IF(client = 'mobile', 'phone', 'desktop') = device
+    ${rankClause}
+  GROUP BY
+    client,
+    t.technology,
+    root_page
+)
+
+SELECT
+  client,
+  technology,
+  bucket AS loading_bucket,
+  bucket / 4 AS inp_bucket,
+  bucket / 2000 AS cls_bucket,
+  COUNT(DISTINCT root_page WHERE lcp = bucket) AS lcp_origins,
+  COUNT(DISTINCT root_page WHERE inp = bucket / 4) AS inp_origins,
+  COUNT(DISTINCT root_page WHERE cls = bucket / 2000) AS cls_origins,
+  COUNT(DISTINCT root_page WHERE fcp = bucket) AS fcp_origins,
+  COUNT(DISTINCT root_page WHERE ttfb = bucket) AS ttfb_origins
+FROM
+  metrics,
+  UNNEST(GENERATE_ARRAY(0.0, 10000.0, 100.0)) AS bucket
+GROUP BY
+  client,
+  technology,
+  bucket
+ORDER BY
+  client,
+  technology,
+  bucket`;
+};
+
+/**
+ * GET /v1/cwv-distribution
+ *
+ * Query parameters:
+ *   technology (required) - comma-separated list of technologies, e.g. "Wix,WordPress"
+ *   date       (required) - crawl date in YYYY-MM-DD format, e.g. "2026-02-01"
+ *   rank       (optional) - numeric rank ceiling, e.g. "10000". Omit or set to "ALL" to include all ranks.
+ */
+export const listCWVDistributionData = async (req, res) => {
+  try {
+    const params = req.query;
+
+    const errors = [];
+    if (!params.technology) errors.push(['technology', 'missing technology parameter']);
+    if (!params.date) errors.push(['date', 'missing date parameter']);
+    if (errors.length > 0) {
+      sendValidationError(res, errors);
+      return;
+    }
+
+    const technologies = convertToArray(params.technology);
+    const date = params.date;
+    const rankParam = params.rank && params.rank !== 'ALL' ? params.rank : null;
+
+    const queryStr = buildQuery(rankParam !== null);
+
+    const queryOptions = {
+      query: queryStr,
+      params: {
+        technologies,
+        date,
+        ...(rankParam !== null && { rank: parseInt(rankParam, 10) })
+      },
+      types: {
+        technologies: ['STRING'],
+        date: 'STRING',
+        ...(rankParam !== null && { rank: 'INT64' })
+      }
+    };
+
+    const [rows] = await bigquery.query(queryOptions);
+
+    const jsonData = JSON.stringify(rows);
+    const etag = generateETag(jsonData);
+    res.setHeader('ETag', `"${etag}"`);
+    if (!isModified(req, etag)) {
+      res.statusCode = 304;
+      res.end();
+      return;
+    }
+
+    res.statusCode = 200;
+    res.end(jsonData);
+
+  } catch (error) {
+    handleControllerError(res, error, 'fetching CWV distribution data');
+  }
+};

src/index.js

@@ -14,6 +14,7 @@ const CONTROLLER_MODULES = {
   geos: './controllers/geosController.js',
   versions: './controllers/versionsController.js',
   static: './controllers/cdnController.js',
+  cwvDistribution: './controllers/cwvDistributionController.js',
 };
 
 const controllers = {};
@@ -37,6 +38,7 @@ const V1_ROUTES = {
   '/v1/geos': ['geos', 'listGeos'],
   '/v1/versions': ['versions', 'listVersions'],
   '/v1/geo-breakdown': ['geoBreakdown', 'listGeoBreakdownData'],
+  '/v1/cwv-distribution': ['cwvDistribution', 'listCWVDistributionData']
 };
 
 // Helper function to set CORS headers

src/package.json

@@ -15,6 +15,7 @@
     "run": "docker run -p 8080:8080 report-api"
   },
   "dependencies": {
+    "@google-cloud/bigquery": "^7.9.1",
     "@google-cloud/firestore": "8.3.0",
     "@google-cloud/functions-framework": "^5.0.2",
     "@google-cloud/storage": "7.19.0",

src/tests/routes.test.js

@@ -73,9 +73,14 @@ jest.unstable_mockModule('../utils/db.js', () => {
     collection: jest.fn().mockImplementation((collectionName) => mockQuery)
   };
 
+  const mockBigQueryInstance = {
+    query: jest.fn().mockResolvedValue([[]])
+  };
+
   return {
     firestore: mockFirestoreInstance,
-    firestoreOld: mockFirestoreInstance
+    firestoreOld: mockFirestoreInstance,
+    bigquery: mockBigQueryInstance
   };
 });
 
@@ -835,4 +840,51 @@ describe('API Routes', () => {
       });
     });
   });
+
+  describe('GET /v1/cwv-distribution', () => {
+    it('should return 400 when technology is missing', async () => {
+      const res = await request(app).get('/v1/cwv-distribution?date=2026-02-01');
+      expect(res.statusCode).toEqual(400);
+      expect(res.body).toHaveProperty('errors');
+    });
+
+    it('should return 400 when date is missing', async () => {
+      const res = await request(app).get('/v1/cwv-distribution?technology=Wix');
+      expect(res.statusCode).toEqual(400);
+      expect(res.body).toHaveProperty('errors');
+    });
+
+    it('should return 400 when both technology and date are missing', async () => {
+      const res = await request(app).get('/v1/cwv-distribution');
+      expect(res.statusCode).toEqual(400);
+      expect(res.body).toHaveProperty('errors');
+    });
+
+    it('should return 200 with valid technology and date', async () => {
+      const res = await request(app).get('/v1/cwv-distribution?technology=Wix&date=2026-02-01');
+      expect(res.statusCode).toEqual(200);
+      expect(Array.isArray(res.body)).toBe(true);
+    });
+
+    it('should return 200 with multiple technologies', async () => {
+      const res = await request(app).get('/v1/cwv-distribution?technology=Wix,WordPress&date=2026-02-01');
+      expect(res.statusCode).toEqual(200);
+      expect(Array.isArray(res.body)).toBe(true);
+    });
+
+    it('should return 200 with rank filter applied', async () => {
+      const res = await request(app).get('/v1/cwv-distribution?technology=Wix&date=2026-02-01&rank=10000');
+      expect(res.statusCode).toEqual(200);
+      expect(Array.isArray(res.body)).toBe(true);
+    });
+
+    it('should handle CORS preflight requests', async () => {
+      const res = await request(app)
+        .options('/v1/cwv-distribution')
+        .set('Origin', 'http://example.com')
+        .set('Access-Control-Request-Method', 'GET');
+      expect(res.statusCode).toEqual(204);
+      expect(res.headers['access-control-allow-origin']).toEqual('*');
+    });
+  });
 });

src/utils/db.js

@@ -1,4 +1,5 @@
 import { Firestore } from '@google-cloud/firestore';
+import { BigQuery } from '@google-cloud/bigquery';
 
 // Initialize Firestore with basic optimizations (default connection using env variables)
 const firestore = new Firestore({
@@ -30,3 +31,10 @@ const firestoreOld = new Firestore({
 
 // Export both connections - maintain backward compatibility
 export { firestore, firestoreOld };
+
+// Initialize BigQuery client
+const bigquery = new BigQuery({
+  projectId: process.env.PROJECT
+});
+
+export { bigquery };

terraform/run-service/variables.tf

@@ -35,7 +35,7 @@ variable "available_cpu" {
 }
 variable "ingress_settings" {
   type        = string
-  default     = "INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER"
+  default     = "INGRESS_TRAFFIC_ALL"
   description = "String value that controls what traffic can reach the function. Check ingress documentation to see the impact of each settings value. Changes to this field will recreate the cloud function."
 }
 variable "timeout" {