rust_imgapi/docs/IMPLEMENTATION.md

# Implementation Notes

Bu belge projede su ana kadar yapilan implementasyonlari teknik olarak ozetler.

## 1. Genel Mimari

Proje Axum tabanli bir API olarak calisir.

Baslica moduller:

- `src/main.rs` -> uygulama bootstrap
- `src/app/` -> router birlestirme ve OpenAPI
- `src/auth/` -> register/login/refresh/logout/me akisi
- `src/images/` -> image upload, process, listeleme ve variant stream akisi
- `src/entities/` -> SeaORM entity tanimlari
- `src/migration/` -> migration dosyalari
- `src/state/` -> `AppState`, JWT ayarlari, DB init
- `src/error/` -> unified `ApiError`
- `src/tests/` -> endpoint testleri

Katman mantigi:

- `controller` -> HTTP request parsing / response
- `service` -> business logic
- `repository` -> DB / fs / token source erisimi
- `processor` -> image decode/resize/encode
- `dto` -> request/response tasiyicilari
- `model` -> domain enum ve tipler

## 2. Auth Sistemi

Account sistemi JWT access + refresh token mantigi ile calisir.

Mevcut endpointler:

- `POST /api/v1/auth/register`
- `POST /api/v1/auth/login`
- `POST /api/v1/auth/refresh`
- `POST /api/v1/auth/logout`
- `GET /api/v1/auth/me`

Davranis:

- sifreler `argon2` ile hashlenir
- access / refresh token `jsonwebtoken` ile uretilir
- refresh token session'lari:
  - DB varsa `refresh_tokens` tablosu
  - DB yoksa in-memory fallback

## 3. Images Modulu

Images modulu su endpointleri sunar:

- `GET /api/v1/images/process`
- `POST /api/v1/images/process`
- `GET /api/v1/images`
- `GET /api/v1/images/{id}/variant`

### 3.1 GET /api/v1/images/process

Bu endpoint query parametrelerini dogrular ve donusum metadata'si uretir.

Desteklenen parametreler:

- `width` / `w`
- `height` / `h`
- `format`
- `quality`
- `crop`

Default degerler:

- `format = webp`
- `crop = cover`
- `quality = 80`

### 3.2 POST /api/v1/images/process

Bu endpoint multipart form-data ile dosya kabul eder.

Beklenen alanlar:

- `file`
- `width`
- `height`
- `format`
- `quality`
- `crop`

Akis:

1. bearer token okunur
2. token validate edilir
3. multipart file byte olarak okunur
4. orijinal dosya `uploads/originals` altina kaydedilir
5. image decode edilir
6. gerekirse resize uygulanir
7. istenen output format'a encode edilir
8. islenmis varyant `uploads/variants` altina kaydedilir
9. DB varsa metadata `images` ve `image_variants` tablolarina yazilir
10. response olarak metadata donulur

### 3.3 GET /api/v1/images

Bu endpoint DB uzerinden image metadata listesi doner.

Not:

- DB yoksa `503 Service Unavailable` doner
- response, her image icin latest variant bilgisini de icerebilir

### 3.4 GET /api/v1/images/{id}/variant

Bu endpoint ilgili image kaydinin en son varyant dosyasini binary olarak stream eder.

Not:

- DB gerektirir
- son varyant secimi `created_at desc` sirasina gore yapilir

## 4. Desteklenen Formatlar

Model tarafinda desteklenen formatlar:

- `avif`
- `png`
- `jpg`
- `jpeg`
- `webp`

Processor tarafinda gercek encode akisi vardir.

Not:

- input decode basarisizsa su an fallback davranisi source bytes donusumu yerine ham byte ile devam etmeye calisabilir veya hata doner; bu kisim ileride daha da sertlestirilebilir
- `crop` enum'u dogrulaniyor fakat su an gercek crop stratejileri tam uygulanmiyor; mevcut implementasyon daha cok resize + format convert seviyesinde

## 5. Token Dogrulama

Image endpointleri icin bearer token zorunludur.

Su an iki yol desteklenir:

1. `IMAGE_ACCESS_TOKEN` env degeri ile gelen dev token
2. mevcut auth sisteminden uretilmis JWT access token

Bu davranis gecis sureci icindir.

Hedef mimari:

- Redis tabanli image token validation
- namespaced key yapisi, or. `image:token:{token}`

## 6. Storage Davranisi

Varsayilan env ayarlari:

- `IMAGE_UPLOAD_DIR=uploads/originals`
- `IMAGE_VARIANT_DIR=uploads/variants`

Yuklenen orijinal dosya:

- `uploads/originals/<uuid>.<ext>`

Uretilen varyant dosya:

- `uploads/variants/<uuid>.<target-ext>`

Onemli not:

- su an response icinde `stored_path` donuluyor
- bu, mevcut implementasyonda debugging ve kontrol kolayligi icin acik
- hedef uretim mimarisinde raw path expose etmek yerine `image_id` veya signed access token tercih edilmelidir

## 7. DB ve Migration Yapisi

### 7.1 Auth Tablolari

Migration:

- `m20260409_000001_create_auth_tables`

Tablolar:

- `users`
- `refresh_tokens`

### 7.2 Images Tablolari

Migration:

- `m20260409_000002_create_image_tables`

Tablolar:

- `images`
- `image_variants`

Iliskiler:

- `users (1) -> (N) images`
- `images (1) -> (N) image_variants`

### 7.3 Migration Calisma Akisi

`src/state/mod.rs` icinde DB baglantisi varsa uygulama acilisinda `Migrator::up` cagrilir.

Yani:

- DB varsa migration'lar otomatik kontrol edilir
- DB baglantisi yoksa app fallback modda acilabilir

## 8. Swagger / OpenAPI

Swagger UI:

- `GET /swagger-ui`

OpenAPI JSON:

- `GET /api-docs/openapi.json`

Swagger'a ekli alanlar:

- auth endpointleri
- image process GET
- image upload POST (multipart form-data)
- image list
- image variant stream

## 9. Env Degiskenleri

Temel env degiskenleri:

- `DATABASE_URL`
- `JWT_SECRET`
- `JWT_ISSUER`
- `ACCESS_TOKEN_TTL_SECS`
- `REFRESH_TOKEN_TTL_SECS`
- `ENABLE_SWAGGER_UI`
- `IMAGE_ACCESS_TOKEN`
- `IMAGE_UPLOAD_DIR`
- `IMAGE_VARIANT_DIR`
- `DB_REQUIRED`

## 10. Mevcut Sinirlar / Sonraki Adimlar

Su an sistem calisir durumda ama halen gelistirilebilir alanlar var:

1. Redis tabanli gercek image token repository
2. gercek crop stratejileri (`cover`, `contain`, `center` vs.)
3. image cache / variant cache
4. raw path expose etmek yerine guvenli public serving
5. `GET /api/v1/images/{id}/variant` icin format/width/height/crop bazli secim
6. islenmis varyantlar icin duplicate-onleme / cache-aside stratejisi
7. local fs yerine object storage destegi

## 11. Windows Build

Repo icinde `win.sh` scripti bulunur.

Amaci:

- `x86_64-pc-windows-gnu` target eklemek
- linker config hazirlamak
- Windows release build almak

Script:

- `.cargo/config.toml` olusturabilir
- `cargo build --target x86_64-pc-windows-gnu --release` calistirir