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