@kb-labs/rest-api-app 1.3.0

package/src/middleware/__tests__/rate-limit.spec.ts

@@ -0,0 +1,283 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/__tests__/rate-limit
+ *
+ * Tests for tenant-aware rate limiting middleware.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { FastifyRequest } from 'fastify';
+
+import { extractTenantId, createRateLimitMiddleware } from '../rate-limit';
+
+interface TenantRateLimiter {
+  checkLimit(tenantId: string, resource: string): Promise<RateLimitResult>;
+}
+
+interface RateLimitResult {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  resetAt: number;
+}
+
+describe('extractTenantId', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.KB_TENANT_ID;
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('should extract tenant ID from X-Tenant-ID header', () => {
+    const request = {
+      headers: { 'x-tenant-id': 'acme-corp' },
+    } as any;
+
+    expect(extractTenantId(request)).toBe('acme-corp');
+  });
+
+  it('should fall back to KB_TENANT_ID env var when header is missing', () => {
+    process.env.KB_TENANT_ID = 'env-tenant';
+
+    const request = {
+      headers: {},
+    } as any;
+
+    expect(extractTenantId(request)).toBe('env-tenant');
+  });
+
+  it('should use default when no header and no env var', () => {
+    const request = {
+      headers: {},
+    } as any;
+
+    expect(extractTenantId(request)).toBe('default');
+  });
+
+  it('should prefer header over env var', () => {
+    process.env.KB_TENANT_ID = 'env-tenant';
+
+    const request = {
+      headers: { 'x-tenant-id': 'header-tenant' },
+    } as any;
+
+    expect(extractTenantId(request)).toBe('header-tenant');
+  });
+});
+
+describe('createRateLimitMiddleware', () => {
+  let app: ReturnType<typeof Fastify>;
+  let mockRateLimiter: TenantRateLimiter;
+
+  const createMockRateLimiter = (overrides: Partial<RateLimitResult> = {}): TenantRateLimiter => {
+    const defaultResult: RateLimitResult = {
+      allowed: true,
+      limit: 100,
+      remaining: 99,
+      resetAt: Date.now() + 60000,
+      ...overrides,
+    };
+
+    return {
+      checkLimit: vi.fn().mockResolvedValue(defaultResult),
+    } as any;
+  };
+
+  beforeEach(async () => {
+    mockRateLimiter = createMockRateLimiter();
+    app = Fastify({ logger: false });
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe('allowed requests', () => {
+    it('should allow request and add rate limit headers', async () => {
+      mockRateLimiter = createMockRateLimiter({
+        allowed: true,
+        limit: 100,
+        remaining: 95,
+        resetAt: Date.now() + 60000,
+      });
+
+      const middleware = createRateLimitMiddleware(mockRateLimiter);
+      app.addHook('preHandler', middleware);
+
+      app.get('/test', async () => ({ ok: true }));
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'x-tenant-id': 'test-tenant' },
+      });
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers['x-ratelimit-limit']).toBe('100');
+      expect(response.headers['x-ratelimit-remaining']).toBe('95');
+      expect(response.headers['x-ratelimit-reset']).toBeDefined();
+
+      expect(mockRateLimiter.checkLimit).toHaveBeenCalledWith('test-tenant', 'requests');
+    });
+
+    it('should store tenantId in request context', async () => {
+      let capturedTenantId: string | undefined;
+
+      mockRateLimiter = createMockRateLimiter({ allowed: true });
+      const middleware = createRateLimitMiddleware(mockRateLimiter);
+      app.addHook('preHandler', middleware);
+
+      app.get('/test', async (request: FastifyRequest) => {
+        capturedTenantId = (request as any).tenantId;
+        return { tenantId: capturedTenantId };
+      });
+
+      await app.ready();
+
+      await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'x-tenant-id': 'captured-tenant' },
+      });
+
+      expect(capturedTenantId).toBe('captured-tenant');
+    });
+  });
+
+  describe('rate limited requests', () => {
+    it('should return 429 when rate limit exceeded', async () => {
+      const resetAt = Date.now() + 30000; // 30 seconds from now
+
+      mockRateLimiter = createMockRateLimiter({
+        allowed: false,
+        limit: 100,
+        remaining: 0,
+        resetAt,
+      });
+
+      const middleware = createRateLimitMiddleware(mockRateLimiter);
+      app.addHook('preHandler', middleware);
+
+      app.get('/test', async () => ({ ok: true }));
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'x-tenant-id': 'limited-tenant' },
+      });
+
+      expect(response.statusCode).toBe(429);
+
+      const body = response.json();
+      expect(body.error).toBe('RATE_LIMIT_EXCEEDED');
+      expect(body.message).toBe('Too many requests. Please try again later.');
+      expect(body.retryAfter).toBeDefined();
+      expect(body.limit).toBe(100);
+      expect(body.resetAt).toBeDefined();
+    });
+
+    it('should include Retry-After header when rate limited', async () => {
+      const resetAt = Date.now() + 45000; // 45 seconds from now
+
+      mockRateLimiter = createMockRateLimiter({
+        allowed: false,
+        resetAt,
+      });
+
+      const middleware = createRateLimitMiddleware(mockRateLimiter);
+      app.addHook('preHandler', middleware);
+
+      app.get('/test', async () => ({ ok: true }));
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+      });
+
+      expect(response.statusCode).toBe(429);
+      expect(response.headers['retry-after']).toBeDefined();
+
+      const retryAfter = parseInt(response.headers['retry-after'] as string, 10);
+      expect(retryAfter).toBeGreaterThan(0);
+      expect(retryAfter).toBeLessThanOrEqual(45);
+    });
+
+    it('should still include rate limit headers when limited', async () => {
+      mockRateLimiter = createMockRateLimiter({
+        allowed: false,
+        limit: 50,
+        remaining: 0,
+        resetAt: Date.now() + 60000,
+      });
+
+      const middleware = createRateLimitMiddleware(mockRateLimiter);
+      app.addHook('preHandler', middleware);
+
+      app.get('/test', async () => ({ ok: true }));
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+      });
+
+      expect(response.headers['x-ratelimit-limit']).toBe('50');
+      expect(response.headers['x-ratelimit-remaining']).toBe('0');
+    });
+  });
+
+  describe('tenant isolation', () => {
+    it('should check rate limit for each tenant separately', async () => {
+      mockRateLimiter = createMockRateLimiter({ allowed: true });
+      const middleware = createRateLimitMiddleware(mockRateLimiter);
+      app.addHook('preHandler', middleware);
+
+      app.get('/test', async () => ({ ok: true }));
+      await app.ready();
+
+      // First tenant
+      await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'x-tenant-id': 'tenant-a' },
+      });
+
+      // Second tenant
+      await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'x-tenant-id': 'tenant-b' },
+      });
+
+      expect(mockRateLimiter.checkLimit).toHaveBeenCalledTimes(2);
+      expect(mockRateLimiter.checkLimit).toHaveBeenCalledWith('tenant-a', 'requests');
+      expect(mockRateLimiter.checkLimit).toHaveBeenCalledWith('tenant-b', 'requests');
+    });
+  });
+
+  describe('default tenant', () => {
+    it('should use default tenant when no header provided', async () => {
+      mockRateLimiter = createMockRateLimiter({ allowed: true });
+      const middleware = createRateLimitMiddleware(mockRateLimiter);
+      app.addHook('preHandler', middleware);
+
+      app.get('/test', async () => ({ ok: true }));
+      await app.ready();
+
+      await app.inject({
+        method: 'GET',
+        url: '/test',
+      });
+
+      expect(mockRateLimiter.checkLimit).toHaveBeenCalledWith('default', 'requests');
+    });
+  });
+});

