{"owner":"xixu-me","repo":"xget","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with\ncode in this repository.\n\n## Project Overview\n\nXget is a high-performance, Cloudflare Workers-based acceleration engine for\ndeveloper resources. It provides unified acceleration for code repositories\n(GitHub, GitLab, etc.), package registries (npm, PyPI, Maven, etc.), container\nregistries (Docker Hub, GHCR, etc.), and AI inference APIs (OpenAI, Anthropic,\netc.).\n\nThe project operates as a reverse proxy that transforms incoming requests to\nmatch various platform APIs while adding security headers, caching, retry logic,\nand performance monitoring.\n\n## Development Commands\n\n### Core Commands\n\n```bash\n# Start development server (Cloudflare Workers local environment)\nnpm run dev              # Runs on http://localhost:8787\n\n# Deploy to Cloudflare Workers production\nnpm run deploy\n\n# Build and run tests\nnpm run test             # Run tests in watch mode\nnpm run test:run         # Run tests once\nnpm run test:coverage    # Generate coverage report\nnpm run test:ui          # Open Vitest UI\n\n# Code quality\nnpm run lint             # Check code quality\nnpm run lint:fix         # Fix linting issues\nnpm run format           # Format code with Prettier\nnpm run format:check     # Check formatting without changes\nnpm run type-check       # TypeScript type checking (no emit)\nnpm run commitlint       # Validate the latest commit message\n```\n\n## Commit Messages\n\n- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for\n  every commit\n- Preferred format: `type(scope): description`\n- Common types: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `chore`\n- The repository installs a `commit-msg` hook via `npm install`; do not bypass\n  it unless explicitly required\n\n## Pre-Commit Requirements\n\n- Before every commit, run the local CI-equivalent checks from\n  `.github/workflows/ci.yml`\n- Required commands: `npm run lint`, `npm run format:check`, `npm run test:run`,\n  and `npm run type-check`\n- If any required check fails, do not commit until the failure is resolved\n- Apply this rule to every commit, including documentation-only changes, unless\n  the user explicitly asks for a different workflow\n\n### Testing Workflow\n\n- Tests use Vitest with `@cloudflare/vitest-pool-workers` for Workers-specific\n  testing\n- Run `npm run test:run` before committing to ensure all tests pass\n- Coverage reports are generated in `coverage/` directory\n\n## Architecture\n\n### Request Flow\n\n1. **Entry Point**: `src/index.js` - Exports default Worker with `fetch()`\n   handler\n2. **Validation**: `src/utils/validation.js` - Validates HTTP methods, path\n   length, detects protocol types\n3. **Platform Detection**: URL path is parsed to identify platform (e.g., `/gh/`\n   → GitHub)\n4. **Path Transformation**:\n   `src/routing/platform-transformers.js#transformPath()` converts request paths\n   to upstream URLs\n5. **Protocol Handling**: Different handlers for Git, Docker, AI inference\n   requests\n6. **Upstream Fetch**: Request forwarded with appropriate headers and retry\n   logic\n7. **Response Processing**: URL rewriting for certain platforms (npm, PyPI),\n   cache storage\n8. **Security Headers**: Added via `src/utils/security.js` before returning to\n   client\n\n### Key Components\n\n#### Configuration (`src/config/`)\n\n- **`index.js`**: Runtime configuration with environment variable overrides\n  - `TIMEOUT_SECONDS`: Request timeout (default: 30s)\n  - `MAX_RETRIES`: Retry attempts (default: 3)\n  - `CACHE_DURATION`: Fallback mutable cache TTL (default: 300s = 5 minutes)\n  - `SECURITY.ALLOWED_METHODS`: HTTP methods (default: GET, HEAD)\n\n- **`platform-catalog.js`**: Platform base URL definitions\n  - `PLATFORM_CATALOG`: Object mapping platform keys to base URLs\n\n- **`routing/platform-index.js`**: Pre-sorted keys for efficient matching\n  - `SORTED_PLATFORMS`: Longest-prefix-first platform matching order\n\n- **`routing/platform-transformers.js`**: Platform-specific path rewriting\n  - `transformPath()`: Converts request paths to platform-specific URLs\n  - Special handling for crates.io (adds `/api/v1/crates` prefix) and Jenkins\n    (adds `/current/` prefix)\n\n#### Protocol Handlers (`src/protocols/`)\n\n- **`git.js`**: Git protocol detection and header configuration\n  - Detects Git operations via User-Agent, endpoints (`/info/refs`,\n    `/git-upload-pack`)\n  - Handles Git LFS via `Accept: application/vnd.git-lfs+json`\n\n- **`docker.js`**: Container registry protocol (OCI/Docker)\n  - Parses WWW-Authenticate headers for token authentication\n  - Handles Docker registry v2 API authentication flow\n  - Special redirect handling to prevent leaking auth tokens to blob storage\n\n- **`ai.js`**: AI inference API detection and header forwarding\n  - Detects requests to `/ip/*` platforms\n  - Preserves all headers for AI API compatibility\n\n#### Utilities (`src/utils/`)\n\n- **`validation.js`**: Request validation logic\n  - `isDockerRequest()`: Detects Docker/OCI operations\n  - `validateRequest()`: Enforces security policies\n\n- **`security.js`**: Security headers and error responses\n  - Adds HSTS, X-Frame-Options, CSP, X-XSS-Protection\n  - `createErrorResponse()`: Generates standardized error responses\n\n- **`performance.js`**: Performance monitoring\n  - `PerformanceMonitor`: Tracks request timing\n  - Adds `X-Performance-Metrics` header to responses\n\n### Caching Strategy\n\n- Uses Cloudflare Cache API for GET requests (200 OK only)\n- Fallback mutable cache TTL controlled by `CACHE_DURATION` config\n- Skips cache for: Git operations, Docker operations, AI inference requests\n- Range requests: First checks for range-specific cache, falls back to full\n  content cache\n\n### Special Platform Handling\n\n#### npm\n\n- Rewrites `https://registry.npmjs.org/` URLs in JSON responses to point to Xget\n  instance\n\n#### PyPI\n\n- Rewrites `https://files.pythonhosted.org` URLs in HTML responses to point to\n  Xget instance\n- Uses separate `pypi-files` platform for file downloads\n\n#### crates.io\n\n- Adds `/api/v1/crates` prefix to all API requests\n- Handles search endpoint (`/?q=`) specially\n\n#### Jenkins\n\n- Adds `/current/` prefix to update center paths\n- Preserves `/experimental/` and `/download/` paths as-is\n\n#### Docker Registries\n\n- Handles authentication via token service\n- Uses manual redirect mode to strip Authorization headers before S3 redirects\n- Auto-retries with public token on 401 responses\n\n## Code Structure Conventions\n\n### File Organization\n\n```\nsrc/\n├── index.js                 # Main Worker entry point\n├── app/\n│   ├── handle-request.js    # Shared request pipeline\n│   └── request-context.js   # Protocol-aware request classification\n├── config/\n│   ├── index.js             # Runtime configuration\n│   ├── platform-catalog.js  # Platform base URLs\n│   └── platforms.js         # Compatibility exports\n├── protocols/\n│   ├── git.js               # Git protocol handler\n│   ├── docker.js            # Docker/OCI handler\n│   └── ai.js                # AI inference handler\n├── response/\n│   └── finalize-response.js # Response shaping and cache writes\n├── routing/\n│   ├── platform-index.js    # Platform matching order\n│   ├── platform-transformers.js\n│   └── resolve-target.js    # Upstream target resolution\n├── upstream/\n│   ├── cache.js             # Cache read helpers\n│   └── fetch-upstream.js    # Upstream transport and retries\n└── utils/\n    ├── validation.js        # Request validation\n    ├── security.js          # Security utilities\n    └── performance.js       # Performance monitoring\n\ntest/\n├── features/               # Feature tests\n├── platforms/              # Platform-specific tests\n├── unit/                   # Unit tests\n├── index.test.js          # Core Worker tests\n└── integration.test.js    # Integration tests\n```\n\n### Important Patterns\n\n#### Protocol Detection Order\n\n1. Check if Docker request (via `isDockerRequest()`)\n2. Check if Git request (via `isGitRequest()`)\n3. Check if Git LFS request (via `isGitLFSRequest()`)\n4. Check if AI request (via `isAIInferenceRequest()`)\n5. Default to standard file download\n\n#### Adding a New Platform\n\n1. Add platform entry to `PLATFORM_CATALOG` in `src/config/platform-catalog.js`\n2. If special path transformation needed, add a transformer in\n   `src/routing/platform-transformers.js`\n3. Add platform tests in `test/platforms/`\n4. Update README.md with platform documentation\n\n#### Retry Logic\n\n- Retries up to `MAX_RETRIES` times with linear backoff\n- Delay: `RETRY_DELAY_MS * attempts` (default: 1000ms, 2000ms, 3000ms)\n- Retries on: Network errors, timeouts, 5xx errors\n- Does NOT retry: 4xx errors (except Docker 401 which has special handling)\n\n#### Error Handling\n\n- All errors caught at top level in `handleRequest()`\n- Errors converted to JSON responses via `createErrorResponse()`\n- Performance metrics still added even on error paths\n\n## Testing Guidelines\n\n### Test Structure\n\n- **Unit tests** (`test/unit/`): Test individual functions in isolation\n- **Feature tests** (`test/features/`): Test specific features (auth, caching,\n  Git, performance)\n- **Platform tests** (`test/platforms/`): Test platform-specific transformations\n- **Integration tests** (`test/integration.test.js`): End-to-end request flows\n\n### Running Specific Tests\n\n```bash\n# Run specific test file\nnpm run test:run test/unit/platforms.test.js\n\n# Run tests matching pattern\nnpm run test:run -- --testNamePattern \"Docker\"\n\n# Run with coverage\nnpm run test:coverage\n```\n\n### Common Test Patterns\n\n```javascript\n// Mock request creation\nconst request = new Request('http://localhost/gh/microsoft/vscode', {\n  method: 'GET',\n  headers: { 'User-Agent': 'git/2.34.1' }\n});\n\n// Mock environment\nconst env = {};\nconst ctx = { waitUntil: () => {} };\n\n// Test the worker\nconst response = await worker.fetch(request, env, ctx);\nexpect(response.status).toBe(200);\n```\n\n## Deployment\n\n### Cloudflare Workers\n\n- Primary deployment target\n- Uses GitHub Actions for CI/CD (`.github/workflows/workers.yml`)\n- Requires `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` secrets\n\n### Cloudflare Pages\n\n- Alternative deployment via adapter in `adapters/pages/`\n- Auto-synced from `main` branch to `pages` branch\n- Uses separate workflow (`.github/workflows/pages-cf.yml`)\n\n### Other Platforms\n\n- **Vercel/Netlify**: Uses Functions adapter in `adapters/functions/`\n- **Deno Deploy**: Uses Functions adapter (compatible format)\n- **Docker**: Multi-stage build using `workerd` runtime\n\n### Environment Variables\n\nConfigure in Cloudflare Workers dashboard or via `wrangler.toml`:\n\n- `TIMEOUT_SECONDS`: Override default timeout\n- `MAX_RETRIES`: Override retry count\n- `CACHE_DURATION`: Override fallback mutable cache TTL\n- `ALLOWED_METHODS`: Override allowed HTTP methods (comma-separated)\n- `ALLOWED_ORIGINS`: Override CORS origins (comma-separated)\n\n## Important Notes\n\n### Security Considerations\n\n- Never log or expose Authorization headers\n- Docker authentication tokens are stripped before S3 redirects\n- All responses include security headers (HSTS, CSP, X-Frame-Options, etc.)\n- Path length limited to prevent URL-based attacks (default: 2048 chars)\n\n### Performance Optimization\n\n- Use `ctx.waitUntil()` for cache writes to avoid blocking response\n- Range requests leverage cache when possible\n- Cloudflare edge caching (`cf` fetch options) for non-protocol requests\n- HTTP/3 enabled for supported clients\n\n### Git/Docker/AI Requests\n\n- Skip normal caching mechanisms\n- Allow POST/PUT/PATCH methods\n- Preserve all upstream headers\n- No performance headers added (to maintain protocol compatibility)\n\n### URL Rewriting\n\n- Only enabled for npm and PyPI platforms\n- Rewrites responses to point to Xget instance instead of upstream\n- Required for package managers to download dependencies through Xget\n\n## Common Tasks\n\n### Adding a New Platform\n\n1. Add to `PLATFORM_CATALOG` in `src/config/platform-catalog.js`\n2. If special transformation needed, update\n   `src/routing/platform-transformers.js`\n3. Add test in `test/platforms/`\n4. Update README.md documentation\n5. Test locally with `npm run dev`\n\n### Debugging Requests\n\n1. Use `npm run dev` to start local server\n2. Add `console.log()` statements in `src/app/handle-request.js` or the relevant\n   extracted pipeline module\n3. Check Wrangler dev server output\n4. Inspect `X-Performance-Metrics` header in responses\n\n### Fixing Test Failures\n\n1. Run specific failing test: `npm run test:run test/path/to/test.js`\n2. Check mock setup matches actual request pattern\n3. Verify platform configuration in `src/config/platform-catalog.js` and\n   `src/routing/platform-transformers.js`\n4. Run all tests before committing: `npm run test:run`\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with\ncode in this repository.\n\n## Project Overview\n\nXget is a high-performance, Cloudflare Workers-based acceleration engine for\ndeveloper resources. It provides unified acceleration for code repositories\n(GitHub, GitLab, etc.), package registries (npm, PyPI, Maven, etc.), container\nregistries (Docker Hub, GHCR, etc.), and AI inference APIs (OpenAI, Anthropic,\netc.).\n\nThe project operates as a reverse proxy that transforms incoming requests to\nmatch various platform APIs while adding security headers, caching, retry logic,\nand performance monitoring.\n\n## Development Commands\n\n### Core Commands\n\n```bash\n# Start development server (Cloudflare Workers local environment)\nnpm run dev              # Runs on http://localhost:8787\n\n# Deploy to Cloudflare Workers production\nnpm run deploy\n\n# Build and run tests\nnpm run test             # Run tests in watch mode\nnpm run test:run         # Run tests once\nnpm run test:coverage    # Generate coverage report\nnpm run test:ui          # Open Vitest UI\n\n# Code quality\nnpm run lint             # Check code quality\nnpm run lint:fix         # Fix linting issues\nnpm run format           # Format code with Prettier\nnpm run format:check     # Check formatting without changes\nnpm run type-check       # TypeScript type checking (no emit)\nnpm run commitlint       # Validate the latest commit message\n```\n\n## Commit Messages\n\n- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for\n  every commit\n- Preferred format: `type(scope): description`\n- Common types: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `chore`\n- The repository installs a `commit-msg` hook via `npm install`; do not bypass\n  it unless explicitly required\n\n## Pre-Commit Requirements\n\n- Before every commit, run the local CI-equivalent checks from\n  `.github/workflows/ci.yml`\n- Required commands: `npm run lint`, `npm run format:check`, `npm run test:run`,\n  and `npm run type-check`\n- If any required check fails, do not commit until the failure is resolved\n- Apply this rule to every commit, including documentation-only changes, unless\n  the user explicitly asks for a different workflow\n\n### Testing Workflow\n\n- Tests use Vitest with `@cloudflare/vitest-pool-workers` for Workers-specific\n  testing\n- Run `npm run test:run` before committing to ensure all tests pass\n- Coverage reports are generated in `coverage/` directory\n\n## Architecture\n\n### Request Flow\n\n1. **Entry Point**: `src/index.js` - Exports default Worker with `fetch()`\n   handler\n2. **Validation**: `src/utils/validation.js` - Validates HTTP methods, path\n   length, detects protocol types\n3. **Platform Detection**: URL path is parsed to identify platform (e.g., `/gh/`\n   → GitHub)\n4. **Path Transformation**:\n   `src/routing/platform-transformers.js#transformPath()` converts request paths\n   to upstream URLs\n5. **Protocol Handling**: Different handlers for Git, Docker, AI inference\n   requests\n6. **Upstream Fetch**: Request forwarded with appropriate headers and retry\n   logic\n7. **Response Processing**: URL rewriting for certain platforms (npm, PyPI),\n   cache storage\n8. **Security Headers**: Added via `src/utils/security.js` before returning to\n   client\n\n### Key Components\n\n#### Configuration (`src/config/`)\n\n- **`index.js`**: Runtime configuration with environment variable overrides\n  - `TIMEOUT_SECONDS`: Request timeout (default: 30s)\n  - `MAX_RETRIES`: Retry attempts (default: 3)\n  - `CACHE_DURATION`: Fallback mutable cache TTL (default: 300s = 5 minutes)\n  - `SECURITY.ALLOWED_METHODS`: HTTP methods (default: GET, HEAD)\n\n- **`platform-catalog.js`**: Platform base URL definitions\n  - `PLATFORM_CATALOG`: Object mapping platform keys to base URLs\n\n- **`routing/platform-index.js`**: Pre-sorted keys for efficient matching\n  - `SORTED_PLATFORMS`: Longest-prefix-first platform matching order\n\n- **`routing/platform-transformers.js`**: Platform-specific path rewriting\n  - `transformPath()`: Converts request paths to platform-specific URLs\n  - Special handling for crates.io (adds `/api/v1/crates` prefix) and Jenkins\n    (adds `/current/` prefix)\n\n#### Protocol Handlers (`src/protocols/`)\n\n- **`git.js`**: Git protocol detection and header configuration\n  - Detects Git operations via User-Agent, endpoints (`/info/refs`,\n    `/git-upload-pack`)\n  - Handles Git LFS via `Accept: application/vnd.git-lfs+json`\n\n- **`docker.js`**: Container registry protocol (OCI/Docker)\n  - Parses WWW-Authenticate headers for token authentication\n  - Handles Docker registry v2 API authentication flow\n  - Special redirect handling to prevent leaking auth tokens to blob storage\n\n- **`ai.js`**: AI inference API detection and header forwarding\n  - Detects requests to `/ip/*` platforms\n  - Preserves all headers for AI API compatibility\n\n#### Utilities (`src/utils/`)\n\n- **`validation.js`**: Request validation logic\n  - `isDockerRequest()`: Detects Docker/OCI operations\n  - `validateRequest()`: Enforces security policies\n\n- **`security.js`**: Security headers and error responses\n  - Adds HSTS, X-Frame-Options, CSP, X-XSS-Protection\n  - `createErrorResponse()`: Generates standardized error responses\n\n- **`performance.js`**: Performance monitoring\n  - `PerformanceMonitor`: Tracks request timing\n  - Adds `X-Performance-Metrics` header to responses\n\n### Caching Strategy\n\n- Uses Cloudflare Cache API for GET requests (200 OK only)\n- Fallback mutable cache TTL controlled by `CACHE_DURATION` config\n- Skips cache for: Git operations, Docker operations, AI inference requests\n- Range requests: First checks for range-specific cache, falls back to full\n  content cache\n\n### Special Platform Handling\n\n#### npm\n\n- Rewrites `https://registry.npmjs.org/` URLs in JSON responses to point to Xget\n  instance\n\n#### PyPI\n\n- Rewrites `https://files.pythonhosted.org` URLs in HTML responses to point to\n  Xget instance\n- Uses separate `pypi-files` platform for file downloads\n\n#### crates.io\n\n- Adds `/api/v1/crates` prefix to all API requests\n- Handles search endpoint (`/?q=`) specially\n\n#### Jenkins\n\n- Adds `/current/` prefix to update center paths\n- Preserves `/experimental/` and `/download/` paths as-is\n\n#### Docker Registries\n\n- Handles authentication via token service\n- Uses manual redirect mode to strip Authorization headers before S3 redirects\n- Auto-retries with public token on 401 responses\n\n## Code Structure Conventions\n\n### File Organization\n\n```\nsrc/\n├── index.js                 # Main Worker entry point\n├── app/\n│   ├── handle-request.js    # Shared request pipeline\n│   └── request-context.js   # Protocol-aware request classification\n├── config/\n│   ├── index.js             # Runtime configuration\n│   ├── platform-catalog.js  # Platform base URLs\n│   └── platforms.js         # Compatibility exports\n├── protocols/\n│   ├── git.js               # Git protocol handler\n│   ├── docker.js            # Docker/OCI handler\n│   └── ai.js                # AI inference handler\n├── response/\n│   └── finalize-response.js # Response shaping and cache writes\n├── routing/\n│   ├── platform-index.js    # Platform matching order\n│   ├── platform-transformers.js\n│   └── resolve-target.js    # Upstream target resolution\n├── upstream/\n│   ├── cache.js             # Cache read helpers\n│   └── fetch-upstream.js    # Upstream transport and retries\n└── utils/\n    ├── validation.js        # Request validation\n    ├── security.js          # Security utilities\n    └── performance.js       # Performance monitoring\n\ntest/\n├── features/               # Feature tests\n├── platforms/              # Platform-specific tests\n├── unit/                   # Unit tests\n├── index.test.js          # Core Worker tests\n└── integration.test.js    # Integration tests\n```\n\n### Important Patterns\n\n#### Protocol Detection Order\n\n1. Check if Docker request (via `isDockerRequest()`)\n2. Check if Git request (via `isGitRequest()`)\n3. Check if Git LFS request (via `isGitLFSRequest()`)\n4. Check if AI request (via `isAIInferenceRequest()`)\n5. Default to standard file download\n\n#### Adding a New Platform\n\n1. Add platform entry to `PLATFORM_CATALOG` in `src/config/platform-catalog.js`\n2. If special path transformation needed, add a transformer in\n   `src/routing/platform-transformers.js`\n3. Add platform tests in `test/platforms/`\n4. Update README.md with platform documentation\n\n#### Retry Logic\n\n- Retries up to `MAX_RETRIES` times with linear backoff\n- Delay: `RETRY_DELAY_MS * attempts` (default: 1000ms, 2000ms, 3000ms)\n- Retries on: Network errors, timeouts, 5xx errors\n- Does NOT retry: 4xx errors (except Docker 401 which has special handling)\n\n#### Error Handling\n\n- All errors caught at top level in `handleRequest()`\n- Errors converted to JSON responses via `createErrorResponse()`\n- Performance metrics still added even on error paths\n\n## Testing Guidelines\n\n### Test Structure\n\n- **Unit tests** (`test/unit/`): Test individual functions in isolation\n- **Feature tests** (`test/features/`): Test specific features (auth, caching,\n  Git, performance)\n- **Platform tests** (`test/platforms/`): Test platform-specific transformations\n- **Integration tests** (`test/integration.test.js`): End-to-end request flows\n\n### Running Specific Tests\n\n```bash\n# Run specific test file\nnpm run test:run test/unit/platforms.test.js\n\n# Run tests matching pattern\nnpm run test:run -- --testNamePattern \"Docker\"\n\n# Run with coverage\nnpm run test:coverage\n```\n\n### Common Test Patterns\n\n```javascript\n// Mock request creation\nconst request = new Request('http://localhost/gh/microsoft/vscode', {\n  method: 'GET',\n  headers: { 'User-Agent': 'git/2.34.1' }\n});\n\n// Mock environment\nconst env = {};\nconst ctx = { waitUntil: () => {} };\n\n// Test the worker\nconst response = await worker.fetch(request, env, ctx);\nexpect(response.status).toBe(200);\n```\n\n## Deployment\n\n### Cloudflare Workers\n\n- Primary deployment target\n- Uses GitHub Actions for CI/CD (`.github/workflows/workers.yml`)\n- Requires `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` secrets\n\n### Cloudflare Pages\n\n- Alternative deployment via adapter in `adapters/pages/`\n- Auto-synced from `main` branch to `pages` branch\n- Uses separate workflow (`.github/workflows/pages-cf.yml`)\n\n### Other Platforms\n\n- **Vercel/Netlify**: Uses Functions adapter in `adapters/functions/`\n- **Deno Deploy**: Uses Functions adapter (compatible format)\n- **Docker**: Multi-stage build using `workerd` runtime\n\n### Environment Variables\n\nConfigure in Cloudflare Workers dashboard or via `wrangler.toml`:\n\n- `TIMEOUT_SECONDS`: Override default timeout\n- `MAX_RETRIES`: Override retry count\n- `CACHE_DURATION`: Override fallback mutable cache TTL\n- `ALLOWED_METHODS`: Override allowed HTTP methods (comma-separated)\n- `ALLOWED_ORIGINS`: Override CORS origins (comma-separated)\n\n## Important Notes\n\n### Security Considerations\n\n- Never log or expose Authorization headers\n- Docker authentication tokens are stripped before S3 redirects\n- All responses include security headers (HSTS, CSP, X-Frame-Options, etc.)\n- Path length limited to prevent URL-based attacks (default: 2048 chars)\n\n### Performance Optimization\n\n- Use `ctx.waitUntil()` for cache writes to avoid blocking response\n- Range requests leverage cache when possible\n- Cloudflare edge caching (`cf` fetch options) for non-protocol requests\n- HTTP/3 enabled for supported clients\n\n### Git/Docker/AI Requests\n\n- Skip normal caching mechanisms\n- Allow POST/PUT/PATCH methods\n- Preserve all upstream headers\n- No performance headers added (to maintain protocol compatibility)\n\n### URL Rewriting\n\n- Only enabled for npm and PyPI platforms\n- Rewrites responses to point to Xget instance instead of upstream\n- Required for package managers to download dependencies through Xget\n\n## Common Tasks\n\n### Adding a New Platform\n\n1. Add to `PLATFORM_CATALOG` in `src/config/platform-catalog.js`\n2. If special transformation needed, update\n   `src/routing/platform-transformers.js`\n3. Add test in `test/platforms/`\n4. Update README.md documentation\n5. Test locally with `npm run dev`\n\n### Debugging Requests\n\n1. Use `npm run dev` to start local server\n2. Add `console.log()` statements in `src/app/handle-request.js` or the relevant\n   extracted pipeline module\n3. Check Wrangler dev server output\n4. Inspect `X-Performance-Metrics` header in responses\n\n### Fixing Test Failures\n\n1. Run specific failing test: `npm run test:run test/path/to/test.js`\n2. Check mock setup matches actual request pattern\n3. Verify platform configuration in `src/config/platform-catalog.js` and\n   `src/routing/platform-transformers.js`\n4. Run all tests before committing: `npm run test:run`\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with\ncode in this repository.\n\n## Project Overview\n\nXget is a high-performance, Cloudflare Workers-based acceleration engine for\ndeveloper resources. It provides unified acceleration for code repositories\n(GitHub, GitLab, etc.), package registries (npm, PyPI, Maven, etc.), container\nregistries (Docker Hub, GHCR, etc.), and AI inference APIs (OpenAI, Anthropic,\netc.).\n\nThe project operates as a reverse proxy that transforms incoming requests to\nmatch various platform APIs while adding security headers, caching, retry logic,\nand performance monitoring.\n\n## Development Commands\n\n### Core Commands\n\n```bash\n# Start development server (Cloudflare Workers local environment)\nnpm run dev              # Runs on http://localhost:8787\n\n# Deploy to Cloudflare Workers production\nnpm run deploy\n\n# Build and run tests\nnpm run test             # Run tests in watch mode\nnpm run test:run         # Run tests once\nnpm run test:coverage    # Generate coverage report\nnpm run test:ui          # Open Vitest UI\n\n# Code quality\nnpm run lint             # Check code quality\nnpm run lint:fix         # Fix linting issues\nnpm run format           # Format code with Prettier\nnpm run format:check     # Check formatting without changes\nnpm run type-check       # TypeScript type checking (no emit)\nnpm run commitlint       # Validate the latest commit message\n```\n\n## Commit Messages\n\n- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for\n  every commit\n- Preferred format: `type(scope): description`\n- Common types: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `chore`\n- The repository installs a `commit-msg` hook via `npm install`; do not bypass\n  it unless explicitly required\n\n## Pre-Commit Requirements\n\n- Before every commit, run the local CI-equivalent checks from\n  `.github/workflows/ci.yml`\n- Required commands: `npm run lint`, `npm run format:check`, `npm run test:run`,\n  and `npm run type-check`\n- If any required check fails, do not commit until the failure is resolved\n- Apply this rule to every commit, including documentation-only changes, unless\n  the user explicitly asks for a different workflow\n\n### Testing Workflow\n\n- Tests use Vitest with `@cloudflare/vitest-pool-workers` for Workers-specific\n  testing\n- Run `npm run test:run` before committing to ensure all tests pass\n- Coverage reports are generated in `coverage/` directory\n\n## Architecture\n\n### Request Flow\n\n1. **Entry Point**: `src/index.js` - Exports default Worker with `fetch()`\n   handler\n2. **Validation**: `src/utils/validation.js` - Validates HTTP methods, path\n   length, detects protocol types\n3. **Platform Detection**: URL path is parsed to identify platform (e.g., `/gh/`\n   → GitHub)\n4. **Path Transformation**:\n   `src/routing/platform-transformers.js#transformPath()` converts request paths\n   to upstream URLs\n5. **Protocol Handling**: Different handlers for Git, Docker, AI inference\n   requests\n6. **Upstream Fetch**: Request forwarded with appropriate headers and retry\n   logic\n7. **Response Processing**: URL rewriting for certain platforms (npm, PyPI),\n   cache storage\n8. **Security Headers**: Added via `src/utils/security.js` before returning to\n   client\n\n### Key Components\n\n#### Configuration (`src/config/`)\n\n- **`index.js`**: Runtime configuration with environment variable overrides\n  - `TIMEOUT_SECONDS`: Request timeout (default: 30s)\n  - `MAX_RETRIES`: Retry attempts (default: 3)\n  - `CACHE_DURATION`: Fallback mutable cache TTL (default: 300s = 5 minutes)\n  - `SECURITY.ALLOWED_METHODS`: HTTP methods (default: GET, HEAD)\n\n- **`platform-catalog.js`**: Platform base URL definitions\n  - `PLATFORM_CATALOG`: Object mapping platform keys to base URLs\n\n- **`routing/platform-index.js`**: Pre-sorted keys for efficient matching\n  - `SORTED_PLATFORMS`: Longest-prefix-first platform matching order\n\n- **`routing/platform-transformers.js`**: Platform-specific path rewriting\n  - `transformPath()`: Converts request paths to platform-specific URLs\n  - Special handling for crates.io (adds `/api/v1/crates` prefix) and Jenkins\n    (adds `/current/` prefix)\n\n#### Protocol Handlers (`src/protocols/`)\n\n- **`git.js`**: Git protocol detection and header configuration\n  - Detects Git operations via User-Agent, endpoints (`/info/refs`,\n    `/git-upload-pack`)\n  - Handles Git LFS via `Accept: application/vnd.git-lfs+json`\n\n- **`docker.js`**: Container registry protocol (OCI/Docker)\n  - Parses WWW-Authenticate headers for token authentication\n  - Handles Docker registry v2 API authentication flow\n  - Special redirect handling to prevent leaking auth tokens to blob storage\n\n- **`ai.js`**: AI inference API detection and header forwarding\n  - Detects requests to `/ip/*` platforms\n  - Preserves all headers for AI API compatibility\n\n#### Utilities (`src/utils/`)\n\n- **`validation.js`**: Request validation logic\n  - `isDockerRequest()`: Detects Docker/OCI operations\n  - `validateRequest()`: Enforces security policies\n\n- **`security.js`**: Security headers and error responses\n  - Adds HSTS, X-Frame-Options, CSP, X-XSS-Protection\n  - `createErrorResponse()`: Generates standardized error responses\n\n- **`performance.js`**: Performance monitoring\n  - `PerformanceMonitor`: Tracks request timing\n  - Adds `X-Performance-Metrics` header to responses\n\n### Caching Strategy\n\n- Uses Cloudflare Cache API for GET requests (200 OK only)\n- Fallback mutable cache TTL controlled by `CACHE_DURATION` config\n- Skips cache for: Git operations, Docker operations, AI inference requests\n- Range requests: First checks for range-specific cache, falls back to full\n  content cache\n\n### Special Platform Handling\n\n#### npm\n\n- Rewrites `https://registry.npmjs.org/` URLs in JSON responses to point to Xget\n  instance\n\n#### PyPI\n\n- Rewrites `https://files.pythonhosted.org` URLs in HTML responses to point to\n  Xget instance\n- Uses separate `pypi-files` platform for file downloads\n\n#### crates.io\n\n- Adds `/api/v1/crates` prefix to all API requests\n- Handles search endpoint (`/?q=`) specially\n\n#### Jenkins\n\n- Adds `/current/` prefix to update center paths\n- Preserves `/experimental/` and `/download/` paths as-is\n\n#### Docker Registries\n\n- Handles authentication via token service\n- Uses manual redirect mode to strip Authorization headers before S3 redirects\n- Auto-retries with public token on 401 responses\n\n## Code Structure Conventions\n\n### File Organization\n\n```\nsrc/\n├── index.js                 # Main Worker entry point\n├── app/\n│   ├── handle-request.js    # Shared request pipeline\n│   └── request-context.js   # Protocol-aware request classification\n├── config/\n│   ├── index.js             # Runtime configuration\n│   ├── platform-catalog.js  # Platform base URLs\n│   └── platforms.js         # Compatibility exports\n├── protocols/\n│   ├── git.js               # Git protocol handler\n│   ├── docker.js            # Docker/OCI handler\n│   └── ai.js                # AI inference handler\n├── response/\n│   └── finalize-response.js # Response shaping and cache writes\n├── routing/\n│   ├── platform-index.js    # Platform matching order\n│   ├── platform-transformers.js\n│   └── resolve-target.js    # Upstream target resolution\n├── upstream/\n│   ├── cache.js             # Cache read helpers\n│   └── fetch-upstream.js    # Upstream transport and retries\n└── utils/\n    ├── validation.js        # Request validation\n    ├── security.js          # Security utilities\n    └── performance.js       # Performance monitoring\n\ntest/\n├── features/               # Feature tests\n├── platforms/              # Platform-specific tests\n├── unit/                   # Unit tests\n├── index.test.js          # Core Worker tests\n└── integration.test.js    # Integration tests\n```\n\n### Important Patterns\n\n#### Protocol Detection Order\n\n1. Check if Docker request (via `isDockerRequest()`)\n2. Check if Git request (via `isGitRequest()`)\n3. Check if Git LFS request (via `isGitLFSRequest()`)\n4. Check if AI request (via `isAIInferenceRequest()`)\n5. Default to standard file download\n\n#### Adding a New Platform\n\n1. Add platform entry to `PLATFORM_CATALOG` in `src/config/platform-catalog.js`\n2. If special path transformation needed, add a transformer in\n   `src/routing/platform-transformers.js`\n3. Add platform tests in `test/platforms/`\n4. Update README.md with platform documentation\n\n#### Retry Logic\n\n- Retries up to `MAX_RETRIES` times with linear backoff\n- Delay: `RETRY_DELAY_MS * attempts` (default: 1000ms, 2000ms, 3000ms)\n- Retries on: Network errors, timeouts, 5xx errors\n- Does NOT retry: 4xx errors (except Docker 401 which has special handling)\n\n#### Error Handling\n\n- All errors caught at top level in `handleRequest()`\n- Errors converted to JSON responses via `createErrorResponse()`\n- Performance metrics still added even on error paths\n\n## Testing Guidelines\n\n### Test Structure\n\n- **Unit tests** (`test/unit/`): Test individual functions in isolation\n- **Feature tests** (`test/features/`): Test specific features (auth, caching,\n  Git, performance)\n- **Platform tests** (`test/platforms/`): Test platform-specific transformations\n- **Integration tests** (`test/integration.test.js`): End-to-end request flows\n\n### Running Specific Tests\n\n```bash\n# Run specific test file\nnpm run test:run test/unit/platforms.test.js\n\n# Run tests matching pattern\nnpm run test:run -- --testNamePattern \"Docker\"\n\n# Run with coverage\nnpm run test:coverage\n```\n\n### Common Test Patterns\n\n```javascript\n// Mock request creation\nconst request = new Request('http://localhost/gh/microsoft/vscode', {\n  method: 'GET',\n  headers: { 'User-Agent': 'git/2.34.1' }\n});\n\n// Mock environment\nconst env = {};\nconst ctx = { waitUntil: () => {} };\n\n// Test the worker\nconst response = await worker.fetch(request, env, ctx);\nexpect(response.status).toBe(200);\n```\n\n## Deployment\n\n### Cloudflare Workers\n\n- Primary deployment target\n- Uses GitHub Actions for CI/CD (`.github/workflows/workers.yml`)\n- Requires `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` secrets\n\n### Cloudflare Pages\n\n- Alternative deployment via adapter in `adapters/pages/`\n- Auto-synced from `main` branch to `pages` branch\n- Uses separate workflow (`.github/workflows/pages-cf.yml`)\n\n### Other Platforms\n\n- **Vercel/Netlify**: Uses Functions adapter in `adapters/functions/`\n- **Deno Deploy**: Uses Functions adapter (compatible format)\n- **Docker**: Multi-stage build using `workerd` runtime\n\n### Environment Variables\n\nConfigure in Cloudflare Workers dashboard or via `wrangler.toml`:\n\n- `TIMEOUT_SECONDS`: Override default timeout\n- `MAX_RETRIES`: Override retry count\n- `CACHE_DURATION`: Override fallback mutable cache TTL\n- `ALLOWED_METHODS`: Override allowed HTTP methods (comma-separated)\n- `ALLOWED_ORIGINS`: Override CORS origins (comma-separated)\n\n## Important Notes\n\n### Security Considerations\n\n- Never log or expose Authorization headers\n- Docker authentication tokens are stripped before S3 redirects\n- All responses include security headers (HSTS, CSP, X-Frame-Options, etc.)\n- Path length limited to prevent URL-based attacks (default: 2048 chars)\n\n### Performance Optimization\n\n- Use `ctx.waitUntil()` for cache writes to avoid blocking response\n- Range requests leverage cache when possible\n- Cloudflare edge caching (`cf` fetch options) for non-protocol requests\n- HTTP/3 enabled for supported clients\n\n### Git/Docker/AI Requests\n\n- Skip normal caching mechanisms\n- Allow POST/PUT/PATCH methods\n- Preserve all upstream headers\n- No performance headers added (to maintain protocol compatibility)\n\n### URL Rewriting\n\n- Only enabled for npm and PyPI platforms\n- Rewrites responses to point to Xget instance instead of upstream\n- Required for package managers to download dependencies through Xget\n\n## Common Tasks\n\n### Adding a New Platform\n\n1. Add to `PLATFORM_CATALOG` in `src/config/platform-catalog.js`\n2. If special transformation needed, update\n   `src/routing/platform-transformers.js`\n3. Add test in `test/platforms/`\n4. Update README.md documentation\n5. Test locally with `npm run dev`\n\n### Debugging Requests\n\n1. Use `npm run dev` to start local server\n2. Add `console.log()` statements in `src/app/handle-request.js` or the relevant\n   extracted pipeline module\n3. Check Wrangler dev server output\n4. Inspect `X-Performance-Metrics` header in responses\n\n### Fixing Test Failures\n\n1. Run specific failing test: `npm run test:run test/path/to/test.js`\n2. Check mock setup matches actual request pattern\n3. Verify platform configuration in `src/config/platform-catalog.js` and\n   `src/routing/platform-transformers.js`\n4. Run all tests before committing: `npm run test:run`\n","category":"root","tokens":3164}]}