API-SENTINEL Project Rules

Proje Tanımı

api-sentinel: 3. parti API endpoint'lerindeki response schema değişikliklerini otomatik tespit edip severity-based alert gönderen, tamamen dinamik ve plugin-tabanlı monitoring sistemi.

Temel Felsefe: Hiçbir entegrasyon (alert kanalı, auth yöntemi, storage backend, provider) hardcoded değil. Kullanıcı runtime'da veya config üzerinden istediği bileşeni ekleyip çıkarabilir.

Tech Stack (Kesin - Değiştirme)

Dil: Python 3.12
API: FastAPI 0.115+ (fonksiyonel endpoint'ler, class-based view KULLANMA)
Scheduler: APScheduler 3.10+ (AsyncIOScheduler)
HTTP Client: httpx 0.27+ (async)
JSON Diff: deepdiff 7.0+
DB: SQLite 3 + raw sqlite3 modülü (ORM KULLANMA) — varsayılan backend
Config: PyYAML
Scraping: httpx + beautifulsoup4
Şifreleme: cryptography (Fernet)
Template: Jinja2 + Tailwind CSS + Alpine.js
Container: Docker + Docker Compose v3.8

Alert Paketleri (Kullanıcı Seçimine Göre — Opsiyonel)

Bunlar requirements.txt'te opsiyonel bağımlılık olarak listelenir. Sistem başlarken hangi kanallar aktifse sadece onların bağımlılığını kontrol eder.

Kanal	Paket	Zorunlu mu?
Email	smtplib (stdlib)	Hayır — stdlib, ekstra paket yok
SMS	httpx (zaten var)	Hayır — multi-provider (Verimor, Netgsm, Twilio, Vonage, İleti Merkezi, Mutlucell)

Dinamik Mimari Kuralları

1. Plugin Registry Pattern

Her genişletilebilir bileşen şu pattern'i kullanır:

# registry.py — merkezi plugin registry
class PluginRegistry:
    """Tüm plugin tiplerini yöneten merkezi registry."""
    # Her plugin tipi için ayrı dict: alert_channels, auth_handlers, storage_backends
    # register(plugin_type, name, cls) ile kayıt
    # get(plugin_type, name) ile erişim
    # list(plugin_type) ile listeleme
    # auto_discover(package_path) ile otomatik keşif

2. Alert Kanalları — Plugin Tabanlı

alerts/ dizinindeki her .py dosyası otomatik keşfedilir (auto-discover)
Her kanal BaseAlertChannel'dan türer
alerts.yaml hangi kanalların aktif olduğunu ve config'ini tanımlar
Kullanıcı yeni bir .py dosyası bırakıp alerts.yaml'a ekleyerek kanal ekler
Hiçbir kanal hardcoded import edilmez, tamamı dinamik yüklenir

# alerts/base.py — Tüm kanalların türediği abstract class
class BaseAlertChannel(ABC):
    """
    Her alert kanalı bu class'tan türemeli.
    channel_name: str — yaml'daki tanımlayıcı (ör: "email", "sms")
    """
    channel_name: str  # Her subclass tanımlamalı

    @abstractmethod
    async def send(self, severity, title, message, details) -> bool: ...

    @abstractmethod
    def validate_config(self, config: dict) -> bool: ...

    @classmethod
    def required_env_vars(cls) -> list[str]: ...

3. Auth Handler'lar — Plugin Tabanlı

auth/ dizininde: bearer, basic, api_key, oauth2
Her handler BaseAuthHandler'dan türer
endpoints.yaml'da endpoint başına auth tipi belirtilir
Kullanıcı yeni auth handler ekleyebilir

4. Provider/Endpoint Yönetimi — Tamamen Dinamik

Web UI + REST API ile yönetim (YAML seed isteğe bağlı)
Runtime'da provider/endpoint ekleme, silme, güncelleme (API üzerinden)
Her endpoint bağımsız schedule'a sahip olabilir

5. Storage Backend — Plugin Tabanlı

Varsayılan: SQLite (sıfır config ile çalışır)
store/base.py abstract interface tanımlar (25 metod)
FileStore ile dosya bazlı JSON arşiv desteği

6. Güvenlik Katmanı

API Auth Middleware: Dashboard ve API erişimi için token bazlı koruma
Rate Limiting: Check endpoint'leri için istek sınırlama
Credential Encryption: Fernet ile at-rest şifreleme
Alert Cooldown: Tekrarlayan alert bastırma mekanizması

Kod Kuralları

Python

Yorum satırları Türkçe yaz
Type hint kullan (tüm fonksiyon parametreleri ve dönüş tipleri)
Docstring kullan (Google style, Türkçe)
logging modülü kullan, print() KULLANMA
asyncio.run() KULLANMA, uvicorn ile çalıştır
Global state / singleton pattern KULLANMA
Hardcoded credential KULLANMA, her şey os.environ üzerinden
Placeholder / TODO / pass bırakma, her fonksiyonu tam yaz
Exception handling: bare except: KULLANMA, spesifik exception yakala
f-string tercih et (.format() yerine)
Import sırası: stdlib → 3rd party → local (isort uyumlu)
Hardcoded import KULLANMA — plugin'ler importlib ile dinamik yüklenecek

Dosya Yapısı

Monorepo: tüm servisler api-sentinel/ altında
Her servisin kendi Dockerfile ve requirements.txt dosyası var
Config dosyaları YAML formatında
Schema snapshot'lar /app/schemas/{provider}/{endpoint}/ altında JSON
SQLite DB: /app/data/schemas.db
Plugin dizinleri: alerts/, auth/, store/ — auto-discover destekli

Docker

Base image: python:3.12-slim
Multi-stage build KULLANMA (gereksiz karmaşıklık)
requirements.txt önce COPY et (cache için)
Non-root user ile çalıştır
Healthcheck tanımla
Network: sentinel-net (bridge)

Test

pytest kullan
Test dosyaları: tests/ dizininde
Fixture'lar: tests/fixtures/ dizininde JSON dosyaları
Minimum %80 coverage hedefi
Mock: 3. parti API çağrılarını mockla (gerçek istek ATMA)
Her plugin tipi için ayrı test: test_alert_plugins.py, test_auth_plugins.py
Kritik modüller: scheduler, fetcher, crypto mutlaka test edilmeli

Severity Kuralları (Kesin - Değiştirme)

Değişiklik	Severity
field_removed	CRITICAL
type_changed	CRITICAL
array_item_schema_changed	CRITICAL
auth_changed	CRITICAL
nullable_changed_to_false	WARNING
required_field_added	WARNING
enum_value_removed	WARNING
depth_changed	WARNING
format_changed	WARNING
field_added	INFO
enum_value_added	INFO
status_code_changed_2xx	INFO

API Endpoint'leri

# Monitoring
GET  /health
GET  /metrics

# Güvenlik
POST /api/auth/login                            # Token al
POST /api/auth/logout                           # Token iptal

# Provider/Endpoint Yönetimi (Dinamik CRUD)
GET    /api/providers
POST   /api/providers                          # Yeni provider ekle
PUT    /api/providers/{name}                   # Provider güncelle
DELETE /api/providers/{name}                   # Provider sil
GET    /api/providers/{name}/endpoints
POST   /api/providers/{name}/endpoints          # Yeni endpoint ekle
PUT    /api/providers/{name}/endpoints/{ep}      # Endpoint güncelle
DELETE /api/providers/{name}/endpoints/{ep}      # Endpoint sil

# Credential Yönetimi
GET    /api/providers/{name}/credentials        # Credential key listesi
POST   /api/providers/{name}/credentials        # Credential ekle/güncelle
DELETE /api/providers/{name}/credentials/{key}   # Credential sil

# Değişiklik Takibi
GET  /api/changes?severity=&provider=&limit=&offset=
GET  /api/changes/{id}
POST /api/changes/{id}/acknowledge

# Manuel Tetikleme
POST /api/check/{provider}/{endpoint}
POST /api/check-all

# Plugin Yönetimi
GET  /api/plugins                              # Tüm plugin'leri listele
GET  /api/plugins/{type}                       # Belirli tipteki plugin'ler (alerts, auth, store)
GET  /api/plugins/{type}/{name}/status          # Plugin durumu ve config doğrulama

# Alert Kanalları Yönetimi
GET    /api/alerts/channels                     # Aktif kanalları listele
POST   /api/alerts/channels                     # Yeni kanal aktifle
PUT    /api/alerts/channels/{name}              # Kanal config güncelle
DELETE /api/alerts/channels/{name}              # Kanal deaktif et
POST   /api/alerts/test/{channel_name}          # Test mesajı gönder
GET    /api/alerts/history                      # Alert gönderim geçmişi

# Ayarlar
GET    /api/settings                            # Tüm ayarlar
POST   /api/settings                            # Ayar kaydet
POST   /api/settings/clear                      # Veri temizle

# Durum
GET    /api/statuses                            # Endpoint durum bilgileri
GET    /api/stats                               # İstatistikler

Dosya Oluşturduktan Sonra

Her .py dosyası için syntax kontrol: python -c "import ast; ast.parse(open('dosya.py').read())"
Her .yaml dosyası için parse kontrol: python -c "import yaml; yaml.safe_load(open('dosya.yaml'))"
docker compose config --quiet ile compose syntax kontrolü
pytest tests/ -v ile test çalıştır
Hata varsa düzelt ve tekrar çalıştır

Yapma Listesi

requirements.txt'te belirtilmeyen paket ekleme
Kubernetes / Helm / K8s referansı yapma
Prometheus / Grafana / Uptime Kuma entegrasyonu yapma (sadece Web UI kullanılacak)
Onay sorma, dosyaları direkt oluştur
Hiçbir alert kanalını, auth yöntemini veya storage backend'i hardcoded bağlama
Plugin olmadan çalışamayacak yapı kurma — sistem sıfır plugin ile de ayağa kalkmalı
Gereksiz harici paket ekleme — mevcut stack ile çöz

FilesExpand file tree

CLAUDE.MD

Latest commit

History