docs: Add comprehensive documentation

codevalley · codevalley · commit 87697f1026df · 2025-03-27T17:56:31.000+05:30
Added:
- README.md with project overview and setup instructions
- API.md with detailed endpoint documentation and examples
- openapi.yaml with OpenAPI 3.0 specification

Documentation includes:
- Installation and setup guide
- Configuration options
- API endpoints with examples
- Rate limiting details
- Error handling
- Project structure
- Contributing guidelines
diff --git a/README.md b/README.md
@@ -1,113 +1,161 @@
-# Jump - Ephemeral Share Service
+# Jump Service
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Rust](https://github.com/rust-lang/rust/workflows/CI/badge.svg)](https://github.com/rust-lang/rust/actions)
-
-
-Jump is a secure and efficient ephemeral sharing service built with Rust. It allows users to share content that automatically expires after a set duration, ensuring data privacy and security.
+A high-performance, Redis-backed temporary payload storage service with rate limiting.
 
 ## Features
 
-- **Ephemeral Sharing**: Content automatically expires after a configurable duration
-- **Secure**: Content is encrypted and only accessible via unique hash IDs
-- **Rate Limited**: Built-in protection against abuse
-- **Type Safe**: Strict MIME type validation for content
-- **Fast**: Built with Rust for optimal performance
-- **Simple API**: RESTful API for easy integration
+- Create, retrieve, and delete temporary payloads
+- Built-in rate limiting
+- Automatic payload expiration
+- High performance with Redis backend
+- Comprehensive logging
+- Detailed error handling
 
-## Getting Started
+## Quick Start
 
 ### Prerequisites
 
-- Rust 1.70 or higher
-- Redis 6.0 or higher
-- Cargo (Rust's package manager)
+- Rust (latest stable)
+- Redis server (6.0 or higher)
+- Cargo (comes with Rust)
 
 ### Installation
 
 1. Clone the repository:
-   ```bash
-   git clone https://github.com/yourusername/jump.git
-   cd jump
-   ```
+```bash
+git clone https://github.com/codevalley/jump.git
+cd jump
+```
 
-2. Copy the example environment file:
-   ```bash
-   cp .env.example .env
-   ```
+2. Start Redis:
+```bash
+# Using Docker
+docker run --name jump-redis -p 6379:6379 -d redis
 
-3. Update the environment variables in `.env` with your configuration.
+# Or use your system's Redis
+systemctl start redis  # Linux
+brew services start redis  # macOS
+```
 
-4. Build the project:
-   ```bash
-   cargo build --release
-   ```
+3. Build and run:
+```bash
+cargo run
+```
 
-5. Run the server:
-   ```bash
-   cargo run --release
-   ```
+The service will start on `http://localhost:8080`.
 
-## Usage
+## API Overview
 
-### Creating a Share
+### Health Check
+```http
+GET /api/health
+```
 
-```bash
-curl -X POST http://localhost:8080/api/v1/payloads \
-  -H "Content-Type: application/json" \
-  -d '{
-    "content": "Your content here",
-    "mime_type": "text/plain",
-    "expiry_time": "2024-03-14T12:00:00Z"
-  }'
+### Create Payload
+```http
+POST /api/v1/payloads
+Content-Type: application/json
+
+{
+  "content": "Your content here",
+  "mime_type": "text/plain",
+  "expiry_time": "2025-03-28T00:00:00Z"  // Optional
+}
 ```
 
-### Retrieving a Share
+### Get Payload
+```http
+GET /api/v1/payloads/{hash_id}
+```
 
-```bash
-curl http://localhost:8080/api/v1/payloads/{hash_id}
+### Delete Payload
+```http
+DELETE /api/v1/payloads/{hash_id}
 ```
 
+For detailed API documentation, see [API.md](docs/API.md).
+
 ## Configuration
 
 The service can be configured using environment variables:
 
-- `SERVER_HOST`: Host to bind the server to (default: "127.0.0.1")
-- `SERVER_PORT`: Port to listen on (default: 8080)
-- `REDIS_URL`: Redis connection URL
-- `RATE_LIMIT_REQUESTS`: Number of requests allowed per window
-- `RATE_LIMIT_WINDOW_SECS`: Rate limit window in seconds
-- `MAX_PAYLOAD_SIZE`: Maximum payload size in bytes
-- `DEFAULT_EXPIRY_HOURS`: Default expiry time in hours
+```bash
+# Server configuration
+PORT=8080
+HOST=127.0.0.1
+
+# Redis configuration
+REDIS_URL=redis://localhost:6379
+REDIS_POOL_SIZE=16
+REDIS_TIMEOUT=5
+
+# Rate limiting
+RATE_LIMIT_REQUESTS=100
+RATE_LIMIT_WINDOW=60  # seconds
+
+# Payload limits
+MAX_PAYLOAD_SIZE=10485760  # 10MB
+DEFAULT_EXPIRY=86400      # 24 hours
+```
 
 ## Development
 
 ### Running Tests
 
 ```bash
+# Run all tests
 cargo test
+
+# Run specific test suite
+cargo test test_api_integration
 ```
 
-### Documentation
+### Code Style
 
-Generate and view the documentation:
+The project follows Rust standard formatting. Format your code using:
 
 ```bash
-cargo doc --open
+cargo fmt
 ```
 
-## API Documentation
+### Logging
 
-The API documentation is available at `/api/docs` when running the server.
+The service uses `tracing` for structured logging. Log levels can be configured using the `RUST_LOG` environment variable:
+
+```bash
+RUST_LOG=debug cargo run
+```
+
+## Project Structure
+
+```
+src/
+├── api/            # HTTP API layer
+│   ├── middleware/ # Rate limiting, logging
+│   └── v1/        # API version 1 endpoints
+├── application/    # Business logic
+│   ├── use_cases/ # Core operations
+│   └── dto/       # Data transfer objects
+├── domain/        # Core domain models
+├── infrastructure/ # External services
+│   └── redis/     # Redis implementation
+└── main.rs        # Application entry point
+```
 
 ## Contributing
 
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [actix-web](https://actix.rs/)
+- Storage powered by [Redis](https://redis.io/)
+- Logging with [tracing](https://docs.rs/tracing)
diff --git a/docs/API.md b/docs/API.md
@@ -0,0 +1,173 @@
+# Jump Service API Documentation
+
+## API Version 1
+
+Base URL: `/api/v1`
+
+## Endpoints
+
+### Create Payload
+
+Creates a new temporary payload.
+
+```http
+POST /payloads
+Content-Type: application/json
+```
+
+#### Request Body
+
+```json
+{
+  "content": "string",
+  "mime_type": "string",
+  "expiry_time": "2025-03-28T00:00:00Z"  // Optional, ISO 8601 format
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| content | string | Yes | The content to store |
+| mime_type | string | Yes | MIME type of the content |
+| expiry_time | string | No | When the content should expire (ISO 8601) |
+
+#### Response
+
+##### Success (201 Created)
+```json
+{
+  "hash_id": "string",
+  "expiry_time": "2025-03-28T00:00:00Z"
+}
+```
+
+##### Errors
+- 400 Bad Request: Invalid request body or MIME type
+- 413 Payload Too Large: Content exceeds size limit
+- 429 Too Many Requests: Rate limit exceeded
+- 500 Internal Server Error: Server error
+
+### Get Payload
+
+Retrieves a payload by its hash ID.
+
+```http
+GET /payloads/{hash_id}
+```
+
+#### Parameters
+
+| Name | In | Type | Required | Description |
+|------|-----|------|----------|-------------|
+| hash_id | path | string | Yes | The unique identifier of the payload |
+
+#### Response
+
+##### Success (200 OK)
+```json
+{
+  "content": "string",
+  "mime_type": "string",
+  "expiry_time": "2025-03-28T00:00:00Z"
+}
+```
+
+##### Errors
+- 404 Not Found: Payload not found or expired
+- 429 Too Many Requests: Rate limit exceeded
+- 500 Internal Server Error: Server error
+
+### Delete Payload
+
+Deletes a payload by its hash ID.
+
+```http
+DELETE /payloads/{hash_id}
+```
+
+#### Parameters
+
+| Name | In | Type | Required | Description |
+|------|-----|------|----------|-------------|
+| hash_id | path | string | Yes | The unique identifier of the payload |
+
+#### Response
+
+##### Success (204 No Content)
+No response body
+
+##### Errors
+- 404 Not Found: Payload not found
+- 429 Too Many Requests: Rate limit exceeded
+- 500 Internal Server Error: Server error
+
+## Rate Limiting
+
+The API implements rate limiting based on client IP address:
+
+- Default limit: 100 requests per 60 seconds
+- Rate limit headers:
+  - `X-RateLimit-Limit`: Maximum requests per window
+  - `X-RateLimit-Remaining`: Remaining requests in current window
+  - `X-RateLimit-Reset`: Time when the rate limit resets (Unix timestamp)
+
+## Error Responses
+
+All error responses follow this format:
+
+```json
+{
+  "error": "string"  // Human-readable error message
+}
+```
+
+## Examples
+
+### Creating a Payload
+
+Request:
+```bash
+curl -X POST http://localhost:8080/api/v1/payloads \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": "Hello, World!",
+    "mime_type": "text/plain",
+    "expiry_time": "2025-03-28T00:00:00Z"
+  }'
+```
+
+Response:
+```json
+{
+  "hash_id": "feb61cd1b3d34efebab6d6a8490071b2",
+  "expiry_time": "2025-03-28T00:00:00Z"
+}
+```
+
+### Retrieving a Payload
+
+Request:
+```bash
+curl http://localhost:8080/api/v1/payloads/feb61cd1b3d34efebab6d6a8490071b2
+```
+
+Response:
+```json
+{
+  "content": "Hello, World!",
+  "mime_type": "text/plain",
+  "expiry_time": "2025-03-28T00:00:00Z"
+}
+```
+
+### Deleting a Payload
+
+Request:
+```bash
+curl -X DELETE http://localhost:8080/api/v1/payloads/feb61cd1b3d34efebab6d6a8490071b2
+```
+
+Response:
+```
+204 No Content
+```
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
