Module 01: Node.js Collection Endpoint

Build an Express.js server that receives analytics beacons, validates the payload, enriches it with server-side data, and inserts it into MySQL.

1. Project Setup

Create a new directory and initialize a Node.js project. We need two packages: express for HTTP handling and mysql2 for the database connection.

mkdir analytics-endpoint && cd analytics-endpoint
npm init -y
npm install express mysql2

After installing, your package.json will list both dependencies. The mysql2 package is preferred over the older mysql package because it supports Promises, prepared statements, and the newer MySQL authentication protocol out of the box.

Once the database exists, run the schema file to create the pageviews table:

mysql -u root analytics < schema.sql

2. Database Schema

The schema.sql file defines the pageviews table. Let us walk through each column and why it exists:

The schema includes three indexes for common query patterns:

• idx_url — Speeds up queries filtering by page URL (indexed on the first 255 characters, since MySQL limits index key length for VARCHAR columns).
• idx_type — Speeds up queries like "show me all errors" or "count pageviews vs. events."
• idx_server_timestamp — Speeds up time-range queries such as "all pageviews in the last 24 hours."

3. The Express Endpoint

The collect.js file is roughly 80 lines. Let us walk through each section.

Step 1: Imports and Connection Pool

const express = require('express');
const mysql = require('mysql2');

const app = express();
const PORT = 3006;

const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  database: 'analytics',
  waitForConnections: true,
  connectionLimit: 10
});

We use a connection pool instead of a single connection. A pool maintains a set of reusable connections to the database. When a request arrives, it borrows a connection from the pool, executes the query, and returns the connection for the next request. This avoids the overhead of establishing a new TCP connection to MySQL for every beacon and prevents connection exhaustion under load.

Step 2: CORS Middleware

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Methods', 'POST, OPTIONS');
  res.header('Access-Control-Allow-Headers', 'Content-Type');
  if (req.method === 'OPTIONS') return res.sendStatus(204);
  next();
});

CORS headers allow the browser to send beacons from any origin to this endpoint. The OPTIONS preflight handler returns 204 immediately — no need to process a preflight request any further. In production, replace '*' with your actual domain.

Step 3: JSON Body Parsing

app.use(express.json());

Express does not parse request bodies by default. This middleware reads the raw body, parses it as JSON, and attaches the result to req.body. Without this line, req.body would be undefined.

Step 4: The POST /collect Route

app.post('/collect', (req, res) => {
  const data = req.body;

  // Validate required fields
  if (!data || typeof data.url !== 'string' || !data.url) {
    return res.status(400).json({ error: 'Missing required field: url' });
  }

  const ALLOWED_TYPES = ['pageview', 'event', 'error', 'performance'];
  const type = data.type || 'pageview';
  if (!ALLOWED_TYPES.includes(type)) {
    return res.status(400).json({ error: 'Invalid type' });
  }

Validation happens before anything touches the database. Two checks:

• url must be a non-empty string. This is the only truly required client field.
• type must be one of the four allowed values. The allowlist is enforced in both the application and the database ENUM. Defense in depth.

  // Enrich with server-side data
  const serverTimestamp = new Date().toISOString()
    .slice(0, 19).replace('T', ' ');
  const clientIp = req.ip;

The server adds two fields the client cannot reliably provide:

• server_timestamp — Formatted as YYYY-MM-DD HH:MM:SS for MySQL DATETIME. The .slice(0, 19).replace('T', ' ') converts ISO 8601 (2026-02-17T10:30:00.000Z) to MySQL format (2026-02-17 10:30:00).
• client_ip — Taken from req.ip, which Express derives from the TCP connection's remote address.

  // Parameterized INSERT
  const sql = `INSERT INTO pageviews
    (url, type, user_agent, viewport_width, viewport_height,
     referrer, client_timestamp, server_timestamp, client_ip,
     session_id, payload)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;

  const params = [
    data.url,
    type,
    data.userAgent   || null,
    data.viewportW   || null,
    data.viewportH   || null,
    data.referrer    || null,
    data.timestamp   || null,
    serverTimestamp,
    clientIp,
    data.sessionId   || null,
    data.payload ? JSON.stringify(data.payload) : null
  ];

  pool.execute(sql, params, (err) => {
    if (err) {
      console.error('MySQL INSERT error:', err.message);
      return res.sendStatus(500);
    }
    res.sendStatus(204);
  });
});

Key design decisions:

• Parameterized queries only — The ? placeholders prevent SQL injection. The mysql2 driver escapes all values automatically. Never concatenate user input into SQL strings.
• Optional fields default to null — If the client did not send userAgent or referrer, we insert NULL rather than an empty string. This makes queries cleaner: WHERE referrer IS NOT NULL finds all referred visits.
• 204 No Content — The response confirms receipt without sending a body. Minimal overhead for an endpoint that will handle thousands of requests.
• pool.execute — Uses a prepared statement under the hood, which is both safer (parameterized) and faster (MySQL can cache the query plan).

Step 5: Start the Server

app.listen(PORT, () => {
  console.log(`Collection endpoint listening on http://localhost:${PORT}`);
});

Run the server with node collect.js. It will listen on port 3006 and begin accepting POST requests at /collect.

4. Testing

Open test.html in a browser (you can serve it from the same Express server or open it directly). The test page includes a minimal collector script that sends a beacon to http://localhost:3006/collect on page load.

Step 1: Start the Server

node collect.js
# Output: Collection endpoint listening on http://localhost:3006

Step 2: Open the Test Page

Open test.html in your browser. Open the browser developer tools (F12) and check the Network tab. You should see a POST request to /collect with a 204 response.

Step 3: Verify the INSERT

Connect to MySQL and query the pageviews table:

mysql -u root analytics -e "SELECT id, url, type, server_timestamp, client_ip FROM pageviews ORDER BY id DESC LIMIT 5;"

You should see a row for the test page visit with the URL, type pageview, a server timestamp, and a client IP of ::1 (IPv6 localhost) or 127.0.0.1.

5. What We Built

Here is the full data flow from browser to database:

In this module you built:

• A MySQL schema with typed columns, a JSON flex column, and indexes for common queries
• An Express endpoint that validates, enriches, and stores analytics data using parameterized queries
• CORS middleware so browsers allow cross-origin beacon delivery
• A test page that sends a beacon and lets you verify the full pipeline

In the next module, we will build the same endpoint in PHP to compare how the two server-side languages handle the same problem.