feat: add caching control (#85)

DakEnviy · web-flow · commit 182169f062fa · 2025-11-10T16:58:55.000+01:00
diff --git a/README-ru.md b/README-ru.md
@@ -53,3 +53,32 @@ const config: Partial<AppConfig> = {
 
 export default config;
 ```
+
+## Управление кешированием
+
+По умолчанию ExpressKit устанавливает `no-cache` заголовки на все ответы. Вы можете управлять этим поведением глобально или на уровне маршрута.
+
+### Глобальная конфигурация
+
+```typescript
+const config: Partial<AppConfig> = {
+  expressEnableCaching: true, // Разрешить кеширование по умолчанию
+};
+```
+
+### Конфигурация на уровне маршрута
+
+```typescript
+const app = new ExpressKit(nodekit, {
+  'GET /api/cached': {
+    enableCaching: true, // Разрешить кеширование для этого маршрута
+    handler: (req, res) => res.json({data: 'кешируемые'}),
+  },
+  'GET /api/fresh': {
+    enableCaching: false, // Принудительно no-cache
+    handler: (req, res) => res.json({data: 'всегда свежие'}),
+  },
+});
+```
+
+Настройка `enableCaching` на уровне маршрута переопределяет глобальную. Состояние доступно в `req.routeInfo.enableCaching`.
diff --git a/README.md b/README.md
@@ -128,3 +128,32 @@ const app = new ExpressKit(nodekit, {
   },
 });
 ```
+
+## Caching Control
+
+By default, ExpressKit sets `no-cache` headers on all responses. You can control this behavior globally or per-route.
+
+### Global configuration
+
+```typescript
+const config: Partial<AppConfig> = {
+  expressEnableCaching: true, // Allow caching by default
+};
+```
+
+### Per-route configuration
+
+```typescript
+const app = new ExpressKit(nodekit, {
+  'GET /api/cached': {
+    enableCaching: true, // Allow caching for this route
+    handler: (req, res) => res.json({data: 'cacheable'}),
+  },
+  'GET /api/fresh': {
+    enableCaching: false, // Force no-cache
+    handler: (req, res) => res.json({data: 'always fresh'}),
+  },
+});
+```
+
+Route-level `enableCaching` overrides the global setting. The caching state is available in `req.routeInfo.enableCaching`.
diff --git a/src/base-middleware.ts b/src/base-middleware.ts
@@ -11,12 +11,6 @@ export function setupBaseMiddleware(ctx: AppContext, expressApp: Express) {
             req.id = requestId;
             res.setHeader(DEFAULT_REQUEST_ID_HEADER, requestId);
 
-            res.setHeader('Surrogate-Control', 'no-store');
-            res.setHeader(
-                'Cache-Control',
-                'no-store, max-age=0, must-revalidate, proxy-revalidate',
-            );
-
             req.routeInfo = {};
 
             const startTime = Date.now();
diff --git a/src/router.ts b/src/router.ts
@@ -91,17 +91,25 @@ export function setupRoutes(ctx: AppContext, expressApp: Express, routes: AppRou
             typeof rawRoute === 'function' ? {handler: rawRoute} : rawRoute;
 
         const {
+            handlerName: routeHandlerName,
             authPolicy: routeAuthPolicy,
+            enableCaching: routeEnableCaching,
             handler: _h,
             beforeAuth: _beforeAuth,
             afterAuth: _afterAuth,
             cspPresets,
             ...restRouteInfo
         } = route;
+
+        const handlerName = routeHandlerName || route.handler.name || UNNAMED_CONTROLLER;
         const authPolicy = routeAuthPolicy || ctx.config.appAuthPolicy || AuthPolicy.disabled;
-        const handlerName = restRouteInfo.handlerName || route.handler.name || UNNAMED_CONTROLLER;
+        const enableCaching =
+            typeof routeEnableCaching === 'boolean'
+                ? routeEnableCaching
+                : Boolean(ctx.config.expressEnableCaching);
+
         const routeInfoMiddleware: AppMiddleware = function routeInfoMiddleware(req, res, next) {
-            Object.assign(req.routeInfo, restRouteInfo, {authPolicy, handlerName});
+            Object.assign(req.routeInfo, restRouteInfo, {handlerName, authPolicy, enableCaching});
 
             res.on('finish', () => {
                 if (req.ctx.config.appTelemetryChEnableSelfStats) {
@@ -129,22 +137,34 @@ export function setupRoutes(ctx: AppContext, expressApp: Express, routes: AppRou
             next();
         };
 
-        const routeMiddleware: AppMiddleware[] = [
-            routeInfoMiddleware,
-            ...(ctx.config.expressCspEnable
-                ? [
-                      cspMiddleware({
-                          appPresets,
-                          routPresets: cspPresets,
-                          reportOnly: ctx.config.expressCspReportOnly,
-                          reportTo: ctx.config.expressCspReportTo,
-                          reportUri: ctx.config.expressCspReportUri,
-                      }),
-                  ]
-                : []),
-            ...(ctx.config.appBeforeAuthMiddleware || []),
-            ...(route.beforeAuth || []),
-        ];
+        const routeMiddleware: AppMiddleware[] = [routeInfoMiddleware];
+
+        if (!enableCaching) {
+            const cacheMiddleware: AppMiddleware = (_req, res, next) => {
+                res.setHeader('Surrogate-Control', 'no-store');
+                res.setHeader(
+                    'Cache-Control',
+                    'no-store, max-age=0, must-revalidate, proxy-revalidate',
+                );
+                next();
+            };
+            routeMiddleware.push(cacheMiddleware);
+        }
+
+        if (ctx.config.expressCspEnable) {
+            routeMiddleware.push(
+                cspMiddleware({
+                    appPresets,
+                    routPresets: cspPresets,
+                    reportOnly: ctx.config.expressCspReportOnly,
+                    reportTo: ctx.config.expressCspReportTo,
+                    reportUri: ctx.config.expressCspReportUri,
+                }),
+            );
+        }
+
+        routeMiddleware.push(...(ctx.config.appBeforeAuthMiddleware || []));
+        routeMiddleware.push(...(route.beforeAuth || []));
 
         const authHandler =
             authPolicy === AuthPolicy.disabled
diff --git a/src/tests/caching.test.ts b/src/tests/caching.test.ts
@@ -0,0 +1,86 @@
+import {ExpressKit, Request, Response} from '..';
+import {NodeKit} from '@gravity-ui/nodekit';
+import request from 'supertest';
+
+describe('Caching Control', () => {
+    it('should set no-cache headers by default', async () => {
+        const nodekit = new NodeKit({config: {}});
+        const app = new ExpressKit(nodekit, {
+            'GET /test': (_req: Request, res: Response) => {
+                res.json({ok: true});
+            },
+        });
+
+        const res = await request.agent(app.express).get('/test');
+        expect(res.headers['cache-control']).toBe(
+            'no-store, max-age=0, must-revalidate, proxy-revalidate',
+        );
+    });
+
+    it('should allow caching when expressEnableCaching is true', async () => {
+        const nodekit = new NodeKit({config: {expressEnableCaching: true}});
+        const app = new ExpressKit(nodekit, {
+            'GET /test': (_req: Request, res: Response) => {
+                res.json({ok: true});
+            },
+        });
+
+        const res = await request.agent(app.express).get('/test');
+        expect(res.headers['cache-control']).toBeUndefined();
+    });
+
+    it('should respect route-level enableCaching flag', async () => {
+        const nodekit = new NodeKit({config: {}});
+        const app = new ExpressKit(nodekit, {
+            'GET /cached': {
+                enableCaching: true,
+                handler: (_req: Request, res: Response) => {
+                    res.json({ok: true});
+                },
+            },
+            'GET /not-cached': {
+                enableCaching: false,
+                handler: (_req: Request, res: Response) => {
+                    res.json({ok: true});
+                },
+            },
+        });
+
+        const cached = await request.agent(app.express).get('/cached');
+        expect(cached.headers['cache-control']).toBeUndefined();
+
+        const notCached = await request.agent(app.express).get('/not-cached');
+        expect(notCached.headers['cache-control']).toBe(
+            'no-store, max-age=0, must-revalidate, proxy-revalidate',
+        );
+    });
+
+    it('should allow route override of global config', async () => {
+        const nodekit = new NodeKit({config: {expressEnableCaching: true}});
+        const app = new ExpressKit(nodekit, {
+            'GET /override': {
+                enableCaching: false,
+                handler: (_req: Request, res: Response) => {
+                    res.json({ok: true});
+                },
+            },
+        });
+
+        const res = await request.agent(app.express).get('/override');
+        expect(res.headers['cache-control']).toBe(
+            'no-store, max-age=0, must-revalidate, proxy-revalidate',
+        );
+    });
+
+    it('should set enableCaching in routeInfo', async () => {
+        const nodekit = new NodeKit({config: {expressEnableCaching: true}});
+        const app = new ExpressKit(nodekit, {
+            'GET /info': (req: Request, res: Response) => {
+                res.json({enableCaching: req.routeInfo.enableCaching});
+            },
+        });
+
+        const res = await request.agent(app.express).get('/info');
+        expect(res.body.enableCaching).toBe(true);
+    });
+});
diff --git a/src/types.ts b/src/types.ts
@@ -65,6 +65,8 @@ declare module '@gravity-ui/nodekit' {
         expressCspReportTo?: CSPMiddlewareParams['reportTo'];
         expressCspReportUri?: CSPMiddlewareParams['reportUri'];
 
+        expressEnableCaching?: boolean;
+
         appCsrfSecret?: string | string[];
         appCsrfLifetime?: number;
         appCsrfHeaderName?: string;
@@ -75,6 +77,7 @@ declare module '@gravity-ui/nodekit' {
         appLangQueryParamName?: string;
         appLangByTld?: Record<string, string | undefined>;
         appGetLangByHostname?: (hostname: string) => string | undefined;
+
         appValidationErrorHandler?: (ctx: AppContext) => AppErrorHandler;
     }
 
@@ -95,6 +98,7 @@ export interface AppRouteParams {
     handlerName?: string;
     disableSelfStats?: boolean;
     disableCsrf?: boolean;
+    enableCaching?: boolean;
 }
 
 export interface AppRouteDescription extends AppRouteParams {
