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

---