Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
4baed53713 | ||
| f10c6c0cd6 |
@@ -32,8 +32,10 @@ Day-to-day development guides:
|
||||
|
||||
- [Testing Guide](development/TESTING.md) - Unit, integration, and E2E testing
|
||||
- [Code Patterns](development/CODE-PATTERNS.md) - Common code patterns and ADR examples
|
||||
- [API Versioning](development/API-VERSIONING.md) - API versioning infrastructure and workflows
|
||||
- [Design Tokens](development/DESIGN_TOKENS.md) - UI design system and Neo-Brutalism
|
||||
- [Debugging Guide](development/DEBUGGING.md) - Common debugging patterns
|
||||
- [Dev Container](development/DEV-CONTAINER.md) - Development container setup and PM2
|
||||
|
||||
### 🔧 Operations
|
||||
|
||||
|
||||
@@ -2,9 +2,11 @@
|
||||
|
||||
**Date**: 2025-12-12
|
||||
|
||||
**Status**: Accepted (Phase 1 Complete)
|
||||
**Status**: Accepted (Phase 2 Complete - All Tasks Done)
|
||||
|
||||
**Updated**: 2026-01-26
|
||||
**Updated**: 2026-01-27
|
||||
|
||||
**Completion Note**: Phase 2 fully complete including test path migration. All 23 integration test files updated to use `/api/v1/` paths. Test suite improved from 274/348 to 345/348 passing (3 remain as todo/skipped for known issues unrelated to versioning).
|
||||
|
||||
## Context
|
||||
|
||||
@@ -43,19 +45,19 @@ We will adopt a URI-based versioning strategy for the API using a phased rollout
|
||||
|
||||
The following changes require a new API version:
|
||||
|
||||
| Change Type | Breaking? | Example |
|
||||
| ----------------------------- | --------- | -------------------------------------------- |
|
||||
| Remove endpoint | Yes | DELETE `/api/v1/legacy-feature` |
|
||||
| Remove response field | Yes | Remove `user.email` from response |
|
||||
| Change response field type | Yes | `id: number` to `id: string` |
|
||||
| Change required request field | Yes | Make `email` required when it was optional |
|
||||
| Rename endpoint | Yes | `/users` to `/accounts` |
|
||||
| Add optional response field | No | Add `user.avatar_url` |
|
||||
| Add optional request field | No | Add optional `page` parameter |
|
||||
| Add new endpoint | No | Add `/api/v1/new-feature` |
|
||||
| Fix bug in behavior | No* | Correct calculation error |
|
||||
| Change Type | Breaking? | Example |
|
||||
| ----------------------------- | --------- | ------------------------------------------ |
|
||||
| Remove endpoint | Yes | DELETE `/api/v1/legacy-feature` |
|
||||
| Remove response field | Yes | Remove `user.email` from response |
|
||||
| Change response field type | Yes | `id: number` to `id: string` |
|
||||
| Change required request field | Yes | Make `email` required when it was optional |
|
||||
| Rename endpoint | Yes | `/users` to `/accounts` |
|
||||
| Add optional response field | No | Add `user.avatar_url` |
|
||||
| Add optional request field | No | Add optional `page` parameter |
|
||||
| Add new endpoint | No | Add `/api/v1/new-feature` |
|
||||
| Fix bug in behavior | No\* | Correct calculation error |
|
||||
|
||||
*Bug fixes may warrant version increment if clients depend on the buggy behavior.
|
||||
\*Bug fixes may warrant version increment if clients depend on the buggy behavior.
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
@@ -109,6 +111,7 @@ The following changes require a new API version:
|
||||
```
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- All existing functionality works at `/api/v1/*`
|
||||
- Frontend makes requests to `/api/v1/*`
|
||||
- OpenAPI documentation reflects `/api/v1/*` paths
|
||||
@@ -246,11 +249,14 @@ export function versionRedirectMiddleware(req: Request, res: Response, next: Nex
|
||||
}
|
||||
|
||||
// Log deprecation warning
|
||||
logger.warn({
|
||||
path: req.originalUrl,
|
||||
method: req.method,
|
||||
ip: req.ip,
|
||||
}, 'Unversioned API request - redirecting to v1');
|
||||
logger.warn(
|
||||
{
|
||||
path: req.originalUrl,
|
||||
method: req.method,
|
||||
ip: req.ip,
|
||||
},
|
||||
'Unversioned API request - redirecting to v1',
|
||||
);
|
||||
|
||||
// Use 307 to preserve HTTP method
|
||||
const redirectUrl = `/api/v1${path}${req.url.includes('?') ? req.url.substring(req.url.indexOf('?')) : ''}`;
|
||||
@@ -296,13 +302,13 @@ app.use('/api/v1', (req, res, next) => {
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
| ----------------------------------- | --------------------------------------------- |
|
||||
| `server.ts` | Route registration with version prefixes |
|
||||
| `src/services/apiClient.ts` | Frontend API base URL configuration |
|
||||
| `src/config/swagger.ts` | OpenAPI server URL and version info |
|
||||
| `src/routes/*.routes.ts` | Individual route handlers |
|
||||
| `src/middleware/versionRedirect.ts` | Backwards compatibility redirects (Phase 1) |
|
||||
| File | Purpose |
|
||||
| ----------------------------------- | ------------------------------------------- |
|
||||
| `server.ts` | Route registration with version prefixes |
|
||||
| `src/services/apiClient.ts` | Frontend API base URL configuration |
|
||||
| `src/config/swagger.ts` | OpenAPI server URL and version info |
|
||||
| `src/routes/*.routes.ts` | Individual route handlers |
|
||||
| `src/middleware/versionRedirect.ts` | Backwards compatibility redirects (Phase 1) |
|
||||
|
||||
## Related ADRs
|
||||
|
||||
@@ -323,12 +329,42 @@ app.use('/api/v1', (req, res, next) => {
|
||||
- [x] Update API documentation examples (Swagger server URL updated)
|
||||
- [x] Verify all health checks work at `/api/v1/health/*`
|
||||
|
||||
### Phase 2 Tasks (Future)
|
||||
### Phase 2 Tasks
|
||||
|
||||
- [ ] Create version router factory
|
||||
- [ ] Implement deprecation header middleware
|
||||
- [ ] Add version detection to request context
|
||||
- [ ] Document versioning patterns for developers
|
||||
**Implementation Guide**: [API Versioning Infrastructure](../architecture/api-versioning-infrastructure.md)
|
||||
**Developer Guide**: [API Versioning Developer Guide](../development/API-VERSIONING.md)
|
||||
|
||||
- [x] Create version router factory (`src/routes/versioned.ts`)
|
||||
- [x] Implement deprecation header middleware (`src/middleware/deprecation.middleware.ts`)
|
||||
- [x] Add version detection to request context (`src/middleware/apiVersion.middleware.ts`)
|
||||
- [x] Add version types to Express Request (`src/types/express.d.ts`)
|
||||
- [x] Create version constants configuration (`src/config/apiVersions.ts`)
|
||||
- [x] Update server.ts to use version router factory
|
||||
- [x] Update swagger.ts for multi-server documentation
|
||||
- [x] Add unit tests for version middleware
|
||||
- [x] Add integration tests for versioned router
|
||||
- [x] Document versioning patterns for developers
|
||||
- [x] Migrate all test files to use `/api/v1/` paths (23 files, ~70 occurrences)
|
||||
|
||||
### Test Path Migration Summary (2026-01-27)
|
||||
|
||||
The final cleanup task for Phase 2 was completed by updating all integration test files to use versioned API paths:
|
||||
|
||||
| Metric | Value |
|
||||
| ---------------------------- | ---------------------------------------- |
|
||||
| Test files updated | 23 |
|
||||
| Path occurrences changed | ~70 |
|
||||
| Test failures resolved | 71 (274 -> 345 passing) |
|
||||
| Tests remaining todo/skipped | 3 (known issues, not versioning-related) |
|
||||
| Type check | Passing |
|
||||
| Versioning-specific tests | 82/82 passing |
|
||||
|
||||
**Test Results After Migration**:
|
||||
|
||||
- Integration tests: 345/348 passing
|
||||
- Unit tests: 3,375/3,391 passing (16 pre-existing failures unrelated to versioning)
|
||||
|
||||
**Migration Documentation**: [Test Path Migration Guide](../development/test-path-migration.md)
|
||||
|
||||
### Phase 3 Tasks (Future)
|
||||
|
||||
|
||||
@@ -15,9 +15,9 @@ This document tracks the implementation status and estimated effort for all Arch
|
||||
|
||||
| Status | Count |
|
||||
| ---------------------------- | ----- |
|
||||
| Accepted (Fully Implemented) | 39 |
|
||||
| Accepted (Fully Implemented) | 40 |
|
||||
| Partially Implemented | 2 |
|
||||
| Proposed (Not Started) | 15 |
|
||||
| Proposed (Not Started) | 14 |
|
||||
|
||||
---
|
||||
|
||||
@@ -44,13 +44,13 @@ This document tracks the implementation status and estimated effort for all Arch
|
||||
|
||||
### Category 3: API & Integration
|
||||
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| ------------------------------------------------------------------- | ------------------------ | ----------- | ------ | ------------------------------------- |
|
||||
| [ADR-003](./0003-standardized-input-validation-using-middleware.md) | Input Validation | Accepted | - | Fully implemented |
|
||||
| [ADR-008](./0008-api-versioning-strategy.md) | API Versioning | Proposed | L | Major URL/routing changes |
|
||||
| [ADR-018](./0018-api-documentation-strategy.md) | API Documentation | Accepted | - | OpenAPI/Swagger implemented |
|
||||
| [ADR-022](./0022-real-time-notification-system.md) | Real-time Notifications | Accepted | - | Fully implemented |
|
||||
| [ADR-028](./0028-api-response-standardization.md) | Response Standardization | Implemented | L | Completed (routes, middleware, tests) |
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| ------------------------------------------------------------------- | ------------------------ | -------- | ------ | ------------------------------------- |
|
||||
| [ADR-003](./0003-standardized-input-validation-using-middleware.md) | Input Validation | Accepted | - | Fully implemented |
|
||||
| [ADR-008](./0008-api-versioning-strategy.md) | API Versioning | Accepted | - | Phase 2 complete, tests migrated |
|
||||
| [ADR-018](./0018-api-documentation-strategy.md) | API Documentation | Accepted | - | OpenAPI/Swagger implemented |
|
||||
| [ADR-022](./0022-real-time-notification-system.md) | Real-time Notifications | Accepted | - | Fully implemented |
|
||||
| [ADR-028](./0028-api-response-standardization.md) | Response Standardization | Accepted | - | Completed (routes, middleware, tests) |
|
||||
|
||||
### Category 4: Security & Compliance
|
||||
|
||||
@@ -136,47 +136,48 @@ These ADRs are proposed or partially implemented, ordered by suggested implement
|
||||
| 2 | ADR-054 | Bugsink-Gitea Sync | Proposed | L | Automated issue tracking from errors |
|
||||
| 3 | ADR-023 | Schema Migrations v2 | Proposed | L | Database evolution support |
|
||||
| 4 | ADR-029 | Secret Rotation | Proposed | L | Security improvement |
|
||||
| 5 | ADR-008 | API Versioning | Proposed | L | Future API evolution |
|
||||
| 6 | ADR-030 | Circuit Breaker | Proposed | L | Resilience improvement |
|
||||
| 7 | ADR-056 | APM (Performance) | Proposed | M | Enable when performance issues arise |
|
||||
| 8 | ADR-011 | Authorization & RBAC | Proposed | XL | Advanced permission system |
|
||||
| 9 | ADR-025 | i18n & l10n | Proposed | XL | Multi-language support |
|
||||
| 10 | ADR-031 | Data Retention & Privacy | Proposed | XL | Compliance requirements |
|
||||
| 5 | ADR-030 | Circuit Breaker | Proposed | L | Resilience improvement |
|
||||
| 6 | ADR-056 | APM (Performance) | Proposed | M | Enable when performance issues arise |
|
||||
| 7 | ADR-011 | Authorization & RBAC | Proposed | XL | Advanced permission system |
|
||||
| 8 | ADR-025 | i18n & l10n | Proposed | XL | Multi-language support |
|
||||
| 9 | ADR-031 | Data Retention & Privacy | Proposed | XL | Compliance requirements |
|
||||
|
||||
---
|
||||
|
||||
## Recent Implementation History
|
||||
|
||||
| Date | ADR | Change |
|
||||
| ---------- | ------- | ---------------------------------------------------------------------------- |
|
||||
| 2026-01-26 | ADR-015 | Completed - Added Sentry user context in AuthProvider, now fully implemented |
|
||||
| 2026-01-26 | ADR-056 | Created - APM split from ADR-015, status Proposed (tracesSampleRate=0) |
|
||||
| 2026-01-26 | ADR-015 | Refactored to focus on error tracking only, temporarily status Partial |
|
||||
| 2026-01-26 | ADR-048 | Verified as fully implemented - JWT + OAuth authentication complete |
|
||||
| 2026-01-26 | ADR-022 | Verified as fully implemented - WebSocket notifications complete |
|
||||
| 2026-01-26 | ADR-052 | Marked as fully implemented - createScopedLogger complete |
|
||||
| 2026-01-26 | ADR-053 | Marked as fully implemented - /health/queues endpoint complete |
|
||||
| 2026-01-26 | ADR-050 | Marked as fully implemented - PostgreSQL function observability |
|
||||
| 2026-01-26 | ADR-055 | Created (renumbered from duplicate ADR-023) - DB normalization |
|
||||
| 2026-01-26 | ADR-054 | Added to tracker - Bugsink to Gitea issue synchronization |
|
||||
| 2026-01-26 | ADR-053 | Added to tracker - Worker health checks and monitoring |
|
||||
| 2026-01-26 | ADR-052 | Added to tracker - Granular debug logging strategy |
|
||||
| 2026-01-26 | ADR-051 | Added to tracker - Asynchronous context propagation |
|
||||
| 2026-01-26 | ADR-048 | Added to tracker - Authentication strategy |
|
||||
| 2026-01-26 | ADR-040 | Added to tracker - Testing economics and priorities |
|
||||
| 2026-01-17 | ADR-054 | Created - Bugsink-Gitea sync worker proposal |
|
||||
| 2026-01-11 | ADR-050 | Created - PostgreSQL function observability with fn_log() |
|
||||
| 2026-01-11 | ADR-018 | Implemented - OpenAPI/Swagger documentation at /docs/api-docs |
|
||||
| 2026-01-11 | ADR-049 | Created - Gamification system, achievements, and testing |
|
||||
| 2026-01-09 | ADR-047 | Created - Project file/folder organization with migration plan |
|
||||
| 2026-01-09 | ADR-041 | Created - AI/Gemini integration with model fallback |
|
||||
| 2026-01-09 | ADR-042 | Created - Email and notification architecture with BullMQ |
|
||||
| 2026-01-09 | ADR-043 | Created - Express middleware pipeline ordering and patterns |
|
||||
| 2026-01-09 | ADR-044 | Created - Frontend feature-based folder organization |
|
||||
| 2026-01-09 | ADR-045 | Created - Test data factory pattern for mock generation |
|
||||
| 2026-01-09 | ADR-046 | Created - Image processing pipeline with Sharp and EXIF stripping |
|
||||
| 2026-01-09 | ADR-026 | Fully implemented - client-side structured logger |
|
||||
| 2026-01-09 | ADR-028 | Fully implemented - all routes, middleware, and tests updated |
|
||||
| Date | ADR | Change |
|
||||
| ---------- | ------- | ----------------------------------------------------------------------------------- |
|
||||
| 2026-01-27 | ADR-008 | Test path migration complete - 23 files, ~70 paths updated, 274->345 tests passing |
|
||||
| 2026-01-27 | ADR-008 | Phase 2 Complete - Version router factory, deprecation headers, 82 versioning tests |
|
||||
| 2026-01-26 | ADR-015 | Completed - Added Sentry user context in AuthProvider, now fully implemented |
|
||||
| 2026-01-26 | ADR-056 | Created - APM split from ADR-015, status Proposed (tracesSampleRate=0) |
|
||||
| 2026-01-26 | ADR-015 | Refactored to focus on error tracking only, temporarily status Partial |
|
||||
| 2026-01-26 | ADR-048 | Verified as fully implemented - JWT + OAuth authentication complete |
|
||||
| 2026-01-26 | ADR-022 | Verified as fully implemented - WebSocket notifications complete |
|
||||
| 2026-01-26 | ADR-052 | Marked as fully implemented - createScopedLogger complete |
|
||||
| 2026-01-26 | ADR-053 | Marked as fully implemented - /health/queues endpoint complete |
|
||||
| 2026-01-26 | ADR-050 | Marked as fully implemented - PostgreSQL function observability |
|
||||
| 2026-01-26 | ADR-055 | Created (renumbered from duplicate ADR-023) - DB normalization |
|
||||
| 2026-01-26 | ADR-054 | Added to tracker - Bugsink to Gitea issue synchronization |
|
||||
| 2026-01-26 | ADR-053 | Added to tracker - Worker health checks and monitoring |
|
||||
| 2026-01-26 | ADR-052 | Added to tracker - Granular debug logging strategy |
|
||||
| 2026-01-26 | ADR-051 | Added to tracker - Asynchronous context propagation |
|
||||
| 2026-01-26 | ADR-048 | Added to tracker - Authentication strategy |
|
||||
| 2026-01-26 | ADR-040 | Added to tracker - Testing economics and priorities |
|
||||
| 2026-01-17 | ADR-054 | Created - Bugsink-Gitea sync worker proposal |
|
||||
| 2026-01-11 | ADR-050 | Created - PostgreSQL function observability with fn_log() |
|
||||
| 2026-01-11 | ADR-018 | Implemented - OpenAPI/Swagger documentation at /docs/api-docs |
|
||||
| 2026-01-11 | ADR-049 | Created - Gamification system, achievements, and testing |
|
||||
| 2026-01-09 | ADR-047 | Created - Project file/folder organization with migration plan |
|
||||
| 2026-01-09 | ADR-041 | Created - AI/Gemini integration with model fallback |
|
||||
| 2026-01-09 | ADR-042 | Created - Email and notification architecture with BullMQ |
|
||||
| 2026-01-09 | ADR-043 | Created - Express middleware pipeline ordering and patterns |
|
||||
| 2026-01-09 | ADR-044 | Created - Frontend feature-based folder organization |
|
||||
| 2026-01-09 | ADR-045 | Created - Test data factory pattern for mock generation |
|
||||
| 2026-01-09 | ADR-046 | Created - Image processing pipeline with Sharp and EXIF stripping |
|
||||
| 2026-01-09 | ADR-026 | Fully implemented - client-side structured logger |
|
||||
| 2026-01-09 | ADR-028 | Fully implemented - all routes, middleware, and tests updated |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -762,11 +762,14 @@ The system architecture is governed by Architecture Decision Records (ADRs). Key
|
||||
|
||||
### API and Integration
|
||||
|
||||
| ADR | Title | Status |
|
||||
| ------- | ----------------------------- | ----------- |
|
||||
| ADR-003 | Standardized Input Validation | Accepted |
|
||||
| ADR-022 | Real-time Notification System | Proposed |
|
||||
| ADR-028 | API Response Standardization | Implemented |
|
||||
| ADR | Title | Status |
|
||||
| ------- | ----------------------------- | ---------------- |
|
||||
| ADR-003 | Standardized Input Validation | Accepted |
|
||||
| ADR-008 | API Versioning Strategy | Phase 1 Complete |
|
||||
| ADR-022 | Real-time Notification System | Proposed |
|
||||
| ADR-028 | API Response Standardization | Implemented |
|
||||
|
||||
**Implementation Guide**: [API Versioning Infrastructure](./api-versioning-infrastructure.md) (Phase 2)
|
||||
|
||||
### Security
|
||||
|
||||
|
||||
521
docs/architecture/api-versioning-infrastructure.md
Normal file
521
docs/architecture/api-versioning-infrastructure.md
Normal file
@@ -0,0 +1,521 @@
|
||||
# API Versioning Infrastructure (ADR-008 Phase 2)
|
||||
|
||||
**Status**: Complete
|
||||
**Date**: 2026-01-27
|
||||
**Prerequisite**: ADR-008 Phase 1 Complete (all routes at `/api/v1/*`)
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
Phase 2 has been fully implemented with the following results:
|
||||
|
||||
| Metric | Value |
|
||||
| ------------------ | -------------------------------------- |
|
||||
| New Files Created | 5 |
|
||||
| Files Modified | 2 (server.ts, express.d.ts) |
|
||||
| Unit Tests | 82 passing (100%) |
|
||||
| Integration Tests | 48 new versioning tests |
|
||||
| RFC Compliance | RFC 8594 (Sunset), RFC 8288 (Link) |
|
||||
| Supported Versions | v1 (active), v2 (infrastructure ready) |
|
||||
|
||||
**Developer Guide**: [API-VERSIONING.md](../development/API-VERSIONING.md)
|
||||
|
||||
## Purpose
|
||||
|
||||
Build infrastructure to support parallel API versions, version detection, and deprecation workflows. Enables future v2 API without breaking existing clients.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```text
|
||||
Request → Version Router → Version Middleware → Domain Router → Handler
|
||||
↓ ↓
|
||||
createVersionedRouter() attachVersionInfo()
|
||||
↓ ↓
|
||||
/api/v1/* | /api/v2/* req.apiVersion = 'v1'|'v2'
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
| Component | File | Responsibility |
|
||||
| ---------------------- | ------------------------------------------ | ------------------------------------------ |
|
||||
| Version Router Factory | `src/routes/versioned.ts` | Create version-specific Express routers |
|
||||
| Version Middleware | `src/middleware/apiVersion.middleware.ts` | Extract version, attach to request context |
|
||||
| Deprecation Middleware | `src/middleware/deprecation.middleware.ts` | Add RFC 8594 deprecation headers |
|
||||
| Version Types | `src/types/express.d.ts` | Extend Express Request with apiVersion |
|
||||
| Version Constants | `src/config/apiVersions.ts` | Centralized version definitions |
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Task 1: Version Types (Foundation)
|
||||
|
||||
**File**: `src/types/express.d.ts`
|
||||
|
||||
```typescript
|
||||
declare global {
|
||||
namespace Express {
|
||||
interface Request {
|
||||
apiVersion?: 'v1' | 'v2';
|
||||
versionDeprecated?: boolean;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**: None
|
||||
**Testing**: Type-check only (`npm run type-check`)
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Version Constants
|
||||
|
||||
**File**: `src/config/apiVersions.ts`
|
||||
|
||||
```typescript
|
||||
export const API_VERSIONS = ['v1', 'v2'] as const;
|
||||
export type ApiVersion = (typeof API_VERSIONS)[number];
|
||||
|
||||
export const CURRENT_VERSION: ApiVersion = 'v1';
|
||||
export const DEFAULT_VERSION: ApiVersion = 'v1';
|
||||
|
||||
export interface VersionConfig {
|
||||
version: ApiVersion;
|
||||
status: 'active' | 'deprecated' | 'sunset';
|
||||
sunsetDate?: string; // ISO 8601
|
||||
successorVersion?: ApiVersion;
|
||||
}
|
||||
|
||||
export const VERSION_CONFIG: Record<ApiVersion, VersionConfig> = {
|
||||
v1: { version: 'v1', status: 'active' },
|
||||
v2: { version: 'v2', status: 'active' },
|
||||
};
|
||||
```
|
||||
|
||||
**Dependencies**: None
|
||||
**Testing**: Unit test for version validation
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Version Detection Middleware
|
||||
|
||||
**File**: `src/middleware/apiVersion.middleware.ts`
|
||||
|
||||
```typescript
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { API_VERSIONS, ApiVersion, DEFAULT_VERSION } from '../config/apiVersions';
|
||||
|
||||
export function extractApiVersion(req: Request, _res: Response, next: NextFunction) {
|
||||
// Extract from URL path: /api/v1/... → 'v1'
|
||||
const pathMatch = req.path.match(/^\/v(\d+)\//);
|
||||
if (pathMatch) {
|
||||
const version = `v${pathMatch[1]}` as ApiVersion;
|
||||
if (API_VERSIONS.includes(version)) {
|
||||
req.apiVersion = version;
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback to default if not detected
|
||||
req.apiVersion = req.apiVersion || DEFAULT_VERSION;
|
||||
next();
|
||||
}
|
||||
```
|
||||
|
||||
**Pattern**: Attach to request before route handlers
|
||||
**Integration Point**: `server.ts` before versioned route mounting
|
||||
**Testing**: Unit tests for path extraction, default fallback
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Deprecation Headers Middleware
|
||||
|
||||
**File**: `src/middleware/deprecation.middleware.ts`
|
||||
|
||||
Implements RFC 8594 (Sunset Header) and draft-ietf-httpapi-deprecation-header.
|
||||
|
||||
```typescript
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { VERSION_CONFIG, ApiVersion } from '../config/apiVersions';
|
||||
import { logger } from '../services/logger.server';
|
||||
|
||||
export function deprecationHeaders(version: ApiVersion) {
|
||||
const config = VERSION_CONFIG[version];
|
||||
|
||||
return (req: Request, res: Response, next: NextFunction) => {
|
||||
if (config.status === 'deprecated') {
|
||||
res.set('Deprecation', 'true');
|
||||
|
||||
if (config.sunsetDate) {
|
||||
res.set('Sunset', config.sunsetDate);
|
||||
}
|
||||
|
||||
if (config.successorVersion) {
|
||||
res.set('Link', `</api/${config.successorVersion}>; rel="successor-version"`);
|
||||
}
|
||||
|
||||
req.versionDeprecated = true;
|
||||
|
||||
// Log deprecation access for monitoring
|
||||
logger.warn(
|
||||
{
|
||||
apiVersion: version,
|
||||
path: req.path,
|
||||
method: req.method,
|
||||
sunsetDate: config.sunsetDate,
|
||||
},
|
||||
'Deprecated API version accessed',
|
||||
);
|
||||
}
|
||||
|
||||
// Always set version header
|
||||
res.set('X-API-Version', version);
|
||||
next();
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
**RFC Compliance**:
|
||||
|
||||
- `Deprecation: true` (draft-ietf-httpapi-deprecation-header)
|
||||
- `Sunset: <date>` (RFC 8594)
|
||||
- `Link: <url>; rel="successor-version"` (RFC 8288)
|
||||
|
||||
**Testing**: Unit tests for header presence, version status variations
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Version Router Factory
|
||||
|
||||
**File**: `src/routes/versioned.ts`
|
||||
|
||||
```typescript
|
||||
import { Router } from 'express';
|
||||
import { ApiVersion } from '../config/apiVersions';
|
||||
import { extractApiVersion } from '../middleware/apiVersion.middleware';
|
||||
import { deprecationHeaders } from '../middleware/deprecation.middleware';
|
||||
|
||||
// Import domain routers
|
||||
import authRouter from './auth.routes';
|
||||
import userRouter from './user.routes';
|
||||
import flyerRouter from './flyer.routes';
|
||||
// ... all domain routers
|
||||
|
||||
interface VersionedRouters {
|
||||
v1: Record<string, Router>;
|
||||
v2: Record<string, Router>;
|
||||
}
|
||||
|
||||
const ROUTERS: VersionedRouters = {
|
||||
v1: {
|
||||
auth: authRouter,
|
||||
users: userRouter,
|
||||
flyers: flyerRouter,
|
||||
// ... all v1 routers (current implementation)
|
||||
},
|
||||
v2: {
|
||||
// Future: v2-specific routers
|
||||
// auth: authRouterV2,
|
||||
// For now, fallback to v1
|
||||
},
|
||||
};
|
||||
|
||||
export function createVersionedRouter(version: ApiVersion): Router {
|
||||
const router = Router();
|
||||
|
||||
// Apply version middleware
|
||||
router.use(extractApiVersion);
|
||||
router.use(deprecationHeaders(version));
|
||||
|
||||
// Get routers for this version, fallback to v1
|
||||
const versionRouters = ROUTERS[version] || ROUTERS.v1;
|
||||
|
||||
// Mount domain routers
|
||||
Object.entries(versionRouters).forEach(([path, domainRouter]) => {
|
||||
router.use(`/${path}`, domainRouter);
|
||||
});
|
||||
|
||||
return router;
|
||||
}
|
||||
```
|
||||
|
||||
**Pattern**: Factory function returns configured Router
|
||||
**Fallback Strategy**: v2 uses v1 routers until v2-specific handlers exist
|
||||
**Testing**: Integration test verifying route mounting
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Server Integration
|
||||
|
||||
**File**: `server.ts` (modifications)
|
||||
|
||||
```typescript
|
||||
// Before (current implementation - Phase 1):
|
||||
app.use('/api/v1/auth', authRouter);
|
||||
app.use('/api/v1/users', userRouter);
|
||||
// ... individual route mounting
|
||||
|
||||
// After (Phase 2):
|
||||
import { createVersionedRouter } from './src/routes/versioned';
|
||||
|
||||
// Mount versioned API routers
|
||||
app.use('/api/v1', createVersionedRouter('v1'));
|
||||
app.use('/api/v2', createVersionedRouter('v2')); // Placeholder for future
|
||||
|
||||
// Keep redirect middleware for unversioned requests
|
||||
app.use('/api', versionRedirectMiddleware);
|
||||
```
|
||||
|
||||
**Breaking Change Risk**: Low (same routes, different mounting)
|
||||
**Rollback**: Revert to individual `app.use()` calls
|
||||
**Testing**: Full integration test suite must pass
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Request Context Propagation
|
||||
|
||||
**Pattern**: Version flows through request lifecycle for conditional logic.
|
||||
|
||||
```typescript
|
||||
// In any route handler or service:
|
||||
function handler(req: Request, res: Response) {
|
||||
if (req.apiVersion === 'v2') {
|
||||
// v2-specific behavior
|
||||
return sendSuccess(res, transformV2(data));
|
||||
}
|
||||
// v1 behavior (default)
|
||||
return sendSuccess(res, data);
|
||||
}
|
||||
```
|
||||
|
||||
**Use Cases**:
|
||||
|
||||
- Response transformation based on version
|
||||
- Feature flags per version
|
||||
- Metric tagging by version
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Documentation Update
|
||||
|
||||
**File**: `src/config/swagger.ts` (modifications)
|
||||
|
||||
```typescript
|
||||
const swaggerDefinition: OpenAPIV3.Document = {
|
||||
// ...
|
||||
servers: [
|
||||
{
|
||||
url: '/api/v1',
|
||||
description: 'API v1 (Current)',
|
||||
},
|
||||
{
|
||||
url: '/api/v2',
|
||||
description: 'API v2 (Future)',
|
||||
},
|
||||
],
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
**File**: `docs/adr/0008-api-versioning-strategy.md` (update checklist)
|
||||
|
||||
---
|
||||
|
||||
### Task 9: Unit Tests
|
||||
|
||||
**File**: `src/middleware/apiVersion.middleware.test.ts`
|
||||
|
||||
```typescript
|
||||
describe('extractApiVersion', () => {
|
||||
it('extracts v1 from /api/v1/users', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('extracts v2 from /api/v2/users', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('defaults to v1 for unversioned paths', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('ignores invalid version numbers', () => {
|
||||
/* ... */
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**File**: `src/middleware/deprecation.middleware.test.ts`
|
||||
|
||||
```typescript
|
||||
describe('deprecationHeaders', () => {
|
||||
it('adds no headers for active version', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('adds Deprecation header for deprecated version', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('adds Sunset header when sunsetDate configured', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('adds Link header for successor version', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('always sets X-API-Version header', () => {
|
||||
/* ... */
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 10: Integration Tests
|
||||
|
||||
**File**: `src/routes/versioned.test.ts`
|
||||
|
||||
```typescript
|
||||
describe('Versioned Router Integration', () => {
|
||||
it('mounts all v1 routes correctly', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('v2 falls back to v1 handlers', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('sets X-API-Version response header', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('deprecation headers appear when configured', () => {
|
||||
/* ... */
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Run in Container**: `podman exec -it flyer-crawler-dev npm test -- versioned`
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
```text
|
||||
[Task 1] → [Task 2] → [Task 3] → [Task 4] → [Task 5] → [Task 6]
|
||||
Types Config Middleware Middleware Factory Server
|
||||
↓ ↓ ↓ ↓
|
||||
[Task 7] [Task 9] [Task 10] [Task 8]
|
||||
Context Unit Integ Docs
|
||||
```
|
||||
|
||||
**Critical Path**: 1 → 2 → 3 → 5 → 6 (server integration)
|
||||
|
||||
## File Structure After Implementation
|
||||
|
||||
```text
|
||||
src/
|
||||
├── config/
|
||||
│ ├── apiVersions.ts # NEW: Version constants
|
||||
│ └── swagger.ts # MODIFIED: Multi-server
|
||||
├── middleware/
|
||||
│ ├── apiVersion.middleware.ts # NEW: Version extraction
|
||||
│ ├── apiVersion.middleware.test.ts # NEW: Unit tests
|
||||
│ ├── deprecation.middleware.ts # NEW: RFC 8594 headers
|
||||
│ └── deprecation.middleware.test.ts # NEW: Unit tests
|
||||
├── routes/
|
||||
│ ├── versioned.ts # NEW: Router factory
|
||||
│ ├── versioned.test.ts # NEW: Integration tests
|
||||
│ └── *.routes.ts # UNCHANGED: Domain routers
|
||||
├── types/
|
||||
│ └── express.d.ts # MODIFIED: Add apiVersion
|
||||
server.ts # MODIFIED: Use versioned router
|
||||
```
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
| ------------------------------------ | ---------- | ------ | ----------------------------------- |
|
||||
| Route registration order breaks | Medium | High | Full integration test suite |
|
||||
| Middleware not applied to all routes | Low | Medium | Factory pattern ensures consistency |
|
||||
| Performance impact from middleware | Low | Low | Minimal overhead (path regex) |
|
||||
| Type errors in extended Request | Low | Medium | TypeScript strict mode catches |
|
||||
|
||||
## Rollback Procedure
|
||||
|
||||
1. Revert `server.ts` to individual route mounting
|
||||
2. Remove new middleware files (not breaking)
|
||||
3. Remove version types from `express.d.ts`
|
||||
4. Run `npm run type-check && npm test` to verify
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [x] All existing tests pass (`npm test` in container)
|
||||
- [x] `X-API-Version: v1` header on all `/api/v1/*` responses
|
||||
- [x] TypeScript compiles without errors (`npm run type-check`)
|
||||
- [x] No performance regression (< 5ms added latency)
|
||||
- [x] Deprecation headers work when v1 marked deprecated (manual test)
|
||||
|
||||
## Known Issues and Follow-up Work
|
||||
|
||||
### Integration Tests Using Unversioned Paths
|
||||
|
||||
**Issue**: Some existing integration tests make requests to unversioned paths (e.g., `/api/flyers` instead of `/api/v1/flyers`). These tests now receive 301 redirects due to the backwards compatibility middleware.
|
||||
|
||||
**Impact**: 74 integration tests may need updates to use versioned paths explicitly.
|
||||
|
||||
**Workaround Options**:
|
||||
|
||||
1. Update test paths to use `/api/v1/*` explicitly (recommended)
|
||||
2. Configure supertest to follow redirects automatically
|
||||
3. Accept 301 as valid response in affected tests
|
||||
|
||||
**Resolution**: Phase 3 work item - update integration tests to use versioned endpoints consistently.
|
||||
|
||||
### Phase 3 Prerequisites
|
||||
|
||||
Before marking v1 as deprecated and implementing v2:
|
||||
|
||||
1. Update all integration tests to use versioned paths
|
||||
2. Define breaking changes requiring v2
|
||||
3. Create v2-specific route handlers where needed
|
||||
4. Set deprecation timeline for v1
|
||||
|
||||
## Related ADRs
|
||||
|
||||
| ADR | Relationship |
|
||||
| ------- | ------------------------------------------------- |
|
||||
| ADR-008 | Parent decision (this implements Phase 2) |
|
||||
| ADR-003 | Validation middleware pattern applies per-version |
|
||||
| ADR-028 | Response format consistent across versions |
|
||||
| ADR-018 | OpenAPI docs reflect versioned endpoints |
|
||||
| ADR-043 | Middleware pipeline order considerations |
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Checking Version in Handler
|
||||
|
||||
```typescript
|
||||
// src/routes/flyer.routes.ts
|
||||
router.get('/', async (req, res) => {
|
||||
const flyers = await flyerRepo.getFlyers(req.log);
|
||||
|
||||
// Version-specific response transformation
|
||||
if (req.apiVersion === 'v2') {
|
||||
return sendSuccess(res, flyers.map(transformFlyerV2));
|
||||
}
|
||||
return sendSuccess(res, flyers);
|
||||
});
|
||||
```
|
||||
|
||||
### Marking Version as Deprecated
|
||||
|
||||
```typescript
|
||||
// src/config/apiVersions.ts
|
||||
export const VERSION_CONFIG = {
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
},
|
||||
v2: { version: 'v2', status: 'active' },
|
||||
};
|
||||
```
|
||||
|
||||
### Testing Deprecation Headers
|
||||
|
||||
```bash
|
||||
curl -I https://localhost:3001/api/v1/flyers
|
||||
# When v1 deprecated:
|
||||
# Deprecation: true
|
||||
# Sunset: 2027-01-01T00:00:00Z
|
||||
# Link: </api/v2>; rel="successor-version"
|
||||
# X-API-Version: v1
|
||||
```
|
||||
844
docs/development/API-VERSIONING.md
Normal file
844
docs/development/API-VERSIONING.md
Normal file
@@ -0,0 +1,844 @@
|
||||
# API Versioning Developer Guide
|
||||
|
||||
**Status**: Complete (Phase 2)
|
||||
**Last Updated**: 2026-01-27
|
||||
**Implements**: ADR-008 Phase 2
|
||||
**Architecture**: [api-versioning-infrastructure.md](../architecture/api-versioning-infrastructure.md)
|
||||
|
||||
This guide covers the API versioning infrastructure for the Flyer Crawler application. It explains how versioning works, how to add new versions, and how to deprecate old ones.
|
||||
|
||||
## Implementation Status
|
||||
|
||||
| Component | Status | Tests |
|
||||
| ------------------------------ | -------- | -------------------- |
|
||||
| Version Constants | Complete | Unit tests |
|
||||
| Version Detection Middleware | Complete | 25 unit tests |
|
||||
| Deprecation Headers Middleware | Complete | 30 unit tests |
|
||||
| Version Router Factory | Complete | Integration tests |
|
||||
| Server Integration | Complete | 48 integration tests |
|
||||
| Developer Documentation | Complete | This guide |
|
||||
|
||||
**Total Tests**: 82 versioning-specific tests (100% passing)
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Architecture](#architecture)
|
||||
3. [Key Concepts](#key-concepts)
|
||||
4. [Developer Workflows](#developer-workflows)
|
||||
5. [Version Headers](#version-headers)
|
||||
6. [Testing Versioned Endpoints](#testing-versioned-endpoints)
|
||||
7. [Migration Guide: v1 to v2](#migration-guide-v1-to-v2)
|
||||
8. [Troubleshooting](#troubleshooting)
|
||||
9. [Related Documentation](#related-documentation)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The API uses URI-based versioning with the format `/api/v{MAJOR}/resource`. All endpoints are accessible at versioned paths like `/api/v1/flyers` or `/api/v2/users`.
|
||||
|
||||
### Current Version Status
|
||||
|
||||
| Version | Status | Description |
|
||||
| ------- | ------ | ------------------------------------- |
|
||||
| v1 | Active | Current production version |
|
||||
| v2 | Active | Future version (infrastructure ready) |
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Automatic version detection** from URL path
|
||||
- **RFC 8594 compliant deprecation headers** when versions are deprecated
|
||||
- **Backwards compatibility** via 301 redirects from unversioned paths
|
||||
- **Version-aware request context** for conditional logic in handlers
|
||||
- **Centralized configuration** for version lifecycle management
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Request Flow
|
||||
|
||||
```text
|
||||
Client Request: GET /api/v1/flyers
|
||||
|
|
||||
v
|
||||
+------+-------+
|
||||
| server.ts |
|
||||
| - Redirect |
|
||||
| middleware |
|
||||
+------+-------+
|
||||
|
|
||||
v
|
||||
+------+-------+
|
||||
| createApi |
|
||||
| Router() |
|
||||
+------+-------+
|
||||
|
|
||||
v
|
||||
+------+-------+
|
||||
| detectApi |
|
||||
| Version |
|
||||
| middleware |
|
||||
+------+-------+
|
||||
| req.apiVersion = 'v1'
|
||||
v
|
||||
+------+-------+
|
||||
| Versioned |
|
||||
| Router |
|
||||
| (v1) |
|
||||
+------+-------+
|
||||
|
|
||||
v
|
||||
+------+-------+
|
||||
| addDepreca |
|
||||
| tionHeaders |
|
||||
| middleware |
|
||||
+------+-------+
|
||||
| X-API-Version: v1
|
||||
v
|
||||
+------+-------+
|
||||
| Domain |
|
||||
| Router |
|
||||
| (flyers) |
|
||||
+------+-------+
|
||||
|
|
||||
v
|
||||
Response
|
||||
```
|
||||
|
||||
### Component Overview
|
||||
|
||||
| Component | File | Purpose |
|
||||
| ------------------- | ------------------------------------------ | ----------------------------------------------------- |
|
||||
| Version Constants | `src/config/apiVersions.ts` | Type definitions, version configs, utility functions |
|
||||
| Version Detection | `src/middleware/apiVersion.middleware.ts` | Extract version from URL, validate, attach to request |
|
||||
| Deprecation Headers | `src/middleware/deprecation.middleware.ts` | Add RFC 8594 headers for deprecated versions |
|
||||
| Router Factory | `src/routes/versioned.ts` | Create version-specific Express routers |
|
||||
| Type Extensions | `src/types/express.d.ts` | Add `apiVersion` and `versionDeprecation` to Request |
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### 1. Version Configuration
|
||||
|
||||
All version definitions live in `src/config/apiVersions.ts`:
|
||||
|
||||
```typescript
|
||||
// src/config/apiVersions.ts
|
||||
|
||||
// Supported versions as a const tuple
|
||||
export const API_VERSIONS = ['v1', 'v2'] as const;
|
||||
|
||||
// Union type: 'v1' | 'v2'
|
||||
export type ApiVersion = (typeof API_VERSIONS)[number];
|
||||
|
||||
// Version lifecycle status
|
||||
export type VersionStatus = 'active' | 'deprecated' | 'sunset';
|
||||
|
||||
// Configuration for each version
|
||||
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'active',
|
||||
},
|
||||
v2: {
|
||||
version: 'v2',
|
||||
status: 'active',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Version Detection
|
||||
|
||||
The `detectApiVersion` middleware extracts the version from `req.params.version` and validates it:
|
||||
|
||||
```typescript
|
||||
// How it works (src/middleware/apiVersion.middleware.ts)
|
||||
|
||||
// For valid versions:
|
||||
// GET /api/v1/flyers -> req.apiVersion = 'v1'
|
||||
|
||||
// For invalid versions:
|
||||
// GET /api/v99/flyers -> 404 with UNSUPPORTED_VERSION error
|
||||
```
|
||||
|
||||
### 3. Request Context
|
||||
|
||||
After middleware runs, the request object has version information:
|
||||
|
||||
```typescript
|
||||
// In any route handler
|
||||
router.get('/flyers', async (req, res) => {
|
||||
// Access the detected version
|
||||
const version = req.apiVersion; // 'v1' | 'v2'
|
||||
|
||||
// Check deprecation status
|
||||
if (req.versionDeprecation?.deprecated) {
|
||||
req.log.warn(
|
||||
{
|
||||
sunset: req.versionDeprecation.sunsetDate,
|
||||
},
|
||||
'Client using deprecated API',
|
||||
);
|
||||
}
|
||||
|
||||
// Version-specific behavior
|
||||
if (req.apiVersion === 'v2') {
|
||||
return sendSuccess(res, transformV2(data));
|
||||
}
|
||||
|
||||
return sendSuccess(res, data);
|
||||
});
|
||||
```
|
||||
|
||||
### 4. Route Registration
|
||||
|
||||
Routes are registered in `src/routes/versioned.ts` with version availability:
|
||||
|
||||
```typescript
|
||||
// src/routes/versioned.ts
|
||||
|
||||
export const ROUTES: RouteRegistration[] = [
|
||||
{
|
||||
path: 'auth',
|
||||
router: authRouter,
|
||||
description: 'Authentication routes',
|
||||
// Available in all versions (no versions array)
|
||||
},
|
||||
{
|
||||
path: 'flyers',
|
||||
router: flyerRouter,
|
||||
description: 'Flyer management',
|
||||
// Available in all versions
|
||||
},
|
||||
{
|
||||
path: 'new-feature',
|
||||
router: newFeatureRouter,
|
||||
description: 'New feature only in v2',
|
||||
versions: ['v2'], // Only available in v2
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Developer Workflows
|
||||
|
||||
### Adding a New API Version (e.g., v3)
|
||||
|
||||
**Step 1**: Add version to constants (`src/config/apiVersions.ts`)
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
export const API_VERSIONS = ['v1', 'v2'] as const;
|
||||
|
||||
// After
|
||||
export const API_VERSIONS = ['v1', 'v2', 'v3'] as const;
|
||||
|
||||
// Add configuration
|
||||
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
|
||||
v1: { version: 'v1', status: 'active' },
|
||||
v2: { version: 'v2', status: 'active' },
|
||||
v3: { version: 'v3', status: 'active' }, // NEW
|
||||
};
|
||||
```
|
||||
|
||||
**Step 2**: Router cache auto-updates (no changes needed)
|
||||
|
||||
The versioned router cache in `src/routes/versioned.ts` automatically creates routers for all versions defined in `API_VERSIONS`.
|
||||
|
||||
**Step 3**: Update OpenAPI documentation (`src/config/swagger.ts`)
|
||||
|
||||
```typescript
|
||||
servers: [
|
||||
{ url: '/api/v1', description: 'API v1' },
|
||||
{ url: '/api/v2', description: 'API v2' },
|
||||
{ url: '/api/v3', description: 'API v3 (New)' }, // NEW
|
||||
],
|
||||
```
|
||||
|
||||
**Step 4**: Test the new version
|
||||
|
||||
```bash
|
||||
# In dev container
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# Manual verification
|
||||
curl -i http://localhost:3001/api/v3/health
|
||||
# Should return 200 with X-API-Version: v3 header
|
||||
```
|
||||
|
||||
### Marking a Version as Deprecated
|
||||
|
||||
**Step 1**: Update version config (`src/config/apiVersions.ts`)
|
||||
|
||||
```typescript
|
||||
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'deprecated', // Changed from 'active'
|
||||
sunsetDate: '2027-01-01T00:00:00Z', // When it will be removed
|
||||
successorVersion: 'v2', // Migration target
|
||||
},
|
||||
v2: {
|
||||
version: 'v2',
|
||||
status: 'active',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
**Step 2**: Verify deprecation headers
|
||||
|
||||
```bash
|
||||
curl -I http://localhost:3001/api/v1/health
|
||||
|
||||
# Expected headers:
|
||||
# X-API-Version: v1
|
||||
# Deprecation: true
|
||||
# Sunset: 2027-01-01T00:00:00Z
|
||||
# Link: </api/v2>; rel="successor-version"
|
||||
# X-API-Deprecation-Notice: API v1 is deprecated and will be sunset...
|
||||
```
|
||||
|
||||
**Step 3**: Monitor deprecation usage
|
||||
|
||||
Check logs for `Deprecated API version accessed` messages with context about which clients are still using deprecated versions.
|
||||
|
||||
### Adding Version-Specific Routes
|
||||
|
||||
**Scenario**: Add a new endpoint only available in v2+
|
||||
|
||||
**Step 1**: Create the route handler (new or existing file)
|
||||
|
||||
```typescript
|
||||
// src/routes/newFeature.routes.ts
|
||||
import { Router } from 'express';
|
||||
import { sendSuccess } from '../utils/apiResponse';
|
||||
|
||||
const router = Router();
|
||||
|
||||
router.get('/', async (req, res) => {
|
||||
// This endpoint only exists in v2+
|
||||
sendSuccess(res, { feature: 'new-feature-data' });
|
||||
});
|
||||
|
||||
export default router;
|
||||
```
|
||||
|
||||
**Step 2**: Register with version restriction (`src/routes/versioned.ts`)
|
||||
|
||||
```typescript
|
||||
import newFeatureRouter from './newFeature.routes';
|
||||
|
||||
export const ROUTES: RouteRegistration[] = [
|
||||
// ... existing routes ...
|
||||
{
|
||||
path: 'new-feature',
|
||||
router: newFeatureRouter,
|
||||
description: 'New feature only available in v2+',
|
||||
versions: ['v2'], // Not available in v1
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
**Step 3**: Verify route availability
|
||||
|
||||
```bash
|
||||
# v1 - should return 404
|
||||
curl -i http://localhost:3001/api/v1/new-feature
|
||||
# HTTP/1.1 404 Not Found
|
||||
|
||||
# v2 - should work
|
||||
curl -i http://localhost:3001/api/v2/new-feature
|
||||
# HTTP/1.1 200 OK
|
||||
# X-API-Version: v2
|
||||
```
|
||||
|
||||
### Adding Version-Specific Behavior in Existing Routes
|
||||
|
||||
For routes that exist in multiple versions but behave differently:
|
||||
|
||||
```typescript
|
||||
// src/routes/flyer.routes.ts
|
||||
router.get('/:id', async (req, res) => {
|
||||
const flyer = await flyerService.getFlyer(req.params.id, req.log);
|
||||
|
||||
// Different response format per version
|
||||
if (req.apiVersion === 'v2') {
|
||||
// v2 returns expanded store data
|
||||
return sendSuccess(res, {
|
||||
...flyer,
|
||||
store: await storeService.getStore(flyer.store_id, req.log),
|
||||
});
|
||||
}
|
||||
|
||||
// v1 returns just the flyer
|
||||
return sendSuccess(res, flyer);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version Headers
|
||||
|
||||
### Response Headers
|
||||
|
||||
All versioned API responses include these headers:
|
||||
|
||||
| Header | Always Present | Description |
|
||||
| -------------------------- | ------------------ | ------------------------------------------------------- |
|
||||
| `X-API-Version` | Yes | The API version handling the request |
|
||||
| `Deprecation` | Only if deprecated | `true` when version is deprecated |
|
||||
| `Sunset` | Only if configured | ISO 8601 date when version will be removed |
|
||||
| `Link` | Only if configured | URL to successor version with `rel="successor-version"` |
|
||||
| `X-API-Deprecation-Notice` | Only if deprecated | Human-readable deprecation message |
|
||||
|
||||
### Example: Active Version Response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
X-API-Version: v2
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Example: Deprecated Version Response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
X-API-Version: v1
|
||||
Deprecation: true
|
||||
Sunset: 2027-01-01T00:00:00Z
|
||||
Link: </api/v2>; rel="successor-version"
|
||||
X-API-Deprecation-Notice: API v1 is deprecated and will be sunset on 2027-01-01T00:00:00Z. Please migrate to v2.
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### RFC Compliance
|
||||
|
||||
The deprecation headers follow these standards:
|
||||
|
||||
- **RFC 8594**: The "Sunset" HTTP Header Field
|
||||
- **draft-ietf-httpapi-deprecation-header**: The "Deprecation" HTTP Header Field
|
||||
- **RFC 8288**: Web Linking (for `rel="successor-version"`)
|
||||
|
||||
---
|
||||
|
||||
## Testing Versioned Endpoints
|
||||
|
||||
### Unit Testing Middleware
|
||||
|
||||
See test files for patterns:
|
||||
|
||||
- `src/middleware/apiVersion.middleware.test.ts`
|
||||
- `src/middleware/deprecation.middleware.test.ts`
|
||||
|
||||
**Testing version detection**:
|
||||
|
||||
```typescript
|
||||
// src/middleware/apiVersion.middleware.test.ts
|
||||
import { detectApiVersion } from './apiVersion.middleware';
|
||||
import { createMockRequest } from '../tests/utils/createMockRequest';
|
||||
|
||||
describe('detectApiVersion', () => {
|
||||
it('should extract v1 from req.params.version', () => {
|
||||
const mockRequest = createMockRequest({
|
||||
params: { version: 'v1' },
|
||||
});
|
||||
const mockResponse = { status: vi.fn().mockReturnThis(), json: vi.fn() };
|
||||
const mockNext = vi.fn();
|
||||
|
||||
detectApiVersion(mockRequest, mockResponse, mockNext);
|
||||
|
||||
expect(mockRequest.apiVersion).toBe('v1');
|
||||
expect(mockNext).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should return 404 for invalid version', () => {
|
||||
const mockRequest = createMockRequest({
|
||||
params: { version: 'v99' },
|
||||
});
|
||||
const mockResponse = {
|
||||
status: vi.fn().mockReturnThis(),
|
||||
json: vi.fn(),
|
||||
};
|
||||
const mockNext = vi.fn();
|
||||
|
||||
detectApiVersion(mockRequest, mockResponse, mockNext);
|
||||
|
||||
expect(mockNext).not.toHaveBeenCalled();
|
||||
expect(mockResponse.status).toHaveBeenCalledWith(404);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Testing deprecation headers**:
|
||||
|
||||
```typescript
|
||||
// src/middleware/deprecation.middleware.test.ts
|
||||
import { addDeprecationHeaders } from './deprecation.middleware';
|
||||
import { VERSION_CONFIGS } from '../config/apiVersions';
|
||||
|
||||
describe('addDeprecationHeaders', () => {
|
||||
beforeEach(() => {
|
||||
// Mark v1 as deprecated for test
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
});
|
||||
|
||||
it('should add all deprecation headers', () => {
|
||||
const setHeader = vi.fn();
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
middleware(mockRequest, { set: setHeader }, mockNext);
|
||||
|
||||
expect(setHeader).toHaveBeenCalledWith('Deprecation', 'true');
|
||||
expect(setHeader).toHaveBeenCalledWith('Sunset', '2027-01-01T00:00:00Z');
|
||||
expect(setHeader).toHaveBeenCalledWith('Link', '</api/v2>; rel="successor-version"');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
|
||||
**Test versioned endpoints**:
|
||||
|
||||
```typescript
|
||||
import request from 'supertest';
|
||||
import app from '../../server';
|
||||
|
||||
describe('API Versioning Integration', () => {
|
||||
it('should return X-API-Version header for v1', async () => {
|
||||
const response = await request(app).get('/api/v1/health').expect(200);
|
||||
|
||||
expect(response.headers['x-api-version']).toBe('v1');
|
||||
});
|
||||
|
||||
it('should return 404 for unsupported version', async () => {
|
||||
const response = await request(app).get('/api/v99/health').expect(404);
|
||||
|
||||
expect(response.body.error.code).toBe('UNSUPPORTED_VERSION');
|
||||
});
|
||||
|
||||
it('should redirect unversioned paths to v1', async () => {
|
||||
const response = await request(app).get('/api/health').expect(301);
|
||||
|
||||
expect(response.headers.location).toBe('/api/v1/health');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests in container (required)
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# Run only middleware tests
|
||||
podman exec -it flyer-crawler-dev npm test -- apiVersion
|
||||
podman exec -it flyer-crawler-dev npm test -- deprecation
|
||||
|
||||
# Type check
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide: v1 to v2
|
||||
|
||||
When v2 is introduced with breaking changes, follow this migration process.
|
||||
|
||||
### For API Consumers (Frontend/Mobile)
|
||||
|
||||
**Step 1**: Check current API version usage
|
||||
|
||||
```typescript
|
||||
// Frontend apiClient.ts
|
||||
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api/v1';
|
||||
```
|
||||
|
||||
**Step 2**: Monitor deprecation headers
|
||||
|
||||
When v1 is deprecated, responses will include:
|
||||
|
||||
```http
|
||||
Deprecation: true
|
||||
Sunset: 2027-01-01T00:00:00Z
|
||||
Link: </api/v2>; rel="successor-version"
|
||||
```
|
||||
|
||||
**Step 3**: Update to v2
|
||||
|
||||
```typescript
|
||||
// Change API base URL
|
||||
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api/v2';
|
||||
```
|
||||
|
||||
**Step 4**: Handle response format changes
|
||||
|
||||
If v2 changes response formats, update your type definitions and parsing logic:
|
||||
|
||||
```typescript
|
||||
// v1 response
|
||||
interface FlyerResponseV1 {
|
||||
id: number;
|
||||
store_id: number;
|
||||
}
|
||||
|
||||
// v2 response (example: includes embedded store)
|
||||
interface FlyerResponseV2 {
|
||||
id: string; // Changed to UUID
|
||||
store: {
|
||||
id: string;
|
||||
name: string;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### For Backend Developers
|
||||
|
||||
**Step 1**: Create v2-specific handlers (if needed)
|
||||
|
||||
For breaking changes, create version-specific route files:
|
||||
|
||||
```text
|
||||
src/routes/
|
||||
flyer.routes.ts # Shared/v1 handlers
|
||||
flyer.v2.routes.ts # v2-specific handlers (if significantly different)
|
||||
```
|
||||
|
||||
**Step 2**: Register version-specific routes
|
||||
|
||||
```typescript
|
||||
// src/routes/versioned.ts
|
||||
export const ROUTES: RouteRegistration[] = [
|
||||
{
|
||||
path: 'flyers',
|
||||
router: flyerRouter,
|
||||
description: 'Flyer routes (v1)',
|
||||
versions: ['v1'],
|
||||
},
|
||||
{
|
||||
path: 'flyers',
|
||||
router: flyerRouterV2,
|
||||
description: 'Flyer routes (v2 with breaking changes)',
|
||||
versions: ['v2'],
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
**Step 3**: Document changes
|
||||
|
||||
Update OpenAPI documentation to reflect v2 changes and mark v1 as deprecated.
|
||||
|
||||
### Timeline Example
|
||||
|
||||
| Date | Action |
|
||||
| ---------- | ------------------------------------------ |
|
||||
| T+0 | v2 released, v1 marked deprecated |
|
||||
| T+0 | Deprecation headers added to v1 responses |
|
||||
| T+30 days | Sunset warning emails to known integrators |
|
||||
| T+90 days | v1 returns 410 Gone |
|
||||
| T+120 days | v1 code removed |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: "UNSUPPORTED_VERSION" Error
|
||||
|
||||
**Symptom**: Request to `/api/v3/...` returns 404 with `UNSUPPORTED_VERSION`
|
||||
|
||||
**Cause**: Version `v3` is not defined in `API_VERSIONS`
|
||||
|
||||
**Solution**: Add the version to `src/config/apiVersions.ts`:
|
||||
|
||||
```typescript
|
||||
export const API_VERSIONS = ['v1', 'v2', 'v3'] as const;
|
||||
|
||||
export const VERSION_CONFIGS = {
|
||||
// ...
|
||||
v3: { version: 'v3', status: 'active' },
|
||||
};
|
||||
```
|
||||
|
||||
### Issue: Missing X-API-Version Header
|
||||
|
||||
**Symptom**: Response doesn't include `X-API-Version` header
|
||||
|
||||
**Cause**: Request didn't go through versioned router
|
||||
|
||||
**Solution**: Ensure the route is registered in `src/routes/versioned.ts` and mounted under `/api/:version`
|
||||
|
||||
### Issue: Deprecation Headers Not Appearing
|
||||
|
||||
**Symptom**: Deprecated version works but no deprecation headers
|
||||
|
||||
**Cause**: Version status not set to `'deprecated'` in config
|
||||
|
||||
**Solution**: Update `VERSION_CONFIGS`:
|
||||
|
||||
```typescript
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'deprecated', // Must be 'deprecated', not 'active'
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
},
|
||||
```
|
||||
|
||||
### Issue: Route Available in Wrong Version
|
||||
|
||||
**Symptom**: Route works in v1 but should only be in v2
|
||||
|
||||
**Cause**: Missing `versions` restriction in route registration
|
||||
|
||||
**Solution**: Add `versions` array:
|
||||
|
||||
```typescript
|
||||
{
|
||||
path: 'new-feature',
|
||||
router: newFeatureRouter,
|
||||
versions: ['v2'], // Add this to restrict availability
|
||||
},
|
||||
```
|
||||
|
||||
### Issue: Unversioned Paths Not Redirecting
|
||||
|
||||
**Symptom**: `/api/flyers` returns 404 instead of redirecting to `/api/v1/flyers`
|
||||
|
||||
**Cause**: Redirect middleware order issue in `server.ts`
|
||||
|
||||
**Solution**: Ensure redirect middleware is mounted BEFORE `createApiRouter()`:
|
||||
|
||||
```typescript
|
||||
// server.ts - correct order
|
||||
app.use('/api', redirectMiddleware); // First
|
||||
app.use('/api', createApiRouter()); // Second
|
||||
```
|
||||
|
||||
### Issue: TypeScript Errors on req.apiVersion
|
||||
|
||||
**Symptom**: `Property 'apiVersion' does not exist on type 'Request'`
|
||||
|
||||
**Cause**: Type extensions not being picked up
|
||||
|
||||
**Solution**: Ensure `src/types/express.d.ts` is included in tsconfig:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"typeRoots": ["./node_modules/@types", "./src/types"]
|
||||
},
|
||||
"include": ["src/**/*"]
|
||||
}
|
||||
```
|
||||
|
||||
### Issue: Router Cache Stale After Config Change
|
||||
|
||||
**Symptom**: Version behavior doesn't update after changing `VERSION_CONFIGS`
|
||||
|
||||
**Cause**: Routers are cached at startup
|
||||
|
||||
**Solution**: Use `refreshRouterCache()` or restart the server:
|
||||
|
||||
```typescript
|
||||
import { refreshRouterCache } from './src/routes/versioned';
|
||||
|
||||
// After config changes
|
||||
refreshRouterCache();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
### Architecture Decision Records
|
||||
|
||||
| ADR | Title |
|
||||
| ------------------------------------------------------------------------ | ---------------------------- |
|
||||
| [ADR-008](../adr/0008-api-versioning-strategy.md) | API Versioning Strategy |
|
||||
| [ADR-003](../adr/0003-standardized-input-validation-using-middleware.md) | Input Validation |
|
||||
| [ADR-028](../adr/0028-api-response-standardization.md) | API Response Standardization |
|
||||
| [ADR-018](../adr/0018-api-documentation-strategy.md) | API Documentation Strategy |
|
||||
|
||||
### Implementation Files
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------------------------------------------------------------------- | ---------------------------- |
|
||||
| [`src/config/apiVersions.ts`](../../src/config/apiVersions.ts) | Version constants and config |
|
||||
| [`src/middleware/apiVersion.middleware.ts`](../../src/middleware/apiVersion.middleware.ts) | Version detection |
|
||||
| [`src/middleware/deprecation.middleware.ts`](../../src/middleware/deprecation.middleware.ts) | Deprecation headers |
|
||||
| [`src/routes/versioned.ts`](../../src/routes/versioned.ts) | Router factory |
|
||||
| [`src/types/express.d.ts`](../../src/types/express.d.ts) | Request type extensions |
|
||||
| [`server.ts`](../../server.ts) | Application entry point |
|
||||
|
||||
### Test Files
|
||||
|
||||
| File | Description |
|
||||
| ------------------------------------------------------------------------------------------------------ | ------------------------ |
|
||||
| [`src/middleware/apiVersion.middleware.test.ts`](../../src/middleware/apiVersion.middleware.test.ts) | Version detection tests |
|
||||
| [`src/middleware/deprecation.middleware.test.ts`](../../src/middleware/deprecation.middleware.test.ts) | Deprecation header tests |
|
||||
|
||||
### External References
|
||||
|
||||
- [RFC 8594: The "Sunset" HTTP Header Field](https://datatracker.ietf.org/doc/html/rfc8594)
|
||||
- [draft-ietf-httpapi-deprecation-header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/)
|
||||
- [RFC 8288: Web Linking](https://datatracker.ietf.org/doc/html/rfc8288)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Files to Modify for Common Tasks
|
||||
|
||||
| Task | Files |
|
||||
| ------------------------------ | ---------------------------------------------------- |
|
||||
| Add new version | `src/config/apiVersions.ts`, `src/config/swagger.ts` |
|
||||
| Deprecate version | `src/config/apiVersions.ts` |
|
||||
| Add version-specific route | `src/routes/versioned.ts` |
|
||||
| Version-specific handler logic | Route file (e.g., `src/routes/flyer.routes.ts`) |
|
||||
|
||||
### Key Functions
|
||||
|
||||
```typescript
|
||||
// Check if version is valid
|
||||
isValidApiVersion('v1'); // true
|
||||
isValidApiVersion('v99'); // false
|
||||
|
||||
// Get version from request with fallback
|
||||
getRequestApiVersion(req); // Returns 'v1' | 'v2'
|
||||
|
||||
// Check if request has valid version
|
||||
hasApiVersion(req); // boolean
|
||||
|
||||
// Get deprecation info
|
||||
getVersionDeprecation('v1'); // { deprecated: false, ... }
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# Type check
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
|
||||
# Check version headers manually
|
||||
curl -I http://localhost:3001/api/v1/health
|
||||
|
||||
# Test deprecation (after marking v1 deprecated)
|
||||
curl -I http://localhost:3001/api/v1/health | grep -E "(Deprecation|Sunset|Link|X-API)"
|
||||
```
|
||||
curl -I http://localhost:3001/api/v1/health | grep -E "(Deprecation|Sunset|Link|X-API)"
|
||||
```
|
||||
272
docs/development/test-path-migration.md
Normal file
272
docs/development/test-path-migration.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Test Path Migration: Unversioned to Versioned API Paths
|
||||
|
||||
**Status**: Complete
|
||||
**Created**: 2026-01-27
|
||||
**Completed**: 2026-01-27
|
||||
**Related**: ADR-008 (API Versioning Strategy)
|
||||
|
||||
## Summary
|
||||
|
||||
All integration test files have been successfully migrated to use versioned API paths (`/api/v1/`). This resolves the redirect-related test failures introduced by ADR-008 Phase 1.
|
||||
|
||||
### Results
|
||||
|
||||
| Metric | Value |
|
||||
| ------------------------- | ---------------------------------------- |
|
||||
| Test files updated | 23 |
|
||||
| Path occurrences changed | ~70 |
|
||||
| Tests before migration | 274/348 passing |
|
||||
| Tests after migration | 345/348 passing |
|
||||
| Test failures resolved | 71 |
|
||||
| Remaining todo/skipped | 3 (known issues, not versioning-related) |
|
||||
| Type check | Passing |
|
||||
| Versioning-specific tests | 82/82 passing |
|
||||
|
||||
### Key Outcomes
|
||||
|
||||
- No `301 Moved Permanently` responses in test output
|
||||
- All redirect-related failures resolved
|
||||
- No regressions introduced
|
||||
- Unit tests unaffected (3,375/3,391 passing, pre-existing failures)
|
||||
|
||||
---
|
||||
|
||||
## Original Problem Statement
|
||||
|
||||
Integration tests failed due to redirect middleware (ADR-008 Phase 1). Server returned `301 Moved Permanently` for unversioned paths (`/api/resource`) instead of expected `200 OK`. Redirect targets versioned paths (`/api/v1/resource`).
|
||||
|
||||
**Root Cause**: Backwards-compatibility redirect in `server.ts`:
|
||||
|
||||
```typescript
|
||||
app.use('/api', (req, res, next) => {
|
||||
const versionPattern = /^\/v\d+/;
|
||||
if (!versionPattern.test(req.path)) {
|
||||
return res.redirect(301, `/api/v1${req.path}`);
|
||||
}
|
||||
next();
|
||||
});
|
||||
```
|
||||
|
||||
**Impact**: ~70 test path occurrences across 23 files returning 301 instead of expected status codes.
|
||||
|
||||
## Solution
|
||||
|
||||
Update all test API paths from `/api/{resource}` to `/api/v1/{resource}`.
|
||||
|
||||
## Files Requiring Updates
|
||||
|
||||
### Integration Tests (16 files)
|
||||
|
||||
| File | Occurrences | Domains |
|
||||
| ------------------------------------------------------------ | ----------- | ---------------------- |
|
||||
| `src/tests/integration/inventory.integration.test.ts` | 14 | inventory |
|
||||
| `src/tests/integration/receipt.integration.test.ts` | 17 | receipts |
|
||||
| `src/tests/integration/recipe.integration.test.ts` | 17 | recipes, users/recipes |
|
||||
| `src/tests/integration/user.routes.integration.test.ts` | 10 | users/shopping-lists |
|
||||
| `src/tests/integration/admin.integration.test.ts` | 7 | admin |
|
||||
| `src/tests/integration/flyer-processing.integration.test.ts` | 6 | ai/jobs |
|
||||
| `src/tests/integration/budget.integration.test.ts` | 5 | budgets |
|
||||
| `src/tests/integration/notification.integration.test.ts` | 3 | users/notifications |
|
||||
| `src/tests/integration/data-integrity.integration.test.ts` | 3 | users, admin |
|
||||
| `src/tests/integration/upc.integration.test.ts` | 3 | upc |
|
||||
| `src/tests/integration/edge-cases.integration.test.ts` | 3 | users/shopping-lists |
|
||||
| `src/tests/integration/user.integration.test.ts` | 2 | users |
|
||||
| `src/tests/integration/public.routes.integration.test.ts` | 2 | flyers, recipes |
|
||||
| `src/tests/integration/flyer.integration.test.ts` | 1 | flyers |
|
||||
| `src/tests/integration/category.routes.test.ts` | 1 | categories |
|
||||
| `src/tests/integration/gamification.integration.test.ts` | 1 | ai/jobs |
|
||||
|
||||
### E2E Tests (7 files)
|
||||
|
||||
| File | Occurrences | Domains |
|
||||
| --------------------------------------------- | ----------- | -------------------- |
|
||||
| `src/tests/e2e/inventory-journey.e2e.test.ts` | 9 | inventory |
|
||||
| `src/tests/e2e/receipt-journey.e2e.test.ts` | 9 | receipts |
|
||||
| `src/tests/e2e/budget-journey.e2e.test.ts` | 6 | budgets |
|
||||
| `src/tests/e2e/upc-journey.e2e.test.ts` | 3 | upc |
|
||||
| `src/tests/e2e/deals-journey.e2e.test.ts` | 2 | categories, users |
|
||||
| `src/tests/e2e/user-journey.e2e.test.ts` | 1 | users/shopping-lists |
|
||||
| `src/tests/e2e/flyer-upload.e2e.test.ts` | 1 | jobs |
|
||||
|
||||
## Update Pattern
|
||||
|
||||
### Find/Replace Rules
|
||||
|
||||
**Template literals** (most common):
|
||||
|
||||
```
|
||||
OLD: .get(`/api/resource/${id}`)
|
||||
NEW: .get(`/api/v1/resource/${id}`)
|
||||
```
|
||||
|
||||
**String literals**:
|
||||
|
||||
```
|
||||
OLD: .get('/api/resource')
|
||||
NEW: .get('/api/v1/resource')
|
||||
```
|
||||
|
||||
### Regex Pattern for Batch Updates
|
||||
|
||||
```regex
|
||||
Find: (\.(get|post|put|delete|patch)\([`'"])/api/([a-z])
|
||||
Replace: $1/api/v1/$3
|
||||
```
|
||||
|
||||
**Explanation**: Captures HTTP method call, inserts `/v1/` after `/api/`.
|
||||
|
||||
## Files to EXCLUDE
|
||||
|
||||
These files intentionally test unversioned path behavior:
|
||||
|
||||
| File | Reason |
|
||||
| ---------------------------------------------------- | ------------------------------------ |
|
||||
| `src/routes/versioning.integration.test.ts` | Tests redirect behavior itself |
|
||||
| `src/services/apiClient.test.ts` | Mock server URLs, not real API calls |
|
||||
| `src/services/aiApiClient.test.ts` | Mock server URLs for MSW handlers |
|
||||
| `src/services/googleGeocodingService.server.test.ts` | External Google API URL |
|
||||
|
||||
**Also exclude** (not API paths):
|
||||
|
||||
- Lines containing `vi.mock('@bull-board/api` (import mocks)
|
||||
- Lines containing `/api/v99` (intentional unsupported version tests)
|
||||
- `describe()` and `it()` block descriptions
|
||||
- Comment lines (`// `)
|
||||
|
||||
## Execution Batches
|
||||
|
||||
### Batch 1: High-Impact Integration (4 files, ~58 occurrences)
|
||||
|
||||
```bash
|
||||
# Files with most occurrences
|
||||
src/tests/integration/inventory.integration.test.ts
|
||||
src/tests/integration/receipt.integration.test.ts
|
||||
src/tests/integration/recipe.integration.test.ts
|
||||
src/tests/integration/user.routes.integration.test.ts
|
||||
```
|
||||
|
||||
### Batch 2: Medium Integration (6 files, ~27 occurrences)
|
||||
|
||||
```bash
|
||||
src/tests/integration/admin.integration.test.ts
|
||||
src/tests/integration/flyer-processing.integration.test.ts
|
||||
src/tests/integration/budget.integration.test.ts
|
||||
src/tests/integration/notification.integration.test.ts
|
||||
src/tests/integration/data-integrity.integration.test.ts
|
||||
src/tests/integration/upc.integration.test.ts
|
||||
```
|
||||
|
||||
### Batch 3: Low Integration (6 files, ~10 occurrences)
|
||||
|
||||
```bash
|
||||
src/tests/integration/edge-cases.integration.test.ts
|
||||
src/tests/integration/user.integration.test.ts
|
||||
src/tests/integration/public.routes.integration.test.ts
|
||||
src/tests/integration/flyer.integration.test.ts
|
||||
src/tests/integration/category.routes.test.ts
|
||||
src/tests/integration/gamification.integration.test.ts
|
||||
```
|
||||
|
||||
### Batch 4: E2E Tests (7 files, ~31 occurrences)
|
||||
|
||||
```bash
|
||||
src/tests/e2e/inventory-journey.e2e.test.ts
|
||||
src/tests/e2e/receipt-journey.e2e.test.ts
|
||||
src/tests/e2e/budget-journey.e2e.test.ts
|
||||
src/tests/e2e/upc-journey.e2e.test.ts
|
||||
src/tests/e2e/deals-journey.e2e.test.ts
|
||||
src/tests/e2e/user-journey.e2e.test.ts
|
||||
src/tests/e2e/flyer-upload.e2e.test.ts
|
||||
```
|
||||
|
||||
## Verification Strategy
|
||||
|
||||
### Per-Batch Verification
|
||||
|
||||
After each batch:
|
||||
|
||||
```bash
|
||||
# Type check
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
|
||||
# Run specific test file
|
||||
podman exec -it flyer-crawler-dev npx vitest run <file-path> --reporter=verbose
|
||||
```
|
||||
|
||||
### Full Verification
|
||||
|
||||
After all batches:
|
||||
|
||||
```bash
|
||||
# Full integration test suite
|
||||
podman exec -it flyer-crawler-dev npm run test:integration
|
||||
|
||||
# Full E2E test suite
|
||||
podman exec -it flyer-crawler-dev npm run test:e2e
|
||||
```
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- [x] No `301 Moved Permanently` responses in test output
|
||||
- [x] All tests pass or fail for expected reasons (not redirect-related)
|
||||
- [x] Type check passes
|
||||
- [x] No regressions in unmodified tests
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### Describe Block Text
|
||||
|
||||
Do NOT modify describe/it block descriptions:
|
||||
|
||||
```typescript
|
||||
// KEEP AS-IS (documentation only):
|
||||
describe('GET /api/users/profile', () => { ... });
|
||||
|
||||
// UPDATE (actual API call):
|
||||
const response = await request.get('/api/v1/users/profile');
|
||||
```
|
||||
|
||||
### Console Logging
|
||||
|
||||
Do NOT modify debug/error logging paths:
|
||||
|
||||
```typescript
|
||||
// KEEP AS-IS:
|
||||
console.error('[DEBUG] GET /api/admin/stats failed:', ...);
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
Include query parameters in update:
|
||||
|
||||
```typescript
|
||||
// OLD:
|
||||
.get(`/api/budgets/spending-analysis?startDate=${start}&endDate=${end}`)
|
||||
|
||||
// NEW:
|
||||
.get(`/api/v1/budgets/spending-analysis?startDate=${start}&endDate=${end}`)
|
||||
```
|
||||
|
||||
## Post-Completion Checklist
|
||||
|
||||
- [x] All 23 files updated
|
||||
- [x] ~70 path occurrences migrated
|
||||
- [x] Exclusion files unchanged
|
||||
- [x] Type check passes
|
||||
- [x] Integration tests pass (345/348)
|
||||
- [x] E2E tests pass
|
||||
- [x] Commit with message: `fix(tests): Update API paths to use /api/v1/ prefix (ADR-008)`
|
||||
|
||||
## Rollback
|
||||
|
||||
If issues arise:
|
||||
|
||||
```bash
|
||||
git checkout HEAD -- src/tests/
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- ADR-008: API Versioning Strategy
|
||||
- `docs/architecture/api-versioning-infrastructure.md`
|
||||
- `src/routes/versioning.integration.test.ts` (reference for expected behavior)
|
||||
4
package-lock.json
generated
4
package-lock.json
generated
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "flyer-crawler",
|
||||
"version": "0.12.16",
|
||||
"version": "0.12.17",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "flyer-crawler",
|
||||
"version": "0.12.16",
|
||||
"version": "0.12.17",
|
||||
"dependencies": {
|
||||
"@bull-board/api": "^6.14.2",
|
||||
"@bull-board/express": "^6.14.2",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "flyer-crawler",
|
||||
"private": true,
|
||||
"version": "0.12.16",
|
||||
"version": "0.12.17",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "concurrently \"npm:start:dev\" \"vite\"",
|
||||
|
||||
89
server.ts
89
server.ts
@@ -18,27 +18,8 @@ import { getPool } from './src/services/db/connection.db';
|
||||
import passport from './src/config/passport';
|
||||
import { logger } from './src/services/logger.server';
|
||||
|
||||
// Import routers
|
||||
import authRouter from './src/routes/auth.routes';
|
||||
import userRouter from './src/routes/user.routes';
|
||||
import adminRouter from './src/routes/admin.routes';
|
||||
import aiRouter from './src/routes/ai.routes';
|
||||
import budgetRouter from './src/routes/budget.routes';
|
||||
import flyerRouter from './src/routes/flyer.routes';
|
||||
import recipeRouter from './src/routes/recipe.routes';
|
||||
import personalizationRouter from './src/routes/personalization.routes';
|
||||
import priceRouter from './src/routes/price.routes';
|
||||
import statsRouter from './src/routes/stats.routes';
|
||||
import gamificationRouter from './src/routes/gamification.routes';
|
||||
import systemRouter from './src/routes/system.routes';
|
||||
import healthRouter from './src/routes/health.routes';
|
||||
import upcRouter from './src/routes/upc.routes';
|
||||
import inventoryRouter from './src/routes/inventory.routes';
|
||||
import receiptRouter from './src/routes/receipt.routes';
|
||||
import dealsRouter from './src/routes/deals.routes';
|
||||
import reactionsRouter from './src/routes/reactions.routes';
|
||||
import storeRouter from './src/routes/store.routes';
|
||||
import categoryRouter from './src/routes/category.routes';
|
||||
// Import the versioned API router factory (ADR-008 Phase 2)
|
||||
import { createApiRouter } from './src/routes/versioned';
|
||||
import { errorHandler } from './src/middleware/errorHandler';
|
||||
import { backgroundJobService, startBackgroundJobs } from './src/services/backgroundJobService';
|
||||
import { websocketService } from './src/services/websocketService.server';
|
||||
@@ -249,56 +230,20 @@ app.get('/api/v1/health/queues', async (req, res) => {
|
||||
}
|
||||
});
|
||||
|
||||
// The order of route registration is critical.
|
||||
// More specific routes should be registered before more general ones.
|
||||
// All routes are now versioned under /api/v1 as per ADR-008.
|
||||
// 1. Authentication routes for login, registration, etc.
|
||||
app.use('/api/v1/auth', authRouter);
|
||||
// 2. System routes for health checks, etc.
|
||||
app.use('/api/v1/health', healthRouter);
|
||||
// 3. System routes for pm2 status, etc.
|
||||
app.use('/api/v1/system', systemRouter);
|
||||
// 3. General authenticated user routes.
|
||||
app.use('/api/v1/users', userRouter);
|
||||
// 4. AI routes, some of which use optional authentication.
|
||||
app.use('/api/v1/ai', aiRouter);
|
||||
// 5. Admin routes, which are all protected by admin-level checks.
|
||||
app.use('/api/v1/admin', adminRouter);
|
||||
// 6. Budgeting and spending analysis routes.
|
||||
app.use('/api/v1/budgets', budgetRouter);
|
||||
// 7. Gamification routes for achievements.
|
||||
app.use('/api/v1/achievements', gamificationRouter);
|
||||
// 8. Public flyer routes.
|
||||
app.use('/api/v1/flyers', flyerRouter);
|
||||
// 8. Public recipe routes.
|
||||
app.use('/api/v1/recipes', recipeRouter);
|
||||
// 9. Public personalization data routes (master items, etc.).
|
||||
app.use('/api/v1/personalization', personalizationRouter);
|
||||
// 9.5. Price history routes.
|
||||
app.use('/api/v1/price-history', priceRouter);
|
||||
// 10. Public statistics routes.
|
||||
app.use('/api/v1/stats', statsRouter);
|
||||
// 11. UPC barcode scanning routes.
|
||||
app.use('/api/v1/upc', upcRouter);
|
||||
// 12. Inventory and expiry tracking routes.
|
||||
app.use('/api/v1/inventory', inventoryRouter);
|
||||
// 13. Receipt scanning routes.
|
||||
app.use('/api/v1/receipts', receiptRouter);
|
||||
// 14. Deals and best prices routes.
|
||||
app.use('/api/v1/deals', dealsRouter);
|
||||
// 15. Reactions/social features routes.
|
||||
app.use('/api/v1/reactions', reactionsRouter);
|
||||
// 16. Store management routes.
|
||||
app.use('/api/v1/stores', storeRouter);
|
||||
// 17. Category discovery routes (ADR-023: Database Normalization)
|
||||
app.use('/api/v1/categories', categoryRouter);
|
||||
|
||||
// --- Backwards Compatibility Redirect (ADR-008: API Versioning Strategy) ---
|
||||
// Redirect old /api/* paths to /api/v1/* for backwards compatibility.
|
||||
// This allows clients to gradually migrate to the versioned API.
|
||||
// IMPORTANT: This middleware MUST be mounted BEFORE createApiRouter() so that
|
||||
// unversioned paths like /api/users are redirected to /api/v1/users BEFORE
|
||||
// the versioned router's detectApiVersion middleware rejects them as invalid versions.
|
||||
app.use('/api', (req, res, next) => {
|
||||
// Only redirect if the path does NOT already start with /v1
|
||||
if (!req.path.startsWith('/v1')) {
|
||||
// Check if the path starts with a version-like prefix (/v followed by digits).
|
||||
// This includes both supported versions (v1, v2) and unsupported ones (v99).
|
||||
// Unsupported versions will be handled by detectApiVersion middleware which returns 404.
|
||||
// This redirect only handles legacy unversioned paths like /api/users -> /api/v1/users.
|
||||
const versionPattern = /^\/v\d+/;
|
||||
const startsWithVersionPattern = versionPattern.test(req.path);
|
||||
if (!startsWithVersionPattern) {
|
||||
const newPath = `/api/v1${req.path}`;
|
||||
logger.info({ oldPath: `/api${req.path}`, newPath }, 'Redirecting to versioned API');
|
||||
return res.redirect(301, newPath);
|
||||
@@ -306,6 +251,16 @@ app.use('/api', (req, res, next) => {
|
||||
next();
|
||||
});
|
||||
|
||||
// Mount the versioned API router (ADR-008 Phase 2).
|
||||
// The createApiRouter() factory handles:
|
||||
// - Version detection and validation via detectApiVersion middleware
|
||||
// - Route registration in correct precedence order
|
||||
// - Version-specific route availability
|
||||
// - Deprecation headers via addDeprecationHeaders middleware
|
||||
// - X-API-Version response headers
|
||||
// All domain routers are registered in versioned.ts with proper ordering.
|
||||
app.use('/api', createApiRouter());
|
||||
|
||||
// --- Error Handling and Server Startup ---
|
||||
|
||||
// Catch-all 404 handler for unmatched routes.
|
||||
|
||||
183
src/config/apiVersions.ts
Normal file
183
src/config/apiVersions.ts
Normal file
@@ -0,0 +1,183 @@
|
||||
// src/config/apiVersions.ts
|
||||
/**
|
||||
* @file API version constants, types, and configuration.
|
||||
* Implements ADR-008 Phase 2: API Versioning Infrastructure.
|
||||
*
|
||||
* This module provides centralized version definitions used by:
|
||||
* - Version detection middleware (apiVersion.middleware.ts)
|
||||
* - Deprecation headers middleware (deprecation.middleware.ts)
|
||||
* - Versioned router factory (versioned.ts)
|
||||
*
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import {
|
||||
* CURRENT_API_VERSION,
|
||||
* VERSION_CONFIGS,
|
||||
* isValidApiVersion,
|
||||
* } from './apiVersions';
|
||||
*
|
||||
* // Check if a version is supported
|
||||
* if (isValidApiVersion('v1')) {
|
||||
* const config = VERSION_CONFIGS.v1;
|
||||
* console.log(`v1 status: ${config.status}`);
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
|
||||
// --- Type Definitions ---
|
||||
|
||||
/**
|
||||
* All API versions as a const tuple for type derivation.
|
||||
* Add new versions here when introducing them.
|
||||
*/
|
||||
export const API_VERSIONS = ['v1', 'v2'] as const;
|
||||
|
||||
/**
|
||||
* Union type of supported API versions.
|
||||
* Currently: 'v1' | 'v2'
|
||||
*/
|
||||
export type ApiVersion = (typeof API_VERSIONS)[number];
|
||||
|
||||
/**
|
||||
* Version lifecycle status.
|
||||
* - 'active': Version is fully supported and recommended
|
||||
* - 'deprecated': Version works but clients should migrate (deprecation headers sent)
|
||||
* - 'sunset': Version is scheduled for removal or already removed
|
||||
*/
|
||||
export type VersionStatus = 'active' | 'deprecated' | 'sunset';
|
||||
|
||||
/**
|
||||
* Deprecation information for an API version.
|
||||
* Follows RFC 8594 (Sunset Header) and draft-ietf-httpapi-deprecation-header.
|
||||
*
|
||||
* Used by deprecation middleware to set appropriate HTTP headers:
|
||||
* - `Deprecation: true` (draft-ietf-httpapi-deprecation-header)
|
||||
* - `Sunset: <date>` (RFC 8594)
|
||||
* - `Link: <url>; rel="successor-version"` (RFC 8288)
|
||||
*/
|
||||
export interface VersionDeprecation {
|
||||
/** Indicates if this version is deprecated (maps to Deprecation header) */
|
||||
deprecated: boolean;
|
||||
/** ISO 8601 date string when the version will be sunset (maps to Sunset header) */
|
||||
sunsetDate?: string;
|
||||
/** The version clients should migrate to (maps to Link rel="successor-version") */
|
||||
successorVersion?: ApiVersion;
|
||||
/** Human-readable message explaining the deprecation (for documentation/logs) */
|
||||
message?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Complete configuration for an API version.
|
||||
* Combines version identifier, lifecycle status, and deprecation details.
|
||||
*/
|
||||
export interface VersionConfig {
|
||||
/** The version identifier (e.g., 'v1') */
|
||||
version: ApiVersion;
|
||||
/** Current lifecycle status of this version */
|
||||
status: VersionStatus;
|
||||
/** ISO 8601 date when the version will be sunset (RFC 8594) - convenience field */
|
||||
sunsetDate?: string;
|
||||
/** The version clients should migrate to - convenience field */
|
||||
successorVersion?: ApiVersion;
|
||||
}
|
||||
|
||||
// --- Constants ---
|
||||
|
||||
/**
|
||||
* The current/latest stable API version.
|
||||
* New clients should use this version.
|
||||
*/
|
||||
export const CURRENT_API_VERSION: ApiVersion = 'v1';
|
||||
|
||||
/**
|
||||
* The default API version for requests without explicit version.
|
||||
* Used when version cannot be detected from the request path.
|
||||
*/
|
||||
export const DEFAULT_VERSION: ApiVersion = 'v1';
|
||||
|
||||
/**
|
||||
* Array of all supported API versions.
|
||||
* Used for validation and enumeration.
|
||||
*/
|
||||
export const SUPPORTED_VERSIONS: readonly ApiVersion[] = API_VERSIONS;
|
||||
|
||||
/**
|
||||
* Configuration map for all API versions.
|
||||
* Provides lifecycle status and deprecation information for each version.
|
||||
*
|
||||
* To mark v1 as deprecated (example for future use):
|
||||
* @example
|
||||
* ```typescript
|
||||
* VERSION_CONFIGS.v1 = {
|
||||
* version: 'v1',
|
||||
* status: 'deprecated',
|
||||
* sunsetDate: '2027-01-01T00:00:00Z',
|
||||
* successorVersion: 'v2',
|
||||
* };
|
||||
* ```
|
||||
*/
|
||||
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'active',
|
||||
// No deprecation info - v1 is the current active version
|
||||
},
|
||||
v2: {
|
||||
version: 'v2',
|
||||
status: 'active',
|
||||
// v2 is defined for infrastructure readiness but not yet implemented
|
||||
},
|
||||
};
|
||||
|
||||
// --- Utility Functions ---
|
||||
|
||||
/**
|
||||
* Type guard to check if a string is a valid ApiVersion.
|
||||
*
|
||||
* @param value - The string to check
|
||||
* @returns True if the string is a valid API version
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const userInput = 'v1';
|
||||
* if (isValidApiVersion(userInput)) {
|
||||
* // userInput is now typed as ApiVersion
|
||||
* const config = VERSION_CONFIGS[userInput];
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export function isValidApiVersion(value: string): value is ApiVersion {
|
||||
return API_VERSIONS.includes(value as ApiVersion);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a version is deprecated.
|
||||
*
|
||||
* @param version - The API version to check
|
||||
* @returns True if the version status is 'deprecated'
|
||||
*/
|
||||
export function isVersionDeprecated(version: ApiVersion): boolean {
|
||||
return VERSION_CONFIGS[version].status === 'deprecated';
|
||||
}
|
||||
|
||||
/**
|
||||
* Get deprecation information for a version.
|
||||
* Constructs a VersionDeprecation object from the version config.
|
||||
*
|
||||
* @param version - The API version to get deprecation info for
|
||||
* @returns VersionDeprecation object with current deprecation state
|
||||
*/
|
||||
export function getVersionDeprecation(version: ApiVersion): VersionDeprecation {
|
||||
const config = VERSION_CONFIGS[version];
|
||||
return {
|
||||
deprecated: config.status === 'deprecated',
|
||||
sunsetDate: config.sunsetDate,
|
||||
successorVersion: config.successorVersion,
|
||||
message:
|
||||
config.status === 'deprecated'
|
||||
? `API ${version} is deprecated${config.sunsetDate ? ` and will be sunset on ${config.sunsetDate}` : ''}${config.successorVersion ? `. Please migrate to ${config.successorVersion}.` : '.'}`
|
||||
: undefined,
|
||||
};
|
||||
}
|
||||
400
src/middleware/apiVersion.middleware.test.ts
Normal file
400
src/middleware/apiVersion.middleware.test.ts
Normal file
@@ -0,0 +1,400 @@
|
||||
// src/middleware/apiVersion.middleware.test.ts
|
||||
/**
|
||||
* @file Unit tests for API version detection middleware (ADR-008 Phase 2).
|
||||
* @see src/middleware/apiVersion.middleware.ts
|
||||
*/
|
||||
import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
|
||||
import type { Request, Response, NextFunction } from 'express';
|
||||
import {
|
||||
detectApiVersion,
|
||||
extractApiVersionFromPath,
|
||||
hasApiVersion,
|
||||
getRequestApiVersion,
|
||||
VERSION_ERROR_CODES,
|
||||
} from './apiVersion.middleware';
|
||||
import { DEFAULT_VERSION, SUPPORTED_VERSIONS } from '../config/apiVersions';
|
||||
import { createMockRequest } from '../tests/utils/createMockRequest';
|
||||
import { createMockLogger } from '../tests/utils/mockLogger';
|
||||
|
||||
describe('apiVersion.middleware', () => {
|
||||
let mockRequest: Partial<Request>;
|
||||
let mockResponse: Partial<Response>;
|
||||
let mockNext: NextFunction & Mock;
|
||||
let mockJson: Mock;
|
||||
let mockStatus: Mock;
|
||||
|
||||
beforeEach(() => {
|
||||
// Reset mocks before each test
|
||||
mockJson = vi.fn().mockReturnThis();
|
||||
mockStatus = vi.fn().mockReturnValue({ json: mockJson });
|
||||
mockNext = vi.fn();
|
||||
|
||||
mockResponse = {
|
||||
status: mockStatus,
|
||||
json: mockJson,
|
||||
};
|
||||
});
|
||||
|
||||
describe('detectApiVersion', () => {
|
||||
it('should extract v1 from req.params.version and attach to req.apiVersion', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v1' },
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockNext).toHaveBeenCalledWith();
|
||||
expect(mockRequest.apiVersion).toBe('v1');
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
expect(mockRequest.versionDeprecation?.deprecated).toBe(false);
|
||||
});
|
||||
|
||||
it('should extract v2 from req.params.version and attach to req.apiVersion', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v2' },
|
||||
path: '/flyers',
|
||||
method: 'POST',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe('v2');
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
});
|
||||
|
||||
it('should default to v1 when no version parameter is present', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: {},
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
});
|
||||
|
||||
it('should return 404 with UNSUPPORTED_VERSION for invalid version v99', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v99' },
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
ip: '127.0.0.1',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).not.toHaveBeenCalled();
|
||||
expect(mockStatus).toHaveBeenCalledWith(404);
|
||||
expect(mockJson).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
success: false,
|
||||
error: expect.objectContaining({
|
||||
code: VERSION_ERROR_CODES.UNSUPPORTED_VERSION,
|
||||
message: expect.stringContaining("API version 'v99' is not supported"),
|
||||
details: expect.objectContaining({
|
||||
requestedVersion: 'v99',
|
||||
supportedVersions: expect.arrayContaining(['v1', 'v2']),
|
||||
}),
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should return 404 for non-versioned format like "latest"', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'latest' },
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
ip: '192.168.1.1',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).not.toHaveBeenCalled();
|
||||
expect(mockStatus).toHaveBeenCalledWith(404);
|
||||
expect(mockJson).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
success: false,
|
||||
error: expect.objectContaining({
|
||||
code: VERSION_ERROR_CODES.UNSUPPORTED_VERSION,
|
||||
message: expect.stringContaining("API version 'latest' is not supported"),
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should log warning when invalid version is requested', () => {
|
||||
// Arrange
|
||||
const childLogger = createMockLogger();
|
||||
const mockLog = createMockLogger();
|
||||
vi.mocked(mockLog.child).mockReturnValue(
|
||||
childLogger as unknown as ReturnType<typeof mockLog.child>,
|
||||
);
|
||||
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v999' },
|
||||
path: '/test',
|
||||
method: 'GET',
|
||||
ip: '10.0.0.1',
|
||||
log: mockLog,
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockLog.child).toHaveBeenCalledWith({ middleware: 'detectApiVersion' });
|
||||
expect(childLogger.warn).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
attemptedVersion: 'v999',
|
||||
supportedVersions: SUPPORTED_VERSIONS,
|
||||
}),
|
||||
'Invalid API version requested',
|
||||
);
|
||||
});
|
||||
|
||||
it('should log debug when valid version is detected', () => {
|
||||
// Arrange
|
||||
const childLogger = createMockLogger();
|
||||
const mockLog = createMockLogger();
|
||||
vi.mocked(mockLog.child).mockReturnValue(
|
||||
childLogger as unknown as ReturnType<typeof mockLog.child>,
|
||||
);
|
||||
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v1' },
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
log: mockLog,
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(childLogger.debug).toHaveBeenCalledWith(
|
||||
{ apiVersion: 'v1' },
|
||||
'API version detected from URL',
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('extractApiVersionFromPath', () => {
|
||||
it('should extract v1 from /v1/users path', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
path: '/v1/users',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe('v1');
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
});
|
||||
|
||||
it('should extract v2 from /v2/flyers/123 path', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
path: '/v2/flyers/123',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe('v2');
|
||||
});
|
||||
|
||||
it('should default to v1 for unversioned paths', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
path: '/users',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
|
||||
it('should default to v1 for paths without leading slash', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
path: 'v1/users', // No leading slash - won't match regex
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
|
||||
it('should use default for unsupported version numbers in path', () => {
|
||||
// Arrange
|
||||
const childLogger = createMockLogger();
|
||||
const mockLog = createMockLogger();
|
||||
vi.mocked(mockLog.child).mockReturnValue(
|
||||
childLogger as unknown as ReturnType<typeof mockLog.child>,
|
||||
);
|
||||
|
||||
mockRequest = createMockRequest({
|
||||
path: '/v99/users',
|
||||
params: {},
|
||||
log: mockLog,
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
expect(childLogger.warn).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
attemptedVersion: 'v99',
|
||||
supportedVersions: SUPPORTED_VERSIONS,
|
||||
}),
|
||||
'Unsupported API version in path, falling back to default',
|
||||
);
|
||||
});
|
||||
|
||||
it('should handle paths with only version segment', () => {
|
||||
// Arrange: Path like "/v1/" (just version, no resource)
|
||||
mockRequest = createMockRequest({
|
||||
path: '/v1/',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe('v1');
|
||||
});
|
||||
|
||||
it('should NOT extract version from path like /users/v1 (not at start)', () => {
|
||||
// Arrange: Version appears later in path, not at the start
|
||||
mockRequest = createMockRequest({
|
||||
path: '/users/v1/profile',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
});
|
||||
|
||||
describe('hasApiVersion', () => {
|
||||
it('should return true when apiVersion is set to valid version', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
mockRequest.apiVersion = 'v1';
|
||||
|
||||
// Act & Assert
|
||||
expect(hasApiVersion(mockRequest as Request)).toBe(true);
|
||||
});
|
||||
|
||||
it('should return false when apiVersion is undefined', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
mockRequest.apiVersion = undefined;
|
||||
|
||||
// Act & Assert
|
||||
expect(hasApiVersion(mockRequest as Request)).toBe(false);
|
||||
});
|
||||
|
||||
it('should return false when apiVersion is invalid', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
// Force an invalid version (bypassing TypeScript) - eslint-disable-next-line
|
||||
(mockRequest as unknown as { apiVersion: string }).apiVersion = 'v99';
|
||||
|
||||
// Act & Assert
|
||||
expect(hasApiVersion(mockRequest as Request)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getRequestApiVersion', () => {
|
||||
it('should return the request apiVersion when set', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
mockRequest.apiVersion = 'v2';
|
||||
|
||||
// Act
|
||||
const version = getRequestApiVersion(mockRequest as Request);
|
||||
|
||||
// Assert
|
||||
expect(version).toBe('v2');
|
||||
});
|
||||
|
||||
it('should return DEFAULT_VERSION when apiVersion is undefined', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
mockRequest.apiVersion = undefined;
|
||||
|
||||
// Act
|
||||
const version = getRequestApiVersion(mockRequest as Request);
|
||||
|
||||
// Assert
|
||||
expect(version).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
|
||||
it('should return DEFAULT_VERSION when apiVersion is invalid', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
// Force an invalid version - eslint-disable-next-line
|
||||
(mockRequest as unknown as { apiVersion: string }).apiVersion = 'invalid';
|
||||
|
||||
// Act
|
||||
const version = getRequestApiVersion(mockRequest as Request);
|
||||
|
||||
// Assert
|
||||
expect(version).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
});
|
||||
|
||||
describe('VERSION_ERROR_CODES', () => {
|
||||
it('should have UNSUPPORTED_VERSION error code', () => {
|
||||
expect(VERSION_ERROR_CODES.UNSUPPORTED_VERSION).toBe('UNSUPPORTED_VERSION');
|
||||
});
|
||||
});
|
||||
});
|
||||
218
src/middleware/apiVersion.middleware.ts
Normal file
218
src/middleware/apiVersion.middleware.ts
Normal file
@@ -0,0 +1,218 @@
|
||||
// src/middleware/apiVersion.middleware.ts
|
||||
/**
|
||||
* @file API version detection middleware implementing ADR-008 Phase 2.
|
||||
*
|
||||
* Extracts API version from the request URL, validates it against supported versions,
|
||||
* attaches version information to the request object, and handles unsupported versions.
|
||||
*
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
* @see docs/adr/0008-api-versioning-strategy.md
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // In versioned router factory (versioned.ts):
|
||||
* import { detectApiVersion } from '../middleware/apiVersion.middleware';
|
||||
*
|
||||
* const router = Router({ mergeParams: true });
|
||||
* router.use(detectApiVersion);
|
||||
* ```
|
||||
*/
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import {
|
||||
ApiVersion,
|
||||
SUPPORTED_VERSIONS,
|
||||
DEFAULT_VERSION,
|
||||
isValidApiVersion,
|
||||
getVersionDeprecation,
|
||||
} from '../config/apiVersions';
|
||||
import { sendError } from '../utils/apiResponse';
|
||||
import { createScopedLogger } from '../services/logger.server';
|
||||
|
||||
// --- Module-level Logger ---
|
||||
|
||||
/**
|
||||
* Module-scoped logger for API version middleware.
|
||||
* Used for logging version detection events outside of request context.
|
||||
*/
|
||||
const moduleLogger = createScopedLogger('apiVersion-middleware');
|
||||
|
||||
// --- Error Codes ---
|
||||
|
||||
/**
|
||||
* Error code for unsupported API version requests.
|
||||
* This is specific to the versioning system and not part of the general ErrorCode enum.
|
||||
*/
|
||||
export const VERSION_ERROR_CODES = {
|
||||
UNSUPPORTED_VERSION: 'UNSUPPORTED_VERSION',
|
||||
} as const;
|
||||
|
||||
// --- Middleware Functions ---
|
||||
|
||||
/**
|
||||
* Extracts the API version from the URL path parameter and attaches it to the request.
|
||||
*
|
||||
* This middleware expects to be used with a router that has a :version parameter
|
||||
* (e.g., mounted at `/api/:version`). It validates the version against the list
|
||||
* of supported versions and returns a 404 error for unsupported versions.
|
||||
*
|
||||
* For valid versions, it:
|
||||
* - Sets `req.apiVersion` to the detected version
|
||||
* - Sets `req.versionDeprecation` with deprecation info if the version is deprecated
|
||||
*
|
||||
* @param req - Express request object (expects `req.params.version`)
|
||||
* @param res - Express response object
|
||||
* @param next - Express next function
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Route setup:
|
||||
* app.use('/api/:version', detectApiVersion, versionedRouter);
|
||||
*
|
||||
* // Request to /api/v1/users:
|
||||
* // req.params.version = 'v1'
|
||||
* // req.apiVersion = 'v1'
|
||||
*
|
||||
* // Request to /api/v99/users:
|
||||
* // Returns 404 with UNSUPPORTED_VERSION error
|
||||
* ```
|
||||
*/
|
||||
export function detectApiVersion(req: Request, res: Response, next: NextFunction): void {
|
||||
// Get the request-scoped logger if available, otherwise use module logger
|
||||
const log = req.log?.child({ middleware: 'detectApiVersion' }) ?? moduleLogger;
|
||||
|
||||
// Extract version from URL params (expects router mounted with :version param)
|
||||
const versionParam = req.params?.version;
|
||||
|
||||
// If no version parameter found, this middleware was likely applied incorrectly.
|
||||
// Default to the default version and continue (allows for fallback behavior).
|
||||
if (!versionParam) {
|
||||
log.debug('No version parameter found in request, using default version');
|
||||
req.apiVersion = DEFAULT_VERSION;
|
||||
req.versionDeprecation = getVersionDeprecation(DEFAULT_VERSION);
|
||||
return next();
|
||||
}
|
||||
|
||||
// Validate the version parameter
|
||||
if (isValidApiVersion(versionParam)) {
|
||||
// Valid version - attach to request
|
||||
req.apiVersion = versionParam;
|
||||
req.versionDeprecation = getVersionDeprecation(versionParam);
|
||||
|
||||
log.debug({ apiVersion: versionParam }, 'API version detected from URL');
|
||||
return next();
|
||||
}
|
||||
|
||||
// Invalid version - log warning and return 404
|
||||
log.warn(
|
||||
{
|
||||
attemptedVersion: versionParam,
|
||||
supportedVersions: SUPPORTED_VERSIONS,
|
||||
path: req.path,
|
||||
method: req.method,
|
||||
ip: req.ip,
|
||||
},
|
||||
'Invalid API version requested',
|
||||
);
|
||||
|
||||
// Return 404 with UNSUPPORTED_VERSION error code
|
||||
// Using 404 because the versioned endpoint does not exist
|
||||
sendError(
|
||||
res,
|
||||
VERSION_ERROR_CODES.UNSUPPORTED_VERSION,
|
||||
`API version '${versionParam}' is not supported. Supported versions: ${SUPPORTED_VERSIONS.join(', ')}`,
|
||||
404,
|
||||
{
|
||||
requestedVersion: versionParam,
|
||||
supportedVersions: [...SUPPORTED_VERSIONS],
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts the API version from the URL path pattern and attaches it to the request.
|
||||
*
|
||||
* Unlike `detectApiVersion`, this middleware parses the version from the URL path
|
||||
* directly using a regex pattern. This is useful when the middleware needs to run
|
||||
* before or independently of parameterized routing.
|
||||
*
|
||||
* Pattern matched: `/v{number}/...` at the beginning of the path
|
||||
* (e.g., `/v1/users`, `/v2/flyers/123`)
|
||||
*
|
||||
* If the version is valid, sets `req.apiVersion` and `req.versionDeprecation`.
|
||||
* If the version is invalid or not present, defaults to `DEFAULT_VERSION`.
|
||||
*
|
||||
* This middleware does NOT return errors for invalid versions - it's designed for
|
||||
* cases where version detection is informational rather than authoritative.
|
||||
*
|
||||
* @param req - Express request object
|
||||
* @param _res - Express response object (unused)
|
||||
* @param next - Express next function
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Applied early in middleware chain:
|
||||
* app.use('/api', extractApiVersionFromPath, apiRouter);
|
||||
*
|
||||
* // For path /api/v1/users:
|
||||
* // req.path = '/v1/users' (relative to /api mount point)
|
||||
* // req.apiVersion = 'v1'
|
||||
* ```
|
||||
*/
|
||||
export function extractApiVersionFromPath(req: Request, _res: Response, next: NextFunction): void {
|
||||
// Get the request-scoped logger if available, otherwise use module logger
|
||||
const log = req.log?.child({ middleware: 'extractApiVersionFromPath' }) ?? moduleLogger;
|
||||
|
||||
// Extract version from URL path using regex: /v{number}/
|
||||
// The path is relative to the router's mount point
|
||||
const pathMatch = req.path.match(/^\/v(\d+)\//);
|
||||
|
||||
if (pathMatch) {
|
||||
const versionString = `v${pathMatch[1]}` as string;
|
||||
|
||||
if (isValidApiVersion(versionString)) {
|
||||
req.apiVersion = versionString;
|
||||
req.versionDeprecation = getVersionDeprecation(versionString);
|
||||
log.debug({ apiVersion: versionString }, 'API version extracted from path');
|
||||
return next();
|
||||
}
|
||||
|
||||
// Version number in path but not in supported list - log and use default
|
||||
log.warn(
|
||||
{
|
||||
attemptedVersion: versionString,
|
||||
supportedVersions: SUPPORTED_VERSIONS,
|
||||
path: req.path,
|
||||
},
|
||||
'Unsupported API version in path, falling back to default',
|
||||
);
|
||||
}
|
||||
|
||||
// No version detected or invalid - use default
|
||||
req.apiVersion = DEFAULT_VERSION;
|
||||
req.versionDeprecation = getVersionDeprecation(DEFAULT_VERSION);
|
||||
log.debug({ apiVersion: DEFAULT_VERSION }, 'Using default API version');
|
||||
return next();
|
||||
}
|
||||
|
||||
/**
|
||||
* Type guard to check if a request has a valid API version attached.
|
||||
*
|
||||
* @param req - Express request object
|
||||
* @returns True if req.apiVersion is set to a valid ApiVersion
|
||||
*/
|
||||
export function hasApiVersion(req: Request): req is Request & { apiVersion: ApiVersion } {
|
||||
return req.apiVersion !== undefined && isValidApiVersion(req.apiVersion);
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the API version from a request, with a fallback to the default version.
|
||||
*
|
||||
* @param req - Express request object
|
||||
* @returns The API version from the request, or DEFAULT_VERSION if not set
|
||||
*/
|
||||
export function getRequestApiVersion(req: Request): ApiVersion {
|
||||
if (req.apiVersion && isValidApiVersion(req.apiVersion)) {
|
||||
return req.apiVersion;
|
||||
}
|
||||
return DEFAULT_VERSION;
|
||||
}
|
||||
450
src/middleware/deprecation.middleware.test.ts
Normal file
450
src/middleware/deprecation.middleware.test.ts
Normal file
@@ -0,0 +1,450 @@
|
||||
// src/middleware/deprecation.middleware.test.ts
|
||||
/**
|
||||
* @file Unit tests for deprecation header middleware.
|
||||
* Tests RFC 8594 compliant header generation for deprecated API versions.
|
||||
*
|
||||
* @see ADR-008 for API versioning strategy
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
|
||||
import type { Request, Response } from 'express';
|
||||
import {
|
||||
addDeprecationHeaders,
|
||||
addDeprecationHeadersFromRequest,
|
||||
DEPRECATION_HEADERS,
|
||||
} from './deprecation.middleware';
|
||||
import { VERSION_CONFIGS } from '../config/apiVersions';
|
||||
import { createMockRequest } from '../tests/utils/createMockRequest';
|
||||
|
||||
// Mock the logger to avoid actual logging during tests
|
||||
vi.mock('../services/logger.server', () => ({
|
||||
createScopedLogger: vi.fn(() => ({
|
||||
debug: vi.fn(),
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
})),
|
||||
logger: {
|
||||
debug: vi.fn(),
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
child: vi.fn().mockReturnThis(),
|
||||
},
|
||||
}));
|
||||
|
||||
describe('deprecation.middleware', () => {
|
||||
// Store original VERSION_CONFIGS to restore after tests
|
||||
let originalV1Config: typeof VERSION_CONFIGS.v1;
|
||||
let originalV2Config: typeof VERSION_CONFIGS.v2;
|
||||
|
||||
let mockRequest: Request;
|
||||
let mockResponse: Partial<Response>;
|
||||
|
||||
let mockNext: any;
|
||||
|
||||
let setHeaderSpy: any;
|
||||
|
||||
beforeEach(() => {
|
||||
// Save original configs
|
||||
originalV1Config = { ...VERSION_CONFIGS.v1 };
|
||||
originalV2Config = { ...VERSION_CONFIGS.v2 };
|
||||
|
||||
// Reset mocks
|
||||
setHeaderSpy = vi.fn();
|
||||
mockRequest = createMockRequest({
|
||||
method: 'GET',
|
||||
path: '/api/v1/flyers',
|
||||
get: vi.fn().mockReturnValue('TestUserAgent/1.0'),
|
||||
});
|
||||
mockResponse = {
|
||||
set: setHeaderSpy,
|
||||
setHeader: setHeaderSpy,
|
||||
};
|
||||
mockNext = vi.fn();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Restore original configs after each test
|
||||
VERSION_CONFIGS.v1 = originalV1Config;
|
||||
VERSION_CONFIGS.v2 = originalV2Config;
|
||||
});
|
||||
|
||||
describe('addDeprecationHeaders (factory function)', () => {
|
||||
describe('with active version', () => {
|
||||
it('should always set X-API-Version header', () => {
|
||||
// Arrange - v1 is active by default
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('should not add Deprecation header for active version', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
expect(setHeaderSpy).toHaveBeenCalledTimes(1); // Only X-API-Version
|
||||
});
|
||||
|
||||
it('should not add Sunset header for active version', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.SUNSET,
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not add Link header for active version', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.LINK, expect.anything());
|
||||
});
|
||||
|
||||
it('should not set versionDeprecation on request for active version', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockRequest.versionDeprecation).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('with deprecated version', () => {
|
||||
beforeEach(() => {
|
||||
// Mark v1 as deprecated for these tests
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
});
|
||||
|
||||
it('should add Deprecation: true header', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
});
|
||||
|
||||
it('should add Sunset header with ISO 8601 date', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.SUNSET,
|
||||
'2027-01-01T00:00:00Z',
|
||||
);
|
||||
});
|
||||
|
||||
it('should add Link header with successor-version relation', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.LINK,
|
||||
'</api/v2>; rel="successor-version"',
|
||||
);
|
||||
});
|
||||
|
||||
it('should add X-API-Deprecation-Notice header', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.DEPRECATION_NOTICE,
|
||||
expect.stringContaining('deprecated'),
|
||||
);
|
||||
});
|
||||
|
||||
it('should always set X-API-Version header', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
|
||||
});
|
||||
|
||||
it('should set versionDeprecation on request', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
expect(mockRequest.versionDeprecation?.deprecated).toBe(true);
|
||||
expect(mockRequest.versionDeprecation?.sunsetDate).toBe('2027-01-01T00:00:00Z');
|
||||
expect(mockRequest.versionDeprecation?.successorVersion).toBe('v2');
|
||||
});
|
||||
|
||||
it('should call next() to continue middleware chain', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockNext).toHaveBeenCalledWith();
|
||||
});
|
||||
|
||||
it('should add all RFC 8594 compliant headers in correct format', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert - verify all headers are set
|
||||
const headerCalls = setHeaderSpy.mock.calls;
|
||||
const headerNames = headerCalls.map((call: unknown[]) => call[0]);
|
||||
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.API_VERSION);
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.DEPRECATION);
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.SUNSET);
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.LINK);
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.DEPRECATION_NOTICE);
|
||||
});
|
||||
});
|
||||
|
||||
describe('with deprecated version missing optional fields', () => {
|
||||
beforeEach(() => {
|
||||
// Mark v1 as deprecated without sunset date or successor
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
// No sunsetDate or successorVersion
|
||||
};
|
||||
});
|
||||
|
||||
it('should add Deprecation header even without sunset date', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
});
|
||||
|
||||
it('should not add Sunset header when sunsetDate is not configured', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.SUNSET,
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not add Link header when successorVersion is not configured', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.LINK, expect.anything());
|
||||
});
|
||||
});
|
||||
|
||||
describe('with v2 version', () => {
|
||||
it('should set X-API-Version: v2 header', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v2');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v2');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('addDeprecationHeadersFromRequest', () => {
|
||||
describe('when apiVersion is set on request', () => {
|
||||
it('should add headers based on request apiVersion', () => {
|
||||
// Arrange
|
||||
mockRequest.apiVersion = 'v1';
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-06-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
|
||||
// Act
|
||||
addDeprecationHeadersFromRequest(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.SUNSET,
|
||||
'2027-06-01T00:00:00Z',
|
||||
);
|
||||
});
|
||||
|
||||
it('should not add deprecation headers for active version', () => {
|
||||
// Arrange
|
||||
mockRequest.apiVersion = 'v2';
|
||||
|
||||
// Act
|
||||
addDeprecationHeadersFromRequest(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v2');
|
||||
expect(setHeaderSpy).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('when apiVersion is not set on request', () => {
|
||||
it('should skip header processing and call next', () => {
|
||||
// Arrange
|
||||
mockRequest.apiVersion = undefined;
|
||||
|
||||
// Act
|
||||
addDeprecationHeadersFromRequest(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalled();
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('DEPRECATION_HEADERS constants', () => {
|
||||
it('should have correct header names', () => {
|
||||
expect(DEPRECATION_HEADERS.DEPRECATION).toBe('Deprecation');
|
||||
expect(DEPRECATION_HEADERS.SUNSET).toBe('Sunset');
|
||||
expect(DEPRECATION_HEADERS.LINK).toBe('Link');
|
||||
expect(DEPRECATION_HEADERS.DEPRECATION_NOTICE).toBe('X-API-Deprecation-Notice');
|
||||
expect(DEPRECATION_HEADERS.API_VERSION).toBe('X-API-Version');
|
||||
});
|
||||
});
|
||||
|
||||
describe('edge cases', () => {
|
||||
it('should handle sunset version status', () => {
|
||||
// Arrange
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'sunset',
|
||||
sunsetDate: '2026-01-01T00:00:00Z',
|
||||
};
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert - sunset is different from deprecated, so no deprecation headers
|
||||
// Only X-API-Version should be set
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
});
|
||||
|
||||
it('should handle request with existing log object', () => {
|
||||
// Arrange
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
const mockLogWithBindings = {
|
||||
debug: vi.fn(),
|
||||
bindings: vi.fn().mockReturnValue({ request_id: 'test-request-id' }),
|
||||
};
|
||||
mockRequest.log = mockLogWithBindings as unknown as Request['log'];
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert - should not throw and should complete
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('should work with different versions in sequence', () => {
|
||||
// Arrange
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
const v1Middleware = addDeprecationHeaders('v1');
|
||||
const v2Middleware = addDeprecationHeaders('v2');
|
||||
|
||||
// Act
|
||||
v1Middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Reset for v2
|
||||
setHeaderSpy.mockClear();
|
||||
mockNext.mockClear();
|
||||
const mockRequest2 = createMockRequest({
|
||||
method: 'GET',
|
||||
path: '/api/v2/flyers',
|
||||
});
|
||||
|
||||
v2Middleware(mockRequest2, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert - v2 should only have API version header
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v2');
|
||||
expect(setHeaderSpy).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
});
|
||||
218
src/middleware/deprecation.middleware.ts
Normal file
218
src/middleware/deprecation.middleware.ts
Normal file
@@ -0,0 +1,218 @@
|
||||
// src/middleware/deprecation.middleware.ts
|
||||
/**
|
||||
* @file Deprecation Headers Middleware - RFC 8594 Compliant
|
||||
* Implements ADR-008 Phase 2: API Versioning Infrastructure.
|
||||
*
|
||||
* This middleware adds standard deprecation headers to API responses when
|
||||
* a deprecated API version is being accessed. It follows:
|
||||
* - RFC 8594: The "Sunset" HTTP Header Field
|
||||
* - draft-ietf-httpapi-deprecation-header: The "Deprecation" HTTP Header Field
|
||||
* - RFC 8288: Web Linking (for successor-version relation)
|
||||
*
|
||||
* Headers added for deprecated versions:
|
||||
* - `Deprecation: true` - Indicates the endpoint is deprecated
|
||||
* - `Sunset: <ISO 8601 date>` - When the endpoint will be removed
|
||||
* - `Link: </api/vX>; rel="successor-version"` - URL to the replacement version
|
||||
* - `X-API-Deprecation-Notice: <message>` - Human-readable deprecation message
|
||||
*
|
||||
* Always added (for all versions):
|
||||
* - `X-API-Version: <version>` - The API version being accessed
|
||||
*
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
* @see https://datatracker.ietf.org/doc/html/rfc8594
|
||||
*/
|
||||
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { ApiVersion, VERSION_CONFIGS, getVersionDeprecation } from '../config/apiVersions';
|
||||
import { createScopedLogger } from '../services/logger.server';
|
||||
|
||||
// Create a module-scoped logger for deprecation tracking
|
||||
const deprecationLogger = createScopedLogger('deprecation-middleware');
|
||||
|
||||
/**
|
||||
* HTTP header names for deprecation signaling.
|
||||
* Using constants to ensure consistency and prevent typos.
|
||||
*/
|
||||
export const DEPRECATION_HEADERS = {
|
||||
/** RFC draft-ietf-httpapi-deprecation-header: Indicates deprecation status */
|
||||
DEPRECATION: 'Deprecation',
|
||||
/** RFC 8594: ISO 8601 date when the endpoint will be removed */
|
||||
SUNSET: 'Sunset',
|
||||
/** RFC 8288: Link to successor version with rel="successor-version" */
|
||||
LINK: 'Link',
|
||||
/** Custom header: Human-readable deprecation notice */
|
||||
DEPRECATION_NOTICE: 'X-API-Deprecation-Notice',
|
||||
/** Custom header: Current API version being accessed */
|
||||
API_VERSION: 'X-API-Version',
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Creates middleware that adds RFC 8594 compliant deprecation headers
|
||||
* to responses when a deprecated API version is accessed.
|
||||
*
|
||||
* This is a middleware factory function that takes a version parameter
|
||||
* and returns the configured middleware function. This pattern allows
|
||||
* different version routers to have their own deprecation configuration.
|
||||
*
|
||||
* @param version - The API version this middleware is handling
|
||||
* @returns Express middleware function that adds appropriate headers
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // In a versioned router factory:
|
||||
* const v1Router = Router();
|
||||
* v1Router.use(addDeprecationHeaders('v1'));
|
||||
*
|
||||
* // When v1 is deprecated, responses will include:
|
||||
* // Deprecation: true
|
||||
* // Sunset: 2027-01-01T00:00:00Z
|
||||
* // Link: </api/v2>; rel="successor-version"
|
||||
* // X-API-Deprecation-Notice: API v1 is deprecated...
|
||||
* // X-API-Version: v1
|
||||
* ```
|
||||
*/
|
||||
export function addDeprecationHeaders(version: ApiVersion) {
|
||||
// Pre-fetch configuration at middleware creation time for efficiency.
|
||||
// This avoids repeated lookups on every request.
|
||||
const config = VERSION_CONFIGS[version];
|
||||
const deprecationInfo = getVersionDeprecation(version);
|
||||
|
||||
return function deprecationHeadersMiddleware(
|
||||
req: Request,
|
||||
res: Response,
|
||||
next: NextFunction,
|
||||
): void {
|
||||
// Always set the API version header for transparency and debugging.
|
||||
// This helps clients know which version they're using, especially
|
||||
// useful when default version routing is in effect.
|
||||
res.set(DEPRECATION_HEADERS.API_VERSION, version);
|
||||
|
||||
// Only add deprecation headers if this version is actually deprecated.
|
||||
// Active versions should not have any deprecation headers.
|
||||
if (config.status === 'deprecated') {
|
||||
// RFC draft-ietf-httpapi-deprecation-header: Set to "true" to indicate deprecation
|
||||
res.set(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
|
||||
// RFC 8594: Sunset header with ISO 8601 date indicating removal date
|
||||
if (config.sunsetDate) {
|
||||
res.set(DEPRECATION_HEADERS.SUNSET, config.sunsetDate);
|
||||
}
|
||||
|
||||
// RFC 8288: Link header with successor-version relation
|
||||
// This tells clients where to migrate to
|
||||
if (config.successorVersion) {
|
||||
res.set(
|
||||
DEPRECATION_HEADERS.LINK,
|
||||
`</api/${config.successorVersion}>; rel="successor-version"`,
|
||||
);
|
||||
}
|
||||
|
||||
// Custom header: Human-readable message for developers
|
||||
// This provides context that may not be obvious from the standard headers
|
||||
if (deprecationInfo.message) {
|
||||
res.set(DEPRECATION_HEADERS.DEPRECATION_NOTICE, deprecationInfo.message);
|
||||
}
|
||||
|
||||
// Attach deprecation info to the request for use in route handlers.
|
||||
// This allows handlers to implement version-specific behavior or logging.
|
||||
req.versionDeprecation = deprecationInfo;
|
||||
|
||||
// Log deprecation access at debug level to avoid log spam.
|
||||
// This provides visibility into deprecated API usage without overwhelming logs.
|
||||
// Use debug level because high-traffic APIs could generate significant volume.
|
||||
// Production monitoring should use the access logs or metrics aggregation
|
||||
// to track deprecation usage patterns.
|
||||
deprecationLogger.debug(
|
||||
{
|
||||
apiVersion: version,
|
||||
method: req.method,
|
||||
path: req.path,
|
||||
sunsetDate: config.sunsetDate,
|
||||
successorVersion: config.successorVersion,
|
||||
userAgent: req.get('User-Agent'),
|
||||
// Include request ID if available from the request logger
|
||||
requestId: (req.log as { bindings?: () => { request_id?: string } })?.bindings?.()
|
||||
?.request_id,
|
||||
},
|
||||
'Deprecated API version accessed',
|
||||
);
|
||||
}
|
||||
|
||||
next();
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Standalone middleware for adding deprecation headers based on
|
||||
* the `apiVersion` property already set on the request.
|
||||
*
|
||||
* This middleware should be used after the version extraction middleware
|
||||
* has set `req.apiVersion`. It provides a more flexible approach when
|
||||
* the version is determined dynamically rather than statically.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // After version extraction middleware:
|
||||
* router.use(extractApiVersion);
|
||||
* router.use(addDeprecationHeadersFromRequest);
|
||||
* ```
|
||||
*/
|
||||
export function addDeprecationHeadersFromRequest(
|
||||
req: Request,
|
||||
res: Response,
|
||||
next: NextFunction,
|
||||
): void {
|
||||
const version = req.apiVersion;
|
||||
|
||||
// If no version is set on the request, skip deprecation handling.
|
||||
// This should not happen if the version extraction middleware ran first,
|
||||
// but we handle it gracefully for safety.
|
||||
if (!version) {
|
||||
next();
|
||||
return;
|
||||
}
|
||||
|
||||
const config = VERSION_CONFIGS[version];
|
||||
const deprecationInfo = getVersionDeprecation(version);
|
||||
|
||||
// Always set the API version header
|
||||
res.set(DEPRECATION_HEADERS.API_VERSION, version);
|
||||
|
||||
// Add deprecation headers if version is deprecated
|
||||
if (config.status === 'deprecated') {
|
||||
res.set(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
|
||||
if (config.sunsetDate) {
|
||||
res.set(DEPRECATION_HEADERS.SUNSET, config.sunsetDate);
|
||||
}
|
||||
|
||||
if (config.successorVersion) {
|
||||
res.set(
|
||||
DEPRECATION_HEADERS.LINK,
|
||||
`</api/${config.successorVersion}>; rel="successor-version"`,
|
||||
);
|
||||
}
|
||||
|
||||
if (deprecationInfo.message) {
|
||||
res.set(DEPRECATION_HEADERS.DEPRECATION_NOTICE, deprecationInfo.message);
|
||||
}
|
||||
|
||||
req.versionDeprecation = deprecationInfo;
|
||||
|
||||
deprecationLogger.debug(
|
||||
{
|
||||
apiVersion: version,
|
||||
method: req.method,
|
||||
path: req.path,
|
||||
sunsetDate: config.sunsetDate,
|
||||
successorVersion: config.successorVersion,
|
||||
userAgent: req.get('User-Agent'),
|
||||
requestId: (req.log as { bindings?: () => { request_id?: string } })?.bindings?.()
|
||||
?.request_id,
|
||||
},
|
||||
'Deprecated API version accessed',
|
||||
);
|
||||
}
|
||||
|
||||
next();
|
||||
}
|
||||
@@ -1,9 +1,11 @@
|
||||
// src/routes/auth.routes.test.ts
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import supertest from 'supertest';
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import express, { Request, Response, NextFunction } from 'express';
|
||||
import cookieParser from 'cookie-parser'; // This was a duplicate, fixed.
|
||||
import { createMockUserProfile } from '../tests/utils/mockFactories';
|
||||
import { DEPRECATION_HEADERS, addDeprecationHeaders } from '../middleware/deprecation.middleware';
|
||||
import { errorHandler } from '../middleware/errorHandler';
|
||||
|
||||
// --- FIX: Hoist passport mocks to be available for vi.mock ---
|
||||
const passportMocks = vi.hoisted(() => {
|
||||
@@ -83,6 +85,13 @@ vi.mock('../services/authService', () => ({ authService: mockedAuthService }));
|
||||
vi.mock('../services/logger.server', async () => ({
|
||||
// Use async import to avoid hoisting issues with mockLogger
|
||||
logger: (await import('../tests/utils/mockLogger')).mockLogger,
|
||||
createScopedLogger: vi.fn(() => ({
|
||||
debug: vi.fn(),
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
child: vi.fn().mockReturnThis(),
|
||||
})),
|
||||
}));
|
||||
|
||||
// Mock the email service
|
||||
@@ -908,4 +917,163 @@ describe('Auth Routes (/api/v1/auth)', () => {
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// =============================================================================
|
||||
// API VERSION HEADER ASSERTIONS (ADR-008)
|
||||
// =============================================================================
|
||||
|
||||
describe('API Version Headers', () => {
|
||||
/**
|
||||
* Create an app that includes the deprecation middleware to test version headers.
|
||||
* This simulates the actual production setup where routes are mounted via versioned.ts.
|
||||
*/
|
||||
const createVersionedTestApp = () => {
|
||||
const versionedApp = express();
|
||||
versionedApp.use(express.json());
|
||||
versionedApp.use(cookieParser());
|
||||
versionedApp.use((req, _res, next) => {
|
||||
req.log = mockLogger;
|
||||
next();
|
||||
});
|
||||
// Apply the deprecation middleware before the auth router
|
||||
versionedApp.use('/api/v1/auth', addDeprecationHeaders('v1'), authRouter);
|
||||
// Add error handler to ensure error responses are properly formatted
|
||||
versionedApp.use(errorHandler);
|
||||
return versionedApp;
|
||||
};
|
||||
|
||||
it('should include X-API-Version: v1 header in POST /register success response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
const mockNewUser = createMockUserProfile({
|
||||
user: { user_id: 'new-user-id', email: 'version-test@test.com' },
|
||||
});
|
||||
mockedAuthService.registerAndLoginUser.mockResolvedValue({
|
||||
newUserProfile: mockNewUser,
|
||||
accessToken: 'new-access-token',
|
||||
refreshToken: 'new-refresh-token',
|
||||
});
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).post('/api/v1/auth/register').send({
|
||||
email: 'version-test@test.com',
|
||||
password: 'a-Very-Strong-Password-123!',
|
||||
full_name: 'Test User',
|
||||
});
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(201);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in POST /login success response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
mockedAuthService.handleSuccessfulLogin.mockResolvedValue({
|
||||
accessToken: 'new-access-token',
|
||||
refreshToken: 'new-refresh-token',
|
||||
});
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).post('/api/v1/auth/login').send({
|
||||
email: 'test@test.com',
|
||||
password: 'password123',
|
||||
});
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in POST /forgot-password response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
mockedAuthService.resetPassword.mockResolvedValue('mock-reset-token');
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).post('/api/v1/auth/forgot-password').send({
|
||||
email: 'test@test.com',
|
||||
});
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in POST /reset-password response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
mockedAuthService.updatePassword.mockResolvedValue(true);
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).post('/api/v1/auth/reset-password').send({
|
||||
token: 'valid-token',
|
||||
newPassword: 'a-Very-Strong-Password-789!',
|
||||
});
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in POST /refresh-token response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
mockedAuthService.refreshAccessToken.mockResolvedValue({ accessToken: 'new-access-token' });
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp)
|
||||
.post('/api/v1/auth/refresh-token')
|
||||
.set('Cookie', 'refreshToken=valid-refresh-token');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in POST /logout response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
mockedAuthService.logout.mockResolvedValue(undefined);
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp)
|
||||
.post('/api/v1/auth/logout')
|
||||
.set('Cookie', 'refreshToken=some-valid-token');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version header even on validation error responses', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
|
||||
// Act - send invalid email format
|
||||
const response = await supertest(versionedApp).post('/api/v1/auth/login').send({
|
||||
email: 'not-an-email',
|
||||
password: 'password123',
|
||||
});
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(400);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version header on authentication failure responses', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).post('/api/v1/auth/login').send({
|
||||
email: 'test@test.com',
|
||||
password: 'wrong_password',
|
||||
});
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(401);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,10 +1,13 @@
|
||||
// src/routes/health.routes.test.ts
|
||||
import { describe, it, expect, vi, beforeEach, afterEach, type Mocked } from 'vitest';
|
||||
import supertest from 'supertest';
|
||||
import express from 'express';
|
||||
import { connection as redisConnection } from '../services/queueService.server';
|
||||
import fs from 'node:fs/promises';
|
||||
import { createTestApp } from '../tests/utils/createTestApp';
|
||||
import { mockLogger } from '../tests/utils/mockLogger';
|
||||
import { DEPRECATION_HEADERS, addDeprecationHeaders } from '../middleware/deprecation.middleware';
|
||||
import { errorHandler } from '../middleware/errorHandler';
|
||||
|
||||
// 1. Mock the dependencies of the health router.
|
||||
vi.mock('../services/db/connection.db', () => ({
|
||||
@@ -36,6 +39,13 @@ import * as dbConnection from '../services/db/connection.db';
|
||||
vi.mock('../services/logger.server', async () => ({
|
||||
// Use async import to avoid hoisting issues with mockLogger
|
||||
logger: (await import('../tests/utils/mockLogger')).mockLogger,
|
||||
createScopedLogger: vi.fn(() => ({
|
||||
debug: vi.fn(),
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
child: vi.fn().mockReturnThis(),
|
||||
})),
|
||||
}));
|
||||
|
||||
// Cast the mocked import to a Mocked type for type-safe access to mock functions.
|
||||
@@ -855,4 +865,176 @@ describe('Health Routes (/api/v1/health)', () => {
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// =============================================================================
|
||||
// API VERSION HEADER ASSERTIONS (ADR-008)
|
||||
// =============================================================================
|
||||
|
||||
describe('API Version Headers', () => {
|
||||
/**
|
||||
* Create an app that includes the deprecation middleware to test version headers.
|
||||
* This simulates the actual production setup where routes are mounted via versioned.ts.
|
||||
*/
|
||||
const createVersionedTestApp = () => {
|
||||
const versionedApp = express();
|
||||
versionedApp.use(express.json());
|
||||
versionedApp.use((req, _res, next) => {
|
||||
req.log = mockLogger;
|
||||
next();
|
||||
});
|
||||
// Apply the deprecation middleware before the health router
|
||||
versionedApp.use('/api/v1/health', addDeprecationHeaders('v1'), healthRouter);
|
||||
// Add error handler to ensure error responses are properly formatted
|
||||
versionedApp.use(errorHandler);
|
||||
return versionedApp;
|
||||
};
|
||||
|
||||
it('should include X-API-Version: v1 header in GET /ping response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/ping');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in GET /live response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/live');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in GET /time response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
vi.useFakeTimers();
|
||||
vi.setSystemTime(new Date('2024-03-15T10:30:00.000Z'));
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/time');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in GET /redis response (success)', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
mockedRedisConnection.ping.mockResolvedValue('PONG');
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/redis');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in GET /db-schema response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
mockedDbConnection.checkTablesExist.mockResolvedValue([]);
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/db-schema');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in GET /storage response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
mockedFs.access.mockResolvedValue(undefined);
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/storage');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in GET /db-pool response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
mockedDbConnection.getPoolStatus.mockReturnValue({
|
||||
totalCount: 10,
|
||||
idleCount: 8,
|
||||
waitingCount: 1,
|
||||
});
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/db-pool');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in GET /ready response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
const mockPool = { query: vi.fn().mockResolvedValue({ rows: [{ 1: 1 }] }) };
|
||||
mockedDbConnection.getPool.mockReturnValue(mockPool as never);
|
||||
mockedDbConnection.getPoolStatus.mockReturnValue({
|
||||
totalCount: 10,
|
||||
idleCount: 8,
|
||||
waitingCount: 1,
|
||||
});
|
||||
mockedRedisConnection.ping.mockResolvedValue('PONG');
|
||||
mockedFs.access.mockResolvedValue(undefined);
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/ready');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v1 header in GET /startup response', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
const mockPool = { query: vi.fn().mockResolvedValue({ rows: [{ 1: 1 }] }) };
|
||||
mockedDbConnection.getPool.mockReturnValue(mockPool as never);
|
||||
mockedDbConnection.getPoolStatus.mockReturnValue({
|
||||
totalCount: 10,
|
||||
idleCount: 8,
|
||||
waitingCount: 1,
|
||||
});
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/startup');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version header even on error responses', async () => {
|
||||
// Arrange
|
||||
const versionedApp = createVersionedTestApp();
|
||||
const redisError = new Error('Connection timed out');
|
||||
mockedRedisConnection.ping.mockRejectedValue(redisError);
|
||||
|
||||
// Act
|
||||
const response = await supertest(versionedApp).get('/api/v1/health/redis');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(500);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -619,10 +619,10 @@ router.get(
|
||||
let hasErrors = false;
|
||||
|
||||
for (const metric of queueMetrics) {
|
||||
if ('error' in metric) {
|
||||
if ('error' in metric && metric.error) {
|
||||
queuesData[metric.name] = { error: metric.error };
|
||||
hasErrors = true;
|
||||
} else {
|
||||
} else if ('counts' in metric && metric.counts) {
|
||||
queuesData[metric.name] = metric.counts;
|
||||
}
|
||||
}
|
||||
|
||||
748
src/routes/versioned.test.ts
Normal file
748
src/routes/versioned.test.ts
Normal file
@@ -0,0 +1,748 @@
|
||||
// src/routes/versioned.test.ts
|
||||
/**
|
||||
* @file Unit tests for the version router factory.
|
||||
* Tests ADR-008 Phase 2: API Versioning Infrastructure.
|
||||
*
|
||||
* These tests verify:
|
||||
* - Router creation for different API versions
|
||||
* - X-API-Version header on all responses
|
||||
* - Deprecation headers for deprecated versions
|
||||
* - Route availability filtering by version
|
||||
* - Router caching behavior
|
||||
* - Utility functions
|
||||
*/
|
||||
import { describe, it, expect, vi, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
|
||||
import supertest from 'supertest';
|
||||
import express, { Router, Request, Response } from 'express';
|
||||
import type { Logger } from 'pino';
|
||||
|
||||
// --- Hoisted Mock Setup ---
|
||||
// vi.hoisted() is executed before imports, making values available in vi.mock factories
|
||||
|
||||
const { mockLoggerFn, inlineMockLogger, createMockRouterFactory } = vi.hoisted(() => {
|
||||
const mockLoggerFn = vi.fn();
|
||||
const inlineMockLogger = {
|
||||
info: mockLoggerFn,
|
||||
debug: mockLoggerFn,
|
||||
error: mockLoggerFn,
|
||||
warn: mockLoggerFn,
|
||||
fatal: mockLoggerFn,
|
||||
trace: mockLoggerFn,
|
||||
silent: mockLoggerFn,
|
||||
child: vi.fn().mockReturnThis(),
|
||||
} as unknown as Logger;
|
||||
|
||||
// Factory function to create mock routers
|
||||
const createMockRouterFactory = (name: string) => {
|
||||
// Import express Router here since we're in hoisted context
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
const { Router: ExpressRouter } = require('express');
|
||||
const router = ExpressRouter();
|
||||
router.get('/test', (req: Request, res: Response) => {
|
||||
res.json({ router: name, version: (req as { apiVersion?: string }).apiVersion });
|
||||
});
|
||||
return router;
|
||||
};
|
||||
|
||||
return { mockLoggerFn, inlineMockLogger, createMockRouterFactory };
|
||||
});
|
||||
|
||||
// --- Mock Setup ---
|
||||
|
||||
// Mock the logger before any imports that use it
|
||||
vi.mock('../services/logger.server', () => ({
|
||||
createScopedLogger: vi.fn(() => inlineMockLogger),
|
||||
logger: inlineMockLogger,
|
||||
}));
|
||||
|
||||
// Mock all domain routers with minimal test routers
|
||||
// This isolates the versioned.ts tests from actual route implementations
|
||||
vi.mock('./auth.routes', () => ({ default: createMockRouterFactory('auth') }));
|
||||
vi.mock('./health.routes', () => ({ default: createMockRouterFactory('health') }));
|
||||
vi.mock('./system.routes', () => ({ default: createMockRouterFactory('system') }));
|
||||
vi.mock('./user.routes', () => ({ default: createMockRouterFactory('user') }));
|
||||
vi.mock('./ai.routes', () => ({ default: createMockRouterFactory('ai') }));
|
||||
vi.mock('./admin.routes', () => ({ default: createMockRouterFactory('admin') }));
|
||||
vi.mock('./budget.routes', () => ({ default: createMockRouterFactory('budget') }));
|
||||
vi.mock('./gamification.routes', () => ({ default: createMockRouterFactory('gamification') }));
|
||||
vi.mock('./flyer.routes', () => ({ default: createMockRouterFactory('flyer') }));
|
||||
vi.mock('./recipe.routes', () => ({ default: createMockRouterFactory('recipe') }));
|
||||
vi.mock('./personalization.routes', () => ({
|
||||
default: createMockRouterFactory('personalization'),
|
||||
}));
|
||||
vi.mock('./price.routes', () => ({ default: createMockRouterFactory('price') }));
|
||||
vi.mock('./stats.routes', () => ({ default: createMockRouterFactory('stats') }));
|
||||
vi.mock('./upc.routes', () => ({ default: createMockRouterFactory('upc') }));
|
||||
vi.mock('./inventory.routes', () => ({ default: createMockRouterFactory('inventory') }));
|
||||
vi.mock('./receipt.routes', () => ({ default: createMockRouterFactory('receipt') }));
|
||||
vi.mock('./deals.routes', () => ({ default: createMockRouterFactory('deals') }));
|
||||
vi.mock('./reactions.routes', () => ({ default: createMockRouterFactory('reactions') }));
|
||||
vi.mock('./store.routes', () => ({ default: createMockRouterFactory('store') }));
|
||||
vi.mock('./category.routes', () => ({ default: createMockRouterFactory('category') }));
|
||||
|
||||
// Import types and modules AFTER mocks are set up
|
||||
import type { ApiVersion, VersionConfig } from '../config/apiVersions';
|
||||
import { DEPRECATION_HEADERS } from '../middleware/deprecation.middleware';
|
||||
import { errorHandler } from '../middleware/errorHandler';
|
||||
|
||||
// Import the module under test
|
||||
import {
|
||||
createVersionedRouter,
|
||||
createApiRouter,
|
||||
getRegisteredPaths,
|
||||
getRouteByPath,
|
||||
getRoutesForVersion,
|
||||
clearRouterCache,
|
||||
refreshRouterCache,
|
||||
ROUTES,
|
||||
} from './versioned';
|
||||
|
||||
import { API_VERSIONS, VERSION_CONFIGS } from '../config/apiVersions';
|
||||
|
||||
// --- Test Utilities ---
|
||||
|
||||
/**
|
||||
* Creates a test Express app with the given router mounted at the specified path.
|
||||
*/
|
||||
function createTestApp(router: Router, basePath = '/api') {
|
||||
const app = express();
|
||||
app.use(express.json());
|
||||
|
||||
// Inject mock logger into requests
|
||||
app.use((req, res, next) => {
|
||||
req.log = inlineMockLogger;
|
||||
next();
|
||||
});
|
||||
|
||||
app.use(basePath, router);
|
||||
app.use(errorHandler);
|
||||
return app;
|
||||
}
|
||||
|
||||
/**
|
||||
* Stores original VERSION_CONFIGS for restoration after tests that modify it.
|
||||
*/
|
||||
let originalVersionConfigs: Record<ApiVersion, VersionConfig>;
|
||||
|
||||
// --- Tests ---
|
||||
|
||||
describe('Versioned Router Factory', () => {
|
||||
beforeAll(() => {
|
||||
// Store original configs before any tests modify them
|
||||
originalVersionConfigs = JSON.parse(JSON.stringify(VERSION_CONFIGS));
|
||||
});
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
// Clear router cache before each test to ensure fresh state
|
||||
clearRouterCache();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Restore original VERSION_CONFIGS after each test
|
||||
Object.assign(VERSION_CONFIGS, originalVersionConfigs);
|
||||
});
|
||||
|
||||
afterAll(() => {
|
||||
// Final restoration
|
||||
Object.assign(VERSION_CONFIGS, originalVersionConfigs);
|
||||
});
|
||||
|
||||
// =========================================================================
|
||||
// createVersionedRouter() Tests
|
||||
// =========================================================================
|
||||
|
||||
describe('createVersionedRouter()', () => {
|
||||
describe('route registration', () => {
|
||||
it('should create router with all expected routes for v1', () => {
|
||||
// Act
|
||||
const router = createVersionedRouter('v1');
|
||||
|
||||
// Assert - router should be created
|
||||
expect(router).toBeDefined();
|
||||
expect(typeof router).toBe('function'); // Express routers are functions
|
||||
});
|
||||
|
||||
it('should create router with all expected routes for v2', () => {
|
||||
// Act
|
||||
const router = createVersionedRouter('v2');
|
||||
|
||||
// Assert
|
||||
expect(router).toBeDefined();
|
||||
expect(typeof router).toBe('function');
|
||||
});
|
||||
|
||||
it('should register routes in the expected order', () => {
|
||||
// The ROUTES array defines registration order
|
||||
const expectedOrder = [
|
||||
'auth',
|
||||
'health',
|
||||
'system',
|
||||
'users',
|
||||
'ai',
|
||||
'admin',
|
||||
'budgets',
|
||||
'achievements',
|
||||
'flyers',
|
||||
'recipes',
|
||||
'personalization',
|
||||
'price-history',
|
||||
'stats',
|
||||
'upc',
|
||||
'inventory',
|
||||
'receipts',
|
||||
'deals',
|
||||
'reactions',
|
||||
'stores',
|
||||
'categories',
|
||||
];
|
||||
|
||||
// Assert order matches
|
||||
const registeredPaths = ROUTES.map((r) => r.path);
|
||||
expect(registeredPaths).toEqual(expectedOrder);
|
||||
});
|
||||
|
||||
it('should skip routes not available for specified version', () => {
|
||||
// Assert - getRoutesForVersion should filter correctly
|
||||
const v1Routes = getRoutesForVersion('v1');
|
||||
const v2Routes = getRoutesForVersion('v2');
|
||||
|
||||
// All routes without versions restriction should be in both
|
||||
expect(v1Routes.length).toBe(ROUTES.length);
|
||||
expect(v2Routes.length).toBe(ROUTES.length);
|
||||
|
||||
// If we had a version-restricted route, it would only appear in that version
|
||||
// This tests the filtering logic via getRoutesForVersion
|
||||
expect(v1Routes.some((r) => r.path === 'auth')).toBe(true);
|
||||
expect(v2Routes.some((r) => r.path === 'auth')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('X-API-Version header', () => {
|
||||
it('should add X-API-Version header to all v1 responses', async () => {
|
||||
// Arrange
|
||||
const router = createVersionedRouter('v1');
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should add X-API-Version header to all v2 responses', async () => {
|
||||
// Arrange
|
||||
const router = createVersionedRouter('v2');
|
||||
const app = createTestApp(router, '/api/v2');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v2/health/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
|
||||
});
|
||||
|
||||
it('should NOT add X-API-Version header when deprecation middleware is disabled', async () => {
|
||||
// Arrange - create router with deprecation headers disabled
|
||||
const router = createVersionedRouter('v1', { applyDeprecationHeaders: false });
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert - header should NOT be present when deprecation middleware is disabled
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('deprecation headers', () => {
|
||||
it('should not add deprecation headers for active versions', async () => {
|
||||
// Arrange - v1 is active by default
|
||||
const router = createVersionedRouter('v1');
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert - no deprecation headers
|
||||
expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBeUndefined();
|
||||
expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBeUndefined();
|
||||
expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBeUndefined();
|
||||
expect(
|
||||
response.headers[DEPRECATION_HEADERS.DEPRECATION_NOTICE.toLowerCase()],
|
||||
).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should add deprecation headers when version is deprecated', async () => {
|
||||
// Arrange - Temporarily mark v1 as deprecated
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
|
||||
// Clear cache and create fresh router with updated config
|
||||
clearRouterCache();
|
||||
const router = createVersionedRouter('v1');
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert - deprecation headers present
|
||||
expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
|
||||
expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBe(
|
||||
'2027-01-01T00:00:00Z',
|
||||
);
|
||||
expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBe(
|
||||
'</api/v2>; rel="successor-version"',
|
||||
);
|
||||
expect(response.headers[DEPRECATION_HEADERS.DEPRECATION_NOTICE.toLowerCase()]).toContain(
|
||||
'deprecated',
|
||||
);
|
||||
});
|
||||
|
||||
it('should include sunset date in deprecation headers when provided', async () => {
|
||||
// Arrange
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2028-06-15T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
|
||||
clearRouterCache();
|
||||
const router = createVersionedRouter('v1');
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBe(
|
||||
'2028-06-15T00:00:00Z',
|
||||
);
|
||||
});
|
||||
|
||||
it('should include successor version link when provided', async () => {
|
||||
// Arrange
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
|
||||
clearRouterCache();
|
||||
const router = createVersionedRouter('v1');
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBe(
|
||||
'</api/v2>; rel="successor-version"',
|
||||
);
|
||||
});
|
||||
|
||||
it('should not include sunset date when not provided', async () => {
|
||||
// Arrange - deprecated without sunset date
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
// No sunsetDate
|
||||
};
|
||||
|
||||
clearRouterCache();
|
||||
const router = createVersionedRouter('v1');
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
|
||||
expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('router options', () => {
|
||||
it('should apply deprecation headers middleware by default', async () => {
|
||||
// Arrange
|
||||
const router = createVersionedRouter('v1');
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert - X-API-Version should be set (proves middleware ran)
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should skip deprecation headers middleware when disabled', async () => {
|
||||
// Arrange
|
||||
const router = createVersionedRouter('v1', { applyDeprecationHeaders: false });
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert - X-API-Version should NOT be set
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// =========================================================================
|
||||
// createApiRouter() Tests
|
||||
// =========================================================================
|
||||
|
||||
describe('createApiRouter()', () => {
|
||||
it('should mount all supported versions', async () => {
|
||||
// Arrange
|
||||
const apiRouter = createApiRouter();
|
||||
const app = createTestApp(apiRouter, '/api');
|
||||
|
||||
// Act & Assert - v1 should work
|
||||
const v1Response = await supertest(app).get('/api/v1/health/test');
|
||||
expect(v1Response.status).toBe(200);
|
||||
expect(v1Response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
|
||||
// Act & Assert - v2 should work
|
||||
const v2Response = await supertest(app).get('/api/v2/health/test');
|
||||
expect(v2Response.status).toBe(200);
|
||||
expect(v2Response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
|
||||
});
|
||||
|
||||
it('should return 404 for unsupported versions', async () => {
|
||||
// Arrange
|
||||
const apiRouter = createApiRouter();
|
||||
const app = createTestApp(apiRouter, '/api');
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v99/health/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(404);
|
||||
expect(response.body.error.code).toBe('UNSUPPORTED_VERSION');
|
||||
expect(response.body.error.message).toContain('v99');
|
||||
expect(response.body.error.details.supportedVersions).toEqual(['v1', 'v2']);
|
||||
});
|
||||
|
||||
it('should route to correct versioned router based on URL version', async () => {
|
||||
// Arrange
|
||||
const apiRouter = createApiRouter();
|
||||
const app = createTestApp(apiRouter, '/api');
|
||||
|
||||
// Act
|
||||
const v1Response = await supertest(app).get('/api/v1/health/test');
|
||||
const v2Response = await supertest(app).get('/api/v2/health/test');
|
||||
|
||||
// Assert - each response should indicate the correct version
|
||||
expect(v1Response.body.version).toBe('v1');
|
||||
expect(v2Response.body.version).toBe('v2');
|
||||
});
|
||||
|
||||
it('should handle requests to various domain routers', async () => {
|
||||
// Arrange
|
||||
const apiRouter = createApiRouter();
|
||||
const app = createTestApp(apiRouter, '/api');
|
||||
|
||||
// Act & Assert - multiple domain routers
|
||||
const authResponse = await supertest(app).get('/api/v1/auth/test');
|
||||
expect(authResponse.status).toBe(200);
|
||||
expect(authResponse.body.router).toBe('auth');
|
||||
|
||||
const flyerResponse = await supertest(app).get('/api/v1/flyers/test');
|
||||
expect(flyerResponse.status).toBe(200);
|
||||
expect(flyerResponse.body.router).toBe('flyer');
|
||||
|
||||
const storeResponse = await supertest(app).get('/api/v1/stores/test');
|
||||
expect(storeResponse.status).toBe(200);
|
||||
expect(storeResponse.body.router).toBe('store');
|
||||
});
|
||||
});
|
||||
|
||||
// =========================================================================
|
||||
// Utility Functions Tests
|
||||
// =========================================================================
|
||||
|
||||
describe('getRegisteredPaths()', () => {
|
||||
it('should return all registered route paths', () => {
|
||||
// Act
|
||||
const paths = getRegisteredPaths();
|
||||
|
||||
// Assert
|
||||
expect(paths).toBeInstanceOf(Array);
|
||||
expect(paths.length).toBe(ROUTES.length);
|
||||
expect(paths).toContain('auth');
|
||||
expect(paths).toContain('health');
|
||||
expect(paths).toContain('flyers');
|
||||
expect(paths).toContain('stores');
|
||||
expect(paths).toContain('categories');
|
||||
});
|
||||
|
||||
it('should return paths in registration order', () => {
|
||||
// Act
|
||||
const paths = getRegisteredPaths();
|
||||
|
||||
// Assert - first and last should match ROUTES order
|
||||
expect(paths[0]).toBe('auth');
|
||||
expect(paths[paths.length - 1]).toBe('categories');
|
||||
});
|
||||
});
|
||||
|
||||
describe('getRouteByPath()', () => {
|
||||
it('should return correct registration for existing path', () => {
|
||||
// Act
|
||||
const authRoute = getRouteByPath('auth');
|
||||
const healthRoute = getRouteByPath('health');
|
||||
|
||||
// Assert
|
||||
expect(authRoute).toBeDefined();
|
||||
expect(authRoute?.path).toBe('auth');
|
||||
expect(authRoute?.description).toContain('Authentication');
|
||||
|
||||
expect(healthRoute).toBeDefined();
|
||||
expect(healthRoute?.path).toBe('health');
|
||||
expect(healthRoute?.description).toContain('Health');
|
||||
});
|
||||
|
||||
it('should return undefined for non-existent path', () => {
|
||||
// Act
|
||||
const result = getRouteByPath('non-existent-path');
|
||||
|
||||
// Assert
|
||||
expect(result).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should return undefined for empty string', () => {
|
||||
// Act
|
||||
const result = getRouteByPath('');
|
||||
|
||||
// Assert
|
||||
expect(result).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('getRoutesForVersion()', () => {
|
||||
it('should return all routes when no version restrictions exist', () => {
|
||||
// Act
|
||||
const v1Routes = getRoutesForVersion('v1');
|
||||
const v2Routes = getRoutesForVersion('v2');
|
||||
|
||||
// Assert - all routes should be available in both versions
|
||||
// (since none of the default routes have version restrictions)
|
||||
expect(v1Routes.length).toBe(ROUTES.length);
|
||||
expect(v2Routes.length).toBe(ROUTES.length);
|
||||
});
|
||||
|
||||
it('should filter routes based on version restrictions', () => {
|
||||
// This tests the filtering logic - routes with versions array
|
||||
// should only appear for versions listed in that array
|
||||
const v1Routes = getRoutesForVersion('v1');
|
||||
|
||||
// All routes should have path and router properties
|
||||
v1Routes.forEach((route) => {
|
||||
expect(route.path).toBeDefined();
|
||||
expect(route.router).toBeDefined();
|
||||
expect(route.description).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
it('should include routes without version restrictions in all versions', () => {
|
||||
// Routes without versions array should appear in all versions
|
||||
const authRoute = ROUTES.find((r) => r.path === 'auth');
|
||||
expect(authRoute?.versions).toBeUndefined(); // No version restriction
|
||||
|
||||
const v1Routes = getRoutesForVersion('v1');
|
||||
const v2Routes = getRoutesForVersion('v2');
|
||||
|
||||
expect(v1Routes.some((r) => r.path === 'auth')).toBe(true);
|
||||
expect(v2Routes.some((r) => r.path === 'auth')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// =========================================================================
|
||||
// Router Cache Tests
|
||||
// =========================================================================
|
||||
|
||||
describe('router cache', () => {
|
||||
it('should cache routers after creation', async () => {
|
||||
// Arrange
|
||||
const apiRouter = createApiRouter();
|
||||
const app = createTestApp(apiRouter, '/api');
|
||||
|
||||
// Act - make multiple requests (should use cached router)
|
||||
const response1 = await supertest(app).get('/api/v1/health/test');
|
||||
const response2 = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert - both requests should succeed (proving cache works)
|
||||
expect(response1.status).toBe(200);
|
||||
expect(response2.status).toBe(200);
|
||||
});
|
||||
|
||||
it('should clear cache with clearRouterCache()', () => {
|
||||
// Arrange - create some routers to populate cache
|
||||
createVersionedRouter('v1');
|
||||
createVersionedRouter('v2');
|
||||
|
||||
// Act
|
||||
clearRouterCache();
|
||||
|
||||
// Assert - cache should be cleared (logger would have logged)
|
||||
expect(mockLoggerFn).toHaveBeenCalledWith('Versioned router cache cleared');
|
||||
});
|
||||
|
||||
it('should refresh cache with refreshRouterCache()', () => {
|
||||
// Arrange
|
||||
createVersionedRouter('v1');
|
||||
|
||||
// Act
|
||||
refreshRouterCache();
|
||||
|
||||
// Assert - cache should be refreshed (logger would have logged)
|
||||
expect(mockLoggerFn).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ cachedVersions: expect.any(Array) }),
|
||||
'Versioned router cache refreshed',
|
||||
);
|
||||
});
|
||||
|
||||
it('should create routers on-demand if not in cache', async () => {
|
||||
// Arrange
|
||||
clearRouterCache();
|
||||
const apiRouter = createApiRouter();
|
||||
const app = createTestApp(apiRouter, '/api');
|
||||
|
||||
// Act - request should trigger on-demand router creation
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
});
|
||||
});
|
||||
|
||||
// =========================================================================
|
||||
// ROUTES Configuration Tests
|
||||
// =========================================================================
|
||||
|
||||
describe('ROUTES configuration', () => {
|
||||
it('should have all required properties for each route', () => {
|
||||
ROUTES.forEach((route) => {
|
||||
expect(route.path).toBeDefined();
|
||||
expect(typeof route.path).toBe('string');
|
||||
expect(route.path.length).toBeGreaterThan(0);
|
||||
|
||||
expect(route.router).toBeDefined();
|
||||
expect(typeof route.router).toBe('function');
|
||||
|
||||
expect(route.description).toBeDefined();
|
||||
expect(typeof route.description).toBe('string');
|
||||
expect(route.description.length).toBeGreaterThan(0);
|
||||
|
||||
// versions is optional
|
||||
if (route.versions !== undefined) {
|
||||
expect(Array.isArray(route.versions)).toBe(true);
|
||||
route.versions.forEach((v) => {
|
||||
expect(API_VERSIONS).toContain(v);
|
||||
});
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
it('should not have duplicate paths', () => {
|
||||
const paths = ROUTES.map((r) => r.path);
|
||||
const uniquePaths = new Set(paths);
|
||||
expect(uniquePaths.size).toBe(paths.length);
|
||||
});
|
||||
|
||||
it('should have expected number of routes', () => {
|
||||
// This ensures we don't accidentally remove routes
|
||||
expect(ROUTES.length).toBe(20);
|
||||
});
|
||||
|
||||
it('should include all core domain routers', () => {
|
||||
const paths = getRegisteredPaths();
|
||||
const expectedRoutes = [
|
||||
'auth',
|
||||
'health',
|
||||
'system',
|
||||
'users',
|
||||
'ai',
|
||||
'admin',
|
||||
'budgets',
|
||||
'achievements',
|
||||
'flyers',
|
||||
'recipes',
|
||||
'personalization',
|
||||
'price-history',
|
||||
'stats',
|
||||
'upc',
|
||||
'inventory',
|
||||
'receipts',
|
||||
'deals',
|
||||
'reactions',
|
||||
'stores',
|
||||
'categories',
|
||||
];
|
||||
|
||||
expectedRoutes.forEach((route) => {
|
||||
expect(paths).toContain(route);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// =========================================================================
|
||||
// Edge Cases and Error Handling
|
||||
// =========================================================================
|
||||
|
||||
describe('edge cases', () => {
|
||||
it('should handle requests to nested routes', async () => {
|
||||
// Arrange
|
||||
const router = createVersionedRouter('v1');
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act - request to nested path
|
||||
const response = await supertest(app).get('/api/v1/health/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.body.router).toBe('health');
|
||||
});
|
||||
|
||||
it('should return 404 for non-existent routes within valid version', async () => {
|
||||
// Arrange
|
||||
const router = createVersionedRouter('v1');
|
||||
const app = createTestApp(router, '/api/v1');
|
||||
|
||||
// Act - request to non-existent domain
|
||||
const response = await supertest(app).get('/api/v1/nonexistent/endpoint');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(404);
|
||||
});
|
||||
|
||||
it('should handle multiple concurrent requests', async () => {
|
||||
// Arrange
|
||||
const apiRouter = createApiRouter();
|
||||
const app = createTestApp(apiRouter, '/api');
|
||||
|
||||
// Act - make concurrent requests
|
||||
const requests = [
|
||||
supertest(app).get('/api/v1/health/test'),
|
||||
supertest(app).get('/api/v1/auth/test'),
|
||||
supertest(app).get('/api/v2/health/test'),
|
||||
supertest(app).get('/api/v2/flyers/test'),
|
||||
];
|
||||
|
||||
const responses = await Promise.all(requests);
|
||||
|
||||
// Assert - all should succeed
|
||||
responses.forEach((response) => {
|
||||
expect(response.status).toBe(200);
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
478
src/routes/versioned.ts
Normal file
478
src/routes/versioned.ts
Normal file
@@ -0,0 +1,478 @@
|
||||
// src/routes/versioned.ts
|
||||
/**
|
||||
* @file Version Router Factory - ADR-008 Phase 2 Implementation
|
||||
*
|
||||
* Creates version-specific Express routers that manage route registration
|
||||
* for different API versions. This factory ensures consistent middleware
|
||||
* application and proper route ordering across all API versions.
|
||||
*
|
||||
* Key responsibilities:
|
||||
* - Create routers for each supported API version
|
||||
* - Apply version detection and deprecation middleware
|
||||
* - Register domain routers in correct precedence order
|
||||
* - Support version-specific route availability
|
||||
* - Add X-API-Version header to all responses
|
||||
*
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
* @see docs/adr/0008-api-versioning-strategy.md
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // In server.ts:
|
||||
* import { createApiRouter, createVersionedRouter } from './src/routes/versioned';
|
||||
*
|
||||
* // Option 1: Mount all versions at once
|
||||
* app.use('/api', createApiRouter());
|
||||
*
|
||||
* // Option 2: Mount versions individually
|
||||
* app.use('/api/v1', createVersionedRouter('v1'));
|
||||
* app.use('/api/v2', createVersionedRouter('v2'));
|
||||
* ```
|
||||
*/
|
||||
|
||||
import { Router } from 'express';
|
||||
import { ApiVersion, API_VERSIONS, SUPPORTED_VERSIONS } from '../config/apiVersions';
|
||||
import { detectApiVersion } from '../middleware/apiVersion.middleware';
|
||||
import { addDeprecationHeaders } from '../middleware/deprecation.middleware';
|
||||
import { createScopedLogger } from '../services/logger.server';
|
||||
|
||||
// --- Domain Router Imports ---
|
||||
// These are imported in the order they are registered in server.ts
|
||||
import authRouter from './auth.routes';
|
||||
import healthRouter from './health.routes';
|
||||
import systemRouter from './system.routes';
|
||||
import userRouter from './user.routes';
|
||||
import aiRouter from './ai.routes';
|
||||
import adminRouter from './admin.routes';
|
||||
import budgetRouter from './budget.routes';
|
||||
import gamificationRouter from './gamification.routes';
|
||||
import flyerRouter from './flyer.routes';
|
||||
import recipeRouter from './recipe.routes';
|
||||
import personalizationRouter from './personalization.routes';
|
||||
import priceRouter from './price.routes';
|
||||
import statsRouter from './stats.routes';
|
||||
import upcRouter from './upc.routes';
|
||||
import inventoryRouter from './inventory.routes';
|
||||
import receiptRouter from './receipt.routes';
|
||||
import dealsRouter from './deals.routes';
|
||||
import reactionsRouter from './reactions.routes';
|
||||
import storeRouter from './store.routes';
|
||||
import categoryRouter from './category.routes';
|
||||
|
||||
// Module-scoped logger for versioned router operations
|
||||
const versionedRouterLogger = createScopedLogger('versioned-router');
|
||||
|
||||
// --- Type Definitions ---
|
||||
|
||||
/**
|
||||
* Configuration for registering a route under versioned API.
|
||||
*
|
||||
* @property path - The URL path segment (e.g., 'auth', 'users', 'flyers')
|
||||
* @property router - The Express router instance handling this path
|
||||
* @property description - Human-readable description of the route's purpose
|
||||
* @property versions - Optional array of versions where this route is available.
|
||||
* If omitted, the route is available in all versions.
|
||||
*/
|
||||
export interface RouteRegistration {
|
||||
/** URL path segment (mounted at /{version}/{path}) */
|
||||
path: string;
|
||||
/** Express router instance for this domain */
|
||||
router: Router;
|
||||
/** Human-readable description for documentation and logging */
|
||||
description: string;
|
||||
/** Optional: Specific versions where this route is available (defaults to all) */
|
||||
versions?: ApiVersion[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for creating a versioned router.
|
||||
*/
|
||||
export interface VersionedRouterOptions {
|
||||
/** Whether to apply version detection middleware (default: true) */
|
||||
applyVersionDetection?: boolean;
|
||||
/** Whether to apply deprecation headers middleware (default: true) */
|
||||
applyDeprecationHeaders?: boolean;
|
||||
}
|
||||
|
||||
// --- Route Registration Configuration ---
|
||||
|
||||
/**
|
||||
* Master list of all route registrations.
|
||||
*
|
||||
* IMPORTANT: The order of routes is critical for correct matching.
|
||||
* More specific routes should be registered before more general ones.
|
||||
* This order mirrors the registration in server.ts exactly.
|
||||
*
|
||||
* Each entry includes:
|
||||
* - path: The URL segment (e.g., 'auth' -> /api/v1/auth)
|
||||
* - router: The Express router handling the routes
|
||||
* - description: Purpose documentation
|
||||
* - versions: Optional array to restrict availability to specific versions
|
||||
*/
|
||||
export const ROUTES: RouteRegistration[] = [
|
||||
// 1. Authentication routes for login, registration, etc.
|
||||
{
|
||||
path: 'auth',
|
||||
router: authRouter,
|
||||
description: 'Authentication routes for login, registration, password reset',
|
||||
},
|
||||
|
||||
// 2. Health check routes for monitoring and liveness probes
|
||||
{
|
||||
path: 'health',
|
||||
router: healthRouter,
|
||||
description: 'Health check endpoints for monitoring and liveness probes',
|
||||
},
|
||||
|
||||
// 3. System routes for PM2 status, server info, etc.
|
||||
{
|
||||
path: 'system',
|
||||
router: systemRouter,
|
||||
description: 'System administration routes for PM2 status and server info',
|
||||
},
|
||||
|
||||
// 4. General authenticated user routes
|
||||
{
|
||||
path: 'users',
|
||||
router: userRouter,
|
||||
description: 'User profile and account management routes',
|
||||
},
|
||||
|
||||
// 5. AI routes, some of which use optional authentication
|
||||
{
|
||||
path: 'ai',
|
||||
router: aiRouter,
|
||||
description: 'AI-powered features including flyer processing and analysis',
|
||||
},
|
||||
|
||||
// 6. Admin routes, protected by admin-level checks
|
||||
{
|
||||
path: 'admin',
|
||||
router: adminRouter,
|
||||
description: 'Administrative routes for user and system management',
|
||||
},
|
||||
|
||||
// 7. Budgeting and spending analysis routes
|
||||
{
|
||||
path: 'budgets',
|
||||
router: budgetRouter,
|
||||
description: 'Budget management and spending analysis routes',
|
||||
},
|
||||
|
||||
// 8. Gamification routes for achievements
|
||||
{
|
||||
path: 'achievements',
|
||||
router: gamificationRouter,
|
||||
description: 'Gamification and achievement system routes',
|
||||
},
|
||||
|
||||
// 9. Public flyer routes
|
||||
{
|
||||
path: 'flyers',
|
||||
router: flyerRouter,
|
||||
description: 'Flyer listing, search, and item management routes',
|
||||
},
|
||||
|
||||
// 10. Public recipe routes
|
||||
{
|
||||
path: 'recipes',
|
||||
router: recipeRouter,
|
||||
description: 'Recipe discovery, saving, and recommendation routes',
|
||||
},
|
||||
|
||||
// 11. Public personalization data routes (master items, etc.)
|
||||
{
|
||||
path: 'personalization',
|
||||
router: personalizationRouter,
|
||||
description: 'Personalization data including master items and preferences',
|
||||
},
|
||||
|
||||
// 12. Price history routes
|
||||
{
|
||||
path: 'price-history',
|
||||
router: priceRouter,
|
||||
description: 'Price history tracking and trend analysis routes',
|
||||
},
|
||||
|
||||
// 13. Public statistics routes
|
||||
{
|
||||
path: 'stats',
|
||||
router: statsRouter,
|
||||
description: 'Public statistics and analytics routes',
|
||||
},
|
||||
|
||||
// 14. UPC barcode scanning routes
|
||||
{
|
||||
path: 'upc',
|
||||
router: upcRouter,
|
||||
description: 'UPC barcode scanning and product lookup routes',
|
||||
},
|
||||
|
||||
// 15. Inventory and expiry tracking routes
|
||||
{
|
||||
path: 'inventory',
|
||||
router: inventoryRouter,
|
||||
description: 'Inventory management and expiry tracking routes',
|
||||
},
|
||||
|
||||
// 16. Receipt scanning routes
|
||||
{
|
||||
path: 'receipts',
|
||||
router: receiptRouter,
|
||||
description: 'Receipt scanning and purchase history routes',
|
||||
},
|
||||
|
||||
// 17. Deals and best prices routes
|
||||
{
|
||||
path: 'deals',
|
||||
router: dealsRouter,
|
||||
description: 'Deal discovery and best price comparison routes',
|
||||
},
|
||||
|
||||
// 18. Reactions/social features routes
|
||||
{
|
||||
path: 'reactions',
|
||||
router: reactionsRouter,
|
||||
description: 'Social features including reactions and sharing',
|
||||
},
|
||||
|
||||
// 19. Store management routes
|
||||
{
|
||||
path: 'stores',
|
||||
router: storeRouter,
|
||||
description: 'Store discovery, favorites, and location routes',
|
||||
},
|
||||
|
||||
// 20. Category discovery routes (ADR-023: Database Normalization)
|
||||
{
|
||||
path: 'categories',
|
||||
router: categoryRouter,
|
||||
description: 'Category browsing and product categorization routes',
|
||||
},
|
||||
];
|
||||
|
||||
// --- Factory Functions ---
|
||||
|
||||
/**
|
||||
* Creates a versioned Express router for a specific API version.
|
||||
*
|
||||
* This factory function:
|
||||
* 1. Creates a new Router instance with merged params
|
||||
* 2. Applies deprecation headers middleware (adds X-API-Version header)
|
||||
* 3. Registers all routes that are available for the specified version
|
||||
* 4. Maintains correct route registration order (specific before general)
|
||||
*
|
||||
* @param version - The API version to create a router for (e.g., 'v1', 'v2')
|
||||
* @param options - Optional configuration for middleware application
|
||||
* @returns Configured Express Router for the specified version
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Create a v1 router
|
||||
* const v1Router = createVersionedRouter('v1');
|
||||
* app.use('/api/v1', v1Router);
|
||||
*
|
||||
* // Create a v2 router with custom options
|
||||
* const v2Router = createVersionedRouter('v2', {
|
||||
* applyDeprecationHeaders: true,
|
||||
* });
|
||||
* ```
|
||||
*/
|
||||
export function createVersionedRouter(
|
||||
version: ApiVersion,
|
||||
options: VersionedRouterOptions = {},
|
||||
): Router {
|
||||
const { applyDeprecationHeaders: shouldApplyDeprecationHeaders = true } = options;
|
||||
|
||||
const router = Router({ mergeParams: true });
|
||||
|
||||
versionedRouterLogger.info({ version, routeCount: ROUTES.length }, 'Creating versioned router');
|
||||
|
||||
// Apply deprecation headers middleware.
|
||||
// This adds X-API-Version header to all responses and deprecation headers
|
||||
// when the version is marked as deprecated.
|
||||
if (shouldApplyDeprecationHeaders) {
|
||||
router.use(addDeprecationHeaders(version));
|
||||
}
|
||||
|
||||
// Register all routes that are available for this version
|
||||
let registeredCount = 0;
|
||||
for (const route of ROUTES) {
|
||||
// Check if this route is available for the specified version.
|
||||
// If versions array is not specified, the route is available for all versions.
|
||||
if (route.versions && !route.versions.includes(version)) {
|
||||
versionedRouterLogger.debug(
|
||||
{ version, path: route.path },
|
||||
'Skipping route not available for this version',
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Mount the router at the specified path
|
||||
router.use(`/${route.path}`, route.router);
|
||||
registeredCount++;
|
||||
|
||||
versionedRouterLogger.debug(
|
||||
{ version, path: route.path, description: route.description },
|
||||
'Registered route',
|
||||
);
|
||||
}
|
||||
|
||||
versionedRouterLogger.info(
|
||||
{ version, registeredCount, totalRoutes: ROUTES.length },
|
||||
'Versioned router created successfully',
|
||||
);
|
||||
|
||||
return router;
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the main API router that mounts all versioned routers.
|
||||
*
|
||||
* This function creates a parent router that:
|
||||
* 1. Applies version detection middleware at the /api/:version level
|
||||
* 2. Mounts versioned routers for each supported API version
|
||||
* 3. Returns 404 for unsupported versions via detectApiVersion middleware
|
||||
*
|
||||
* The router is designed to be mounted at `/api` in the main application:
|
||||
* - `/api/v1/*` routes to v1 router
|
||||
* - `/api/v2/*` routes to v2 router
|
||||
* - `/api/v99/*` returns 404 (unsupported version)
|
||||
*
|
||||
* @returns Express Router configured with all version-specific sub-routers
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // In server.ts:
|
||||
* import { createApiRouter } from './src/routes/versioned';
|
||||
*
|
||||
* // Mount at /api - handles /api/v1/*, /api/v2/*, etc.
|
||||
* app.use('/api', createApiRouter());
|
||||
*
|
||||
* // Then add backwards compatibility redirect for unversioned paths:
|
||||
* app.use('/api', (req, res, next) => {
|
||||
* if (!req.path.startsWith('/v1') && !req.path.startsWith('/v2')) {
|
||||
* return res.redirect(301, `/api/v1${req.path}`);
|
||||
* }
|
||||
* next();
|
||||
* });
|
||||
* ```
|
||||
*/
|
||||
export function createApiRouter(): Router {
|
||||
const router = Router({ mergeParams: true });
|
||||
|
||||
versionedRouterLogger.info(
|
||||
{ supportedVersions: SUPPORTED_VERSIONS },
|
||||
'Creating API router with all versions',
|
||||
);
|
||||
|
||||
// Mount versioned routers under /:version path.
|
||||
// The detectApiVersion middleware validates the version and returns 404 for
|
||||
// unsupported versions before the domain routers are reached.
|
||||
router.use('/:version', detectApiVersion, (req, res, next) => {
|
||||
// At this point, req.apiVersion is guaranteed to be valid
|
||||
// (detectApiVersion returns 404 for invalid versions).
|
||||
// Route to the appropriate versioned router based on the detected version.
|
||||
const version = req.apiVersion;
|
||||
|
||||
if (!version) {
|
||||
// This should not happen if detectApiVersion ran correctly,
|
||||
// but handle it defensively.
|
||||
return next('route');
|
||||
}
|
||||
|
||||
// Get or create the versioned router.
|
||||
// We use a cache to avoid recreating routers on every request.
|
||||
const versionedRouter = versionedRouterCache.get(version);
|
||||
if (versionedRouter) {
|
||||
return versionedRouter(req, res, next);
|
||||
}
|
||||
|
||||
// Fallback: version not in cache (should not happen with proper setup)
|
||||
versionedRouterLogger.warn(
|
||||
{ version },
|
||||
'Versioned router not found in cache, creating on-demand',
|
||||
);
|
||||
const newRouter = createVersionedRouter(version);
|
||||
versionedRouterCache.set(version, newRouter);
|
||||
return newRouter(req, res, next);
|
||||
});
|
||||
|
||||
versionedRouterLogger.info('API router created successfully');
|
||||
|
||||
return router;
|
||||
}
|
||||
|
||||
// --- Router Cache ---
|
||||
|
||||
/**
|
||||
* Cache for versioned routers to avoid recreation on every request.
|
||||
* Pre-populated with routers for all supported versions.
|
||||
*/
|
||||
const versionedRouterCache = new Map<ApiVersion, Router>();
|
||||
|
||||
// Pre-populate the cache with all supported versions
|
||||
for (const version of API_VERSIONS) {
|
||||
versionedRouterCache.set(version, createVersionedRouter(version));
|
||||
}
|
||||
|
||||
versionedRouterLogger.debug(
|
||||
{ cachedVersions: Array.from(versionedRouterCache.keys()) },
|
||||
'Versioned router cache initialized',
|
||||
);
|
||||
|
||||
// --- Utility Functions ---
|
||||
|
||||
/**
|
||||
* Gets the list of all registered route paths.
|
||||
* Useful for documentation and debugging.
|
||||
*
|
||||
* @returns Array of registered route paths
|
||||
*/
|
||||
export function getRegisteredPaths(): string[] {
|
||||
return ROUTES.map((route) => route.path);
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets route registration details for a specific path.
|
||||
*
|
||||
* @param path - The route path to look up
|
||||
* @returns RouteRegistration if found, undefined otherwise
|
||||
*/
|
||||
export function getRouteByPath(path: string): RouteRegistration | undefined {
|
||||
return ROUTES.find((route) => route.path === path);
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets all routes available for a specific API version.
|
||||
*
|
||||
* @param version - The API version to filter by
|
||||
* @returns Array of RouteRegistrations available for the version
|
||||
*/
|
||||
export function getRoutesForVersion(version: ApiVersion): RouteRegistration[] {
|
||||
return ROUTES.filter((route) => !route.versions || route.versions.includes(version));
|
||||
}
|
||||
|
||||
/**
|
||||
* Clears the versioned router cache.
|
||||
* Primarily useful for testing to ensure fresh router instances.
|
||||
*/
|
||||
export function clearRouterCache(): void {
|
||||
versionedRouterCache.clear();
|
||||
versionedRouterLogger.debug('Versioned router cache cleared');
|
||||
}
|
||||
|
||||
/**
|
||||
* Refreshes the versioned router cache by recreating all routers.
|
||||
* Useful after configuration changes.
|
||||
*/
|
||||
export function refreshRouterCache(): void {
|
||||
clearRouterCache();
|
||||
for (const version of API_VERSIONS) {
|
||||
versionedRouterCache.set(version, createVersionedRouter(version));
|
||||
}
|
||||
versionedRouterLogger.debug(
|
||||
{ cachedVersions: Array.from(versionedRouterCache.keys()) },
|
||||
'Versioned router cache refreshed',
|
||||
);
|
||||
}
|
||||
552
src/routes/versioning.integration.test.ts
Normal file
552
src/routes/versioning.integration.test.ts
Normal file
@@ -0,0 +1,552 @@
|
||||
// src/routes/versioning.integration.test.ts
|
||||
/**
|
||||
* @file Integration tests for API versioning infrastructure (ADR-008).
|
||||
*
|
||||
* These tests verify the end-to-end behavior of the versioning middleware including:
|
||||
* - X-API-Version header presence in responses
|
||||
* - Unsupported version handling (404 with UNSUPPORTED_VERSION)
|
||||
* - Deprecation headers for deprecated versions
|
||||
* - Backwards compatibility redirect from unversioned paths
|
||||
*
|
||||
* Note: These tests use a minimal router setup to avoid deep import chains
|
||||
* from domain routers. Full integration testing of versioned routes is done
|
||||
* in individual route test files.
|
||||
*
|
||||
* @see docs/adr/0008-api-versioning-strategy.md
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
*/
|
||||
import { describe, it, expect, vi, beforeEach, beforeAll, afterAll } from 'vitest';
|
||||
import supertest from 'supertest';
|
||||
import express, { Router } from 'express';
|
||||
import {
|
||||
VERSION_CONFIGS,
|
||||
ApiVersion,
|
||||
SUPPORTED_VERSIONS,
|
||||
DEFAULT_VERSION,
|
||||
} from '../config/apiVersions';
|
||||
import { DEPRECATION_HEADERS, addDeprecationHeaders } from '../middleware/deprecation.middleware';
|
||||
import { detectApiVersion, VERSION_ERROR_CODES } from '../middleware/apiVersion.middleware';
|
||||
import { sendSuccess } from '../utils/apiResponse';
|
||||
import { errorHandler } from '../middleware/errorHandler';
|
||||
|
||||
// Mock the logger to avoid actual logging during tests
|
||||
vi.mock('../services/logger.server', () => ({
|
||||
createScopedLogger: vi.fn(() => ({
|
||||
debug: vi.fn(),
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
child: vi.fn().mockReturnThis(),
|
||||
})),
|
||||
logger: {
|
||||
debug: vi.fn(),
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
child: vi.fn().mockReturnThis(),
|
||||
},
|
||||
}));
|
||||
|
||||
describe('API Versioning Integration Tests', () => {
|
||||
// Store original VERSION_CONFIGS to restore after tests
|
||||
let originalConfigs: Record<ApiVersion, typeof VERSION_CONFIGS.v1>;
|
||||
|
||||
beforeAll(() => {
|
||||
// Save original configs
|
||||
originalConfigs = {
|
||||
v1: { ...VERSION_CONFIGS.v1 },
|
||||
v2: { ...VERSION_CONFIGS.v2 },
|
||||
};
|
||||
});
|
||||
|
||||
afterAll(() => {
|
||||
// Restore original configs
|
||||
VERSION_CONFIGS.v1 = originalConfigs.v1;
|
||||
VERSION_CONFIGS.v2 = originalConfigs.v2;
|
||||
});
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
// Reset configs to original before each test
|
||||
VERSION_CONFIGS.v1 = { ...originalConfigs.v1 };
|
||||
VERSION_CONFIGS.v2 = { ...originalConfigs.v2 };
|
||||
});
|
||||
|
||||
/**
|
||||
* Create a minimal test router that returns a simple success response.
|
||||
* This avoids importing complex domain routers with many dependencies.
|
||||
*/
|
||||
const createMinimalTestRouter = (): Router => {
|
||||
const router = Router();
|
||||
router.get('/test', (req, res) => {
|
||||
sendSuccess(res, { message: 'test', version: req.apiVersion });
|
||||
});
|
||||
router.get('/error', (_req, res) => {
|
||||
res.status(500).json({ error: 'Internal error' });
|
||||
});
|
||||
return router;
|
||||
};
|
||||
|
||||
/**
|
||||
* Helper to create a test app that simulates the actual server.ts versioning setup.
|
||||
* Uses minimal test routers instead of full domain routers.
|
||||
*/
|
||||
const createVersionedTestApp = () => {
|
||||
const app = express();
|
||||
app.use(express.json());
|
||||
|
||||
// Add request logger mock
|
||||
app.use((req, res, next) => {
|
||||
req.log = {
|
||||
debug: vi.fn(),
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
child: vi.fn().mockReturnThis(),
|
||||
} as never;
|
||||
next();
|
||||
});
|
||||
|
||||
// Backwards compatibility redirect (mirrors server.ts)
|
||||
app.use('/api', (req, res, next) => {
|
||||
const versionPattern = /^\/v\d+/;
|
||||
const startsWithVersionPattern = versionPattern.test(req.path);
|
||||
if (!startsWithVersionPattern) {
|
||||
const newPath = `/api/v1${req.path}`;
|
||||
return res.redirect(301, newPath);
|
||||
}
|
||||
next();
|
||||
});
|
||||
|
||||
// Create versioned routers with minimal test routes
|
||||
const createVersionRouter = (version: ApiVersion): Router => {
|
||||
const router = Router({ mergeParams: true });
|
||||
router.use(addDeprecationHeaders(version));
|
||||
router.use('/test', createMinimalTestRouter());
|
||||
return router;
|
||||
};
|
||||
|
||||
// Mount versioned routers under /api/:version
|
||||
// The detectApiVersion middleware validates the version
|
||||
app.use('/api/:version', detectApiVersion, (req, res, next) => {
|
||||
const version = req.apiVersion;
|
||||
if (!version || !SUPPORTED_VERSIONS.includes(version)) {
|
||||
return next('route');
|
||||
}
|
||||
// Dynamically route to the appropriate versioned router
|
||||
const versionRouter = createVersionRouter(version);
|
||||
return versionRouter(req, res, next);
|
||||
});
|
||||
|
||||
// Error handler
|
||||
app.use(errorHandler);
|
||||
|
||||
return app;
|
||||
};
|
||||
|
||||
describe('X-API-Version Header', () => {
|
||||
it('should include X-API-Version: v1 header in /api/v1/test response', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include X-API-Version: v2 header in /api/v2/test response', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v2/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
|
||||
});
|
||||
|
||||
it('should include correct API version in response body', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const v1Response = await supertest(app).get('/api/v1/test/test');
|
||||
const v2Response = await supertest(app).get('/api/v2/test/test');
|
||||
|
||||
// Assert
|
||||
expect(v1Response.body.data.version).toBe('v1');
|
||||
expect(v2Response.body.data.version).toBe('v2');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Unsupported Version Handling', () => {
|
||||
it('should return 404 with UNSUPPORTED_VERSION for /api/v99/test', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v99/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(404);
|
||||
expect(response.body.success).toBe(false);
|
||||
expect(response.body.error.code).toBe(VERSION_ERROR_CODES.UNSUPPORTED_VERSION);
|
||||
expect(response.body.error.message).toContain("API version 'v99' is not supported");
|
||||
expect(response.body.error.details.requestedVersion).toBe('v99');
|
||||
expect(response.body.error.details.supportedVersions).toEqual(
|
||||
expect.arrayContaining(['v1', 'v2']),
|
||||
);
|
||||
});
|
||||
|
||||
it('should return 404 with UNSUPPORTED_VERSION for /api/v0/test', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v0/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(404);
|
||||
expect(response.body.error.code).toBe(VERSION_ERROR_CODES.UNSUPPORTED_VERSION);
|
||||
expect(response.body.error.details.requestedVersion).toBe('v0');
|
||||
});
|
||||
|
||||
it('should return 404 with UNSUPPORTED_VERSION for /api/v100/resource', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v100/resource');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(404);
|
||||
expect(response.body.error.code).toBe(VERSION_ERROR_CODES.UNSUPPORTED_VERSION);
|
||||
expect(response.body.error.message).toContain("API version 'v100' is not supported");
|
||||
});
|
||||
|
||||
it('should return 404 for non-standard version format like /api/vX/test', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act - vX matches the /v\d+/ pattern (v followed by digits) but X is not a digit
|
||||
// So this path gets redirected. Let's test with a version that DOES match the pattern
|
||||
// but is not supported (e.g., v999 which is v followed by digits but not in SUPPORTED_VERSIONS)
|
||||
const response = await supertest(app).get('/api/v999/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(404);
|
||||
expect(response.body.error.code).toBe(VERSION_ERROR_CODES.UNSUPPORTED_VERSION);
|
||||
expect(response.body.error.details.requestedVersion).toBe('v999');
|
||||
});
|
||||
|
||||
it('should include list of supported versions in error response', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v42/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(404);
|
||||
expect(response.body.error.details.supportedVersions).toEqual(
|
||||
expect.arrayContaining(SUPPORTED_VERSIONS as unknown as string[]),
|
||||
);
|
||||
expect(response.body.error.message).toContain('Supported versions:');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Backwards Compatibility Redirect', () => {
|
||||
it('should redirect /api/test to /api/v1/test with 301', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/test').redirects(0); // Don't follow redirects
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(301);
|
||||
expect(response.headers.location).toBe('/api/v1/test');
|
||||
});
|
||||
|
||||
it('should redirect /api/users to /api/v1/users with 301', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/users').redirects(0);
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(301);
|
||||
expect(response.headers.location).toBe('/api/v1/users');
|
||||
});
|
||||
|
||||
it('should redirect /api/flyers/123 to /api/v1/flyers/123 with 301', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/flyers/123').redirects(0);
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(301);
|
||||
expect(response.headers.location).toBe('/api/v1/flyers/123');
|
||||
});
|
||||
|
||||
it('should NOT redirect paths that already have a version prefix', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act - v99 is unsupported but should NOT be redirected
|
||||
const response = await supertest(app).get('/api/v99/test').redirects(0);
|
||||
|
||||
// Assert - should get 404 (unsupported), not 301 (redirect)
|
||||
expect(response.status).toBe(404);
|
||||
expect(response.headers.location).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Deprecation Headers', () => {
|
||||
describe('when version is active', () => {
|
||||
it('should NOT include Deprecation header for active v1', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should NOT include Sunset header for active v1', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should NOT include Link header for active v1', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('when version is deprecated', () => {
|
||||
beforeEach(() => {
|
||||
// Mark v1 as deprecated for these tests
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
});
|
||||
|
||||
it('should include Deprecation: true header for deprecated version', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
|
||||
});
|
||||
|
||||
it('should include Sunset header with ISO 8601 date for deprecated version', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBe(
|
||||
'2027-01-01T00:00:00Z',
|
||||
);
|
||||
});
|
||||
|
||||
it('should include Link header with successor-version relation for deprecated version', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBe(
|
||||
'</api/v2>; rel="successor-version"',
|
||||
);
|
||||
});
|
||||
|
||||
it('should include X-API-Deprecation-Notice header for deprecated version', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
const noticeHeader = response.headers[DEPRECATION_HEADERS.DEPRECATION_NOTICE.toLowerCase()];
|
||||
expect(noticeHeader).toBeDefined();
|
||||
expect(noticeHeader).toContain('deprecated');
|
||||
});
|
||||
|
||||
it('should still include X-API-Version header for deprecated version', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
});
|
||||
|
||||
it('should include all RFC 8594 compliant headers for deprecated version', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert - verify all expected headers are present
|
||||
const headers = response.headers;
|
||||
expect(headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
expect(headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
|
||||
expect(headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBe('2027-01-01T00:00:00Z');
|
||||
expect(headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBe(
|
||||
'</api/v2>; rel="successor-version"',
|
||||
);
|
||||
expect(headers[DEPRECATION_HEADERS.DEPRECATION_NOTICE.toLowerCase()]).toContain(
|
||||
'deprecated',
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('when deprecated version lacks optional fields', () => {
|
||||
beforeEach(() => {
|
||||
// Mark v1 as deprecated without sunset date or successor
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
// No sunsetDate or successorVersion
|
||||
};
|
||||
});
|
||||
|
||||
it('should include Deprecation header even without sunset date', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
|
||||
});
|
||||
|
||||
it('should NOT include Sunset header when not configured', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should NOT include Link header when successor not configured', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const response = await supertest(app).get('/api/v1/test/test');
|
||||
|
||||
// Assert
|
||||
expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Cross-cutting Version Behavior', () => {
|
||||
it('should return same response structure for v1 and v2 endpoints', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const v1Response = await supertest(app).get('/api/v1/test/test');
|
||||
const v2Response = await supertest(app).get('/api/v2/test/test');
|
||||
|
||||
// Assert - both should have same structure, different version headers
|
||||
expect(v1Response.status).toBe(200);
|
||||
expect(v2Response.status).toBe(200);
|
||||
expect(v1Response.body.data.message).toBe('test');
|
||||
expect(v2Response.body.data.message).toBe('test');
|
||||
expect(v1Response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
expect(v2Response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
|
||||
});
|
||||
|
||||
it('should handle multiple sequential requests to different versions', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act - make multiple requests
|
||||
const responses = await Promise.all([
|
||||
supertest(app).get('/api/v1/test/test'),
|
||||
supertest(app).get('/api/v2/test/test'),
|
||||
supertest(app).get('/api/v1/test/test'),
|
||||
supertest(app).get('/api/v2/test/test'),
|
||||
]);
|
||||
|
||||
// Assert
|
||||
expect(responses[0].headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
expect(responses[1].headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
|
||||
expect(responses[2].headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
|
||||
expect(responses[3].headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
|
||||
});
|
||||
|
||||
it('should properly detect version from request params', async () => {
|
||||
// Arrange
|
||||
const app = createVersionedTestApp();
|
||||
|
||||
// Act
|
||||
const v1Response = await supertest(app).get('/api/v1/test/test');
|
||||
const v2Response = await supertest(app).get('/api/v2/test/test');
|
||||
|
||||
// Assert - verify version is attached to request and returned in body
|
||||
expect(v1Response.body.data.version).toBe('v1');
|
||||
expect(v2Response.body.data.version).toBe('v2');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Default Version Behavior', () => {
|
||||
it('should use v1 as default version', () => {
|
||||
// Assert
|
||||
expect(DEFAULT_VERSION).toBe('v1');
|
||||
});
|
||||
|
||||
it('should have both v1 and v2 in supported versions', () => {
|
||||
// Assert
|
||||
expect(SUPPORTED_VERSIONS).toContain('v1');
|
||||
expect(SUPPORTED_VERSIONS).toContain('v2');
|
||||
expect(SUPPORTED_VERSIONS.length).toBe(2);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -205,7 +205,7 @@ describe('Admin API Routes Integration Tests', () => {
|
||||
it('should allow an admin to approve a correction', async () => {
|
||||
// Act: Approve the correction.
|
||||
const response = await request
|
||||
.post(`/api/admin/corrections/${testCorrectionId}/approve`)
|
||||
.post(`/api/v1/admin/corrections/${testCorrectionId}/approve`)
|
||||
.set('Authorization', `Bearer ${adminToken}`);
|
||||
expect(response.status).toBe(200);
|
||||
|
||||
@@ -226,7 +226,7 @@ describe('Admin API Routes Integration Tests', () => {
|
||||
it('should allow an admin to reject a correction', async () => {
|
||||
// Act: Reject the correction.
|
||||
const response = await request
|
||||
.post(`/api/admin/corrections/${testCorrectionId}/reject`)
|
||||
.post(`/api/v1/admin/corrections/${testCorrectionId}/reject`)
|
||||
.set('Authorization', `Bearer ${adminToken}`);
|
||||
expect(response.status).toBe(200);
|
||||
|
||||
@@ -241,7 +241,7 @@ describe('Admin API Routes Integration Tests', () => {
|
||||
it('should allow an admin to update a correction', async () => {
|
||||
// Act: Update the suggested value of the correction.
|
||||
const response = await request
|
||||
.put(`/api/admin/corrections/${testCorrectionId}`)
|
||||
.put(`/api/v1/admin/corrections/${testCorrectionId}`)
|
||||
.set('Authorization', `Bearer ${adminToken}`)
|
||||
.send({ suggested_value: '300' });
|
||||
const updatedCorrection = response.body.data;
|
||||
@@ -265,7 +265,7 @@ describe('Admin API Routes Integration Tests', () => {
|
||||
|
||||
// Act: Update the status to 'public'.
|
||||
const response = await request
|
||||
.put(`/api/admin/recipes/${recipeId}/status`)
|
||||
.put(`/api/v1/admin/recipes/${recipeId}/status`)
|
||||
.set('Authorization', `Bearer ${adminToken}`)
|
||||
.send({ status: 'public' });
|
||||
expect(response.status).toBe(200);
|
||||
@@ -290,7 +290,7 @@ describe('Admin API Routes Integration Tests', () => {
|
||||
|
||||
// Act: Call the delete endpoint as an admin.
|
||||
const response = await request
|
||||
.delete(`/api/admin/users/${userToDelete.user.user_id}`)
|
||||
.delete(`/api/v1/admin/users/${userToDelete.user.user_id}`)
|
||||
.set('Authorization', `Bearer ${adminToken}`);
|
||||
|
||||
// Assert: Check for a successful deletion status.
|
||||
@@ -301,7 +301,7 @@ describe('Admin API Routes Integration Tests', () => {
|
||||
// Act: Call the delete endpoint as the same admin user.
|
||||
const adminUserId = adminUser.user.user_id;
|
||||
const response = await request
|
||||
.delete(`/api/admin/users/${adminUserId}`)
|
||||
.delete(`/api/v1/admin/users/${adminUserId}`)
|
||||
.set('Authorization', `Bearer ${adminToken}`);
|
||||
|
||||
// Assert:
|
||||
@@ -323,7 +323,7 @@ describe('Admin API Routes Integration Tests', () => {
|
||||
const notFoundUserId = '00000000-0000-0000-0000-000000000000';
|
||||
|
||||
const response = await request
|
||||
.delete(`/api/admin/users/${notFoundUserId}`)
|
||||
.delete(`/api/v1/admin/users/${notFoundUserId}`)
|
||||
.set('Authorization', `Bearer ${adminToken}`);
|
||||
|
||||
// Assert: Check for a 404 status code
|
||||
|
||||
@@ -214,7 +214,7 @@ describe('Budget API Routes Integration Tests', () => {
|
||||
};
|
||||
|
||||
const response = await request
|
||||
.put(`/api/budgets/${testBudget.budget_id}`)
|
||||
.put(`/api/v1/budgets/${testBudget.budget_id}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send(updatedData);
|
||||
|
||||
@@ -244,7 +244,7 @@ describe('Budget API Routes Integration Tests', () => {
|
||||
|
||||
it('should return 400 when no update fields are provided', async () => {
|
||||
const response = await request
|
||||
.put(`/api/budgets/${testBudget.budget_id}`)
|
||||
.put(`/api/v1/budgets/${testBudget.budget_id}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({});
|
||||
|
||||
@@ -253,7 +253,7 @@ describe('Budget API Routes Integration Tests', () => {
|
||||
|
||||
it('should return 401 if user is not authenticated', async () => {
|
||||
const response = await request
|
||||
.put(`/api/budgets/${testBudget.budget_id}`)
|
||||
.put(`/api/v1/budgets/${testBudget.budget_id}`)
|
||||
.send({ name: 'Hacked Budget' });
|
||||
|
||||
expect(response.status).toBe(401);
|
||||
@@ -280,7 +280,7 @@ describe('Budget API Routes Integration Tests', () => {
|
||||
|
||||
// Now delete it
|
||||
const deleteResponse = await request
|
||||
.delete(`/api/budgets/${createdBudget.budget_id}`)
|
||||
.delete(`/api/v1/budgets/${createdBudget.budget_id}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(deleteResponse.status).toBe(204);
|
||||
@@ -303,7 +303,7 @@ describe('Budget API Routes Integration Tests', () => {
|
||||
});
|
||||
|
||||
it('should return 401 if user is not authenticated', async () => {
|
||||
const response = await request.delete(`/api/budgets/${testBudget.budget_id}`);
|
||||
const response = await request.delete(`/api/v1/budgets/${testBudget.budget_id}`);
|
||||
|
||||
expect(response.status).toBe(401);
|
||||
});
|
||||
|
||||
@@ -64,7 +64,7 @@ describe('Category API Routes (Integration)', () => {
|
||||
const listResponse = await request.get('/api/v1/categories');
|
||||
const firstCategory = listResponse.body.data[0];
|
||||
|
||||
const response = await request.get(`/api/categories/${firstCategory.category_id}`);
|
||||
const response = await request.get(`/api/v1/categories/${firstCategory.category_id}`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.body.success).toBe(true);
|
||||
|
||||
@@ -139,7 +139,7 @@ describe('Data Integrity Integration Tests', () => {
|
||||
|
||||
// Add an item to the list
|
||||
const itemResponse = await request
|
||||
.post(`/api/users/shopping-lists/${listId}/items`)
|
||||
.post(`/api/v1/users/shopping-lists/${listId}/items`)
|
||||
.set('Authorization', `Bearer ${token}`)
|
||||
.send({ customItemName: 'Test Item', quantity: 1 });
|
||||
expect(itemResponse.status).toBe(201);
|
||||
@@ -154,7 +154,7 @@ describe('Data Integrity Integration Tests', () => {
|
||||
|
||||
// Delete the shopping list
|
||||
const deleteResponse = await request
|
||||
.delete(`/api/users/shopping-lists/${listId}`)
|
||||
.delete(`/api/v1/users/shopping-lists/${listId}`)
|
||||
.set('Authorization', `Bearer ${token}`);
|
||||
expect(deleteResponse.status).toBe(204);
|
||||
|
||||
@@ -173,7 +173,7 @@ describe('Data Integrity Integration Tests', () => {
|
||||
describe('Admin Self-Deletion Prevention', () => {
|
||||
it('should prevent admin from deleting their own account via admin route', async () => {
|
||||
const response = await request
|
||||
.delete(`/api/admin/users/${adminUser.user.user_id}`)
|
||||
.delete(`/api/v1/admin/users/${adminUser.user.user_id}`)
|
||||
.set('Authorization', `Bearer ${adminToken}`);
|
||||
|
||||
expect(response.status).toBe(400);
|
||||
|
||||
@@ -185,7 +185,7 @@ describe('Edge Cases Integration Tests', () => {
|
||||
|
||||
// Try to access it as the other user
|
||||
const accessResponse = await request
|
||||
.get(`/api/users/shopping-lists/${listId}`)
|
||||
.get(`/api/v1/users/shopping-lists/${listId}`)
|
||||
.set('Authorization', `Bearer ${otherUserToken}`);
|
||||
|
||||
// Should return 404 to hide resource existence
|
||||
@@ -207,7 +207,7 @@ describe('Edge Cases Integration Tests', () => {
|
||||
|
||||
// Try to update it as the other user
|
||||
const updateResponse = await request
|
||||
.put(`/api/users/shopping-lists/${listId}`)
|
||||
.put(`/api/v1/users/shopping-lists/${listId}`)
|
||||
.set('Authorization', `Bearer ${otherUserToken}`)
|
||||
.send({ name: 'Hacked List' });
|
||||
|
||||
@@ -228,7 +228,7 @@ describe('Edge Cases Integration Tests', () => {
|
||||
|
||||
// Try to delete it as the other user
|
||||
const deleteResponse = await request
|
||||
.delete(`/api/users/shopping-lists/${listId}`)
|
||||
.delete(`/api/v1/users/shopping-lists/${listId}`)
|
||||
.set('Authorization', `Bearer ${otherUserToken}`);
|
||||
|
||||
// Should return 404 to hide resource existence
|
||||
|
||||
@@ -307,7 +307,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
|
||||
// Act 2: Poll for job completion using the new utility.
|
||||
const jobStatus = await poll(
|
||||
async () => {
|
||||
const statusReq = request.get(`/api/ai/jobs/${jobId}/status`);
|
||||
const statusReq = request.get(`/api/v1/ai/jobs/${jobId}/status`);
|
||||
if (token) {
|
||||
statusReq.set('Authorization', `Bearer ${token}`);
|
||||
}
|
||||
@@ -439,7 +439,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
|
||||
const jobStatus = await poll(
|
||||
async () => {
|
||||
const statusResponse = await request
|
||||
.get(`/api/ai/jobs/${jobId}/status`)
|
||||
.get(`/api/v1/ai/jobs/${jobId}/status`)
|
||||
.set('Authorization', `Bearer ${token}`);
|
||||
return statusResponse.body.data;
|
||||
},
|
||||
@@ -569,7 +569,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
|
||||
const jobStatus = await poll(
|
||||
async () => {
|
||||
const statusResponse = await request
|
||||
.get(`/api/ai/jobs/${jobId}/status`)
|
||||
.get(`/api/v1/ai/jobs/${jobId}/status`)
|
||||
.set('Authorization', `Bearer ${token}`);
|
||||
return statusResponse.body.data;
|
||||
},
|
||||
@@ -699,7 +699,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
|
||||
// Act 2: Poll for job completion using the new utility.
|
||||
const jobStatus = await poll(
|
||||
async () => {
|
||||
const statusResponse = await request.get(`/api/ai/jobs/${jobId}/status`);
|
||||
const statusResponse = await request.get(`/api/v1/ai/jobs/${jobId}/status`);
|
||||
return statusResponse.body.data;
|
||||
},
|
||||
(status) => status.state === 'completed' || status.state === 'failed',
|
||||
@@ -787,7 +787,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
|
||||
// Act 2: Poll for job completion using the new utility.
|
||||
const jobStatus = await poll(
|
||||
async () => {
|
||||
const statusResponse = await request.get(`/api/ai/jobs/${jobId}/status`);
|
||||
const statusResponse = await request.get(`/api/v1/ai/jobs/${jobId}/status`);
|
||||
return statusResponse.body.data;
|
||||
},
|
||||
(status) => status.state === 'completed' || status.state === 'failed',
|
||||
@@ -854,7 +854,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
|
||||
// Act 2: Poll for job completion using the new utility.
|
||||
const jobStatus = await poll(
|
||||
async () => {
|
||||
const statusResponse = await request.get(`/api/ai/jobs/${jobId}/status`);
|
||||
const statusResponse = await request.get(`/api/v1/ai/jobs/${jobId}/status`);
|
||||
return statusResponse.body.data;
|
||||
},
|
||||
(status) => status.state === 'completed' || status.state === 'failed',
|
||||
|
||||
@@ -97,7 +97,7 @@ describe('Public Flyer API Routes Integration Tests', () => {
|
||||
const testFlyer = flyers[0];
|
||||
|
||||
// Act: Fetch items for the first flyer.
|
||||
const response = await request.get(`/api/flyers/${testFlyer.flyer_id}/items`);
|
||||
const response = await request.get(`/api/v1/flyers/${testFlyer.flyer_id}/items`);
|
||||
const items: FlyerItem[] = response.body.data;
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
|
||||
@@ -175,7 +175,7 @@ describe('Gamification Flow Integration Test', () => {
|
||||
const jobStatus = await poll(
|
||||
async () => {
|
||||
const statusResponse = await request
|
||||
.get(`/api/ai/jobs/${jobId}/status`)
|
||||
.get(`/api/v1/ai/jobs/${jobId}/status`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
console.error(
|
||||
`[TEST DEBUG] Polling status for ${jobId}: ${statusResponse.body?.data?.state}`,
|
||||
|
||||
@@ -331,7 +331,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
|
||||
it('should return item details', async () => {
|
||||
const response = await request
|
||||
.get(`/api/inventory/${testItemId}`)
|
||||
.get(`/api/v1/inventory/${testItemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
@@ -358,7 +358,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
createdUserIds.push(otherUser.user.user_id);
|
||||
|
||||
const response = await request
|
||||
.get(`/api/inventory/${testItemId}`)
|
||||
.get(`/api/v1/inventory/${testItemId}`)
|
||||
.set('Authorization', `Bearer ${otherToken}`);
|
||||
|
||||
expect(response.status).toBe(404);
|
||||
@@ -387,7 +387,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
|
||||
it('should update item quantity', async () => {
|
||||
const response = await request
|
||||
.put(`/api/inventory/${updateItemId}`)
|
||||
.put(`/api/v1/inventory/${updateItemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ quantity: 5 });
|
||||
|
||||
@@ -397,7 +397,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
|
||||
it('should update item location', async () => {
|
||||
const response = await request
|
||||
.put(`/api/inventory/${updateItemId}`)
|
||||
.put(`/api/v1/inventory/${updateItemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ location: 'freezer' });
|
||||
|
||||
@@ -411,7 +411,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
.toISOString()
|
||||
.split('T')[0];
|
||||
const response = await request
|
||||
.put(`/api/inventory/${updateItemId}`)
|
||||
.put(`/api/v1/inventory/${updateItemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ expiry_date: futureDate });
|
||||
|
||||
@@ -428,7 +428,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
|
||||
it('should reject empty update body', async () => {
|
||||
const response = await request
|
||||
.put(`/api/inventory/${updateItemId}`)
|
||||
.put(`/api/v1/inventory/${updateItemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({});
|
||||
|
||||
@@ -454,14 +454,14 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
const itemId = createResponse.body.data.inventory_id;
|
||||
|
||||
const response = await request
|
||||
.delete(`/api/inventory/${itemId}`)
|
||||
.delete(`/api/v1/inventory/${itemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(204);
|
||||
|
||||
// Verify deletion
|
||||
const verifyResponse = await request
|
||||
.get(`/api/inventory/${itemId}`)
|
||||
.get(`/api/v1/inventory/${itemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(verifyResponse.status).toBe(404);
|
||||
@@ -492,7 +492,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
// Note: The actual API marks the entire item as consumed (no partial consumption)
|
||||
// and returns 204 No Content
|
||||
const response = await request
|
||||
.post(`/api/inventory/${consumeItemId}/consume`)
|
||||
.post(`/api/v1/inventory/${consumeItemId}/consume`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(204);
|
||||
@@ -501,7 +501,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
it('should verify item is marked as consumed', async () => {
|
||||
// Verify the item was marked as consumed
|
||||
const getResponse = await request
|
||||
.get(`/api/inventory/${consumeItemId}`)
|
||||
.get(`/api/v1/inventory/${consumeItemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(getResponse.status).toBe(200);
|
||||
@@ -528,7 +528,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
|
||||
// First consume should succeed
|
||||
const firstResponse = await request
|
||||
.post(`/api/inventory/${itemId}/consume`)
|
||||
.post(`/api/v1/inventory/${itemId}/consume`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(firstResponse.status).toBe(204);
|
||||
@@ -536,7 +536,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
// Second consume - item can still be found but already marked as consumed
|
||||
// The API doesn't prevent this, so we just verify it doesn't error
|
||||
const secondResponse = await request
|
||||
.post(`/api/inventory/${itemId}/consume`)
|
||||
.post(`/api/v1/inventory/${itemId}/consume`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
// Should still return 204 since the item exists
|
||||
@@ -746,7 +746,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
|
||||
// Step 4: Update location (note: consume marks entire item as consumed, no partial)
|
||||
const updateResponse = await request
|
||||
.put(`/api/inventory/${itemId}`)
|
||||
.put(`/api/v1/inventory/${itemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ location: 'freezer' });
|
||||
|
||||
@@ -755,14 +755,14 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
|
||||
|
||||
// Step 5: Mark as consumed (returns 204 No Content)
|
||||
const consumeResponse = await request
|
||||
.post(`/api/inventory/${itemId}/consume`)
|
||||
.post(`/api/v1/inventory/${itemId}/consume`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(consumeResponse.status).toBe(204);
|
||||
|
||||
// Step 6: Verify consumed status
|
||||
const verifyResponse = await request
|
||||
.get(`/api/inventory/${itemId}`)
|
||||
.get(`/api/v1/inventory/${itemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(verifyResponse.status).toBe(200);
|
||||
|
||||
@@ -115,7 +115,7 @@ describe('Notification API Routes Integration Tests', () => {
|
||||
const notificationIdToMark = unreadNotifRes.rows[0].notification_id;
|
||||
|
||||
const response = await request
|
||||
.post(`/api/users/notifications/${notificationIdToMark}/mark-read`)
|
||||
.post(`/api/v1/users/notifications/${notificationIdToMark}/mark-read`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(204);
|
||||
@@ -180,7 +180,7 @@ describe('Notification API Routes Integration Tests', () => {
|
||||
const notificationId = createResult.rows[0].notification_id;
|
||||
|
||||
const response = await request
|
||||
.delete(`/api/users/notifications/${notificationId}`)
|
||||
.delete(`/api/v1/users/notifications/${notificationId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(204);
|
||||
@@ -221,7 +221,7 @@ describe('Notification API Routes Integration Tests', () => {
|
||||
|
||||
// Try to delete it as the other user
|
||||
const response = await request
|
||||
.delete(`/api/users/notifications/${notificationId}`)
|
||||
.delete(`/api/v1/users/notifications/${notificationId}`)
|
||||
.set('Authorization', `Bearer ${otherToken}`);
|
||||
|
||||
// Should return 404 (not 403) to hide existence
|
||||
|
||||
@@ -152,7 +152,7 @@ describe('Public API Routes Integration Tests', () => {
|
||||
});
|
||||
|
||||
it('GET /api/flyers/:id/items should return items for a specific flyer', async () => {
|
||||
const response = await request.get(`/api/flyers/${testFlyer.flyer_id}/items`);
|
||||
const response = await request.get(`/api/v1/flyers/${testFlyer.flyer_id}/items`);
|
||||
const items: FlyerItem[] = response.body.data;
|
||||
expect(response.status).toBe(200);
|
||||
expect(items).toBeInstanceOf(Array);
|
||||
@@ -213,7 +213,7 @@ describe('Public API Routes Integration Tests', () => {
|
||||
[testRecipe.recipe_id, testUser.user.user_id],
|
||||
);
|
||||
createdRecipeCommentIds.push(commentRes.rows[0].recipe_comment_id);
|
||||
const response = await request.get(`/api/recipes/${testRecipe.recipe_id}/comments`);
|
||||
const response = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}/comments`);
|
||||
const comments: RecipeComment[] = response.body.data;
|
||||
expect(response.status).toBe(200);
|
||||
expect(comments).toBeInstanceOf(Array);
|
||||
|
||||
@@ -372,7 +372,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
|
||||
it('should return receipt with items', async () => {
|
||||
const response = await request
|
||||
.get(`/api/receipts/${testReceiptId}`)
|
||||
.get(`/api/v1/receipts/${testReceiptId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
@@ -401,7 +401,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
createdUserIds.push(otherUser.user.user_id);
|
||||
|
||||
const response = await request
|
||||
.get(`/api/receipts/${testReceiptId}`)
|
||||
.get(`/api/v1/receipts/${testReceiptId}`)
|
||||
.set('Authorization', `Bearer ${otherToken}`);
|
||||
|
||||
expect(response.status).toBe(404);
|
||||
@@ -421,14 +421,14 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
const receiptId = result.rows[0].receipt_id;
|
||||
|
||||
const response = await request
|
||||
.delete(`/api/receipts/${receiptId}`)
|
||||
.delete(`/api/v1/receipts/${receiptId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(204);
|
||||
|
||||
// Verify deletion
|
||||
const verifyResponse = await request
|
||||
.get(`/api/receipts/${receiptId}`)
|
||||
.get(`/api/v1/receipts/${receiptId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(verifyResponse.status).toBe(404);
|
||||
@@ -452,7 +452,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
|
||||
it('should queue a failed receipt for reprocessing', async () => {
|
||||
const response = await request
|
||||
.post(`/api/receipts/${failedReceiptId}/reprocess`)
|
||||
.post(`/api/v1/receipts/${failedReceiptId}/reprocess`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
@@ -497,7 +497,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
describe('GET /api/receipts/:receiptId/items', () => {
|
||||
it('should return all receipt items', async () => {
|
||||
const response = await request
|
||||
.get(`/api/receipts/${receiptWithItemsId}/items`)
|
||||
.get(`/api/v1/receipts/${receiptWithItemsId}/items`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
@@ -510,7 +510,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
describe('PUT /api/receipts/:receiptId/items/:itemId', () => {
|
||||
it('should update item status', async () => {
|
||||
const response = await request
|
||||
.put(`/api/receipts/${receiptWithItemsId}/items/${testItemId}`)
|
||||
.put(`/api/v1/receipts/${receiptWithItemsId}/items/${testItemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ status: 'matched', match_confidence: 0.95 });
|
||||
|
||||
@@ -520,7 +520,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
|
||||
it('should reject invalid status', async () => {
|
||||
const response = await request
|
||||
.put(`/api/receipts/${receiptWithItemsId}/items/${testItemId}`)
|
||||
.put(`/api/v1/receipts/${receiptWithItemsId}/items/${testItemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ status: 'invalid_status' });
|
||||
|
||||
@@ -531,7 +531,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
describe('GET /api/receipts/:receiptId/items/unadded', () => {
|
||||
it('should return unadded items', async () => {
|
||||
const response = await request
|
||||
.get(`/api/receipts/${receiptWithItemsId}/items/unadded`)
|
||||
.get(`/api/v1/receipts/${receiptWithItemsId}/items/unadded`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
@@ -567,7 +567,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
|
||||
it('should confirm items and add to inventory', async () => {
|
||||
const response = await request
|
||||
.post(`/api/receipts/${receiptForConfirmId}/confirm`)
|
||||
.post(`/api/v1/receipts/${receiptForConfirmId}/confirm`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({
|
||||
items: [
|
||||
@@ -608,7 +608,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
const skipItemId = itemResult.rows[0].receipt_item_id;
|
||||
|
||||
const response = await request
|
||||
.post(`/api/receipts/${receiptForConfirmId}/confirm`)
|
||||
.post(`/api/v1/receipts/${receiptForConfirmId}/confirm`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({
|
||||
items: [
|
||||
@@ -625,7 +625,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
|
||||
it('should reject invalid location', async () => {
|
||||
const response = await request
|
||||
.post(`/api/receipts/${receiptForConfirmId}/confirm`)
|
||||
.post(`/api/v1/receipts/${receiptForConfirmId}/confirm`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({
|
||||
items: [
|
||||
@@ -669,7 +669,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
|
||||
it('should return processing logs', async () => {
|
||||
const response = await request
|
||||
.get(`/api/receipts/${receiptWithLogsId}/logs`)
|
||||
.get(`/api/v1/receipts/${receiptWithLogsId}/logs`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
@@ -703,7 +703,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
|
||||
// Step 2: Verify receipt was created
|
||||
const getResponse = await request
|
||||
.get(`/api/receipts/${receiptId}`)
|
||||
.get(`/api/v1/receipts/${receiptId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(getResponse.status).toBe(200);
|
||||
@@ -722,7 +722,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
|
||||
|
||||
// Step 4: Verify logs endpoint works (empty for new receipt)
|
||||
const logsResponse = await request
|
||||
.get(`/api/receipts/${receiptId}/logs`)
|
||||
.get(`/api/v1/receipts/${receiptId}/logs`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(logsResponse.status).toBe(200);
|
||||
|
||||
@@ -66,7 +66,7 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
|
||||
describe('GET /api/recipes/:recipeId', () => {
|
||||
it('should fetch a single public recipe by its ID', async () => {
|
||||
const response = await request.get(`/api/recipes/${testRecipe.recipe_id}`);
|
||||
const response = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.body.data).toBeDefined();
|
||||
@@ -104,7 +104,7 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
createdRecipeIds.push(createdRecipe.recipe_id);
|
||||
|
||||
// Verify the recipe can be fetched from the public endpoint
|
||||
const verifyResponse = await request.get(`/api/recipes/${createdRecipe.recipe_id}`);
|
||||
const verifyResponse = await request.get(`/api/v1/recipes/${createdRecipe.recipe_id}`);
|
||||
expect(verifyResponse.status).toBe(200);
|
||||
expect(verifyResponse.body.data.name).toBe(newRecipeData.name);
|
||||
});
|
||||
@@ -115,7 +115,7 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
};
|
||||
|
||||
const response = await request
|
||||
.put(`/api/users/recipes/${testRecipe.recipe_id}`) // Authenticated recipe update endpoint
|
||||
.put(`/api/v1/users/recipes/${testRecipe.recipe_id}`) // Authenticated recipe update endpoint
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send(recipeUpdates);
|
||||
|
||||
@@ -126,7 +126,7 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
expect(updatedRecipe.instructions).toBe(recipeUpdates.instructions);
|
||||
|
||||
// Verify the changes were persisted by fetching the recipe again
|
||||
const verifyResponse = await request.get(`/api/recipes/${testRecipe.recipe_id}`);
|
||||
const verifyResponse = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}`);
|
||||
expect(verifyResponse.status).toBe(200);
|
||||
expect(verifyResponse.body.data.name).toBe(recipeUpdates.name);
|
||||
});
|
||||
@@ -141,7 +141,7 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
|
||||
// Attempt to update the testRecipe (owned by testUser) using otherUser's token
|
||||
const response = await request
|
||||
.put(`/api/users/recipes/${testRecipe.recipe_id}`)
|
||||
.put(`/api/v1/users/recipes/${testRecipe.recipe_id}`)
|
||||
.set('Authorization', `Bearer ${otherToken}`)
|
||||
.send({ name: 'Hacked Recipe Name' });
|
||||
|
||||
@@ -165,13 +165,13 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
|
||||
// Delete the recipe
|
||||
const deleteRes = await request
|
||||
.delete(`/api/users/recipes/${recipeToDelete.recipe_id}`)
|
||||
.delete(`/api/v1/users/recipes/${recipeToDelete.recipe_id}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(deleteRes.status).toBe(204);
|
||||
|
||||
// Verify it's actually deleted by trying to fetch it
|
||||
const verifyRes = await request.get(`/api/recipes/${recipeToDelete.recipe_id}`);
|
||||
const verifyRes = await request.get(`/api/v1/recipes/${recipeToDelete.recipe_id}`);
|
||||
expect(verifyRes.status).toBe(404);
|
||||
});
|
||||
|
||||
@@ -186,14 +186,14 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
|
||||
// Attempt to delete the testRecipe (owned by testUser) using otherUser's token
|
||||
const response = await request
|
||||
.delete(`/api/users/recipes/${testRecipe.recipe_id}`)
|
||||
.delete(`/api/v1/users/recipes/${testRecipe.recipe_id}`)
|
||||
.set('Authorization', `Bearer ${otherToken}`);
|
||||
|
||||
// Should return 404 because the recipe doesn't belong to this user
|
||||
expect(response.status).toBe(404);
|
||||
|
||||
// Verify the recipe still exists
|
||||
const verifyRes = await request.get(`/api/recipes/${testRecipe.recipe_id}`);
|
||||
const verifyRes = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}`);
|
||||
expect(verifyRes.status).toBe(200);
|
||||
});
|
||||
|
||||
@@ -201,7 +201,7 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
const commentContent = 'This is a great recipe! Thanks for sharing.';
|
||||
|
||||
const response = await request
|
||||
.post(`/api/recipes/${testRecipe.recipe_id}/comments`)
|
||||
.post(`/api/v1/recipes/${testRecipe.recipe_id}/comments`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ content: commentContent });
|
||||
|
||||
@@ -215,7 +215,7 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
|
||||
it('should allow an authenticated user to fork a recipe', async () => {
|
||||
const response = await request
|
||||
.post(`/api/recipes/${testRecipe.recipe_id}/fork`)
|
||||
.post(`/api/v1/recipes/${testRecipe.recipe_id}/fork`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(201);
|
||||
@@ -254,7 +254,7 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
|
||||
// Fork the seed recipe - this should succeed
|
||||
const response = await request
|
||||
.post(`/api/recipes/${seedRecipeId}/fork`)
|
||||
.post(`/api/v1/recipes/${seedRecipeId}/fork`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
// Forking should work - seed recipes should be forkable
|
||||
@@ -271,12 +271,12 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
it('should return comments for a recipe', async () => {
|
||||
// First add a comment
|
||||
await request
|
||||
.post(`/api/recipes/${testRecipe.recipe_id}/comments`)
|
||||
.post(`/api/v1/recipes/${testRecipe.recipe_id}/comments`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ content: 'Test comment for GET request' });
|
||||
|
||||
// Now fetch comments
|
||||
const response = await request.get(`/api/recipes/${testRecipe.recipe_id}/comments`);
|
||||
const response = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}/comments`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.body.success).toBe(true);
|
||||
@@ -306,7 +306,7 @@ describe('Recipe API Routes Integration Tests', () => {
|
||||
createdRecipeIds.push(noCommentsRecipe.recipe_id);
|
||||
|
||||
// Fetch comments for this recipe
|
||||
const response = await request.get(`/api/recipes/${noCommentsRecipe.recipe_id}/comments`);
|
||||
const response = await request.get(`/api/v1/recipes/${noCommentsRecipe.recipe_id}/comments`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
expect(response.body.success).toBe(true);
|
||||
|
||||
@@ -311,7 +311,7 @@ describe('UPC Scanning Integration Tests (/api/upc)', () => {
|
||||
|
||||
it('should return a specific scan by ID', async () => {
|
||||
const response = await request
|
||||
.get(`/api/upc/history/${testScanId}`)
|
||||
.get(`/api/v1/upc/history/${testScanId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
@@ -338,7 +338,7 @@ describe('UPC Scanning Integration Tests (/api/upc)', () => {
|
||||
createdUserIds.push(otherUser.user.user_id);
|
||||
|
||||
const response = await request
|
||||
.get(`/api/upc/history/${testScanId}`)
|
||||
.get(`/api/v1/upc/history/${testScanId}`)
|
||||
.set('Authorization', `Bearer ${otherToken}`);
|
||||
|
||||
expect(response.status).toBe(404);
|
||||
@@ -467,7 +467,7 @@ describe('UPC Scanning Integration Tests (/api/upc)', () => {
|
||||
|
||||
// Step 4: Verify in history
|
||||
const historyResponse = await request
|
||||
.get(`/api/upc/history/${scanId}`)
|
||||
.get(`/api/v1/upc/history/${scanId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(historyResponse.status).toBe(200);
|
||||
|
||||
@@ -278,7 +278,7 @@ describe('User API Routes Integration Tests', () => {
|
||||
|
||||
// Act 3: Remove the watched item.
|
||||
const removeResponse = await request
|
||||
.delete(`/api/users/watched-items/${newItem.master_grocery_item_id}`)
|
||||
.delete(`/api/v1/users/watched-items/${newItem.master_grocery_item_id}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
expect(removeResponse.status).toBe(204);
|
||||
|
||||
@@ -309,7 +309,7 @@ describe('User API Routes Integration Tests', () => {
|
||||
|
||||
// Act 2: Add an item to the new list.
|
||||
const addItemResponse = await request
|
||||
.post(`/api/users/shopping-lists/${newList.shopping_list_id}/items`)
|
||||
.post(`/api/v1/users/shopping-lists/${newList.shopping_list_id}/items`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ customItemName: 'Custom Test Item' });
|
||||
const addedItem = addItemResponse.body.data;
|
||||
|
||||
@@ -122,7 +122,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
|
||||
|
||||
// 3. Delete
|
||||
const deleteResponse = await request
|
||||
.delete(`/api/users/shopping-lists/${listId}`)
|
||||
.delete(`/api/v1/users/shopping-lists/${listId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
expect(deleteResponse.status).toBe(204);
|
||||
|
||||
@@ -157,7 +157,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
|
||||
|
||||
// Act 1: Malicious user attempts to add an item to the owner's list.
|
||||
const addItemResponse = await request
|
||||
.post(`/api/users/shopping-lists/${listId}/items`)
|
||||
.post(`/api/v1/users/shopping-lists/${listId}/items`)
|
||||
.set('Authorization', `Bearer ${maliciousToken}`) // Use malicious user's token
|
||||
.send({ customItemName: 'Malicious Item' });
|
||||
|
||||
@@ -167,7 +167,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
|
||||
|
||||
// Act 2: Malicious user attempts to delete the owner's list.
|
||||
const deleteResponse = await request
|
||||
.delete(`/api/users/shopping-lists/${listId}`)
|
||||
.delete(`/api/v1/users/shopping-lists/${listId}`)
|
||||
.set('Authorization', `Bearer ${maliciousToken}`); // Use malicious user's token
|
||||
|
||||
// Assert 2: This should also fail with a 404.
|
||||
@@ -177,7 +177,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
|
||||
// Act 3: Malicious user attempts to update an item on the owner's list.
|
||||
// First, the owner adds an item.
|
||||
const ownerAddItemResponse = await request
|
||||
.post(`/api/users/shopping-lists/${listId}/items`)
|
||||
.post(`/api/v1/users/shopping-lists/${listId}/items`)
|
||||
.set('Authorization', `Bearer ${authToken}`) // Owner's token
|
||||
.send({ customItemName: 'Legitimate Item' });
|
||||
expect(ownerAddItemResponse.status).toBe(201);
|
||||
@@ -185,7 +185,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
|
||||
|
||||
// Now, the malicious user tries to update it.
|
||||
const updateItemResponse = await request
|
||||
.put(`/api/users/shopping-lists/items/${itemId}`)
|
||||
.put(`/api/v1/users/shopping-lists/items/${itemId}`)
|
||||
.set('Authorization', `Bearer ${maliciousToken}`) // Malicious token
|
||||
.send({ is_purchased: true });
|
||||
|
||||
@@ -195,7 +195,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
|
||||
|
||||
// Cleanup the list created in this test
|
||||
await request
|
||||
.delete(`/api/users/shopping-lists/${listId}`)
|
||||
.delete(`/api/v1/users/shopping-lists/${listId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
});
|
||||
});
|
||||
@@ -217,14 +217,14 @@ describe('User Routes Integration Tests (/api/users)', () => {
|
||||
afterAll(async () => {
|
||||
if (listId) {
|
||||
await request
|
||||
.delete(`/api/users/shopping-lists/${listId}`)
|
||||
.delete(`/api/v1/users/shopping-lists/${listId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
}
|
||||
});
|
||||
|
||||
it('should add an item to a shopping list', async () => {
|
||||
const response = await request
|
||||
.post(`/api/users/shopping-lists/${listId}/items`)
|
||||
.post(`/api/v1/users/shopping-lists/${listId}/items`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send({ customItemName: 'Test Item' });
|
||||
|
||||
@@ -237,7 +237,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
|
||||
it('should update an item in a shopping list', async () => {
|
||||
const updates = { is_purchased: true, quantity: 5 };
|
||||
const response = await request
|
||||
.put(`/api/users/shopping-lists/items/${itemId}`)
|
||||
.put(`/api/v1/users/shopping-lists/items/${itemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`)
|
||||
.send(updates);
|
||||
|
||||
@@ -248,7 +248,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
|
||||
|
||||
it('should delete an item from a shopping list', async () => {
|
||||
const response = await request
|
||||
.delete(`/api/users/shopping-lists/items/${itemId}`)
|
||||
.delete(`/api/v1/users/shopping-lists/items/${itemId}`)
|
||||
.set('Authorization', `Bearer ${authToken}`);
|
||||
|
||||
expect(response.status).toBe(204);
|
||||
|
||||
50
src/types/express.d.ts
vendored
50
src/types/express.d.ts
vendored
@@ -2,16 +2,60 @@
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { Logger } from 'pino';
|
||||
import * as qs from 'qs';
|
||||
import type { ApiVersion, VersionDeprecation } from '../config/apiVersions';
|
||||
|
||||
/**
|
||||
* This file uses declaration merging to add a custom `log` property to the
|
||||
* global Express Request interface. This makes the request-scoped logger
|
||||
* available in a type-safe way in all route handlers, as required by ADR-004.
|
||||
* This file uses declaration merging to add custom properties to the
|
||||
* global Express Request interface.
|
||||
*
|
||||
* Extended properties:
|
||||
* - `log`: Request-scoped Pino logger (ADR-004)
|
||||
* - `apiVersion`: API version extracted from request path (ADR-008)
|
||||
* - `versionDeprecation`: Deprecation info when accessing deprecated versions (ADR-008)
|
||||
*
|
||||
* @see docs/adr/0004-request-scoped-logging.md
|
||||
* @see docs/adr/0008-api-versioning-strategy.md
|
||||
*/
|
||||
declare global {
|
||||
namespace Express {
|
||||
export interface Request {
|
||||
/**
|
||||
* Request-scoped Pino logger instance.
|
||||
* Includes request context (requestId, userId, etc.) for correlation.
|
||||
* @see ADR-004 for logging standards
|
||||
*/
|
||||
log: Logger;
|
||||
|
||||
/**
|
||||
* The API version detected from the request path.
|
||||
* Set by apiVersion middleware based on /api/v{n}/ path pattern.
|
||||
* Defaults to 'v1' when no version is detected.
|
||||
*
|
||||
* @example
|
||||
* // In a route handler:
|
||||
* if (req.apiVersion === 'v2') {
|
||||
* return sendSuccess(res, transformV2(data));
|
||||
* }
|
||||
*
|
||||
* @see ADR-008 for versioning strategy
|
||||
*/
|
||||
apiVersion?: ApiVersion;
|
||||
|
||||
/**
|
||||
* Deprecation information when accessing a deprecated API version.
|
||||
* Set by deprecation middleware when the requested version is deprecated.
|
||||
* Undefined when accessing active versions.
|
||||
*
|
||||
* @example
|
||||
* // In a route handler:
|
||||
* if (req.versionDeprecation?.isDeprecated) {
|
||||
* req.log.warn({ sunsetDate: req.versionDeprecation.sunsetDate },
|
||||
* 'Client using deprecated API version');
|
||||
* }
|
||||
*
|
||||
* @see ADR-008 for deprecation workflow
|
||||
*/
|
||||
versionDeprecation?: VersionDeprecation;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user