{"id":29141181,"url":"https://github.com/blackshadowsoftwareltd/fuel_cost_server","last_synced_at":"2025-06-30T18:05:36.490Z","repository":{"id":299494589,"uuid":"1003197132","full_name":"blackshadowsoftwareltd/fuel_cost_server","owner":"blackshadowsoftwareltd","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-16T20:22:53.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-16T21:30:49.230Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackshadowsoftwareltd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-16T19:20:07.000Z","updated_at":"2025-06-16T20:22:56.000Z","dependencies_parsed_at":"2025-06-16T21:32:23.230Z","dependency_job_id":"8901381f-4771-4d1b-902b-bc9015b88615","html_url":"https://github.com/blackshadowsoftwareltd/fuel_cost_server","commit_stats":null,"previous_names":["blackshadowsoftwareltd/fuel_cost_server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/blackshadowsoftwareltd/fuel_cost_server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackshadowsoftwareltd%2Ffuel_cost_server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackshadowsoftwareltd%2Ffuel_cost_server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackshadowsoftwareltd%2Ffuel_cost_server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackshadowsoftwareltd%2Ffuel_cost_server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackshadowsoftwareltd","download_url":"https://codeload.github.com/blackshadowsoftwareltd/fuel_cost_server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackshadowsoftwareltd%2Ffuel_cost_server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262825646,"owners_count":23370419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-30T18:05:34.875Z","updated_at":"2025-06-30T18:05:36.478Z","avatar_url":"https://github.com/blackshadowsoftwareltd.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fuel Cost Server\n\nA Rust REST API server for tracking fuel costs with email/password authentication. Data is stored in SQLite with JSON serialization for flexible fuel entry storage.\n\n## Features\n\n- **Email/Password Authentication**: Simple signup and signin\n- **Auto-account Creation**: Creates account automatically if user doesn't exist during signin\n- **Fuel Entry Management**: Full CRUD operations for fuel entries\n- **JSON Storage**: Fuel entries stored as JSON strings in database for flexibility\n- **SQLite Database**: Lightweight, file-based database\n- **CORS Support**: Cross-origin resource sharing enabled\n\n## Prerequisites\n\n- [Rust](https://rustup.rs/) (latest stable version)\n- [Git](https://git-scm.com/)\n\n## Installation \u0026 Setup\n\n1. **Clone the repository**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd fuel_cost_server\n   ```\n\n2. **Install dependencies and run**\n   ```bash\n   # Option 1: Use the provided script (recommended)\n   ./run_server.sh\n   \n   # Option 2: Manual build and run\n   cargo build\n   cargo run\n   ```\n\nThe server will start on `http://localhost:3002`\n\n**Note**: The SQLite database file (`fuel_cost.db`) will be created automatically on first run.\n\n## API Endpoints\n\nAll API responses follow a consistent format. Successful responses return the requested data, while error responses return structured error information:\n\n```json\n{\n  \"error\": \"Brief error description\",\n  \"details\": \"Detailed error message with specific information\"\n}\n```\n\n### Authentication\n\n#### Sign Up\n- **POST** `/api/auth/signup`\n- **Body**: \n  ```json\n  {\n    \"email\": \"user@example.com\",\n    \"password\": \"password123\"\n  }\n  ```\n- **Response**: \n  ```json\n  {\n    \"user_id\": \"uuid-string\",\n    \"email\": \"user@example.com\"\n  }\n  ```\n\n#### Sign In\n- **POST** `/api/auth/signin`\n- **Body**: \n  ```json\n  {\n    \"email\": \"user@example.com\",\n    \"password\": \"password123\"\n  }\n  ```\n- **Response**: \n  ```json\n  {\n    \"user_id\": \"uuid-string\",\n    \"email\": \"user@example.com\"\n  }\n  ```\n- **Note**: If user doesn't exist, account will be created automatically\n\n### Fuel Entries\n\n#### Create Fuel Entry (Single)\n- **POST** `/api/fuel-entries`\n- **Body**: \n  ```json\n  {\n    \"user_id\": \"uuid-string\",\n    \"liters\": 50.5,\n    \"price_per_liter\": 1.45,\n    \"total_cost\": 73.23,\n    \"date_time\": \"2024-01-15T10:30:00Z\",\n    \"odometer_reading\": 125000.5\n  }\n  ```\n\n#### Create Fuel Entries (Bulk)\n- **POST** `/api/fuel-entries/bulk`\n- **Body**: \n  ```json\n  {\n    \"user_id\": \"uuid-string\",\n    \"entries\": [\n      {\n        \"liters\": 45.5,\n        \"price_per_liter\": 1.42,\n        \"total_cost\": 64.61,\n        \"date_time\": \"2024-01-10T08:30:00Z\",\n        \"odometer_reading\": 124500.0\n      },\n      {\n        \"liters\": 52.3,\n        \"price_per_liter\": 1.45,\n        \"total_cost\": 75.84,\n        \"date_time\": \"2024-01-15T14:20:00Z\",\n        \"odometer_reading\": 124950.5\n      }\n    ]\n  }\n  ```\n- **Response**: \n  ```json\n  {\n    \"message\": \"Successfully created 2 fuel entries\",\n    \"count\": 2,\n    \"entries\": [/* array of created entries */]\n  }\n  ```\n\n#### Get All Fuel Entries\n- **GET** `/api/fuel-entries/{user_id}`\n- **Response**: Array of fuel entry objects\n\n#### Get Specific Fuel Entry\n- **GET** `/api/fuel-entries/{user_id}/{fuel_entry_id}`\n- **Response**: Single fuel entry object\n\n#### Update Fuel Entry\n- **PUT** `/api/fuel-entries/{user_id}/{fuel_entry_id}`\n- **Body**: (partial updates supported)\n  ```json\n  {\n    \"liters\": 52.0,\n    \"total_cost\": 75.40\n  }\n  ```\n\n#### Delete Fuel Entry\n- **DELETE** `/api/fuel-entries/{user_id}/{fuel_entry_id}`\n- **Response**: \n  ```json\n  {\n    \"message\": \"Fuel entry deleted successfully\"\n  }\n  ```\n\n#### Delete Fuel Entries (Bulk)\n- **POST** `/api/fuel-entries/bulk/delete`\n- **Request Body**:\n  ```json\n  {\n    \"user_id\": \"string\",\n    \"entry_ids\": [\"string\", \"string\", ...]\n  }\n  ```\n- **Response**:\n  ```json\n  {\n    \"message\": \"Successfully deleted 2 fuel entries\",\n    \"deleted_count\": 2,\n    \"total_requested\": 3,\n    \"not_found_count\": 1,\n    \"deleted_ids\": [\"entry-uuid-1\", \"entry-uuid-2\"]\n  }\n  ```\n- **Note**: Transaction-safe operation. Only deletes entries that exist and belong to the user. Returns detailed results including which entries were successfully deleted.\n\n## Data Models\n\n### User\n```json\n{\n  \"id\": \"string\",\n  \"email\": \"string\",\n  \"password_hash\": \"string\",\n  \"created_at\": \"datetime\"\n}\n```\n\n### Fuel Entry\n```json\n{\n  \"id\": \"string\",\n  \"user_id\": \"string\",\n  \"liters\": \"number\",\n  \"price_per_liter\": \"number\",\n  \"total_cost\": \"number\",\n  \"date_time\": \"datetime\",\n  \"odometer_reading\": \"number (optional)\"\n}\n```\n\n## Database Schema\n\nThe database uses a simplified schema with JSON storage:\n\n### users table\n- `id` (TEXT PRIMARY KEY)\n- `email` (TEXT UNIQUE NOT NULL)\n- `password_hash` (TEXT NOT NULL)\n- `created_at` (TEXT NOT NULL)\n\n### fuel_entries table\n- `id` (TEXT PRIMARY KEY)\n- `user_id` (TEXT NOT NULL) - Foreign key to users table for efficient filtering\n- `data` (TEXT NOT NULL) - JSON string containing all fuel entry data\n\n## Testing with Postman\n\n1. Import the `Fuel_Cost_API.postman_collection.json` file into Postman\n2. Set the `base_url` variable to `http://localhost:3002`\n3. Use the collection to test all endpoints\n\n### Quick Test Flow:\n1. **Sign up** a new user → copy `user_id` from response\n2. **Create fuel entry** or **Create bulk entries** → copy `id`(s) from response\n3. **Get all entries** for the user\n4. **Update** a fuel entry\n5. **Delete** a single entry or **Delete bulk entries**\n\n## Development\n\n### Project Structure\n```\nsrc/\n├── main.rs          # Server setup and routing\n├── models.rs        # Data structures and request/response models\n├── database.rs      # Database operations and queries\n├── auth.rs          # Password hashing and verification\n└── handlers.rs      # HTTP request handlers\n```\n\n### Building\n```bash\ncargo build\n```\n\n### Running in Development\n```bash\ncargo run\n```\n\n### Running Tests\n```bash\n# Run the test script (if available)\n./test_api.sh\n```\n\n## Configuration\n\n- **Database**: SQLite file (`fuel_cost.db`) created automatically\n- **Server Port**: 3002 (configurable in `main.rs`)\n- **CORS**: Permissive (allows all origins)\n\n## Troubleshooting\n\n### Database Issues\n- **Error**: \"unable to open database file\"\n  - **Solution**: The server will now create the database automatically. Ensure you have write permissions in the project directory.\n\n### Build Issues\n- **Error**: \"cargo not found\"\n  - **Solution**: Install Rust using `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`\n\n### Server Issues\n- **Error**: \"Address already in use\"\n  - **Solution**: Stop any existing server with `pkill -f fuel_cost_server` or change the port in `main.rs`\n\n### Testing Issues\n- **Error**: Connection refused\n  - **Solution**: Ensure the server is running on `http://localhost:3002`\n\n### API Error Messages\nCommon error responses and their meanings:\n\n#### Authentication Errors\n- **409 Conflict**: \"User already exists\" - Email is already registered\n- **401 Unauthorized**: \"Invalid credentials\" - Wrong password\n- **500 Internal Server Error**: Database or password hashing issues\n\n#### Fuel Entry Errors  \n- **400 Bad Request**: \"Invalid user ID\" - User doesn't exist in database\n- **400 Bad Request**: \"Empty entries list\" - Bulk creation with no entries\n- **400 Bad Request**: \"Empty entry IDs list\" - Bulk deletion with no entry IDs\n- **404 Not Found**: \"Fuel entry not found\" - Entry doesn't exist or wrong user\n- **422 Unprocessable Entity**: Missing required fields (user_id, liters, etc.)\n- **500 Internal Server Error**: Database operation failed\n\n**Note**: Bulk operations use database transactions - if any entry fails, all entries in the batch are rolled back.\n\nAll error responses include detailed `details` field with specific information to help debug the issue.\n\n## Files Structure\n```\nfuel_cost_server/\n├── src/\n│   ├── main.rs              # Server setup and routing\n│   ├── models.rs            # Data structures\n│   ├── database.rs          # Database operations\n│   ├── auth.rs              # Password handling\n│   └── handlers.rs          # HTTP handlers\n├── fuel_cost.db             # SQLite database (auto-created)\n├── run_server.sh            # Startup script\n├── test_api.sh              # API testing script\n├── README.md                # This file\n└── *.postman_collection.json # Postman collections\n```\n\n## Security Notes\n\n- Passwords are hashed using bcrypt\n- No JWT tokens - simplified authentication\n- User access controlled by user_id parameter in requests\n- Database queries use parameterized statements to prevent SQL injection\n- Database file excluded from git via .gitignore\n\n## License\n\n[Add your license here]\n\n## Contributing\n\n[Add contribution guidelines here]","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackshadowsoftwareltd%2Ffuel_cost_server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackshadowsoftwareltd%2Ffuel_cost_server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackshadowsoftwareltd%2Ffuel_cost_server/lists"}