@kb-labs/rest-api-app 1.3.0 → 1.4.0

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

@@ -1,283 +0,0 @@
-/**
- * @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

@@ -1,160 +0,0 @@
-/**
- * @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

@@ -1,67 +0,0 @@
-/**
- * @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

@@ -1,136 +0,0 @@
-/**
- * @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;
-  });
-}
-