Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

7.2 KB
Raw Blame
import { createHash, randomUUID } from "node:crypto";
import { setTimeout as delay } from "node:timers/promises";
import {
  FastifyRequest,
  onResponseHookHandler,
  onSendHookHandler,
  preHandlerHookHandler,
  RouteShorthandOptions,
} from "fastify";
import { Redis } from "ioredis";

export interface DashboardCacheOptions {
  redis: Pick<Redis, "eval" | "status">;
  namespace: string;
  ttlMs?: number;
  lockMs?: number;
  maxResponseBytes?: number;
}

// The read/claim and publish/release operations are atomic across backend
// workers. An expired owner must never overwrite a newer owner's response.
const READ_OR_CLAIM = `
  if ARGV[3] ~= '' then
    local completed = redis.call('GET', KEYS[3])
    if completed then return {'completed', completed} end
  end
  local value = redis.call('GET', KEYS[1])
  if value then return {'hit', value} end
  if redis.call('SET', KEYS[2], ARGV[1], 'NX', 'PX', ARGV[2]) then return {'owner'} end
  return {'wait', redis.call('GET', KEYS[2])}
`;
const PUBLISH = `
  if redis.call('GET', KEYS[2]) ~= ARGV[1] then return 0 end
  if tonumber(ARGV[3]) > 0 then redis.call('SET', KEYS[1], ARGV[2], 'PX', ARGV[3]) end
  redis.call('SET', KEYS[3], ARGV[4], 'PX', 5000)
  redis.call('DEL', KEYS[2])
  return 1
`;
const RELEASE = `
  if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end
  return 0
`;
const RENEW = `
  if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) end
  return 0
`;

function canonical(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(canonical);
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value)
        .sort(([a], [b]) => a.localeCompare(b))
        .map(([key, item]) => [key, canonical(item)])
    );
  }
  return value;
}

const hooks = <T>(hook: T | T[] | undefined): T[] => (hook === undefined ? [] : Array.isArray(hook) ? hook : [hook]);

export function createDashboardCache({
  redis,
  namespace,
  ttlMs = 30_000,
  lockMs = 5_000,
  maxResponseBytes = 256 * 1024,
}: DashboardCacheOptions) {
  const owners = new WeakMap<
    FastifyRequest,
    { key: string; lock: string; token: string; startedAt: number; heartbeat: NodeJS.Timeout }
  >();

  const release: onResponseHookHandler = async request => {
    const owner = owners.get(request);
    if (!owner) return;
    clearInterval(owner.heartbeat);
    owners.delete(request);
    try {
      await redis.eval(RELEASE, 1, owner.lock, owner.token);
    } catch {
      // The lease expires even if Redis is unavailable during cleanup.
    }
  };

  const read: preHandlerHookHandler = async (request, reply) => {
    // This hook is appended AFTER access checks, time validation and segment
    // expansion. Cache identity uses the resolved Site and full expanded query.
    if (
      ttlMs <= 0 ||
      request.method !== "GET" ||
      redis.status !== "ready" ||
      /(?:no-cache|no-store|max-age=0)/i.test(String(request.headers["cache-control"] || ""))
    )
      return;

    const digest = createHash("sha256")
      .update(
        JSON.stringify(
          canonical({
            route: request.routeOptions.url,
            params: request.params,
            query: request.query,
          })
        )
      )
      .digest("hex");
    const key = `dashboard:v1:{${namespace}:${digest}}`;
    const lock = `${key}:lock`;
    const token = randomUUID();
    const deadline = Date.now() + 70_000;
    let waited = false;
    let waitingFor = "";

    try {
      while (!reply.raw.destroyed && !request.raw.aborted && Date.now() < deadline) {
        const [result, payload] = (await redis.eval(
          READ_OR_CLAIM,
          3,
          key,
          lock,
          `${key}:done:${waitingFor}`,
          token,
          lockMs,
          waitingFor
        )) as string[];
        if (result === "completed") {
          const completion = JSON.parse(payload);
          if (completion.retry) return;
          reply.header("X-Rybbit-Cache", "COALESCED");
          return reply.code(completion.status).type(completion.type).send(completion.payload);
        }
        if (result === "hit") {
          reply.header("X-Rybbit-Cache", waited ? "COALESCED" : "HIT");
          return reply.type("application/json; charset=utf-8").send(payload);
        }
        if (result === "owner") {
          // A live slow query renews its short lease. A crashed worker leaves
          // followers waiting at most one lease, rather than the query timeout.
          let renewing = false;
          const heartbeat = setInterval(
            async () => {
              if (renewing) return;
              renewing = true;
              try {
                if (reply.raw.destroyed || request.raw.aborted || !(await redis.eval(RENEW, 1, lock, token, lockMs)))
                  clearInterval(heartbeat);
              } catch {
                // An unavailable Redis cannot prevent the original query from
                // completing. Publication still verifies ownership afterwards.
              } finally {
                renewing = false;
              }
            },
            Math.max(10, Math.floor(lockMs / 3))
          );
          heartbeat.unref();
          owners.set(request, { key, lock, token, startedAt: Date.now(), heartbeat });
          reply.header("X-Rybbit-Cache", "MISS");
          return;
        }
        waited = true;
        waitingFor = payload;
        await delay(50);
      }
    } catch (error) {
      request.log.debug({ err: error }, "Dashboard cache unavailable; querying directly");
    }
    // Cache availability never decides whether analytics can be served.
  };

  const write: onSendHookHandler = async (request, reply, payload) => {
    const owner = owners.get(request);
    if (!owner) return payload;
    clearInterval(owner.heartbeat);
    // Count freshness from query start, not completion: a slow query must not
    // add its execution time on top of the promised cache lifetime.
    const remaining = owner.startedAt + ttlMs - Date.now();
    const type = String(reply.getHeader("content-type") || "");
    const shareable =
      type.startsWith("application/json") &&
      typeof payload === "string" &&
      Buffer.byteLength(payload) <= maxResponseBytes;
    const cacheTtl = shareable && reply.statusCode === 200 ? Math.max(Math.floor(remaining), 0) : 0;
    // Only callers already waiting for this owner's token can receive an error
    // completion. New requests retry normally; failures never enter the cache.
    const completion = JSON.stringify(shareable ? { status: reply.statusCode, type, payload } : { retry: true });
    try {
      await redis.eval(
        PUBLISH,
        3,
        owner.key,
        owner.lock,
        `${owner.key}:done:${owner.token}`,
        owner.token,
        typeof payload === "string" ? payload : "",
        cacheTtl,
        completion
      );
      owners.delete(request);
    } catch (error) {
      request.log.debug({ err: error }, "Could not cache dashboard response");
    }
    return payload;
  };

  return <T extends RouteShorthandOptions>(options: T): T => ({
    ...options,
    preHandler: [...hooks(options.preHandler), read],
    onSend: [...hooks(options.onSend), write],
    onResponse: [...hooks(options.onResponse), release],
  });
}