

# Run a virtual waiting room with a network call in a CloudFront Functions viewer request event

The following code example shows how to draw a waiting room ticket with one cf.fetch call per viewer, and admit viewers by comparing a signed cookie with a watermark in KeyValueStore.

------
#### [ JavaScript ]

**JavaScript runtime 2.0 for CloudFront Functions**  
 There's more on GitHub. Find the complete example and learn how to set up and run in the [CloudFront Functions examples](https://github.com/aws-samples/amazon-cloudfront-functions/tree/main/network-call-waiting-room) repository. 

```javascript
import cf from 'cloudfront';
import crypto from 'crypto';

// Viewer request function.
// A virtual waiting room. The queue is two integers: a ticket counter behind an origin and a
// watermark (serving) in KeyValueStore.
//   valid pass cookie (wr_a)          -> forwarded, x-wr: admitted, no call
//   ticket cookie (wr_t) >= serving   -> waiting page with the position, no call
//   ticket cookie (wr_t) <  serving   -> 302 to the same URL with a new pass, no call
//   no ticket, browser page load      -> one call: POST /enqueue draws a ticket (fail closed)
//   no ticket, anything else          -> 503 browsers-only, no call
//   GET <prefix>leave                 -> cookies cleared, one cf.beacon frees the place
// An admission job raises the watermark in KVS; AWS WAF guards the counter with a CAPTCHA.

// The origin id (the origin's Name in the console) of the queue API on this distribution.
const QUEUE_ORIGIN_ID = 'waiting-room';
const ENQUEUE_PATH = '/enqueue';
const LEAVE_PATH = '/leave';
// The path the waiting room protects: cookies are scoped to it, and <prefix>leave leaves the line.
const PATH_PREFIX = '/';
const STATE_KEY = 'queue-state'; // from the admission job: { mode, epoch, serving, step, tick }
const SECRET_KEYS = ['queue-secret-cur', 'queue-secret-prev']; // cur signs, either verifies
const SHARDS = 8; // counter items; the admission job reads the same number
const ADMIT_SECONDS = 120; // wr_a lifetime; renewing it is free while wr_t is below the watermark
const TICKET_SECONDS = 7200;
const STALE_MS = 5 * 60 * 1000; // queue-state older than this: the admission job stopped ticking
const REFRESH_SECONDS = 5;
const TICKET_COOKIE = 'wr_t';
const PASS_COOKIE = 'wr_a';
const WAF_TOKEN_COOKIE = 'aws-waf-token';
const COOKIE_ATTRIBUTES = 'Path=' + PATH_PREFIX + '; Secure; HttpOnly; SameSite=Lax';
const JWT_HEADER = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.'; // {"alg":"HS256","typ":"JWT"}, the only header accepted
// Inserted by an AWS WAF count rule from the Bot Control token id label; WAF overwrites any viewer copy.
const WAF_TOKEN_ID_HEADER = 'x-amzn-waf-wr-token-id';
const JA4_HEADER = 'cloudfront-viewer-ja4-fingerprint';
const DOC = '<!doctype html><meta charset="utf-8">';
const VERDICT_HEADER = 'x-wr';
const PLACE_HEADER = 'x-wr-place';

function headerValue(headers, name) {
    return headers[name] ? headers[name].value : '';
}

function sign(secret, text) {
    return crypto.createHmac('sha256', secret).update(text).digest('base64url');
}

function sha256(text, encoding) {
    return crypto.createHash('sha256').update(text).digest(encoding);
}

function signJwt(claims, secret) {
    const signed = JWT_HEADER + Buffer.from(JSON.stringify(claims)).toString('base64url');
    return signed + '.' + sign(secret, signed);
}

// Constant time: timing never tells how much of a signature matched.
function constantTimeEquals(expected, actual) {
    let difference = expected.length ^ actual.length;
    for (let i = 0; i < expected.length; i++) {
        difference |= expected.charCodeAt(i) ^ actual.charCodeAt(i);
    }
    return difference === 0;
}

// The claims of a token this queue signed, or null.
function verifyJwt(cookie, secrets) {
    const token = cookie ? cookie.value : '';
    const dot = token.lastIndexOf('.');
    if (token.indexOf(JWT_HEADER) !== 0 || dot <= JWT_HEADER.length) {
        return null;
    }
    let valid = false;
    for (let i = 0; i < secrets.length; i++) {
        if (constantTimeEquals(sign(secrets[i], token.slice(0, dot)), token.slice(dot + 1))) {
            valid = true;
        }
    }
    if (!valid) {
        return null;
    }
    try {
        return JSON.parse(Buffer.from(token.slice(JWT_HEADER.length, dot), 'base64url').toString());
    } catch (error) {
        return null;
    }
}

// no-store: any answer may carry a ticket or a pass.
function respond(statusCode, verdict, extraHeaders, body) {
    const headers = {
        'cache-control': { value: 'no-store' },
        'content-type': { value: 'text/html; charset=utf-8' },
    };
    headers[VERDICT_HEADER] = { value: verdict };
    const response = { statusCode: statusCode, headers: Object.assign(headers, extraHeaders) };
    if (body) {
        response.body = body;
    }
    return response;
}

function withCookie(response, name, value, maxAge) {
    response.cookies = response.cookies || {};
    response.cookies[name] = { value: value, attributes: COOKIE_ATTRIBUTES + '; Max-Age=' + maxAge };
    return response;
}

function waitingPage(verdict, title, line) {
    const html = DOC + '<meta http-equiv="refresh" content="' + REFRESH_SECONDS + '">' +
        '<title>' + title + '</title><body style="font:18px system-ui;max-width:34em;margin:4em auto">' +
        '<h1>' + title + '</h1><p>' + line + '</p>' +
        '<p><a href="' + PATH_PREFIX + 'leave">Leave the line</a></p>';
    return respond(200, verdict, { 'retry-after': { value: String(REFRESH_SECONDS) } }, html);
}

function expiredCookie(domain) {
    return { value: '', attributes: 'Path=/; Secure; ' + domain + 'Max-Age=0' };
}

// Clears the HttpOnly cookies and aws-waf-token (both Domain forms), so the CAPTCHA comes back.
function leftPage(host, place) {
    const extraHeaders = {};
    extraHeaders[PLACE_HEADER] = { value: place };
    const page = respond(200, 'left', extraHeaders,
        DOC + '<title>You left the line</title><p>You left the line. <a href="' + PATH_PREFIX + '">Join again</a></p>');
    withCookie(withCookie(page, TICKET_COOKIE, '', 0), PASS_COOKIE, '', 0);
    const wafToken = [expiredCookie(''), expiredCookie('Domain=' + host + '; ')];
    page.cookies[WAF_TOKEN_COOKIE] = Object.assign(expiredCookie(''), { multiValue: wafToken });
    return page;
}

// KVS reads, not network calls; a missing key leaves state null or a secret out.
// allSettled, not all: a missing previous secret must not throw away the state.
async function readQueue() {
    const store = cf.kvs();
    const reads = await Promise.allSettled([
        store.get(STATE_KEY, { format: 'json' }),
        store.get(SECRET_KEYS[0]),
        store.get(SECRET_KEYS[1]),
    ]);
    const secrets = [];
    for (let i = 1; i < reads.length; i++) {
        if (reads[i].status === 'fulfilled' && reads[i].value) {
            secrets.push(reads[i].value);
        }
    }
    return { state: reads[0].status === 'fulfilled' ? reads[0].value : null, secrets: secrets };
}

// One cf.beacon puts the ticket in a skip set (a set: a replayed cookie frees one place).
function leaveLine(state, ticket, host) {
    if (ticket < 0 || ticket < state.serving) {
        return leftPage(host, 'none');
    }
    try {
        cf.beacon(LEAVE_PATH, {
            originId: QUEUE_ORIGIN_ID,
            method: 'POST',
            headers: { 'content-type': 'application/json' }, // plain strings, not { value } objects
            body: JSON.stringify({ epoch: state.epoch, ticket: ticket }),
            logDeliveryErrors: true, // late failures go to CloudWatch Logs
        });
        return leftPage(host, 'freed');
    } catch (error) {
        return leftPage(host, 'failed'); // only an invalid call throws
    }
}

// wr_a binds to a hash of the WAF token id, the user agent and JA4: a copied pass fails elsewhere.
function clientBinding(headers) {
    const client = [headerValue(headers, WAF_TOKEN_ID_HEADER), headerValue(headers, 'user-agent'),
        headerValue(headers, JA4_HEADER)].join('|');
    return sha256(client, 'base64url').slice(0, 22);
}

function positionPage(ticket, state, now) {
    if (now * 1000 - state.tick > STALE_MS) {
        return waitingPage('paused', 'The queue is paused', 'You keep your place in line.');
    }
    const ahead = ticket - state.serving + 1;
    const minutes = Math.ceil(ahead / Math.max(state.step, 1));
    return waitingPage('waiting', 'You are in line', 'Position about <b>' + ahead + '</b>, roughly ' + minutes + ' min.');
}

// The one network call: the shard's counter hands out its next number, or throws.
async function drawTicket(epoch, shard) {
    const enqueueResponse = await cf.fetch(ENQUEUE_PATH, {
        originId: QUEUE_ORIGIN_ID,
        method: 'POST',
        headers: { 'content-type': 'application/json' }, // plain strings, not { value } objects
        body: JSON.stringify({ epoch: epoch, shard: shard }),
        includeBody: true, // default false; the counter is in the body
    });
    if (!enqueueResponse.ok) {
        throw new Error('enqueue returned ' + enqueueResponse.status); // 429: the API throttled
    }
    const text = await enqueueResponse.text(); // assign first: no await inside call arguments
    const ticket = (JSON.parse(text).n - 1) * SHARDS + shard;
    if (!(ticket >= 0)) {
        throw new Error('enqueue sent no counter');
    }
    return ticket;
}

async function handler(event) {
    const request = event.request;
    const headers = request.headers;
    const now = Math.floor(Date.now() / 1000); // JWT times are in seconds
    delete headers[VERDICT_HEADER]; // only this function tells the origin what happened

    const queue = await readQueue();
    const state = queue.state;
    const secrets = queue.secrets;
    // The epoch makes a counter reset safe: tickets of an old line stop counting.
    const claims = state ? verifyJwt(request.cookies[TICKET_COOKIE], secrets) : null;
    const ticket = claims && claims.epoch === state.epoch && typeof claims.ticket === 'number' ? claims.ticket : -1;

    if (request.uri === PATH_PREFIX + 'leave') {
        return leaveLine(state, ticket, headerValue(headers, 'host'));
    }
    if (state && state.mode === 'off') {
        headers[VERDICT_HEADER] = { value: 'off' };
        return request;
    }
    if (!state || !secrets.length) {
        return waitingPage('starting', 'The queue is starting', 'Please wait a moment.');
    }

    const binding = clientBinding(headers);
    const pass = verifyJwt(request.cookies[PASS_COOKIE], secrets);
    if (pass && pass.epoch === state.epoch && pass.exp > now && pass.bnd === binding) {
        headers[VERDICT_HEADER] = { value: 'admitted' };
        return request;
    }

    // In line. Tickets below the watermark are admitted.
    if (ticket >= 0) {
        if (ticket >= state.serving) {
            return positionPage(ticket, state, now);
        }
        const admitted = respond(302, 'admit', { location: { value: request.uri } });
        const newPass = signJwt({ epoch: state.epoch, exp: now + ADMIT_SECONDS, bnd: binding }, secrets[0]);
        return withCookie(admitted, PASS_COOKIE, newPass, ADMIT_SECONDS);
    }

    // No ticket. Only a browser page load may draw one.
    if (request.method !== 'GET' || headerValue(headers, 'accept').indexOf('text/html') === -1) {
        return respond(503, 'browsers-only',
            { 'content-type': { value: 'application/json' }, 'retry-after': { value: String(REFRESH_SECONDS) } },
            '{"waitingRoom":"open this URL in a browser"}');
    }

    // A hash of the request id, not Math.random(): no network call may follow random values.
    const shard = parseInt(sha256(event.context.requestId, 'hex').slice(0, 8), 16) % SHARDS;
    let drawn;
    try {
        drawn = await drawTicket(state.epoch, shard);
    } catch (error) {
        // Fail closed: no ticket, nothing reaches the origin, the page retries.
        return waitingPage('busy', 'Busy, retrying', 'The line is very long right now (' + error.name + ').');
    }
    const queued = waitingPage('queued', 'You are in line', 'Your ticket is <b>' + drawn + '</b>. Finding your position.');
    const newTicket = signJwt({ epoch: state.epoch, ticket: drawn, iat: now }, secrets[0]);
    return withCookie(queued, TICKET_COOKIE, newTicket, TICKET_SECONDS);
}
```

------

For a complete list of AWS SDK developer guides and code examples, see [Using CloudFront with an AWS SDK](sdk-general-information-section.md). This topic also includes information about getting started and details about previous SDK versions.