fix: add chain tip etag generator

src/api/routes/ft.ts

@@ -16,7 +16,7 @@
   StacksAddressParam,
   TokenQuerystringParams,
 } from '../schemas';
-import { handleTokenCache } from '../util/cache';
+import { handleChainTipCache, handleTokenCache } from '../util/cache';
 import { generateTokenErrorResponse, TokenErrorResponseSchema } from '../util/errors';
 import { parseMetadataLocaleBundle } from '../util/helpers';
 
@@ -25,6 +25,7 @@
   options,
   done
 ) => {
+  fastify.addHook('preHandler', handleChainTipCache);
   fastify.get(
     '/ft',
     {

src/api/routes/status.ts

@@ -3,12 +3,14 @@
 import { Server } from 'http';
 import { ApiStatusResponse } from '../schemas';
 import { SERVER_VERSION } from '@hirosystems/api-toolkit';
+import { handleChainTipCache } from '../util/cache';
 
 export const StatusRoutes: FastifyPluginCallback<
   Record<never, never>,
   Server,
   TypeBoxTypeProvider
 > = (fastify, options, done) => {
+  fastify.addHook('preHandler', handleChainTipCache);
   fastify.get(
     '/',
     {

src/api/schemas.ts

@@ -340,6 +340,7 @@ export const ApiStatusResponse = Type.Object(
           queued: Type.Optional(Type.Integer({ examples: [512] })),
           done: Type.Optional(Type.Integer({ examples: [12532] })),
           failed: Type.Optional(Type.Integer({ examples: [11] })),
+          invalid: Type.Optional(Type.Integer({ examples: [20] })),
         },
         { title: 'Api Job Count' }
       )

src/api/util/cache.ts

@@ -1,18 +1,25 @@
 import { FastifyReply, FastifyRequest } from 'fastify';
 import { SmartContractRegEx } from '../schemas';
-import { logger } from '@hirosystems/api-toolkit';
+import { CACHE_CONTROL_MUST_REVALIDATE, parseIfNoneMatchHeader } from '@hirosystems/api-toolkit';
 
-/**
- * A `Cache-Control` header used for re-validation based caching.
- * * `public` == allow proxies/CDNs to cache as opposed to only local browsers.
- * * `no-cache` == clients can cache a resource but should revalidate each time before using it.
- * * `must-revalidate` == somewhat redundant directive to assert that cache must be revalidated, required by some CDNs
- */
-const CACHE_CONTROL_MUST_REVALIDATE = 'public, no-cache, must-revalidate';
+enum ETagType {
+  chainTip = 'chain_tip',
+  token = 'token',
+}
 
-export async function handleTokenCache(request: FastifyRequest, reply: FastifyReply) {
+async function handleCache(type: ETagType, request: FastifyRequest, reply: FastifyReply) {
   const ifNoneMatch = parseIfNoneMatchHeader(request.headers['if-none-match']);
-  const etag = await getTokenEtag(request);
+  let etag: string | undefined;
+  switch (type) {
+    case ETagType.chainTip:
+      // TODO: We should use the `index_block_hash` here instead of the `block_hash`, but we'll need
+      // a DB change for this.
+      etag = (await request.server.db.getChainTipBlockHeight()).toString();
+      break;
+    case ETagType.token:
+      etag = await getTokenEtag(request);
+      break;
+  }
   if (etag) {
     if (ifNoneMatch && ifNoneMatch.includes(etag)) {
       await reply.header('Cache-Control', CACHE_CONTROL_MUST_REVALIDATE).code(304).send();
@@ -22,6 +29,14 @@
   }
 }
 
+export async function handleTokenCache(request: FastifyRequest, reply: FastifyReply) {
+  return handleCache(ETagType.token, request, reply);
+}
+
+export async function handleChainTipCache(request: FastifyRequest, reply: FastifyReply) {
+  return handleCache(ETagType.chainTip, request, reply);
+}
+
 export function setReplyNonCacheable(reply: FastifyReply) {
   reply.removeHeader('Cache-Control');
   reply.removeHeader('Etag');
@@ -52,47 +67,3 @@
     return undefined;
   }
 }
-
-/**
- * Parses the etag values from a raw `If-None-Match` request header value.
- * The wrapping double quotes (if any) and validation prefix (if any) are stripped.
- * The parsing is permissive to account for commonly non-spec-compliant clients, proxies, CDNs, etc.
- * E.g. the value:
- * ```js
- * `"a", W/"b", c,d,   "e", "f"`
- * ```
- * Would be parsed and returned as:
- * ```js
- * ['a', 'b', 'c', 'd', 'e', 'f']
- * ```
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match#syntax
- * ```
- * If-None-Match: "etag_value"
- * If-None-Match: "etag_value", "etag_value", ...
- * If-None-Match: *
- * ```
- * @param ifNoneMatchHeaderValue - raw header value
- * @returns an array of etag values
- */
-function parseIfNoneMatchHeader(ifNoneMatchHeaderValue: string | undefined): string[] | undefined {
-  if (!ifNoneMatchHeaderValue) {
-    return undefined;
-  }
-  // Strip wrapping double quotes like `"hello"` and the ETag validation-prefix like `W/"hello"`.
-  // The API returns compliant, strong-validation ETags (double quoted ASCII), but can't control what
-  // clients, proxies, CDNs, etc may provide.
-  const normalized = /^(?:"|W\/")?(.*?)"?$/gi.exec(ifNoneMatchHeaderValue.trim())?.[1];
-  if (!normalized) {
-    // This should never happen unless handling a buggy request with something like `If-None-Match: ""`,
-    // or if there's a flaw in the above code. Log warning for now.
-    logger.warn(`Normalized If-None-Match header is falsy: ${ifNoneMatchHeaderValue}`);
-    return undefined;
-  } else if (normalized.includes(',')) {
-    // Multiple etag values provided, likely irrelevant extra values added by a proxy/CDN.
-    // Split on comma, also stripping quotes, weak-validation prefixes, and extra whitespace.
-    return normalized.split(/(?:W\/"|")?(?:\s*),(?:\s*)(?:W\/"|")?/gi);
-  } else {
-    // Single value provided (the typical case)
-    return [normalized];
-  }
-}

tests/api/cache.test.ts

@@ -24,6 +24,35 @@ describe('ETag cache', () => {
     await db.close();
   });
 
+  test('chain tip cache control', async () => {
+    const response = await fastify.inject({ method: 'GET', url: '/metadata/v1/' });
+    const json = response.json();
+    expect(json).toStrictEqual({
+      server_version: 'token-metadata-api v0.0.1 (test:123456)',
+      status: 'ready',
+      chain_tip: {
+        block_height: 1,
+      },
+    });
+    expect(response.headers.etag).not.toBeUndefined();
+    const etag = response.headers.etag;
+
+    const cached = await fastify.inject({
+      method: 'GET',
+      url: '/metadata/v1/',
+      headers: { 'if-none-match': etag },
+    });
+    expect(cached.statusCode).toBe(304);
+
+    await db.chainhook.updateChainTipBlockHeight(100);
+    const cached2 = await fastify.inject({
+      method: 'GET',
+      url: '/metadata/v1/',
+      headers: { 'if-none-match': etag },
+    });
+    expect(cached2.statusCode).toBe(200);
+  });
+
   test('FT cache control', async () => {
     await insertAndEnqueueTestContractWithTokens(
       db,