rust_imgapi/AGENTS.md

# 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

---