Proyecto: Shortener (acortador de URLs)

Descripción

Este proyecto es una aplicación de acortador de URLs escrita en Java usando Javalin como framework web. Incluye:

• Interfaz web (Thymeleaf + recursos estáticos) para registrar usuarios, crear/administrar enlaces, ver estadísticas y generar códigos QR.
• API REST para operaciones sobre URLs.
• Servicio gRPC para operaciones de creación y listado de URLs (definido en src/main/proto/shortener.proto).
• Persistencia con MongoDB (driver sync y reactive-streams incluidos como dependencias).
• Autenticación basada en JWT para las rutas API.

Características principales

• Acortar URLs y redirigir (/acortar, /go/{shortUrl}).
• Generación de códigos QR en base64 al crear un short URL.
• Estadísticas de acceso (IP, browser, plataforma, timestamp) y vista con Google Maps (clave por variable de entorno).
• Dashboard y gestión de usuarios (roles: admin, usuario, anonymous).
• Endpoints API bajo /api/* protegidos por JWT (excepto /api/login).
• Generación de shadowJar para producción (plugin ShadowJar configurado en build.gradle).

Requisitos

• JDK 17+ (o JDK recomendado por el desarrollador).
• Gradle (incluye wrapper gradlew y gradlew.bat).
• MongoDB en ejecución (si quieres persistencia real).
• Variables de entorno opcionales para configuración (ver sección "Variables de entorno").

Dependencias importantes (seleccionadas)

• Javalin (web framework)
• MongoDB Java Drivers (sync y reactive-streams)
• Thymeleaf (templating)
• Jackson (JSON)
• JJWT (JWT handling)
• gRPC / Protobuf (protoc, grpc-java)
• ZXing (generación de QR)

Estructura del proyecto

Directorio principal de interés:

• src/main/java/edu/pucmm/eict/ - Código fuente Java
  • Main.java - Punto de entrada. Arranca Javalin, configura Thymeleaf, registra rutas y middleware.
  • controladores/ - Controladores HTTP: AuthController, UrlController, UserController, APIs REST y gRPC controllers.
  • clientes/grpc/ - Cliente y servidor gRPC, implementación del servicio UrlShortenerServiceImpl.
  • modelos/ - Modelos Url, Usuario, AccessDetail.
  • services/ - Lógica de negocio: UrlService, UserService.
  • util/ - Utilidades, por ejemplo JwtUtil para manejo de tokens.
• src/main/proto/shortener.proto - Definición Protobuf del servicio gRPC.
• src/main/resources/public/ - Recursos estáticos (templates Thymeleaf, JS, HTML cliente).
• build.gradle - Configuración de build, plugins (ShadowJar, protobuf), dependencias.

Configuración y variables de entorno

La aplicación soporta las siguientes variables de entorno (opcional):

• PORT - Puerto donde arranca la aplicación (por defecto: 7000).
• BASE_URL - Dominio base usado para construir los short URLs (por defecto: http://localhost:7000).
• GOOGLE_MAPS_API_KEY - Clave para mostrar mapas/estadísticas con Google Maps.
• JWT_SECRET - Clave secreta usada por JwtUtil para firmar/validar tokens JWT (si no está, revise JwtUtil para comportamiento por defecto).

Compilar y ejecutar

Usando el wrapper de Gradle (recomendado):

PowerShell (Windows):

.\n+\gradlew.bat build
.
\gradlew.bat shadowJar

O para ejecutar directamente desde Gradle:

.
\gradlew.bat run

Al usar shadowJar se genera un JAR ejecutable en build/libs/ que puede ejecutarse con:

java -jar build\libs\proyecto-final-1.0-SNAPSHOT-all.jar

Endpoints REST (resumen)

Rutas expuestas por la app (parcial):

• Autenticación / sesiones (web):

  • GET /login, /register, /logout
  • POST /login, /register (web forms)
  • POST /api/login (retorna JWT para API)

• URLs y redirecciones:

  • POST /acortar - Crea un short URL (form)
  • GET /go/{shortUrl} - Redirige a la URL original y registra acceso
  • GET /urls - Lista URLs (según usuario en sesión)
  • POST /dashboard/urls/acortar - Endpoint usado desde dashboard (ajax o form)
  • POST /dashboard/urls/delete - Eliminar URL
  • GET /stats/{shortUrl} - Obtener estadísticas (vista web)
  • GET /preview?url=... - Obtiene vista previa de una URL (usa microlink API)

• API JSON:

  • GET /api/urls - Listar URLs (requiere JWT con rol apropiado)
  • POST /api/urls - Crear URL vía API (requiere JWT)

gRPC

El servicio gRPC está definido en src/main/proto/shortener.proto con el paquete edu.pucmm.eict.clientes.grpc.

Servicios principales:

• UrlShortenerService
  • CreateUrl(CreateUrlRequest) -> CreateUrlResponse
  • ListUrls(ListUrlsRequest) -> ListUrlsResponse

El proyecto incluye dependencias y configuración de protobuf en build.gradle para generar las clases gRPC durante el build.

Notas de seguridad y despliegue

• JWT: Asegúrate de configurar JWT_SECRET con una clave segura en producción.
• HTTPS: En producción usa un proxy (NGINX) o plataforma que sirva TLS. No expongas tokens JWT sin TLS.
• MongoDB: No dejes la base de datos pública sin autenticación. Usa credenciales/roles y conexiones seguras.
• Dependencias: Revisa build.gradle y actualiza versiones si es necesario. Ejecuta análisis de seguridad (por ejemplo, Trivy / sonarqube) cuando agregues dependencias.

Desarrollo local rápido

1. Clonar el repositorio.
2. Ejecutar gradlew.bat run.
3. Abrir http://localhost:7000 en tu navegador (o el puerto configurado por PORT).

Pruebas

El proyecto está configurado para usar JUnit 5. Ejecuta las pruebas con:

.
\gradlew.bat test

Contacto

Para preguntas o mejoras, abre un issue o contacta al mantenedor del repositorio.