CVS Proxy REST API

Overview

CVS Proxy is a Flask-based REST API that provides a proxy for CVS (Concurrent Versions System) repository operations. It allows you to interact with CVS repositories through a RESTful interface, enabling programmatic access to repository information and file contents.

Features

• List repository tree structure
• Compare file differences between revisions
• Retrieve file revision history
• Fetch raw file content at specific revisions
• Health check endpoint
• Docker containerization support

Prerequisites

• Docker (recommended)
• OR
  • Python 3.8+
  • CVS command-line client installed
  • Virtual environment recommended

Installation and Running

Docker (Recommended)

1. Build the Docker image

docker build -t cvs-proxy .

2. Run the container with CVS repository URL

docker run -d \
  -p 5000:5000 \
  -e CVS_URL=:pserver:username@cvs.example.com:/path/to/repository \
  cvs-proxy

Local Development

1. Clone the repository

git clone https://github.com/yourusername/cvs-proxy.git
cd cvs-proxy

2. Create and activate a virtual environment

python3 -m venv venv
source venv/bin/activate

3. Install dependencies using pip-compile

pip install -r requirements.txt

4. Install the package

pip install -e .

Configuration

Environment Variables

The following environment variables can be used to configure the CVS Proxy:

• CVS_URL: Full CVS repository URL (required)
  • Format: :pserver:username@hostname:/path/to/repository
• FLASK_HOST: Host to bind the server (default: 0.0.0.0)
• FLASK_PORT: Port to run the server (default: 5000)
• FLASK_DEBUG: Enable debug mode (default: false)

Configuration Methods

1. Environment Variables (Recommended for Docker)

export CVS_URL=:pserver:username@cvs.example.com:/path/to/repository

2. .env File (For local development) Create a .env file in the project root:

CVS_URL=:pserver:username@cvs.example.com:/path/to/repository

API Endpoints

All endpoints are versioned with the /v1 prefix.

GET /v1/tree

List repository tree structure

• Optional query param: module

GET /v1/diff

Get diff between two revisions of a file

• Required params: file, rev1, rev2

GET /v1/history

Get revision history for a file

• Required param: file

GET /v1/file

Get raw file content at a specific revision

• Required param: file
• Optional param: revision

GET /v1/health

Simple health check endpoint

Example Requests

1. List repository tree

GET /v1/tree
GET /v1/tree?module=project_name

2. Get file diff

GET /v1/diff?file=src/main.py&rev1=1.1&rev2=1.2

3. Get file history

GET /v1/history?file=README.md

4. Get file content

GET /v1/file?file=config.json
GET /v1/file?file=config.json&revision=1.3

Web UI

The CVS Proxy includes a modern, responsive web-based interface for browsing repositories. The UI is automatically served from the root path (/) when the application starts.

Features

• Repository Tree Navigation: Browse the complete repository structure
• File Viewing: Display file contents
• Revision History: View complete revision history for any file
• Diff Viewer: Compare different versions of files with color-coded output
• Real-time Status: Connection status indicator

Accessing the UI

Once the application is running, open your browser and navigate to:

http://localhost:5000

For more details about the UI, see ui/README.md

Development

Dependency Management

This project uses pip-tools to manage dependencies with pinned versions for reproducible builds.

Files:

• requirements.in: Direct dependencies (source of truth)
• requirements.txt: Pinned dependencies (auto-generated by pip-compile)

Updating Dependencies:

1. To add a new dependency, edit requirements.in and add the package name
2. Regenerate requirements.txt:

pip-compile requirements.in

3. To update all dependencies to their latest versions:

pip-compile --upgrade requirements.in

4. Install the updated dependencies:

pip install -r requirements.txt

Running Tests

python -m unittest discover cvs_proxy

Project Structure

cvs-proxy/
├── cvs_proxy/
│   ├── __init__.py
│   ├── app.py              # Flask application with API endpoints
│   ├── cvs_client.py       # CVS client implementation
│   └── test_cvs_client.py  # Tests
├── ui/                     # Web-based repository browser
│   ├── index.html
│   ├── styles.css
│   ├── api.js
│   ├── ui.js
│   ├── app.js
│   └── README.md
├── openapi.yaml            # OpenAPI 3.0 specification
├── README.md               # This file
├── requirements.in         # Direct dependencies (source of truth)
├── requirements.txt        # Pinned dependencies (auto-generated)
├── setup.py
└── Dockerfile

Security Considerations

• Ensure your CVS repository URL is correctly formatted
• Use secure, environment-specific configurations
• The API does not implement additional authentication beyond CVS repository configuration
• The UI properly escapes all HTML content to prevent XSS attacks

License

[Specify your license here]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.