Revise and expand Xget project documentation
Rewrites the CLAUDE.md file for improved clarity, conciseness, and structure. Updates project overview, development commands, architecture, configuration, platform handling, testing, deployment, and security sections. Adds more detailed explanations, reorganizes content, and provides clearer instructions for contributors and maintainers.
This commit is contained in:
xixu-me committed
1 parent
70070132f7
commit
c03964d702
1 file changed
+218
-227
@@ -4,318 +4,309 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## Project Overview
|
||||
|
||||
Xget is a high-performance, security-focused acceleration engine for developer resources. It's a Cloudflare Workers application written in JavaScript that proxies and accelerates access to 40+ platforms including code repositories (GitHub, GitLab), package managers (npm, PyPI, Maven), container registries (Docker Hub, ghcr.io), AI inference providers (OpenAI, Anthropic), and Linux distributions.
|
||||
Xget is a high-performance, Cloudflare Workers-based acceleration engine for developer resources. It provides unified acceleration for code repositories (GitHub, GitLab, etc.), package registries (npm, PyPI, Maven, etc.), container registries (Docker Hub, GHCR, etc.), and AI inference APIs (OpenAI, Anthropic, etc.).
|
||||
|
||||
**Key characteristics:**
|
||||
|
||||
- Runs on Cloudflare Workers (edge computing platform)
|
||||
- Single-file architecture: all core logic in `src/index.js` (~1500 lines)
|
||||
- Configuration-driven platform support via `src/config/platforms.js`
|
||||
- No external dependencies in production (uses only Web APIs and Cloudflare Workers APIs)
|
||||
- Supports HTTP/3, intelligent caching, retry logic, and performance monitoring
|
||||
The project operates as a reverse proxy that transforms incoming requests to match various platform APIs while adding security headers, caching, retry logic, and performance monitoring.
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Local Development
|
||||
### Core Commands
|
||||
|
||||
```bash
|
||||
npm run dev # Start local development server with Wrangler
|
||||
npm start # Alias for npm run dev
|
||||
# Start development server (Cloudflare Workers local environment)
|
||||
npm run dev # Runs on http://localhost:8787
|
||||
|
||||
# Deploy to Cloudflare Workers production
|
||||
npm run deploy
|
||||
|
||||
# Build and run tests
|
||||
npm run test # Run tests in watch mode
|
||||
npm run test:run # Run tests once
|
||||
npm run test:coverage # Generate coverage report
|
||||
npm run test:ui # Open Vitest UI
|
||||
|
||||
# Code quality
|
||||
npm run lint # Check code quality
|
||||
npm run lint:fix # Fix linting issues
|
||||
npm run format # Format code with Prettier
|
||||
npm run format:check # Check formatting without changes
|
||||
npm run type-check # TypeScript type checking (no emit)
|
||||
```
|
||||
|
||||
### Testing
|
||||
### Testing Workflow
|
||||
|
||||
```bash
|
||||
npm test # Run all tests with Vitest (watch mode)
|
||||
npm run test:run # Run tests once without watch mode
|
||||
npm run test:coverage # Generate coverage report (requires 80% threshold)
|
||||
npm run test:ui # Launch Vitest UI
|
||||
npm run test:watch # Explicitly run in watch mode
|
||||
```
|
||||
|
||||
**Run a single test file:**
|
||||
|
||||
```bash
|
||||
npx vitest run test/platforms.test.js
|
||||
```
|
||||
|
||||
**Run tests matching a pattern:**
|
||||
|
||||
```bash
|
||||
npm test -- --grep "GitHub"
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
npm run lint # Run ESLint on src/ and test/
|
||||
npm run lint:fix # Auto-fix ESLint issues
|
||||
npm run format # Format code with Prettier
|
||||
npm run format:check # Check formatting without modifying
|
||||
npm run type-check # Run TypeScript type checking (no emit)
|
||||
```
|
||||
|
||||
### Deployment
|
||||
|
||||
```bash
|
||||
npm run deploy # Deploy to Cloudflare Workers
|
||||
```
|
||||
|
||||
**Note:** Deployment requires Cloudflare account and proper wrangler authentication (`wrangler login`).
|
||||
- Tests use Vitest with `@cloudflare/vitest-pool-workers` for Workers-specific testing
|
||||
- Run `npm run test:run` before committing to ensure all tests pass
|
||||
- Coverage reports are generated in `coverage/` directory
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Request Flow
|
||||
### Request Flow
|
||||
|
||||
1. **Request Reception** (`src/index.js` fetch handler)
|
||||
- Validates HTTP method (GET/HEAD by default, POST allowed for Git operations)
|
||||
- Enforces path length limits (max 2048 characters)
|
||||
- Creates `PerformanceMonitor` instance for timing metrics
|
||||
1. **Entry Point**: `src/index.js` - Exports default Worker with `fetch()` handler
|
||||
2. **Validation**: `src/utils/validation.js` - Validates HTTP methods, path length, detects protocol types
|
||||
3. **Platform Detection**: URL path is parsed to identify platform (e.g., `/gh/` → GitHub)
|
||||
4. **Path Transformation**: `src/config/platforms.js#transformPath()` converts request paths to upstream URLs
|
||||
5. **Protocol Handling**: Different handlers for Git, Docker, AI inference requests
|
||||
6. **Upstream Fetch**: Request forwarded with appropriate headers and retry logic
|
||||
7. **Response Processing**: URL rewriting for certain platforms (npm, PyPI), cache storage
|
||||
8. **Security Headers**: Added via `src/utils/security.js` before returning to client
|
||||
|
||||
2. **Platform Detection & URL Transformation**
|
||||
- Extracts platform prefix from URL path (e.g., `/gh/user/repo` → platform: `gh`)
|
||||
- Uses `transformPath()` from `src/config/platforms.js` to convert Xget URL to upstream URL
|
||||
- Platform config in `PLATFORMS` object maps prefixes to base URLs
|
||||
### Key Components
|
||||
|
||||
3. **Protocol Detection**
|
||||
- **Git detection** (`isGitRequest`): checks for `/info/refs`, `/git-upload-pack`, `/git-receive-pack`, Git User-Agent
|
||||
- **Docker detection** (`isDockerRequest`): checks for `/v2/` paths, Docker User-Agent, OCI manifest headers
|
||||
- **Git LFS detection** (`isGitLFSRequest`): checks for `.git/info/lfs`, `application/vnd.git-lfs+json`
|
||||
- **AI inference detection** (`isAIInferenceRequest`): checks for `ip-` platform prefix
|
||||
#### Configuration (`src/config/`)
|
||||
|
||||
4. **Caching Layer**
|
||||
- Cache is **skipped** for Git, Git LFS, Docker, and AI inference requests
|
||||
- Uses Cloudflare Cache API for HTTP GET/HEAD requests
|
||||
- Default TTL: 1800 seconds (30 minutes)
|
||||
- Supports HTTP Range requests with intelligent cache lookup
|
||||
- **`index.js`**: Runtime configuration with environment variable overrides
|
||||
- `TIMEOUT_SECONDS`: Request timeout (default: 30s)
|
||||
- `MAX_RETRIES`: Retry attempts (default: 3)
|
||||
- `CACHE_DURATION`: Cache TTL (default: 1800s = 30 minutes)
|
||||
- `SECURITY.ALLOWED_METHODS`: HTTP methods (default: GET, HEAD)
|
||||
|
||||
5. **Upstream Fetch with Retry**
|
||||
- Retry logic: max 3 attempts with linear backoff (1000ms × retry count)
|
||||
- Timeout: 30 seconds per request
|
||||
- Request headers are proxied (User-Agent, Authorization, Range, etc.)
|
||||
- Special handling for Git (`service=git-upload-pack` query params) and Docker (authentication flow)
|
||||
- **`platforms.js`**: Platform definitions and path transformations
|
||||
- `PLATFORMS`: Object mapping platform keys to base URLs
|
||||
- `SORTED_PLATFORMS`: Pre-sorted keys for efficient matching
|
||||
- `transformPath()`: Converts request paths to platform-specific URLs
|
||||
- Special handling for crates.io (adds `/api/v1/crates` prefix), Jenkins (adds `/current/` prefix), and Homebrew
|
||||
|
||||
6. **Response Processing**
|
||||
- Adds security headers (HSTS, CSP, X-Frame-Options, etc.)
|
||||
- Adds performance metrics via `X-Performance-Metrics` header
|
||||
- Caches successful responses (200-299 status codes)
|
||||
- Handles CORS for allowed origins
|
||||
#### Protocol Handlers (`src/protocols/`)
|
||||
|
||||
### Platform Configuration System
|
||||
- **`git.js`**: Git protocol detection and header configuration
|
||||
- Detects Git operations via User-Agent, endpoints (`/info/refs`, `/git-upload-pack`)
|
||||
- Handles Git LFS via `Accept: application/vnd.git-lfs+json`
|
||||
|
||||
**File:** `src/config/platforms.js`
|
||||
- **`docker.js`**: Container registry protocol (OCI/Docker)
|
||||
- Parses WWW-Authenticate headers for token authentication
|
||||
- Handles Docker registry v2 API authentication flow
|
||||
- Special redirect handling to prevent leaking auth tokens to blob storage
|
||||
|
||||
This file contains:
|
||||
- **`ai.js`**: AI inference API detection and header forwarding
|
||||
- Detects requests to `/ip/*` platforms
|
||||
- Preserves all headers for AI API compatibility
|
||||
|
||||
- `PLATFORMS` object: maps platform prefixes to base URLs (e.g., `gh: 'https://github.com'`)
|
||||
- `transformPath(effectivePath, platform)` function: converts Xget paths to upstream paths
|
||||
- Handles special cases like container registries (`cr-*` platforms)
|
||||
- Strips platform prefix and reconstructs correct upstream URL structure
|
||||
#### Utilities (`src/utils/`)
|
||||
|
||||
**Adding a new platform:**
|
||||
- **`validation.js`**: Request validation logic
|
||||
- `isDockerRequest()`: Detects Docker/OCI operations
|
||||
- `validateRequest()`: Enforces security policies
|
||||
|
||||
1. Add entry to `PLATFORMS` object with prefix and base URL
|
||||
2. If URL transformation needs special logic, add case in `transformPath()`
|
||||
3. Add tests in `test/platforms.test.js`
|
||||
4. Update documentation (README.md)
|
||||
- **`security.js`**: Security headers and error responses
|
||||
- Adds HSTS, X-Frame-Options, CSP, X-XSS-Protection
|
||||
- `createErrorResponse()`: Generates standardized error responses
|
||||
|
||||
### Configuration & Environment
|
||||
- **`performance.js`**: Performance monitoring
|
||||
- `PerformanceMonitor`: Tracks request timing
|
||||
- Adds `X-Performance-Metrics` header to responses
|
||||
|
||||
**File:** `src/config/index.js`
|
||||
### Caching Strategy
|
||||
|
||||
The `createConfig(env)` function creates runtime configuration from environment variables:
|
||||
- Uses Cloudflare Cache API for GET requests (200 OK only)
|
||||
- Cache TTL controlled by `CACHE_DURATION` config
|
||||
- Skips cache for: Git operations, Docker operations, AI inference requests
|
||||
- Range requests: First checks for range-specific cache, falls back to full content cache
|
||||
|
||||
- `TIMEOUT_SECONDS` (default: 30)
|
||||
- `MAX_RETRIES` (default: 3)
|
||||
- `RETRY_DELAY_MS` (default: 1000)
|
||||
- `CACHE_DURATION` (default: 1800)
|
||||
- `ALLOWED_METHODS` (default: 'GET,HEAD')
|
||||
- `ALLOWED_ORIGINS` (default: '*')
|
||||
- `MAX_PATH_LENGTH` (default: 2048)
|
||||
### Special Platform Handling
|
||||
|
||||
Environment variables are set via Cloudflare Workers dashboard or `wrangler.toml`.
|
||||
#### npm
|
||||
|
||||
## Testing Strategy
|
||||
- Rewrites `https://registry.npmjs.org/` URLs in JSON responses to point to Xget instance
|
||||
|
||||
**Framework:** Vitest with `@cloudflare/vitest-pool-workers` (simulates Cloudflare Workers environment)
|
||||
#### PyPI
|
||||
|
||||
**Test Organization:**
|
||||
- Rewrites `https://files.pythonhosted.org` URLs in HTML responses to point to Xget instance
|
||||
- Uses separate `pypi-files` platform for file downloads
|
||||
|
||||
- `test/index.test.js` - Core request handling logic
|
||||
- `test/platforms.test.js` - Platform URL transformation logic
|
||||
- `test/integration.test.js` - End-to-end integration tests
|
||||
- `test/security.test.js` - Security validation (headers, input validation)
|
||||
- `test/performance.test.js` - Performance monitoring tests
|
||||
- `test/range-cache.test.js` - HTTP Range request caching
|
||||
- `test/container-registry.test.js` - Docker/OCI registry support
|
||||
- `test/[platform].test.js` - Platform-specific tests (npm, homebrew, jenkins, etc.)
|
||||
- `test/helpers/test-utils.js` - Shared test utilities and mock helpers
|
||||
#### crates.io
|
||||
|
||||
**Coverage requirements:** 80% minimum (branches, functions, lines, statements)
|
||||
- Adds `/api/v1/crates` prefix to all API requests
|
||||
- Handles search endpoint (`/?q=`) specially
|
||||
|
||||
**Important testing notes:**
|
||||
#### Jenkins
|
||||
|
||||
- Tests run in a simulated Cloudflare Workers environment (not Node.js)
|
||||
- Use `SELF.fetch()` to test the worker (provided by vitest-pool-workers)
|
||||
- Mock external fetch calls using `vi.spyOn(globalThis, 'fetch')`
|
||||
- Test fixtures in `test/fixtures/` for sample responses
|
||||
- Adds `/current/` prefix to update center paths
|
||||
- Preserves `/experimental/` and `/download/` paths as-is
|
||||
|
||||
## Code Style & Conventions
|
||||
#### Docker Registries
|
||||
|
||||
**Enforced by ESLint + Prettier:**
|
||||
- Handles authentication via token service
|
||||
- Uses manual redirect mode to strip Authorization headers before S3 redirects
|
||||
- Auto-retries with public token on 401 responses
|
||||
|
||||
- 2-space indentation
|
||||
- Single quotes for strings
|
||||
- Semicolons required
|
||||
- camelCase for variables/functions
|
||||
- UPPER_SNAKE_CASE for constants
|
||||
- PascalCase for classes
|
||||
- Use JSDoc comments for all exported functions and classes
|
||||
## Code Structure Conventions
|
||||
|
||||
**Example JSDoc:**
|
||||
### File Organization
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Transforms incoming request path to upstream platform URL.
|
||||
*
|
||||
* @param {string} effectivePath - The path from the Xget URL
|
||||
* @param {string} platform - Platform prefix (e.g., 'gh', 'npm')
|
||||
* @returns {string} Transformed path for upstream request
|
||||
*
|
||||
* @example
|
||||
* transformPath('/gh/user/repo/file.txt', 'gh')
|
||||
* // Returns: '/user/repo/file.txt'
|
||||
*/
|
||||
```
|
||||
src/
|
||||
├── index.js # Main Worker entry point
|
||||
├── config/
|
||||
│ ├── index.js # Runtime configuration
|
||||
│ └── platforms.js # Platform definitions
|
||||
├── protocols/
|
||||
│ ├── git.js # Git protocol handler
|
||||
│ ├── docker.js # Docker/OCI handler
|
||||
│ └── ai.js # AI inference handler
|
||||
└── utils/
|
||||
├── validation.js # Request validation
|
||||
├── security.js # Security utilities
|
||||
└── performance.js # Performance monitoring
|
||||
|
||||
test/
|
||||
├── features/ # Feature tests
|
||||
├── platforms/ # Platform-specific tests
|
||||
├── unit/ # Unit tests
|
||||
├── index.test.js # Core Worker tests
|
||||
└── integration.test.js # Integration tests
|
||||
```
|
||||
|
||||
## Common Development Tasks
|
||||
### Important Patterns
|
||||
|
||||
### Adding Support for a New Platform
|
||||
#### Protocol Detection Order
|
||||
|
||||
1. Add platform to `src/config/platforms.js`:
|
||||
1. Check if Docker request (via `isDockerRequest()`)
|
||||
2. Check if Git request (via `isGitRequest()`)
|
||||
3. Check if Git LFS request (via `isGitLFSRequest()`)
|
||||
4. Check if AI request (via `isAIInferenceRequest()`)
|
||||
5. Default to standard file download
|
||||
|
||||
```javascript
|
||||
export const PLATFORMS = {
|
||||
// ... existing platforms
|
||||
'newplatform': 'https://newplatform.com'
|
||||
};
|
||||
```
|
||||
#### Adding a New Platform
|
||||
|
||||
2. If special URL transformation needed, update `transformPath()` in `src/config/platforms.js`
|
||||
1. Add platform entry to `PLATFORMS` object in `src/config/platforms.js`
|
||||
2. If special path transformation needed, add case in `transformPath()` function
|
||||
3. Add platform tests in `test/platforms/`
|
||||
4. Update README.md with platform documentation
|
||||
|
||||
3. Add tests in `test/platforms.test.js` or create `test/newplatform.test.js`
|
||||
#### Retry Logic
|
||||
|
||||
4. Update README.md with platform prefix and examples
|
||||
- Retries up to `MAX_RETRIES` times with linear backoff
|
||||
- Delay: `RETRY_DELAY_MS * attempts` (default: 1000ms, 2000ms, 3000ms)
|
||||
- Retries on: Network errors, timeouts, 5xx errors
|
||||
- Does NOT retry: 4xx errors (except Docker 401 which has special handling)
|
||||
|
||||
### Debugging Cloudflare Workers Locally
|
||||
#### Error Handling
|
||||
|
||||
- Wrangler provides local development server with hot reload
|
||||
- Use `console.log()` - output appears in terminal
|
||||
- Performance metrics available via `X-Performance-Metrics` response header
|
||||
- Use `npm run dev` and test with `curl` or browser
|
||||
- All errors caught at top level in `handleRequest()`
|
||||
- Errors converted to JSON responses via `createErrorResponse()`
|
||||
- Performance metrics still added even on error paths
|
||||
|
||||
### Working with Docker/Container Registries
|
||||
## Testing Guidelines
|
||||
|
||||
Docker registry protocol requires:
|
||||
### Test Structure
|
||||
|
||||
- Authentication flow handling (`/v2/auth` endpoint)
|
||||
- WWW-Authenticate header parsing
|
||||
- Token fetching and proxying
|
||||
- Special MIME types (`application/vnd.docker.distribution.manifest.v2+json`)
|
||||
- **Unit tests** (`test/unit/`): Test individual functions in isolation
|
||||
- **Feature tests** (`test/features/`): Test specific features (auth, caching, Git, performance)
|
||||
- **Platform tests** (`test/platforms/`): Test platform-specific transformations
|
||||
- **Integration tests** (`test/integration.test.js`): End-to-end request flows
|
||||
|
||||
See `isDockerRequest()` and Docker-specific logic in `src/index.js:800-850`.
|
||||
### Running Specific Tests
|
||||
|
||||
### Handling Git Operations
|
||||
```bash
|
||||
# Run specific test file
|
||||
npm run test:run test/unit/platforms.test.js
|
||||
|
||||
Git protocol detection checks:
|
||||
# Run tests matching pattern
|
||||
npm run test:run -- --grep "Docker"
|
||||
|
||||
- URL paths: `/info/refs`, `/git-upload-pack`, `/git-receive-pack`
|
||||
- Query params: `service=git-upload-pack`
|
||||
- User-Agent: `git/` prefix
|
||||
# Run with coverage
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
Git requests **bypass cache** to ensure real-time data.
|
||||
### Common Test Patterns
|
||||
|
||||
## Security Considerations
|
||||
```javascript
|
||||
// Mock request creation
|
||||
const request = new Request('http://localhost/gh/microsoft/vscode', {
|
||||
method: 'GET',
|
||||
headers: { 'User-Agent': 'git/2.34.1' }
|
||||
});
|
||||
|
||||
**Never disable security headers** - they protect against XSS, clickjacking, and MITM attacks.
|
||||
// Mock environment
|
||||
const env = {};
|
||||
const ctx = { waitUntil: () => {} };
|
||||
|
||||
**Input validation:**
|
||||
// Test the worker
|
||||
const response = await worker.fetch(request, env, ctx);
|
||||
expect(response.status).toBe(200);
|
||||
```
|
||||
|
||||
- Always check path length before processing
|
||||
- Validate platform prefix exists in `PLATFORMS` config
|
||||
- Sanitize user input to prevent path traversal
|
||||
## Deployment
|
||||
|
||||
**Request method restrictions:**
|
||||
### Cloudflare Workers
|
||||
|
||||
- Default: GET/HEAD only
|
||||
- Git operations: also allow POST
|
||||
- Enforce via `ALLOWED_METHODS` configuration
|
||||
- Primary deployment target
|
||||
- Uses GitHub Actions for CI/CD (`.github/workflows/workers.yml`)
|
||||
- Requires `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` secrets
|
||||
|
||||
**CORS policy:**
|
||||
### Cloudflare Pages
|
||||
|
||||
- Default allows all origins (`*`)
|
||||
- Can be restricted via `ALLOWED_ORIGINS` environment variable
|
||||
- Always set appropriate CORS headers
|
||||
- Alternative deployment via adapter in `adapters/pages/`
|
||||
- Auto-synced from `main` branch to `pages` branch
|
||||
- Uses separate workflow (`.github/workflows/pages-cf.yml`)
|
||||
|
||||
## Deployment Options
|
||||
### Other Platforms
|
||||
|
||||
**Cloudflare Workers (Primary):**
|
||||
- **Vercel/Netlify**: Uses Functions adapter in `adapters/functions/`
|
||||
- **Deno Deploy**: Uses Functions adapter (compatible format)
|
||||
- **Docker**: Multi-stage build using `workerd` runtime
|
||||
|
||||
- Run `npm run deploy` after `wrangler login`
|
||||
- Configure environment variables in Cloudflare dashboard
|
||||
- Uses `wrangler.toml` for worker configuration
|
||||
### Environment Variables
|
||||
|
||||
**Self-hosted (Docker):**
|
||||
Configure in Cloudflare Workers dashboard or via `wrangler.toml`:
|
||||
|
||||
- Multi-stage Dockerfile builds worker with Wrangler
|
||||
- Runs with `workerd` runtime (Cloudflare's open-source Workers runtime)
|
||||
- Exposes port 8080
|
||||
- Uses `config.capnp` for workerd configuration
|
||||
- `TIMEOUT_SECONDS`: Override default timeout
|
||||
- `MAX_RETRIES`: Override retry count
|
||||
- `CACHE_DURATION`: Override cache TTL
|
||||
- `ALLOWED_METHODS`: Override allowed HTTP methods (comma-separated)
|
||||
- `ALLOWED_ORIGINS`: Override CORS origins (comma-separated)
|
||||
|
||||
**EdgeOne Pages (Alternative edge platform):**
|
||||
## Important Notes
|
||||
|
||||
- Similar to Cloudflare Workers
|
||||
- See README.md for deployment instructions
|
||||
### Security Considerations
|
||||
|
||||
## Performance Optimization
|
||||
- Never log or expose Authorization headers
|
||||
- Docker authentication tokens are stripped before S3 redirects
|
||||
- All responses include security headers (HSTS, CSP, X-Frame-Options, etc.)
|
||||
- Path length limited to prevent URL-based attacks (default: 2048 chars)
|
||||
|
||||
**Key performance features:**
|
||||
### Performance Optimization
|
||||
|
||||
- HTTP/3 support (via Cloudflare)
|
||||
- Brotli/gzip compression
|
||||
- Connection keep-alive and pre-warming
|
||||
- Edge caching with 30-minute default TTL
|
||||
- Parallel retry logic with linear backoff
|
||||
- Performance monitoring built-in (`PerformanceMonitor` class)
|
||||
- Use `ctx.waitUntil()` for cache writes to avoid blocking response
|
||||
- Range requests leverage cache when possible
|
||||
- Cloudflare edge caching (`cf` fetch options) for non-protocol requests
|
||||
- HTTP/3 enabled for supported clients
|
||||
|
||||
**Monitoring metrics:**
|
||||
### Git/Docker/AI Requests
|
||||
|
||||
- `cache_hit` - Successful cache retrieval
|
||||
- `attempt_N` - Nth retry attempt timestamp
|
||||
- `success` - Successful upstream fetch
|
||||
- Response includes `X-Performance-Metrics` with timing data
|
||||
- Skip normal caching mechanisms
|
||||
- Allow POST/PUT/PATCH methods
|
||||
- Preserve all upstream headers
|
||||
- No performance headers added (to maintain protocol compatibility)
|
||||
|
||||
## Troubleshooting
|
||||
### URL Rewriting
|
||||
|
||||
**Tests failing with "fetch is not defined":**
|
||||
- Only enabled for npm and PyPI platforms
|
||||
- Rewrites responses to point to Xget instance instead of upstream
|
||||
- Required for package managers to download dependencies through Xget
|
||||
|
||||
- Ensure using `@cloudflare/vitest-pool-workers` pool
|
||||
- Check `vitest.config.js` has correct pool configuration
|
||||
## Common Tasks
|
||||
|
||||
**Wrangler deployment fails:**
|
||||
### Adding a New Platform
|
||||
|
||||
- Run `wrangler login` first
|
||||
- Check `wrangler.toml` configuration
|
||||
- Verify Cloudflare account has Workers enabled
|
||||
1. Add to `PLATFORMS` object in `src/config/platforms.js`
|
||||
2. If special transformation needed, update `transformPath()`
|
||||
3. Add test in `test/platforms/`
|
||||
4. Update README.md documentation
|
||||
5. Test locally with `npm run dev`
|
||||
|
||||
**Cache not working:**
|
||||
### Debugging Requests
|
||||
|
||||
- Ensure not testing Git/Docker/AI requests (cache bypassed)
|
||||
- Check Cloudflare Workers cache API is available (not available in `wrangler dev`)
|
||||
- Verify HTTP status is 2xx
|
||||
1. Use `npm run dev` to start local server
|
||||
2. Add `console.log()` statements in `src/index.js`
|
||||
3. Check Wrangler dev server output
|
||||
4. Inspect `X-Performance-Metrics` header in responses
|
||||
|
||||
**Platform URL transformation incorrect:**
|
||||
### Fixing Test Failures
|
||||
|
||||
- Check `transformPath()` logic in `src/config/platforms.js`
|
||||
- Add console.log to debug URL construction
|
||||
- Verify platform prefix matches `PLATFORMS` key
|
||||
1. Run specific failing test: `npm run test:run test/path/to/test.js`
|
||||
2. Check mock setup matches actual request pattern
|
||||
3. Verify platform configuration in `src/config/platforms.js`
|
||||
4. Run all tests before committing: `npm run test:run`
|
||||
Reference in new issue
Block a user