How niiqow/syltra-token-service works
Project type and purpose
• This is a standalone Go-based microservice (Syltra Token Service) responsible for JWT authentication, refresh-token rotation, session tracking, and secure token management.
• It exposes a REST API (login, refresh, logout, validate) built with the Gin framework, persisting refresh tokens and device info in PostgreSQL.
File structure
• cmd/main.go: application entrypoint, router & middleware setup.
• internal/config: environment/config loader.
• internal/handlers: HTTP controllers for auth endpoints.
• internal/middleware: rate limiting, auth-context injection.
• internal/services: business logic (token creation, rotation, validation).
• internal/repository: DB access (GORM) for users/refresh tokens.
• internal/models: domain models and DB migration scripts.
• internal/database: migration runner.
• docs/: Swagger JSON/YAML.
• Dockerfile: container build.
README for additional insights
• Core flows: login → issue JWT + refresh token; refresh → rotate token; logout(s) → revoke tokens; validation endpoint.
• External dependency: USERS_SERVICE_URL (to fetch or verify user info).
• Uses HMAC-SHA256 for JWT, GORM to talk to PostgreSQL, rate limiter to throttle abuse.
a. Main components
• API Gateway (or direct ingress): accepts HTTP(S) requests.
• Syltra Token Service:
• HTTP Layer (Gin router)
• Middleware Layer (rate limiter, auth context)
• Handler Layer (auth_handler.go)
• Service Layer (AuthService)
• Repository Layer (UserRepo, RefreshTokenRepo)
• Database: PostgreSQL (refresh_tokens table + migrations)
• External User Service: USERS_SERVICE_URL for user verification
• Swagger UI (docs served under /swagger)
b. Relationships & interactions
1. Client → API Gateway → Gin HTTP Layer.
2. Request passes through rate-limiter & auth middleware.
3. Handler invokes AuthService methods.
4. AuthService calls:
• UserRepo (or external Users Service) for credential check.
• RefreshTokenRepo to create, rotate, revoke tokens.
5. Repositories interact with PostgreSQL.
6. AuthService returns JWT & refresh token to handler → client.
7. Swagger UI served from docs/ endpoint.
c. Architectural patterns & design principles
• Layered (Clean) architecture: separation between handlers (API), services (business logic), repositories (data access), models.
• Hexagonal influences: external services (Users Service) and DB are adapters.
• Middleware pipeline: cross-cutting concerns (rate limiting, JWT validation).
• Migration-driven DB schema (internal/database + internal/models/migrations).
d. Key technologies
• Go 1.22, Gin framework
• GORM ORM for PostgreSQL 15
• JWT with HMAC-SHA256 via jwt-go
• Swagger for API docs
• Docker for containerization