package/src/middleware/__tests__/request-id.spec.ts

@@ -0,0 +1,160 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/__tests__/request-id
+ *
+ * Tests for request ID middleware.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { FastifyRequest, FastifyReply } from 'fastify';
+
+import { registerRequestIdMiddleware } from '../request-id';
+
+describe('registerRequestIdMiddleware', () => {
+  let app: ReturnType<typeof Fastify>;
+
+  beforeEach(async () => {
+    app = Fastify({ logger: false });
+    registerRequestIdMiddleware(app);
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe('request ID generation', () => {
+    it('should generate request ID if not provided', async () => {
+      app.get('/test', async () => {
+        return { message: 'ok' };
+      });
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+      });
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers['x-request-id']).toBeDefined();
+      expect(response.headers['x-trace-id']).toBeDefined();
+      expect(typeof response.headers['x-request-id']).toBe('string');
+      expect(typeof response.headers['x-trace-id']).toBe('string');
+    });
+
+    it('should use provided request ID from header', async () => {
+      app.get('/test', async () => {
+        return { message: 'ok' };
+      });
+
+      await app.ready();
+
+      const customRequestId = 'custom-request-123';
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: {
+          'x-request-id': customRequestId,
+        },
+      });
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers['x-request-id']).toBe(customRequestId);
+    });
+
+    it('should use provided trace ID from header', async () => {
+      app.get('/test', async () => {
+        return { message: 'ok' };
+      });
+
+      await app.ready();
+
+      const customTraceId = 'custom-trace-456';
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: {
+          'x-trace-id': customTraceId,
+        },
+      });
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers['x-trace-id']).toBe(customTraceId);
+    });
+  });
+
+  describe('logger integration', () => {
+    it('should attach logger to request object', async () => {
+      let requestLogger: any;
+
+      app.get('/test', async (request: FastifyRequest) => {
+        requestLogger = (request as any).log;
+        return { message: 'ok' };
+      });
+
+      await app.ready();
+
+      await app.inject({
+        method: 'GET',
+        url: '/test',
+      });
+
+      // Verify request.log is defined and has expected methods
+      expect(requestLogger).toBeDefined();
+      expect(typeof requestLogger.debug).toBe('function');
+      expect(typeof requestLogger.info).toBe('function');
+      expect(typeof requestLogger.warn).toBe('function');
+      expect(typeof requestLogger.error).toBe('function');
+    });
+
+    it('should attach logger to reply object', async () => {
+      let replyLogger: any;
+
+      app.get('/test', async (request: FastifyRequest, reply: FastifyReply) => {
+        replyLogger = (reply as any).log;
+        return { message: 'ok' };
+      });
+
+      await app.ready();
+
+      await app.inject({
+        method: 'GET',
+        url: '/test',
+      });
+
+      // Verify reply.log is defined and has expected methods
+      expect(replyLogger).toBeDefined();
+      expect(typeof replyLogger.debug).toBe('function');
+      expect(typeof replyLogger.info).toBe('function');
+      expect(typeof replyLogger.warn).toBe('function');
+      expect(typeof replyLogger.error).toBe('function');
+    });
+
+    it('should allow calling logger methods without errors', async () => {
+      let requestLogger: any;
+
+      app.get('/test', async (request: FastifyRequest) => {
+        requestLogger = (request as any).log;
+
+        // Call all logger methods to ensure they work
+        requestLogger.debug('Debug message', { foo: 'bar' });
+        requestLogger.info('Info message', { baz: 'qux' });
+        requestLogger.warn('Warning message');
+        requestLogger.error('Error message');
+
+        return { message: 'ok' };
+      });
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+      });
+
+      expect(response.statusCode).toBe(200);
+      // If we got here without errors, logger methods work correctly
+      expect(requestLogger).toBeDefined();
+    });
+  });
+});

