servcraft 0.1.0 → 0.1.3

package/src/modules/session/session.service.ts

@@ -0,0 +1,340 @@
+/**
+ * Session Service
+ * Redis-based session management with optional Prisma persistence
+ */
+import { randomUUID } from 'crypto';
+import type { Redis } from 'ioredis';
+import { getRedis } from '../../database/redis.js';
+import { prisma } from '../../database/prisma.js';
+import { logger } from '../../core/logger.js';
+import type { Session, CreateSessionData, SessionConfig, SessionStats } from './types.js';
+import { SessionRepository } from './session.repository.js';
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_PREFIX = 'session:';
+
+export class SessionService {
+  private redis: Redis;
+  private repository: SessionRepository;
+  private config: Required<SessionConfig>;
+
+  constructor(config: SessionConfig = {}) {
+    this.redis = getRedis();
+    this.repository = new SessionRepository(prisma);
+    this.config = {
+      ttlMs: config.ttlMs ?? DEFAULT_TTL_MS,
+      prefix: config.prefix ?? DEFAULT_PREFIX,
+      persistToDb: config.persistToDb ?? false,
+      slidingExpiration: config.slidingExpiration ?? true,
+    };
+
+    logger.info({ config: this.config }, 'Session service initialized');
+  }
+
+  /**
+   * Create a new session
+   */
+  async create(data: CreateSessionData): Promise<Session> {
+    const id = randomUUID();
+    const now = new Date();
+    const ttlMs = data.expiresInMs ?? this.config.ttlMs;
+    const expiresAt = new Date(now.getTime() + ttlMs);
+
+    const session: Session = {
+      id,
+      userId: data.userId,
+      userAgent: data.userAgent,
+      ipAddress: data.ipAddress,
+      data: data.data,
+      expiresAt,
+      createdAt: now,
+      lastAccessedAt: now,
+    };
+
+    // Store in Redis
+    const redisKey = this.buildKey(id);
+    const ttlSeconds = Math.ceil(ttlMs / 1000);
+    await this.redis.setex(redisKey, ttlSeconds, JSON.stringify(session));
+
+    // Optionally persist to database
+    if (this.config.persistToDb) {
+      await this.repository.create({
+        id,
+        userId: data.userId,
+        userAgent: data.userAgent,
+        ipAddress: data.ipAddress,
+        expiresAt,
+      });
+    }
+
+    logger.debug({ sessionId: id, userId: data.userId }, 'Session created');
+    return session;
+  }
+
+  /**
+   * Get session by ID
+   */
+  async get(sessionId: string): Promise<Session | null> {
+    const redisKey = this.buildKey(sessionId);
+    const data = await this.redis.get(redisKey);
+
+    if (!data) {
+      // Try database fallback if persistence is enabled
+      if (this.config.persistToDb) {
+        const dbSession = await this.repository.findById(sessionId);
+        if (dbSession) {
+          // Restore to Redis
+          const ttlMs = dbSession.expiresAt.getTime() - Date.now();
+          if (ttlMs > 0) {
+            await this.redis.setex(redisKey, Math.ceil(ttlMs / 1000), JSON.stringify(dbSession));
+            return dbSession;
+          }
+        }
+      }
+      return null;
+    }
+
+    const session = JSON.parse(data) as Session;
+
+    // Check if expired
+    if (new Date(session.expiresAt) < new Date()) {
+      await this.destroy(sessionId);
+      return null;
+    }
+
+    // Sliding expiration: refresh TTL on access
+    if (this.config.slidingExpiration) {
+      await this.touch(sessionId);
+    }
+
+    return session;
+  }
+
+  /**
+   * Validate session and return user ID
+   */
+  async validate(sessionId: string): Promise<string | null> {
+    const session = await this.get(sessionId);
+    return session?.userId ?? null;
+  }
+
+  /**
+   * Update session data
+   */
+  async update(sessionId: string, data: Partial<Session['data']>): Promise<Session | null> {
+    const session = await this.get(sessionId);
+    if (!session) return null;
+
+    session.data = { ...session.data, ...data };
+    session.lastAccessedAt = new Date();
+
+    const redisKey = this.buildKey(sessionId);
+    const ttlMs = session.expiresAt.getTime() - Date.now();
+
+    if (ttlMs > 0) {
+      await this.redis.setex(redisKey, Math.ceil(ttlMs / 1000), JSON.stringify(session));
+    }
+
+    return session;
+  }
+
+  /**
+   * Touch session (refresh TTL)
+   */
+  async touch(sessionId: string): Promise<boolean> {
+    const session = await this.getWithoutTouch(sessionId);
+    if (!session) return false;
+
+    const now = new Date();
+    session.lastAccessedAt = now;
+    session.expiresAt = new Date(now.getTime() + this.config.ttlMs);
+
+    const redisKey = this.buildKey(sessionId);
+    const ttlSeconds = Math.ceil(this.config.ttlMs / 1000);
+    await this.redis.setex(redisKey, ttlSeconds, JSON.stringify(session));
+
+    // Update database if persistence is enabled
+    if (this.config.persistToDb) {
+      await this.repository.updateExpiration(sessionId, session.expiresAt);
+    }
+
+    return true;
+  }
+
+  /**
+   * Destroy session
+   */
+  async destroy(sessionId: string): Promise<boolean> {
+    const redisKey = this.buildKey(sessionId);
+    const deleted = await this.redis.del(redisKey);
+
+    // Delete from database if persistence is enabled
+    if (this.config.persistToDb) {
+      await this.repository.delete(sessionId);
+    }
+
+    if (deleted > 0) {
+      logger.debug({ sessionId }, 'Session destroyed');
+    }
+
+    return deleted > 0;
+  }
+
+  /**
+   * Destroy all sessions for a user
+   */
+  async destroyUserSessions(userId: string): Promise<number> {
+    // Get all sessions for user from database
+    const sessions = await this.repository.findByUserId(userId);
+    let count = 0;
+
+    // Delete from Redis
+    for (const session of sessions) {
+      const redisKey = this.buildKey(session.id);
+      const deleted = await this.redis.del(redisKey);
+      if (deleted > 0) count++;
+    }
+
+    // Delete from database
+    if (this.config.persistToDb) {
+      await this.repository.deleteByUserId(userId);
+    }
+
+    // Also scan Redis for any sessions not in database
+    const pattern = `${this.config.prefix}*`;
+    const keys = await this.redis.keys(pattern);
+    for (const key of keys) {
+      const data = await this.redis.get(key);
+      if (data) {
+        const session = JSON.parse(data) as Session;
+        if (session.userId === userId) {
+          await this.redis.del(key);
+          count++;
+        }
+      }
+    }
+
+    logger.info({ userId, count }, 'User sessions destroyed');
+    return count;
+  }
+
+  /**
+   * Get all sessions for a user
+   */
+  async getUserSessions(userId: string): Promise<Session[]> {
+    const sessions: Session[] = [];
+
+    // Scan Redis for user sessions
+    const pattern = `${this.config.prefix}*`;
+    const keys = await this.redis.keys(pattern);
+
+    for (const key of keys) {
+      const data = await this.redis.get(key);
+      if (data) {
+        const session = JSON.parse(data) as Session;
+        if (session.userId === userId && new Date(session.expiresAt) > new Date()) {
+          sessions.push(session);
+        }
+      }
+    }
+
+    return sessions.sort(
+      (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
+    );
+  }
+
+  /**
+   * Get session stats
+   */
+  async getStats(): Promise<SessionStats> {
+    const pattern = `${this.config.prefix}*`;
+    const keys = await this.redis.keys(pattern);
+    const userSessions = new Map<string, number>();
+    let activeSessions = 0;
+
+    for (const key of keys) {
+      const data = await this.redis.get(key);
+      if (data) {
+        const session = JSON.parse(data) as Session;
+        if (new Date(session.expiresAt) > new Date()) {
+          activeSessions++;
+          const count = userSessions.get(session.userId) || 0;
+          userSessions.set(session.userId, count + 1);
+        }
+      }
+    }
+
+    return { activeSessions, userSessions };
+  }
+
+  /**
+   * Cleanup expired sessions
+   */
+  async cleanup(): Promise<number> {
+    let count = 0;
+
+    // Redis handles TTL automatically, but clean database
+    if (this.config.persistToDb) {
+      count = await this.repository.deleteExpired();
+      if (count > 0) {
+        logger.info({ count }, 'Cleaned up expired sessions from database');
+      }
+    }
+
+    return count;
+  }
+
+  /**
+   * Clear all sessions (for testing)
+   */
+  async clear(): Promise<void> {
+    const pattern = `${this.config.prefix}*`;
+    const keys = await this.redis.keys(pattern);
+    if (keys.length > 0) {
+      await this.redis.del(...keys);
+    }
+
+    if (this.config.persistToDb) {
+      await this.repository.clear();
+    }
+  }
+
+  /**
+   * Build Redis key for session
+   */
+  private buildKey(sessionId: string): string {
+    return `${this.config.prefix}${sessionId}`;
+  }
+
+  /**
+   * Get session without triggering sliding expiration
+   */
+  private async getWithoutTouch(sessionId: string): Promise<Session | null> {
+    const redisKey = this.buildKey(sessionId);
+    const data = await this.redis.get(redisKey);
+
+    if (!data) return null;
+
+    const session = JSON.parse(data) as Session;
+
+    if (new Date(session.expiresAt) < new Date()) {
+      return null;
+    }
+
+    return session;
+  }
+}
+
+let sessionService: SessionService | null = null;
+
+export function getSessionService(): SessionService {
+  if (!sessionService) {
+    sessionService = new SessionService();
+  }
+  return sessionService;
+}
+
+export function createSessionService(config?: SessionConfig): SessionService {
+  sessionService = new SessionService(config);
+  return sessionService;
+}

package/src/modules/session/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Session Types
+ */
+
+export interface Session {
+  id: string;
+  userId: string;
+  userAgent?: string;
+  ipAddress?: string;
+  data?: Record<string, unknown>;
+  expiresAt: Date;
+  createdAt: Date;
+  lastAccessedAt?: Date;
+}
+
+export interface CreateSessionData {
+  userId: string;
+  userAgent?: string;
+  ipAddress?: string;
+  data?: Record<string, unknown>;
+  expiresInMs?: number;
+}
+
+export interface SessionConfig {
+  /** Session TTL in milliseconds (default: 24 hours) */
+  ttlMs?: number;
+  /** Redis key prefix (default: 'session:') */
+  prefix?: string;
+  /** Whether to persist sessions to database (default: false) */
+  persistToDb?: boolean;
+  /** Sliding expiration - refresh TTL on access (default: true) */
+  slidingExpiration?: boolean;
+}
+
+export interface SessionStats {
+  activeSessions: number;
+  userSessions: Map<string, number>;
+}

package/src/modules/swagger/index.ts

@@ -1,3 +1,9 @@
 export { registerSwagger, commonResponses, paginationQuery, idParam } from './swagger.service.js';
 export { buildOpenApiSchema, generateRouteSchema } from './schema-builder.js';
-export type { SwaggerConfig, SwaggerTag, SwaggerServer, RouteSchema, EndpointDoc } from './types.js';
+export type {
+  SwaggerConfig,
+  SwaggerTag,
+  SwaggerServer,
+  RouteSchema,
+  EndpointDoc,
+} from './types.js';

package/src/modules/swagger/schema-builder.ts

@@ -24,8 +24,16 @@ export function buildOpenApiSchema(
   }
 
   if (includeTimestamps) {
-    properties.createdAt = { type: 'string', format: 'date-time', description: 'Creation timestamp' };
-    properties.updatedAt = { type: 'string', format: 'date-time', description: 'Last update timestamp' };
+    properties.createdAt = {
+      type: 'string',
+      format: 'date-time',
+      description: 'Creation timestamp',
+    };
+    properties.updatedAt = {
+      type: 'string',
+      format: 'date-time',
+      description: 'Last update timestamp',
+    };
   }
 
   return {
@@ -106,7 +114,10 @@ export function generateRouteSchema(
                   properties: {
                     data: {
                       type: 'array',
-                      items: buildOpenApiSchema(fields, { includeId: true, includeTimestamps: true }),
+                      items: buildOpenApiSchema(fields, {
+                        includeId: true,
+                        includeTimestamps: true,
+                      }),
                     },
                     meta: {
                       type: 'object',
@@ -190,7 +201,7 @@ export function generateRouteSchema(
         },
       };
 
-    case 'update':
+    case 'update': {
       // Make all fields optional for update
       const optionalFields = fields.map((f) => ({ ...f, isOptional: true }));
       return {
@@ -226,6 +237,7 @@ export function generateRouteSchema(
           },
         },
       };
+    }
 
     case 'delete':
       return {

package/src/modules/swagger/swagger.service.ts

@@ -6,8 +6,6 @@ import { logger } from '../../core/logger.js';
 import type { SwaggerConfig } from './types.js';
 
 const defaultConfig: SwaggerConfig = {
-  enabled: true,
-  route: '/docs',
   title: 'Servcraft API',
   description: 'API documentation generated by Servcraft',
   version: '1.0.0',
@@ -24,11 +22,6 @@ export async function registerSwagger(
 ): Promise<void> {
   const swaggerConfig = { ...defaultConfig, ...customConfig };
 
-  if (swaggerConfig.enabled === false) {
-    logger.info('Swagger documentation disabled');
-    return;
-  }
-
   await app.register(swagger, {
     openapi: {
       openapi: '3.0.3',
@@ -60,7 +53,7 @@ export async function registerSwagger(
   });
 
   await app.register(swaggerUi, {
-    routePrefix: swaggerConfig.route || '/docs',
+    routePrefix: '/docs',
     uiConfig: {
       docExpansion: 'list',
       deepLinking: true,
@@ -77,7 +70,7 @@ export async function registerSwagger(
 }
 
 // Helper to generate schema from Zod
-export function zodToJsonSchema(zodSchema: unknown): Record<string, unknown> {
+export function zodToJsonSchema(_zodSchema: unknown): Record<string, unknown> {
   // This is a simplified version - for full support use zod-to-json-schema package
   return {
     type: 'object',
@@ -152,7 +145,13 @@ export const paginationQuery = {
   type: 'object',
   properties: {
     page: { type: 'integer', minimum: 1, default: 1, description: 'Page number' },
-    limit: { type: 'integer', minimum: 1, maximum: 100, default: 20, description: 'Items per page' },
+    limit: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 100,
+      default: 20,
+      description: 'Items per page',
+    },
     sortBy: { type: 'string', description: 'Field to sort by' },
     sortOrder: { type: 'string', enum: ['asc', 'desc'], default: 'asc', description: 'Sort order' },
     search: { type: 'string', description: 'Search query' },

package/src/modules/swagger/types.ts

@@ -1,6 +1,4 @@
 export interface SwaggerConfig {
-  enabled?: boolean;
-  route?: string;
   title: string;
   description: string;
   version: string;

package/src/modules/upload/index.ts

@@ -0,0 +1,14 @@
+export { UploadService, getUploadService, createUploadService } from './upload.service.js';
+export { registerUploadRoutes } from './upload.routes.js';
+export type {
+  UploadedFile,
+  UploadConfig,
+  UploadOptions,
+  MultipartFile,
+  StorageProvider,
+  ImageTransformOptions,
+  LocalStorageConfig,
+  S3Config,
+  CloudinaryConfig,
+  GCSConfig,
+} from './types.js';

package/src/modules/upload/types.ts

@@ -0,0 +1,83 @@
+export type StorageProvider = 'local' | 's3' | 'cloudinary' | 'gcs';
+
+export interface UploadedFile {
+  id: string;
+  originalName: string;
+  filename: string;
+  mimetype: string;
+  size: number;
+  path: string;
+  url: string;
+  provider: StorageProvider;
+  bucket?: string;
+  metadata?: Record<string, unknown>;
+  userId?: string;
+  createdAt: Date;
+}
+
+export interface UploadConfig {
+  provider: StorageProvider;
+  maxFileSize: number; // in bytes
+  allowedMimeTypes: string[];
+  local?: LocalStorageConfig;
+  s3?: S3Config;
+  cloudinary?: CloudinaryConfig;
+  gcs?: GCSConfig;
+}
+
+export interface LocalStorageConfig {
+  uploadDir: string;
+  publicPath: string;
+}
+
+export interface S3Config {
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  bucket: string;
+  endpoint?: string; // For S3-compatible services
+  acl?: 'private' | 'public-read' | 'public-read-write';
+}
+
+export interface CloudinaryConfig {
+  cloudName: string;
+  apiKey: string;
+  apiSecret: string;
+  folder?: string;
+}
+
+export interface GCSConfig {
+  projectId: string;
+  keyFilename?: string;
+  credentials?: {
+    client_email: string;
+    private_key: string;
+  };
+  bucket: string;
+}
+
+export interface ImageTransformOptions {
+  width?: number;
+  height?: number;
+  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+  format?: 'jpeg' | 'png' | 'webp' | 'avif';
+  quality?: number;
+  blur?: number;
+  grayscale?: boolean;
+}
+
+export interface UploadOptions {
+  filename?: string;
+  folder?: string;
+  isPublic?: boolean;
+  metadata?: Record<string, unknown>;
+  transform?: ImageTransformOptions;
+}
+
+export interface MultipartFile {
+  filename: string;
+  mimetype: string;
+  encoding: string;
+  file: NodeJS.ReadableStream;
+  toBuffer(): Promise<Buffer>;
+}