Server-Side API

Relevant source files

Purpose and Scope

This document describes the server-side HTTP API that powers the Repomix web interface. The API is built with the Hono framework and provides endpoints for processing repositories remotely or via ZIP file uploads.

The server acts as a robust wrapper around the repomix core library, handling request validation with Zod, structured logging with winston, memory-efficient ZIP decompression with fflate, and real-time progress updates via NDJSON streaming with Gzip flush capabilities.

Server Architecture

The server is implemented as a Node.js application using the Hono web framework with the @hono/node-server adapter website/server/src/index.ts2-3 It is optimized for performance using V8 compile cache warmup to reduce cold-start latency in serverless environments website/server/src/index.ts18-32

The server utilizes a middleware stack for security and performance, including CORS, Cloudflare Origin Guard, Gzip compression, and rate limiting website/server/src/index.ts42-60

Architecture Diagram: Server Components and Request Lifecycle

Sources: website/server/src/index.ts18-77 website/server/src/actions/packAction.ts17-71 website/server/src/middlewares/rateLimit.ts12-69 website/server/src/domains/pack/utils/cache.ts16-87

Request Validation and Security

The server enforces strict validation and security constraints to prevent resource exhaustion and malicious input.

Input Validation

The packAction extracts form data and validates it using validateRequest against the packRequestSchema website/server/src/actions/packAction.ts26-61 This utilizes Zod for schema definition and validation website/server/src/actions/packRequestSchema.ts1-15

URL: Validates remote repository strings website/server/src/actions/packAction.ts53
File: Accepts ZIP uploads for local processing website/server/src/actions/packAction.ts52
Options: Validates formatting flags and sanitizes includePatterns/ignorePatterns via sanitizePattern website/server/src/actions/packAction.ts63-70

Cloudflare Turnstile Integration

The server implements a strict "fail-closed" Turnstile verification for the /api/pack endpoint website/server/src/middlewares/turnstile.ts104-106

Token Verification: Tokens are sent via the X-Turnstile-Token header website/server/src/middlewares/turnstile.ts9
Action Binding: The server verifies that the token was minted specifically for the pack action to prevent replay attacks website/server/src/middlewares/turnstile.ts22
Hostname Check: Tokens are validated against allowed hostnames like repomix.com website/server/src/middlewares/turnstile.ts28

ZIP Security Limits

When processing ZIP uploads, extractZipWithSecurity enforces ZIP_SECURITY_LIMITS website/server/src/domains/pack/processZipFile.ts12-18:

MAX_FILES: 10,000 files per archive website/server/src/domains/pack/processZipFile.ts162
MAX_UNCOMPRESSED_SIZE: 100MB website/server/src/domains/pack/processZipFile.ts170
MAX_COMPRESSION_RATIO: 100:1 to detect ZIP bombs website/server/src/domains/pack/processZipFile.ts183-189
Path Traversal: Validates every entry path to prevent directory traversal attacks website/server/src/domains/pack/processZipFile.ts199-200

Sources: website/server/src/actions/packAction.ts17-71 website/server/src/domains/pack/processZipFile.ts146-200 website/server/src/middlewares/turnstile.ts50-161

Core Logic and Data Flow

The server branches logic based on the input type, eventually delegating to the repomix core's runDefaultAction.

Remote Repository Processing

The processRemoteRepo function handles URL-based requests website/server/src/domains/pack/remoteRepo.ts29:

Cache Check: Generates a cache key based on URL and options; returns cached results if available website/server/src/domains/pack/remoteRepo.ts40-47
Clone: Performs a shallow clone (--depth 1) into a temporary directory using git clone website/server/src/domains/pack/remoteRepo.ts15-27
Process: Executes runDefaultAction with skipLocalConfig: true to prevent loading untrusted configuration from the remote repo website/server/src/domains/pack/remoteRepo.ts71-89

Local ZIP Processing

The processZipFile function handles uploaded archives website/server/src/domains/pack/processZipFile.ts23:

Extraction: Uses fflate for memory-efficient decompression into a temporary directory website/server/src/domains/pack/processZipFile.ts152-157
Security Check: Enables securityCheck: true in cliOptions to scan for secrets during core processing website/server/src/domains/pack/processZipFile.ts46

Data Mapping: Code Entity to API Interface

API Entity	Code Source	Logic
`PackResult`	`website/client/components/api/client.ts:31-50`	Defines the structure for content and metadata including `totalTokens` and `suspiciousFiles`.
`ProcessPackResult`	`website/server/src/types.ts:49-52`	Includes the `PackResult` and a `cached` boolean.
`RequestCache`	`website/server/src/domains/pack/utils/cache.ts:16-87`	Uses Brotli compression (`brotliCompress`) to store results in memory website/server/src/domains/pack/utils/cache.ts5-67
`NDJSON Stream`	`website/server/src/actions/packAction.ts:120-149`	Streams progress events and final result with `Z_SYNC_FLUSH` using Node's `zlib` website/server/src/actions/packAction.ts110-148

Code Entity Interaction: Request Handling

Sources: website/server/src/domains/pack/remoteRepo.ts15-161 website/server/src/domains/pack/processZipFile.ts23-141 website/server/src/actions/packAction.ts110-148 website/client/components/api/client.ts104-180

Logging and Monitoring

Repomix uses a structured logging system integrated with Google Cloud Logging.

Structured Logging with Winston

The logger maps Winston levels to Cloud Logging severity levels (e.g., error -> ERROR) website/server/src/utils/logger.ts7-16 In production, logs are output as JSON via winston.format.json() website/server/src/utils/logger.ts27

Resource Monitoring

The server tracks memory usage and request outcomes:

Memory Metrics: Captures memory state before and after processing using getMemoryUsage() and logMemoryUsage() website/server/src/utils/logger.ts94-102
Event Tracking: All pack outcomes (success, validation error, rate limited) are logged under the pack_completed event website/server/src/actions/packEventSchema.ts15-17
Rejection Classification: Validation failures are categorized into stable labels like invalid_url or file_too_large via classifyRejectReason website/server/src/actions/packEventSchema.ts63-79

Sources: website/server/src/utils/logger.ts1-103 website/server/src/actions/packEventSchema.ts1-79

Deployment Configuration

The server is deployed to Google Cloud Run using a multi-step Cloud Build pipeline.

Cloud Build Pipeline

The cloudbuild.yaml defines the deployment lifecycle website/server/cloudbuild.yaml1-84:

Build: Builds the Docker image using website/server/Dockerfile website/server/cloudbuild.yaml3-15
Push: Pushes the image to Artifact Registry website/server/cloudbuild.yaml18-22
Deploy: Deploys to Cloud Run with 1024Mi memory, 2 CPUs, and a 35s timeout website/server/cloudbuild.yaml25-49
Secrets: Mounts secrets for Upstash Redis, Cloudflare Guard, and Turnstile website/server/cloudbuild.yaml55-56

Sources: website/server/cloudbuild.yaml1-84