121 lines
5.8 KiB
Markdown
121 lines
5.8 KiB
Markdown
# Proxy Detection API - Code Organization
|
|
|
|
This document describes the organized file structure of the Proxy Detection API.
|
|
|
|
## File Structure
|
|
|
|
The application has been organized into separate modules for better maintainability:
|
|
|
|
### Core Files
|
|
|
|
- **`index.ts`** - Entry point for the application
|
|
- **`server.ts`** - Server setup and initialization
|
|
- **`routes.ts`** - Route definitions and registration
|
|
|
|
### Module Files
|
|
|
|
- **`types.ts`** - TypeScript type definitions and interfaces
|
|
- **`config.ts`** - Configuration and environment variables
|
|
- **`middleware.ts`** - Authentication and other middleware functions
|
|
- **`handlers.ts`** - Route handler functions
|
|
- **`utils.ts`** - Utility functions for IP detection and processing
|
|
|
|
### Service Files
|
|
|
|
- **`proxyService.ts`** - IP extraction service (existing)
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ index.ts │
|
|
│ (Entry Point) │
|
|
└─────────────────────┬───────────────────────────────────────┘
|
|
│
|
|
┌─────────────────────▼───────────────────────────────────────┐
|
|
│ server.ts │
|
|
│ (Server Configuration) │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│
|
|
│ │ config │ │ middleware │ │ routes ││
|
|
│ └─────────────┘ └─────────────┘ └─────────────────────────┘│
|
|
└─────────────────────┬───────────────────────────────────────┘
|
|
│
|
|
┌─────────────────────▼───────────────────────────────────────┐
|
|
│ handlers.ts │
|
|
│ (Route Handlers) │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│
|
|
│ │ utils │ │ types │ │ proxyService ││
|
|
│ └─────────────┘ └─────────────┘ └─────────────────────────┘│
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Module Responsibilities
|
|
|
|
### `types.ts`
|
|
- `ApiResponse` - Main API response interface
|
|
- `HealthResponse` - Health check response interface
|
|
- `IPChainResult` - IP chain result interface
|
|
- `DetailedDebugResponse` - Debug endpoint response interface
|
|
|
|
### `config.ts`
|
|
- Environment variable management
|
|
- Server configuration settings
|
|
- CORS and trust proxy settings
|
|
- Application constants
|
|
|
|
### `utils.ts`
|
|
- `getClientIP()` - Enhanced IP detection with 30+ header sources
|
|
- `getFullIPChain()` - Extract full proxy chain information
|
|
- `normalizeHeaders()` - Normalize headers to consistent format
|
|
- `extractGeolocation()` - Extract geolocation from headers
|
|
- `extractProxyInfo()` - Extract proxy information from headers
|
|
|
|
### `middleware.ts`
|
|
- `authMiddleware()` - API key authentication
|
|
- Handles both header and query parameter authentication
|
|
- Skips authentication for health and debug endpoints
|
|
|
|
### `handlers.ts`
|
|
- `healthHandler()` - Health check endpoint
|
|
- `mainHandler()` - Main proxy detection endpoint
|
|
- `randomHandler()` - Random cached result endpoint
|
|
- `detailedDebugHandler()` - Detailed debug information endpoint
|
|
- In-memory result caching management
|
|
|
|
### `routes.ts`
|
|
- Route registration and organization
|
|
- Maps endpoints to their respective handlers
|
|
- Maintains authentication bypass configuration
|
|
|
|
### `server.ts`
|
|
- Fastify server instance creation
|
|
- CORS configuration
|
|
- Middleware registration
|
|
- Server startup and error handling
|
|
|
|
## Benefits of This Organization
|
|
|
|
1. **Separation of Concerns** - Each file has a specific responsibility
|
|
2. **Maintainability** - Easier to locate and modify specific functionality
|
|
3. **Testability** - Individual modules can be unit tested independently
|
|
4. **Reusability** - Utility functions can be easily reused
|
|
5. **Type Safety** - Centralized type definitions ensure consistency
|
|
6. **Configuration Management** - All settings are centralized and manageable
|
|
|
|
## Development Workflow
|
|
|
|
1. **Adding new endpoints**: Add handler to `handlers.ts`, register route in `routes.ts`
|
|
2. **Modifying IP detection**: Update functions in `utils.ts`
|
|
3. **Changing configuration**: Update `config.ts`
|
|
4. **Adding new types**: Add to `types.ts`
|
|
5. **Adding middleware**: Add to `middleware.ts`
|
|
|
|
## Running the Application
|
|
|
|
The application starts from `index.ts` which:
|
|
1. Creates a server instance
|
|
2. Configures middleware and routes
|
|
3. Starts the server
|
|
4. Handles startup errors
|
|
|
|
All functionality remains the same as the original monolithic version, but is now organized for better maintainability and scalability.
|