package/src/middleware/cache.ts

@@ -0,0 +1,67 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/cache
+ * Cache middleware for ETag/Last-Modified support
+ */
+
+import type { FastifyInstance } from 'fastify';
+import { createHash } from 'crypto';
+
+/**
+ * Generate ETag from content
+ */
+export function generateETag(content: string | Buffer | object): string {
+  const contentStr = typeof content === 'object' ? JSON.stringify(content) : content.toString();
+  const hash = createHash('sha256').update(contentStr).digest('hex');
+  return `"${hash.substring(0, 16)}"`; // Short hash for ETag
+}
+
+/**
+ * Register cache middleware
+ */
+export function registerCacheMiddleware(server: FastifyInstance): void {
+  server.addHook('onSend', async (request, reply, payload) => {
+    // Only cache successful GET requests
+    if (request.method !== 'GET' || reply.statusCode >= 300) {
+      return payload;
+    }
+
+    // Skip cache for streaming responses
+    if (reply.getHeader('content-type') === 'text/event-stream') {
+      return payload;
+    }
+
+    // Check If-None-Match header (ETag)
+    const ifNoneMatch = request.headers['if-none-match'];
+    if (ifNoneMatch && payload) {
+      const payloadStr = typeof payload === 'object' ? JSON.stringify(payload) : String(payload);
+      const etag = generateETag(payloadStr);
+      
+      if (ifNoneMatch === etag || ifNoneMatch === `W/${etag}`) {
+        reply.code(304).header('ETag', etag);
+        return undefined; // Not Modified
+      }
+      
+      reply.header('ETag', etag);
+    }
+
+    // Check If-Modified-Since header (Last-Modified)
+    const ifModifiedSince = request.headers['if-modified-since'];
+    if (ifModifiedSince && payload) {
+      // For now, we'll use finishedAt from job metadata if available
+      // This is a simplified implementation - in production, use actual modification time
+      const lastModified = new Date().toUTCString();
+      reply.header('Last-Modified', lastModified);
+      
+      const ifModifiedSinceDate = new Date(ifModifiedSince);
+      const lastModifiedDate = new Date(lastModified);
+      
+      if (lastModifiedDate <= ifModifiedSinceDate) {
+        reply.code(304);
+        return undefined; // Not Modified
+      }
+    }
+
+    return payload;
+  });
+}
+

