proxlock/backend

💧 A Vapor Swift backend for ProxLock, providing API proxy functionality with authentication, device validation, and usage tracking.

Overview

This is the backend service for ProxLock, built with the Vapor web framework. It provides a robust API proxy solution with features including:

User authentication via Clerk
API key management
Device validation using Apple DeviceCheck
Project and usage tracking
Request proxying with rate limiting

Prerequisites

Before you begin, ensure you have the following installed:

Swift 6.1+ - Download Swift
PostgreSQL 16+ - Download PostgreSQL
macOS 13+ (for local development)
Docker (optional, for containerized development)

Setup Instructions

Local Development

Clone the repository

``bash git clone <repository-url> cd backend ``

Install dependencies

``bash swift package resolve ``

Set up PostgreSQL database

Create a PostgreSQL database for the application: ``bash createdb proxlock_dev ``

Configure environment variables

Create a .env file in the root directory with the following variables: ``env DATABASE_HOST=localhost DATABASE_PORT=5432 DATABASE_NAME=proxlock_dev DATABASE_USERNAME=your_postgres_username DATABASE_PASSWORD=your_postgres_password CLERK_WEBHOOK_SECRET=your_clerk_webhook_secret ``

Run database migrations

The application will automatically run migrations on startup, or you can run them manually: ``bash swift run ProxLock migrate ``

Start the server

``bash swift run ``

The server will start on http://localhost:8080 by default.

Docker Development

Set up environment variables

Create a .env file or export the following environment variables: ``bash export DATABASE_NAME=proxlock export DATABASE_USERNAME=vapor export DATABASE_PASSWORD=password export CLERK_WEBHOOK_SECRET=your_clerk_webhook_secret ``

Build and start services

``bash docker compose build docker compose up ``

Access the application

The API will be available at http://localhost:8080

Environment Variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | DATABASE_HOST | PostgreSQL hostname | No | localhost | | DATABASE_PORT | PostgreSQL port | No | 5432 | | DATABASE_NAME | Database name | Yes | - | | DATABASE_USERNAME | Database username | Yes | - | | DATABASE_PASSWORD | Database password | Yes | - | | CLERK_WEBHOOK_SECRET | Clerk webhook secret for authentication | Yes | - | | CLERK_ADMIN_IDS | The Clerk User IDs denoting administrators | no | - | | BLACKLISTED_PROXY_DESTINATIONS | Hosts that will always be rejected by /proxy | no | - | | MINIMUM_TERMS_DATE_FOR_PROXY | The minimum date for a user to have last accepted TOS for proxy use to be allowed. (Type: Epoch TimeInterval) | no | 1767225600 | | TERMS_LAST_UPDATED | The minimum date for a user to have last accepted TOS for non-proxy api use to be allowed. (Type: Epoch TimeInterval) | no | 1767225600 |

Error Codes

| Code | Description | |----------|-------------| | -1 | The user has not accepted the latest TOS and must do so before the action is permitted |

Building and Running

Build the project

swift build

Run the application

swift run

Run tests

swift test

Run migrations manually

swift run ProxLock migrate

Revert migrations

swift run ProxLock migrate --revert

Project Structure

backend/
├── Sources/
│   └── ProxLock/
│       ├── Controllers/      # Request handlers
│       ├── DTOs/             # Data transfer objects
│       ├── Middleware/       # Custom middleware
│       ├── Migrations/       # Database migrations
│       ├── Models/           # Database models
│       ├── Webhooks/         # Webhook handlers
│       ├── configure.swift   # Application configuration
│       ├── entrypoint.swift  # Application entry point
│       └── routes.swift      # Route definitions
├── Tests/                    # Test files
├── Dockerfile               # Docker build configuration
├── docker-compose.yml       # Docker Compose configuration
└── Package.swift            # Swift package dependencies

Contributing

We welcome contributions to ProxLock! Here's how you can help:

Getting Started

Fork the repository and clone your fork
Create a new branch for your feature or bug fix:

``bash git checkout -b feat/your-feature-name # or git checkout -b fix/your-bug-fix ``

Make your changes following these guidelines:

- Follow Swift style conventions - Write clear, descriptive commit messages - Add comments for complex logic - Ensure your code compiles without warnings

Test your changes

- Run the test suite: swift test - Test manually if applicable - Ensure migrations work correctly if you've modified the database schema

Submit a pull request

- Push your branch to your fork - Create a pull request with a clear description of your changes - Reference any related issues

Code Style Guidelines

Use Swift 6.1+ features and best practices
Follow Vapor conventions for route and controller structure
Keep controllers focused and single-responsibility
Use DTOs for request/response data
Add appropriate error handling
Document public APIs and complex logic

Database Changes

If you're modifying the database schema:

Create a new migration in the respective model's file within Sources/ProxLock/Migrations/
Follow the existing migration patterns
Test migrations both forward and backward
Update model files if needed

Testing

Write tests for new features when possible
Ensure existing tests pass
Test edge cases and error conditions

Questions?

If you have questions or need help, please:

Open an issue for bugs or feature requests
Check existing issues and discussions
Review the Vapor documentation

Resources

License

See the License file for details.

Package Metadata

Repository: proxlock/backend

Default branch: master

README: README.md