first commit
This commit is contained in:
Beyhan Oğur
200
AGENTS.md
Normal file
200
AGENTS.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# Copilot Rules for Rust Image Manipulation API
|
||||
|
||||
## Project Overview
|
||||
This project is a Rust-based API built with:
|
||||
- `axum = "0.8.8"`
|
||||
- `sea-orm = { version = "1.1.20", features = ["sqlx-postgres", "runtime-tokio-native-tls", "macros"] }`
|
||||
- `tokio = { version = "1.51.1", features = ["full"] }`
|
||||
- `tower-http = { version = "0.6.8", features = ["trace"] }`
|
||||
|
||||
The main purpose of the API is image manipulation with support for:
|
||||
- `avif`
|
||||
- `png`
|
||||
- `jpg`
|
||||
- `jpeg`
|
||||
- `webp`
|
||||
|
||||
The project already has an account system. Use it as-is unless explicitly asked to modify it.
|
||||
|
||||
Redis will be used for:
|
||||
- temporary/signed access tokens
|
||||
- time-based access control
|
||||
- caching image manipulation results if needed
|
||||
|
||||
---
|
||||
|
||||
## General Coding Rules
|
||||
1. Prefer idiomatic Rust.
|
||||
2. Follow Axum patterns for handlers, extractors, routers, and state management.
|
||||
3. Keep business logic in services, not in controllers/handlers.
|
||||
4. Use SeaORM for database access.
|
||||
5. Use async/await everywhere I/O is involved.
|
||||
6. Avoid blocking operations on the Tokio runtime.
|
||||
7. Write small, composable functions.
|
||||
8. Prefer strong types over raw strings for domain concepts.
|
||||
9. Handle errors explicitly and return structured API errors.
|
||||
10. Do not introduce unnecessary dependencies.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Rules
|
||||
Use the following structure for new image-related code:
|
||||
- `images/model`
|
||||
- `images/controller`
|
||||
- `images/service`
|
||||
- `images/repository`
|
||||
- `images/dto`
|
||||
- `images/processor`
|
||||
|
||||
If auth/token logic is needed for image access:
|
||||
- keep verification in middleware or a dedicated auth/token service
|
||||
- keep Redis interaction isolated in a repository or cache layer
|
||||
|
||||
### Layer Responsibilities
|
||||
- **controller/handler**: HTTP request parsing, response formatting
|
||||
- **service**: business rules, token validation flow, image transformation orchestration
|
||||
- **repository**: DB/Redis access
|
||||
- **processor**: actual image resize/crop/convert operations
|
||||
- **model**: entities and domain types
|
||||
- **dto**: request/response payloads
|
||||
|
||||
---
|
||||
|
||||
## Image Manipulation Rules
|
||||
1. Support these output formats:
|
||||
- avif
|
||||
- png
|
||||
- jpg
|
||||
- jpeg
|
||||
- webp
|
||||
|
||||
2. Accept image manipulation parameters such as:
|
||||
- `width` / `w`
|
||||
- `height` / `h`
|
||||
- `format`
|
||||
- `quality`
|
||||
- `crop`
|
||||
|
||||
3. Support crop modes like:
|
||||
- `cover`
|
||||
- `contain`
|
||||
- `fill`
|
||||
- `center`
|
||||
- `top`
|
||||
- `bottom`
|
||||
- `left`
|
||||
- `right`
|
||||
- `smart` if implemented later
|
||||
|
||||
4. Validate all manipulation inputs:
|
||||
- width and height must be positive
|
||||
- quality must be within a valid range
|
||||
- format must be one of the supported formats
|
||||
- crop mode must be recognized
|
||||
|
||||
5. Never trust query parameters directly without validation.
|
||||
|
||||
6. Preserve aspect ratio when required by crop mode.
|
||||
|
||||
7. If a requested format is unsupported, return a clear API error.
|
||||
|
||||
8. If the image cannot be decoded or converted, return a meaningful error response.
|
||||
|
||||
---
|
||||
|
||||
## Token Access Rules
|
||||
1. Image manipulation must be accessible through time-limited tokens.
|
||||
2. Tokens may be stored or validated through Redis.
|
||||
3. Token validation must occur before image processing.
|
||||
4. Token expiration must be enforced.
|
||||
5. Do not expose raw internal storage paths through public APIs.
|
||||
6. Tokens should be treated as opaque values from the client perspective.
|
||||
7. If token is invalid or expired, return `401 Unauthorized` or `403 Forbidden` as appropriate.
|
||||
|
||||
---
|
||||
|
||||
## Redis Rules
|
||||
1. Use Redis for short-lived access control data.
|
||||
2. Keep Redis keys namespaced, for example:
|
||||
- `image:token:{token}`
|
||||
- `image:cache:{hash}`
|
||||
3. Set TTL explicitly for temporary tokens.
|
||||
4. Prefer cache-aside patterns if storing processed image results.
|
||||
5. Redis access code must be isolated and reusable.
|
||||
|
||||
---
|
||||
|
||||
## SeaORM Rules
|
||||
1. Use entities generated or structured consistently with SeaORM conventions.
|
||||
2. Keep DB operations in repository layer.
|
||||
3. Avoid mixing query building into handlers.
|
||||
4. Return repository-level errors as domain errors or application errors.
|
||||
5. Use migrations for schema changes.
|
||||
6. Do not hardcode SQL unless necessary.
|
||||
|
||||
---
|
||||
|
||||
## Axum Rules
|
||||
1. Use `Router` cleanly and split routes by module.
|
||||
2. Prefer typed extractors for shared state.
|
||||
3. Use `State<AppState>` for database/Redis/shared services.
|
||||
4. Use middleware only for cross-cutting concerns like auth, logging, rate limiting.
|
||||
5. Return JSON responses with consistent shape.
|
||||
6. Use `tower_http::trace::TraceLayer` for request tracing.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Rules
|
||||
1. Define a unified error type for the API.
|
||||
2. Convert infrastructure errors into application errors.
|
||||
3. Return consistent error response payloads.
|
||||
4. Do not panic in request handlers.
|
||||
5. Log errors where useful, but avoid leaking secrets.
|
||||
|
||||
---
|
||||
|
||||
## Naming Rules
|
||||
1. Use clear module names:
|
||||
- `account`
|
||||
- `images`
|
||||
- `auth`
|
||||
- `shared`
|
||||
- `config`
|
||||
2. Name functions by behavior, not implementation.
|
||||
3. Prefer `create_*`, `get_*`, `update_*`, `delete_*`, `process_*`, `validate_*`.
|
||||
4. Keep DTO names explicit, for example:
|
||||
- `CreateTokenRequest`
|
||||
- `ManipulateImageRequest`
|
||||
- `ImageResponse`
|
||||
|
||||
---
|
||||
|
||||
## When Generating Code
|
||||
Copilot should:
|
||||
- follow existing project style
|
||||
- reuse existing account/auth infrastructure
|
||||
- avoid changing unrelated modules
|
||||
- prefer minimal, targeted changes
|
||||
- keep code ready for testing
|
||||
- add comments only when they add clarity
|
||||
|
||||
---
|
||||
|
||||
## What Copilot Should Not Do
|
||||
- Do not rewrite the whole project unless explicitly asked.
|
||||
- Do not replace SeaORM with another ORM.
|
||||
- Do not introduce framework changes away from Axum.
|
||||
- Do not hardcode credentials or secrets.
|
||||
- Do not store tokens insecurely.
|
||||
- Do not bypass validation for convenience.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Defaults
|
||||
- Default output format: `webp` unless user requests otherwise.
|
||||
- Default crop mode: `cover`
|
||||
- Default quality: `80`
|
||||
- Default dimension behavior: preserve aspect ratio when only one side is provided
|
||||
- Default access: token required for protected image processing routes
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user