feat: Add authentication example application with User entity, repository, and security config

canermastan · canermastan · commit b35d3f56e204 · 2025-05-30T16:23:42.000+03:00
diff --git a/src/main/java/examples/auth_example/AppSecurityConfig.java b/src/main/java/examples/auth_example/AppSecurityConfig.java
@@ -0,0 +1,54 @@
+package examples.auth_example;
+
+import jazzyframework.di.annotations.Component;
+import jazzyframework.security.config.SecurityConfig;
+
+/**
+ * Security configuration for the Authentication Example Application.
+ * 
+ * <p>This configuration demonstrates how to set up URL-based security rules
+ * for a typical web application with authentication endpoints.
+ * 
+ * <h3>Security Rules:</h3>
+ * <ul>
+ *   <li><b>Public endpoints:</b> Home page and authentication endpoints</li>
+ *   <li><b>Secure endpoints:</b> Protected resources requiring JWT token</li>
+ *   <li><b>Admin endpoints:</b> Administrative functions requiring ADMIN role</li>
+ * </ul>
+ * 
+ * <p>The {@code @Component} annotation ensures this configuration is automatically
+ * discovered and used by the Jazzy Framework's security system.
+ * 
+ * @author Caner Mastan
+ * @see SecurityConfig
+ */
+@Component
+public class AppSecurityConfig extends SecurityConfig {
+    
+    /**
+     * Configures security rules for the application.
+     * 
+     * <p>This method defines which endpoints are public, which require authentication,
+     * and which require admin privileges. The configuration uses wildcards to
+     * efficiently cover multiple related endpoints.
+     */
+    @Override
+    public void configure() {
+        // Define public endpoints (no authentication required)
+        publicEndpoints(
+            "/",                    // Home page - welcome message
+            "/api/auth/**"          // All auth endpoints (register, login, me)
+        );
+        
+        // Define secure endpoints (authentication required)
+        requireAuth(
+            "/api/protected",       // Example protected endpoint
+            "/api/user/**"          // User-specific endpoints (profile, settings, etc.)
+        );
+        
+        // Define admin endpoints (admin role required)
+        requireRole("ADMIN", 
+            "/api/admin/**"         // Administrative endpoints (user management, etc.)
+        );
+    }
+} 
diff --git a/src/main/java/examples/auth_example/AuthExampleApp.java b/src/main/java/examples/auth_example/AuthExampleApp.java
@@ -0,0 +1,64 @@
+package examples.auth_example;
+
+import jazzyframework.core.Config;
+import jazzyframework.core.Server;
+import jazzyframework.routing.Router;
+import jazzyframework.security.annotations.EnableJazzyAuth;
+import jazzyframework.security.annotations.LoginMethod;
+
+/**
+ * Authentication Example Application
+ * 
+ * This example demonstrates how to use @EnableJazzyAuth annotation
+ * to automatically enable authentication endpoints in your Jazzy application.
+ * 
+ * Features enabled:
+ * - POST /api/auth/register - User registration
+ * - POST /api/auth/login - User login  
+ * - GET /api/auth/me - Get current user info
+ * 
+ * JWT authentication with email-based login
+ */
+@EnableJazzyAuth(
+    userClass = User.class,
+    repositoryClass = UserRepository.class,
+    loginMethod = LoginMethod.EMAIL,
+    jwtExpirationHours = 24,
+    authBasePath = "/api/auth"
+)
+public class AuthExampleApp {
+    
+    public static void main(String[] args) {
+        System.out.println("🚀 Starting Jazzy Auth Example Application...");
+        
+        Config config = new Config();
+        config.setEnableMetrics(true);
+        config.setServerPort(8080);
+        
+        Router router = new Router();
+        
+        // Configure routes
+        configureRoutes(router);
+        
+        // Start server
+        Server server = new Server(router, config);
+        server.start(config.getServerPort());
+        
+        System.out.println("✅ Authentication endpoints available:");
+        System.out.println("📝 POST /api/auth/register - Register new user");
+        System.out.println("🔐 POST /api/auth/login - User login");
+        System.out.println("👤 GET /api/auth/me - Get current user");
+        System.out.println("🌐 Server running on http://localhost:" + config.getServerPort());
+    }
+    
+    /**
+     * Configure application routes
+     */
+    private static void configureRoutes(Router router) {
+        // Example: Public welcome endpoint
+        router.GET("/", "home", HomeController.class);
+        
+        // Example: Protected endpoint (requires authentication in SecurityConfig)
+        router.GET("/api/protected", "protectedEndpoint", HomeController.class);
+    }
+} 
diff --git a/src/main/java/examples/auth_example/HomeController.java b/src/main/java/examples/auth_example/HomeController.java
@@ -0,0 +1,43 @@
+package examples.auth_example;
+
+import jazzyframework.http.Request;
+import jazzyframework.http.Response;
+import jazzyframework.http.JSON;
+
+/**
+ * Home Controller for Auth Example
+ */
+public class HomeController {
+    
+    /**
+     * Welcome endpoint
+     * GET /
+     */
+    public Response home(Request request) {
+        return Response.json(
+            JSON.of(
+                "message", "Welcome to Jazzy Auth Example!",
+                "endpoints", new String[]{
+                    "POST /api/auth/register",
+                    "POST /api/auth/login", 
+                    "GET /api/auth/me",
+                    "GET /api/protected (requires Bearer token)"
+                }
+            )
+        );
+    }
+    
+    /**
+     * Protected endpoint example - JWT validation handled automatically by SecurityInterceptor
+     * GET /api/protected
+     */
+    public Response protectedEndpoint(Request request) {
+        return Response.json(
+            JSON.of(
+                "message", "This is a protected endpoint!",
+                "note", "You successfully accessed a protected endpoint with JWT!",
+                "info", "JWT validation was handled automatically by SecurityInterceptor"
+            )
+        );
+    }
+} 
diff --git a/src/main/java/examples/auth_example/README.md b/src/main/java/examples/auth_example/README.md
@@ -0,0 +1,191 @@
+# Jazzy Framework - Authentication Example
+
+Bu örnek uygulama, `@EnableJazzyAuth` annotation'ının nasıl kullanılacağını gösterir.
+
+## Özellikler
+
+- 📧 **Email tabanlı authentication**
+- 🔐 **JWT token sistemi** 
+- 🚀 **Zero-configuration setup**
+- 📝 **Otomatik endpoint'ler**
+
+## Otomatik Oluşturulan Endpoint'ler
+
+`@EnableJazzyAuth` annotation'ı otomatik olarak şu endpoint'leri oluşturur:
+
+### 1. Kullanıcı Kaydı
+```
+POST /api/auth/register
+Content-Type: application/json
+
+{
+    "email": "user@example.com",
+    "password": "password123",
+    "name": "John Doe"
+}
+```
+
+**Başarılı Yanıt:**
+```json
+{
+    "message": "User registered successfully",
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "user": {
+        "id": "1",
+        "email": "user@example.com"
+    }
+}
+```
+
+### 2. Kullanıcı Girişi
+```
+POST /api/auth/login
+Content-Type: application/json
+
+{
+    "email": "user@example.com", 
+    "password": "password123"
+}
+```
+
+**Başarılı Yanıt:**
+```json
+{
+    "message": "Login successful",
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "user": {
+        "id": "1",
+        "email": "user@example.com"
+    }
+}
+```
+
+### 3. Mevcut Kullanıcı Bilgisi
+```
+GET /api/auth/me
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**Başarılı Yanıt:**
+```json
+{
+    "user": {
+        "id": "1",
+        "email": "user@example.com",
+        "username": null
+    }
+}
+```
+
+## Nasıl Çalıştırılır
+
+1. **Uygulamayı başlatın:**
+   ```bash
+   javac -cp "lib/*" src/main/java/examples/auth_example/*.java
+   java -cp "lib/*:src/main/java" examples.auth_example.AuthExampleApp
+   ```
+
+2. **Test edin:**
+   ```bash
+   # Kullanıcı kaydı
+   curl -X POST http://localhost:8080/api/auth/register \
+     -H "Content-Type: application/json" \
+     -d '{"email":"test@example.com","password":"123456","name":"Test User"}'
+
+   # Giriş yapın
+   curl -X POST http://localhost:8080/api/auth/login \
+     -H "Content-Type: application/json" \
+     -d '{"email":"test@example.com","password":"123456"}'
+
+   # Token ile kullanıcı bilgisi alın
+   curl -X GET http://localhost:8080/api/auth/me \
+     -H "Authorization: Bearer YOUR_TOKEN_HERE"
+   ```
+
+## Configuration
+
+`@EnableJazzyAuth` annotation'ı şu parametreleri destekler:
+
+```java
+@EnableJazzyAuth(
+    userClass = User.class,              // Kullanıcı entity class'ı
+    repositoryClass = UserRepository.class, // Kullanıcı repository interface'i
+    loginMethod = LoginMethod.EMAIL,     // EMAIL, USERNAME, veya BOTH
+    jwtExpirationHours = 24,            // JWT token süresi (saat)
+    authBasePath = "/api/auth"          // Auth endpoint'lerinin base path'i
+)
+```
+
+## Gereksinimler
+
+### User Entity
+
+User class'ınız şu field'lara sahip olmalı:
+
+- `id` (Long) - Kullanıcı ID'si
+- `email` (String) - Email adresi (EMAIL veya BOTH login method için)
+- `username` (String) - Kullanıcı adı (USERNAME veya BOTH login method için)  
+- `password` (String) - Şifre (otomatik hash'lenir)
+
+### User Repository
+
+User repository interface'iniz `BaseRepository`'yi extend etmelidir:
+
+```java
+public interface UserRepository extends BaseRepository<User, Long> {
+    // İsteğe bağlı özel query methodları ekleyebilirsiniz
+    // Optional<User> findByEmail(String email);
+    // Optional<User> findByUsername(String username);
+}
+```
+
+**Not:** Repository interface'i otomatik olarak Jazzy Framework'ün DI container'ında register edilir.
+
+## Güvenlik Konfigürasyonu (Opsiyonel)
+
+Endpoint'leri korumak için `SecurityConfig` class'ı oluşturabilirsiniz:
+
+```java
+@Component
+public class AppSecurityConfig extends SecurityConfig {
+    
+    @Override
+    public void configure() {
+        // Public endpoint'ler (authentication gerektirmez)
+        publicEndpoints(
+            "/",                    // Ana sayfa
+            "/api/auth/**"          // Tüm auth endpoint'leri
+        );
+        
+        // Secure endpoint'ler (authentication gerektirir)
+        requireAuth(
+            "/api/protected",       // Korumalı endpoint
+            "/api/user/**"          // Kullanıcıya özel endpoint'ler
+        );
+        
+        // Admin endpoint'leri (ADMIN rolü gerektirir)
+        requireRole("ADMIN", 
+            "/api/admin/**"         // Admin endpoint'leri
+        );
+    }
+}
+```
+
+### Wildcard Destek
+
+SecurityConfig şu wildcard'ları destekler:
+
+- `*` - Tek path segment'i ile eşleşir
+- `**` - Herhangi sayıda path segment'i ile eşleşir
+
+**Örnekler:**
+- `/api/auth/**` → `/api/auth/login`, `/api/auth/register`, `/api/auth/user/profile` ile eşleşir
+- `/user/*` → `/user/123` ile eşleşir ama `/user/123/profile` ile eşleşmez
+
+## Avantajları
+
+- ✅ **Zero Configuration** - Sadece annotation ekleyin
+- ✅ **Otomatik JWT** - Token üretimi ve doğrulama otomatik
+- ✅ **Flexible User Entity** - Kendi User class'ınızı kullanın
+- ✅ **Multiple Login Methods** - Email, username veya her ikisi
+- ✅ **Standard Java** - External dependency yok 
diff --git a/src/main/java/examples/auth_example/User.java b/src/main/java/examples/auth_example/User.java
diff --git a/src/main/java/examples/auth_example/UserRepository.java b/src/main/java/examples/auth_example/UserRepository.java