package/src/middleware/envelope.ts

@@ -0,0 +1,136 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/envelope
+ * Response envelope wrapper middleware
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { errorEnvelopeSchema } from '@kb-labs/rest-api-contracts';
+
+/**
+ * Register envelope middleware
+ */
+export function registerEnvelopeMiddleware(
+  server: FastifyInstance,
+  config: RestApiConfig
+): void {
+  // Add response schema version header and wrap in envelope
+  // Use 'onSend' hook to modify payload after Fastify serializes it but before sending
+  // This ensures we get the serialized JSON string and can wrap it properly
+  server.addHook('onSend', async (request, reply, payload) => {
+    // Set header with try-catch to prevent ERR_HTTP_HEADERS_SENT
+    try {
+      if (!reply.raw.headersSent) {
+        reply.header('x-schema-version', config.apiVersion);
+      }
+    } catch (err) {
+      // Headers already sent, ignore
+    }
+
+    // Skip envelope wrapping for streaming responses
+    if (reply.getHeader('content-type') === 'text/event-stream') {
+      return payload;
+    }
+
+    // Skip if payload is not a string (Buffer or Stream)
+    if (typeof payload !== 'string') {
+      return payload;
+    }
+
+    // Parse the serialized JSON payload
+    let parsedPayload: unknown;
+    try {
+      parsedPayload = JSON.parse(payload);
+    } catch {
+      // If not JSON, return as is
+      return payload;
+    }
+
+    // If payload is already an envelope (has 'ok' field), return as is
+    if (parsedPayload && typeof parsedPayload === 'object' && 'ok' in parsedPayload) {
+      return payload;
+    }
+
+    // Wrap all non-streaming responses in envelope
+    // Note: Even 4xx/5xx responses with data should be wrapped with ok: true
+    // (e.g., 503 for health/ready still contains useful data)
+
+    // Handle empty payloads
+    let dataToWrap = parsedPayload;
+
+    // If payload is undefined or null, wrap as null
+    if (parsedPayload === null || parsedPayload === undefined) {
+      dataToWrap = null;
+    }
+
+    // For responses with data (including 4xx/5xx with payload), wrap with ok: true
+    // The HTTP status code indicates the result, but envelope.ok indicates successful request processing
+    // Only responses without payload (handled by error handler) should have ok: false
+    const envelope = {
+      ok: true as const,
+      data: dataToWrap,
+      meta: {
+        requestId: (request as any).id || '',
+        durationMs: reply.elapsedTime || 0,
+        apiVersion: config.apiVersion,
+      },
+    };
+
+    // Set Content-Type header if not set
+    if (!reply.getHeader('content-type')) {
+      try {
+        if (!reply.raw.headersSent) {
+          reply.header('content-type', 'application/json');
+        }
+      } catch (err) {
+        // Headers already sent, ignore
+      }
+    }
+
+    // Serialize and return envelope as string
+    return JSON.stringify(envelope);
+  });
+
+  // Error handler
+  server.setErrorHandler(async (error: any, request, reply) => {
+    const statusCode = error.statusCode || 500;
+
+    // Extract error details
+    const errorCode = (error as any).code || 'E_INTERNAL';
+    const message = error.message || 'Internal server error';
+    const details = (error as any).details || {};
+    const cause = (error as any).cause;
+    const traceId = (error as any).traceId;
+
+    // Store error code for metrics
+    (reply as any).errorCode = errorCode;
+
+    // Log error with correlation ID
+    if ((request as any).kbLogger) {
+      (request as any).kbLogger.error('Request error', error, {
+        errorCode,
+        statusCode,
+      });
+    }
+
+    const errorEnvelope = errorEnvelopeSchema.parse({
+      ok: false,
+      error: {
+        code: errorCode,
+        message,
+        details,
+        cause,
+        traceId,
+      },
+      meta: {
+        requestId: request.id,
+        durationMs: reply.elapsedTime || 0,
+        apiVersion: config.apiVersion,
+      },
+    });
+
+    reply.status(statusCode);
+    return errorEnvelope;
+  });
+}
+