feat: add Warning http response deprecation notices (#2253)

* feat: add `Warning` http response deprecation notices for deprecated endpoints

* ci: lint fix

Author: zone117x

src/api/deprecation-plugin.ts

@@ -0,0 +1,39 @@
+import fp from 'fastify-plugin';
+import { FastifyPluginAsync } from 'fastify';
+
+declare module 'fastify' {
+  interface FastifySchema {
+    deprecatedMessage?: string;
+  }
+}
+
+const pluginCb: FastifyPluginAsync<{ defaultDeprecatedMessage: string }> = async (
+  fastify,
+  options
+) => {
+  fastify.addHook('onSend', async (request, reply) => {
+    if (request.routeOptions.schema?.deprecated) {
+      const warningMessage =
+        request.routeOptions.schema.deprecatedMessage ??
+        options.defaultDeprecatedMessage ??
+        'Endpoint is deprecated';
+      const warning = `299 - "Deprecated: ${warningMessage}"`;
+      if (!reply.getHeader('Warning')) {
+        void reply.header('Warning', warning);
+      }
+    }
+  });
+  await Promise.resolve();
+};
+
+/**
+ * Fastify plugin that adds deprecation warnings to HTTP responses.
+ *
+ * If a route's schema has `deprecated: true`, a `Warning` header will be added to the response.
+ * - If the schema includes a `deprecatedMessage`, it will be used in the warning.
+ * - If not, the plugin uses the `defaultDeprecatedMessage` provided in the plugin options.
+ * - If neither is available, a generic warning message `299 - "Deprecated"` is used.
+ */
+const DeprecationPlugin = fp(pluginCb);
+
+export default DeprecationPlugin;

src/api/init.ts

@@ -57,6 +57,7 @@ import FastifyMetrics from 'fastify-metrics';
 import FastifyCors from '@fastify/cors';
 import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
 import * as promClient from 'prom-client';
+import DeprecationPlugin from './deprecation-plugin';
 
 export interface ApiServer {
   fastifyApp: FastifyInstance;
@@ -271,6 +272,11 @@ export async function startApiServer(opts: {
   // Setup direct proxy to core-node RPC endpoints (/v2)
   await fastify.register(CoreNodeRpcProxyRouter, { prefix: '/v2' });
 
+  // Middleware to annotate http responses with deprecation warnings
+  await fastify.register(DeprecationPlugin, {
+    defaultDeprecatedMessage: 'See https://docs.hiro.so/stacks/api for more information',
+  });
+
   // Wait for all routes and middleware to be ready before starting the server
   await fastify.ready();
 

tests/api/address.test.ts

@@ -1547,6 +1547,9 @@ describe('address tests', () => {
     );
     expect(fetchAddrBalance1.status).toBe(200);
     expect(fetchAddrBalance1.type).toBe('application/json');
+    expect(fetchAddrBalance1.headers['warning']).toBe(
+      '299 - "Deprecated: See https://docs.hiro.so/stacks/api for more information"'
+    );
     const expectedResp1 = {
       stx: {
         balance: '88679',