Rust-URL-Shortening

Architecture Documentation

Overview

The Rust URL Shortener is built using a modern, layered architecture that emphasizes separation of concerns, maintainability, and performance.

Technology Stack

• Web Framework: Actix-web 4.x
• Database ORM: Diesel 2.x
• Database: SQLite (easily adaptable to PostgreSQL/MySQL)
• Async Runtime: Tokio (via actix-rt)
• Serialization: Serde

Project Structure

rust-url-shortener/
├── src/
│   ├── main.rs           # Application entry point
│   ├── lib.rs            # Library root, module declarations
│   ├── config.rs         # Configuration management
│   ├── db.rs             # Database connection pool setup
│   ├── error.rs          # Custom error types and handlers
│   ├── handlers.rs       # HTTP request handlers
│   ├── loggers.rs        # Logging configuration
│   ├── models.rs         # Database models and structures
│   ├── routes.rs         # Route configuration
│   ├── schema.rs         # Database schema (generated by Diesel)
│   └── utils.rs          # Utility functions
├── tests/
│   └── integrationTests.rs  # Integration tests
├── migrations/           # Database migrations
├── docs/                 # Documentation
└── examples/             # Usage examples

Architectural Layers

1. HTTP Layer (routes.rs, handlers.rs)

Responsibility: Handle HTTP requests and responses

• routes.rs: Defines all API endpoints and maps them to handlers
• handlers.rs: Implements the business logic for each endpoint
• Request validation
• Response formatting
• Error handling

2. Business Logic Layer (handlers.rs, utils.rs)

Responsibility: Core application logic

• URL validation
• Short code generation
• Business rules enforcement
• Data transformation

3. Data Access Layer (db.rs, models.rs)

Responsibility: Database interactions

• db.rs: Connection pool management
• models.rs: Data structures that map to database tables
• CRUD operations
• Query execution

4. Database Layer (schema.rs, migrations/)

Responsibility: Data persistence

• Schema definition
• Migration management
• Data integrity constraints

Component Interaction Flow

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ HTTP Request
       ▼
┌─────────────────────────────────────────┐
│         Actix-web Server                │
│  ┌──────────────────────────────────┐   │
│  │      Middleware Layer            │   │
│  │  - Logger                        │   │
│  │  - Error Handler                 │   │
│  └──────────────┬───────────────────┘   │
│                 ▼                        │
│  ┌──────────────────────────────────┐   │
│  │         Routes                   │   │
│  │  - POST /                        │   │
│  │  - GET /                         │   │
│  │  - GET /{short_code}             │   │
│  └──────────────┬───────────────────┘   │
│                 ▼                        │
│  ┌──────────────────────────────────┐   │
│  │         Handlers                 │   │
│  │  - Business Logic                │   │
│  │  - Validation                    │   │
│  └──────────────┬───────────────────┘   │
│                 ▼                        │
│  ┌──────────────────────────────────┐   │
│  │         Models/DB                │   │
│  │  - Diesel ORM                    │   │
│  │  - Connection Pool               │   │
│  └──────────────┬───────────────────┘   │
└─────────────────┼───────────────────────┘
                  ▼
           ┌──────────────┐
           │   Database   │
           │   (SQLite)   │
           └──────────────┘

Key Design Decisions

1. Actix-web Framework

Rationale:

• High performance (one of the fastest web frameworks)
• Excellent async/await support
• Rich middleware ecosystem
• Strong type safety

2. Diesel ORM

Rationale:

• Compile-time query verification
• Type-safe query builder
• Excellent migration support
• Performance comparable to hand-written SQL

3. SQLite Database

Rationale:

• Zero configuration
• Serverless
• Easy deployment
• Perfect for small to medium scale
• Can be easily migrated to PostgreSQL/MySQL

4. Connection Pooling

Implementation: r2d2 connection pool

Benefits:

• Reuses database connections
• Reduces connection overhead
• Handles concurrent requests efficiently

Data Flow

Creating a Short URL

1. Client sends POST request with original_url
2. Route handler receives request
3. Handler validates URL format
4. Handler generates unique short code
5. Handler saves URL mapping to database
6. Handler returns short URL to client

Redirecting to Original URL

1. Client requests GET /{short_code}
2. Route handler receives short code
3. Handler queries database for original URL
4. If found, returns 302 redirect
5. If not found, returns 404 error
6. Updates usage statistics (if tracking enabled)

Error Handling Strategy

┌─────────────────────────────────────┐
│     Error Types (error.rs)          │
│  - DatabaseError                    │
│  - ValidationError                  │
│  - NotFoundError                    │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│    Error Handler Middleware         │
│  - Converts errors to HTTP responses│
│  - Logs errors                      │
│  - Returns user-friendly messages   │
└─────────────────────────────────────┘

Security Considerations

Current Implementation

• Input validation for URLs
• SQL injection protection (via Diesel ORM)
• No exposed internal errors to clients

Recommended Enhancements

• Rate limiting per IP
• HTTPS enforcement
• CORS configuration
• URL blacklist/whitelist
• Authentication/Authorization
• Short code predictability protection

Scalability Considerations

Current Capacity

• Single-instance deployment
• SQLite database
• Suitable for: 10k-100k URLs, moderate traffic

Scaling Strategies

1. Vertical Scaling: Increase server resources
2. Database Migration: Move to PostgreSQL/MySQL
3. Caching Layer: Add Redis for frequently accessed URLs
4. Load Balancing: Multiple instances behind load balancer
5. CDN Integration: Cache redirects at edge locations

Performance Characteristics

• URL Creation: O(1) - Direct database insert
• URL Lookup: O(1) - Indexed database query
• List URLs: O(n) - Full table scan

Future Enhancements

1. Analytics Dashboard: Track clicks, referrers, geographic data
2. Custom Short Codes: Allow user-defined short codes
3. Expiration Dates: Auto-delete old URLs
4. API Authentication: JWT or API key based auth
5. Batch Operations: Create multiple URLs at once
6. QR Code Generation: Generate QR codes for short URLs
7. Link Preview: Show preview of destination URL

This site is open source. Improve this page.